diff --git a/.vscodeignore b/.vscodeignore index 2db69c15..65811dca 100644 --- a/.vscodeignore +++ b/.vscodeignore @@ -45,5 +45,5 @@ node_modules/** # Documentation and media usage.md -CLAUDE.md +AGENTS.md *.gif diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..22cffe04 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,123 @@ +# Coder Extension Development Guidelines + +You are an experienced, pragmatic software engineer. Simple solutions +over clever ones. Readability is a primary concern. + +## Our Relationship + +We're colleagues - push back on bad ideas and speak up when something +doesn't make sense. Honesty over agreeableness. + +- Disagree when I'm wrong - act as a critical peer reviewer +- Call out bad ideas, unreasonable expectations, and mistakes +- Ask for clarification rather than making assumptions +- Discuss architectural decisions before implementation; + routine fixes don't need discussion + +## Foundational Rules + +- Doing it right is better than doing it fast +- YAGNI - don't add features we don't need right now +- Make the smallest reasonable changes to achieve the goal +- Reduce code duplication, even if it takes extra effort +- Match the style of surrounding code - consistency within a file matters +- Fix bugs immediately when you find them + +## Essential Commands + +| Task | Command | +| ------------------------- | --------------------------------------------------- | +| **Build** | `pnpm build` | +| **Watch mode** | `pnpm watch` | +| **Package** | `pnpm package` | +| **Type check** | `pnpm typecheck` | +| **Format** | `pnpm format` | +| **Format check** | `pnpm format:check` | +| **Lint** | `pnpm lint` | +| **Lint with auto-fix** | `pnpm lint:fix` | +| **All unit tests** | `pnpm test` | +| **Extension tests** | `pnpm test:extension` | +| **Webview tests** | `pnpm test:webview` | +| **Integration tests** | `pnpm test:integration` | +| **Single extension test** | `pnpm test:extension ./test/unit/filename.test.ts` | +| **Single webview test** | `pnpm test:webview ./test/webview/filename.test.ts` | + +## Testing + +- Test observable behavior and outputs, not implementation details +- Descriptive names, minimal setup, no shared mutable state +- Never mock in end-to-end tests; minimize mocking in unit tests +- Find root causes, not symptoms - read error messages carefully +- When mocking constructors (classes) with + `vi.mocked(...).mockImplementation()`, use regular functions, not arrow + functions. Arrow functions can't be called with `new`. + +```typescript +// Wrong +vi.mocked(SomeClass).mockImplementation(() => mock); +// Correct +vi.mocked(SomeClass).mockImplementation(function () { + return mock; +}); +``` + +### Test File Organization + +```text +test/ +├── unit/ # Extension unit tests (mirrors src/ structure) +├── webview/ # Webview unit tests (by package name) +├── integration/ # VS Code integration tests (uses Mocha, not Vitest) +├── utils/ # Test utilities that are also tested +└── mocks/ # Shared test mocks +``` + +## Code Style + +- TypeScript with strict typing +- Use Prettier for code formatting and ESLint for code linting +- Use ES6 features (arrow functions, destructuring, etc.) +- Use `const` by default; `let` only when necessary +- Never use `any` - use exact types when possible +- Avoid `as unknown as` - fix the types instead +- Prefix unused variables with underscore (e.g., `_unused`) +- Error handling: wrap and type errors appropriately +- Use async/await for promises, avoid explicit Promise construction where + possible +- Unit test files must be named `*.test.ts` and use Vitest +- Extension tests go in `./test/unit/` +- Webview tests go in `./test/webview//` +- Never disable ESLint rules without user approval + +### Naming and Comments + +Names should describe what code does, not how it's implemented. + +Comments explain what code does or why it exists: + +- Never add comments about what used to be there or how things changed +- Never use temporal terms like "new", "improved", "refactored", "legacy" +- Code should be evergreen - describe it as it is +- Do not add comments when you can instead use proper variable/function + naming + +### Avoid Unnecessary Changes + +When fixing a bug or adding a feature, don't modify code unrelated to your +task. Unnecessary changes make PRs harder to review and can introduce +regressions. + +Don't reword existing comments or code unless the change is directly +motivated by your task. Don't delete existing comments that explain +non-obvious behavior. + +When adding tests for existing behavior, read existing tests first to +understand what's covered. Add cases for uncovered behavior. Edit existing +tests as needed, but don't change what they verify. + +## Version Control + +- Commit frequently throughout development +- Never skip or disable pre-commit hooks +- Check `git status` before using `git add` +- Don't use `git push --force` unless explicitly requested diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 33b99155..00000000 --- a/CLAUDE.md +++ /dev/null @@ -1,88 +0,0 @@ -# Coder Extension Development Guidelines - -## Working Style - -You're an experienced, pragmatic engineer. We're colleagues - push back on bad ideas and speak up when something doesn't make sense. Honesty over agreeableness. - -- Simple solutions over clever ones. Readability is a primary concern. -- YAGNI - don't add features we don't need right now -- Make the smallest reasonable changes to achieve the goal -- Reduce code duplication, even if it takes extra effort -- Match the style of surrounding code - consistency within a file matters -- Fix bugs immediately when you find them - -## Naming and Comments - -Names should describe what code does, not how it's implemented. - -Comments explain what code does or why it exists: - -- Never add comments about what used to be there or how things changed -- Never use temporal terms like "new", "improved", "refactored", "legacy" -- Code should be evergreen - describe it as it is -- Do not add comments when you can instead use proper variable/function naming - -## Testing and Debugging - -- Tests must comprehensively cover functionality -- Never mock behavior in end-to-end tests - use real data -- Mock as little as possible in unit tests - try to use real data -- Find root causes, not symptoms. Read error messages carefully before attempting fixes. -- When mocking constructors (classes) with `vi.mocked(...).mockImplementation()`, use regular functions, not arrow functions. Arrow functions can't be called with `new`. - ```typescript - // ✗ Wrong - vi.mocked(SomeClass).mockImplementation(() => mock); - // ✓ Correct - vi.mocked(SomeClass).mockImplementation(function () { - return mock; - }); - ``` - -## Version Control - -- Commit frequently throughout development -- Never skip or disable pre-commit hooks -- Check `git status` before using `git add` - -## Build and Test Commands - -- Build: `pnpm build` -- Watch mode: `pnpm watch` -- Package: `pnpm package` -- Type check: `pnpm typecheck` -- Format: `pnpm format` -- Format check: `pnpm format:check` -- Lint: `pnpm lint` -- Lint with auto-fix: `pnpm lint:fix` -- All unit tests: `pnpm test` -- Extension tests: `pnpm test:extension` -- Webview tests: `pnpm test:webview` -- Integration tests: `pnpm test:integration` -- Run specific extension test: `pnpm test:extension ./test/unit/filename.test.ts` -- Run specific webview test: `pnpm test:webview ./test/webview/filename.test.ts` - -## Test File Organization - -```text -test/ -├── unit/ # Extension unit tests (mirrors src/ structure) -├── webview/ # Webview unit tests (by package name) -├── integration/ # VS Code integration tests (uses Mocha, not Vitest) -├── utils/ # Test utilities that are also tested -└── mocks/ # Shared test mocks -``` - -## Code Style - -- TypeScript with strict typing -- Use Prettier for code formatting and ESLint for code linting -- Use ES6 features (arrow functions, destructuring, etc.) -- Use `const` by default; `let` only when necessary -- Never use `any`, and use exact types when you can -- Prefix unused variables with underscore (e.g., `_unused`) -- Error handling: wrap and type errors appropriately -- Use async/await for promises, avoid explicit Promise construction where possible -- Unit test files must be named `*.test.ts` and use Vitest -- Extension tests go in `./test/unit/` -- Webview tests go in `./test/webview//` -- Never disable ESLint rules without user approval diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9c554484..f81a2f06 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,11 +60,17 @@ file to display network information. ## Other features -There is a sidebar that shows all the user's workspaces, and all users' -workspaces if the user has the required permissions. +The extension provides several sidebar panels: -There are also notifications for an outdated workspace and for workspaces that -are close to shutting down. +- **My Workspaces / All Workspaces** - tree views showing workspaces with status + indicators, quick actions, and search. +- **Coder Tasks** - a React webview for creating, monitoring, and managing AI + agent tasks with real-time log streaming. +- **Coder Chat** - an embedded chat UI for delegating tasks to AI coding agents + (gated behind the `coder.agentsEnabled` context flag). + +There are also notifications for outdated workspace templates and for workspaces +that are close to shutting down. ## Webviews diff --git a/README.md b/README.md index 05c11d2e..392bf440 100644 --- a/README.md +++ b/README.md @@ -5,22 +5,39 @@ [!["Join us on Discord"](https://badgen.net/discord/online-members/coder)](https://coder.com/chat?utm_source=github.com/coder/vscode-coder&utm_medium=github&utm_campaign=readme.md) -The Coder Remote extension lets you open [Coder](https://github.com/coder/coder) -workspaces with a single click. +The Coder Remote extension connects your editor to +[Coder](https://github.com/coder/coder) workspaces with a single click. -- Open workspaces from the dashboard in a single click. -- Automatically start workspaces when opened. -- No command-line or local dependencies required - just install your editor! -- Works in air-gapped or restricted networks. Just connect to your Coder - deployment! -- Supports multiple editors: VS Code, Cursor, and Windsurf. +![Demo](https://github.com/coder/vscode-coder/raw/main/demo.gif?raw=true) -> [!NOTE] -> The extension builds on VS Code-provided implementations of SSH. Make -> sure you have the correct SSH extension installed for your editor -> (`ms-vscode-remote.remote-ssh` or `codeium.windsurf-remote-openssh` for Windsurf). +## Features + +- **One-click workspace access** - open workspaces from the Coder dashboard or + the editor sidebar. Workspaces start automatically when opened. +- **Multi-editor support** - works with VS Code, Cursor, Windsurf, and other + VS Code forks. +- **Workspace sidebar** - browse, search, and create workspaces. View agent + metadata and app statuses at a glance. +- **Coder Tasks** - create, monitor, and manage AI agent tasks directly from + the sidebar with real-time log streaming. +- **Coder Chat** - delegate development tasks to AI coding agents from the + sidebar. Requires [Coder Agents](https://coder.com/docs/ai-coder/agents) to + be enabled on your deployment. +- **Multi-deployment support** - connect to multiple Coder deployments and + switch between them without losing credentials. +- **Dev container support** - open dev containers running inside workspaces. +- **Secure authentication** - session tokens stored in the OS keyring + (macOS/Windows), with optional OAuth 2.1 support. +- **Air-gapped / restricted networks** - no external dependencies beyond your + Coder deployment. +- **Automatic SSH tuning** - applies recommended SSH settings for reliable + long-lived connections and recovers from sleep/wake. -![Demo](https://github.com/coder/vscode-coder/raw/main/demo.gif?raw=true) +> [!NOTE] +> The extension builds on VS Code-provided implementations of SSH. Make sure you +> have the correct SSH extension installed for your editor +> (`ms-vscode-remote.remote-ssh`, `anysphere.remote-ssh` for Cursor, or +> `codeium.windsurf-remote-openssh` for Windsurf). ## Getting Started @@ -34,11 +51,6 @@ ext install coder.coder-remote Alternatively, manually install the VSIX from the [latest release](https://github.com/coder/vscode-coder/releases/latest). -### Variables Reference - -Coder uses `${userHome}` from VS Code's +All extension settings are under the `coder.*` namespace in the Settings UI. +Paths in settings accept `~` and `${userHome}` from VS Code's [variables reference](https://code.visualstudio.com/docs/editor/variables-reference). -Use this when formatting paths in the Coder extension settings rather than `~` -or `$HOME`. - -Example: ${userHome}/foo/bar.baz