From 1bed976e8d14101edfb693611c264e558453a2d0 Mon Sep 17 00:00:00 2001 From: Johnny Eric Amancio Date: Mon, 25 May 2026 14:16:17 +0200 Subject: [PATCH] docs: Update dev setup instructions (#10508) --- CONTRIBUTING.md | 62 +++++- .../contributing/development-environment.md | 178 +++++++++--------- .../kilo-docs/pages/contributing/index.md | 30 ++- 3 files changed, 169 insertions(+), 101 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d31f9bf6901..7eb86bbf8bd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,13 +42,73 @@ The Kilo Community is [on Discord](https://kilo.ai/discord). ## Developing Kilo CLI - **Requirements:** Bun 1.3.13+, Java 21 (see [Prerequisites](#prerequisites) above) -- Install dependencies and start the dev server from the repo root: +- Install dependencies and start the CLI from the repo root: ```bash bun install bun dev ``` + `bun dev` and `bun run dev` both run the local CLI. For the VS Code extension, use `bun run extension`. + +## Common Checks + +From the repo root: + +```bash +bun install +bun run lint +bun run typecheck +``` + +`bun run typecheck` wraps `bun turbo typecheck`. Use `bun turbo typecheck --force` if you need to bypass the Turbo cache. + +Do **not** run `bun test` from the repo root. The root test script intentionally exits with failure so tests run from the package that owns them. + +### CLI checks + +From `packages/opencode/`: + +```bash +bun run typecheck +bun test +bun test ./path/to/file.test.ts +``` + +For backend/API validation, see [`TESTING.md`](./TESTING.md). It covers starting the local backend with `bun dev serve` and making `curl` requests against it. After changing server endpoints in `packages/opencode/src/server/`, run `./script/generate.ts` from the repo root to regenerate `packages/sdk/js/`. + +### VS Code extension checks + +From `packages/kilo-vscode/`: + +```bash +bun run typecheck +bun run lint +bun run test:unit +bun run test +bun run compile +bun run package +``` + +### Documentation checks + +From the repo root: + +```bash +bun run --filter @kilocode/kilo-docs test +bun run --filter @kilocode/kilo-docs build +bun run --filter @kilocode/kilo-docs dev +``` + +For manual docs validation, run the docs site locally, preview the affected page, and check changed links and rendered content. + +### Guardrails + +- User-facing changes usually need a changeset (`bunx changeset add` or a file under `.changeset/`). +- After changing server endpoints, regenerate the SDK with `./script/generate.ts`. +- After adding or changing guarded URLs in `packages/kilo-vscode/`, `packages/kilo-vscode/webview-ui/`, or `packages/opencode/src/`, run `bun run script/extract-source-links.ts` from the repo root. +- When editing shared `packages/opencode/` files, keep Kilo changes small and mark Kilo-only edits with `// kilocode_change` for a single line or `// kilocode_change start` / `// kilocode_change end` for a block. Do not add these markers inside `kilocode`-named paths. + ### Developing the VS Code Extension Build and launch the extension in an isolated VS Code instance: diff --git a/packages/kilo-docs/pages/contributing/development-environment.md b/packages/kilo-docs/pages/contributing/development-environment.md index 477b4a5e4ee..439cd778d74 100644 --- a/packages/kilo-docs/pages/contributing/development-environment.md +++ b/packages/kilo-docs/pages/contributing/development-environment.md @@ -16,8 +16,9 @@ This document will help you set up your development environment and understand h Before you begin, make sure you have the following installed: 1. **Git** - For version control -2. **Node.js** (version v20.18.1 (See `.nvmrc` for latest) or higher recommended) and npm +2. **Bun 1.3.13+** - Required for installing dependencies and running scripts 3. **Visual Studio Code** - Our recommended IDE for development +4. **Java 21** - Required only when running JetBrains plugin checks or repo-level checks that include `@kilocode/kilo-jetbrains` ## Getting Started @@ -37,10 +38,10 @@ Before you begin, make sure you have the following installed: 1. **Install dependencies**: ```bash - pnpm install + bun install ``` - This command will install dependencies for the main extension, webview UI, and e2e tests. + This command will install dependencies for all workspace packages. 1. **Install VSCode Extensions**: - **Required**: [ESBuild Problem Matchers](https://marketplace.visualstudio.com/items?itemName=connor4312.esbuild-problem-matchers) - Helps display build errors correctly. @@ -54,134 +55,128 @@ The full list of recommended extensions is in `.vscode/extensions.json` ### Project Structure -The project is organized into several key directories: +The project is organized into several key packages: -- **`src/`** - Core extension code - - **`core/`** - Core functionality and tools - - **`services/`** - Service implementations -- **`webview-ui/`** - Frontend UI code -- **`e2e/`** - End-to-end tests -- **`scripts/`** - Utility scripts -- **`assets/`** - Static assets like images and icons +- **`packages/opencode/`** - Kilo CLI, agent runtime, local HTTP server, session management, and TUI +- **`packages/kilo-vscode/`** - VS Code extension, webview UI, Agent Manager, and extension packaging +- **`packages/sdk/js/`** - Generated TypeScript SDK for the local server API +- **`packages/kilo-docs/`** - Documentation site +- **`packages/kilo-jetbrains/`** - JetBrains plugin ## Development Workflow -### Building the Extension +### Running the CLI -To build the extension: +To run the CLI from the repo root: ```bash -pnpm build +bun dev ``` -This will: +`bun dev` and `bun run dev` are equivalent. Both run the local source in `packages/opencode/`; they do not use a globally installed `kilo` binary. -1. Build the webview UI -2. Compile TypeScript -3. Bundle the extension -4. Create a `.vsix` file in the `bin/` directory +### Backend/API Validation + +For backend and API validation, use the root [TESTING.md](https://github.com/Kilo-Org/kilocode/blob/main/TESTING.md) guide. It covers starting the local backend with: + +```bash +bun dev serve +``` + +and validating behavior with `curl` requests against the local server. + +If you change server endpoints in `packages/opencode/src/server/`, regenerate the SDK from the repo root: + +```bash +./script/generate.ts +``` ### Running the Extension To run the extension in development mode: -1. Press `F5` (or select **Run** → **Start Debugging**) in VSCode -2. This will open a new VSCode window with Kilo Code loaded - -### Hot Reloading - -- **Webview UI changes**: Changes to the webview UI will appear immediately without restarting -- **Core extension changes**: Changes to the core extension code will automatically reload the ext host - -In development mode (NODE_ENV="development"), changing the core code will trigger a `workbench.action.reloadWindow` command, so it is no longer necessary to manually start/stop the debugger and tasks. - -> **Important**: In production builds, when making changes to the core extension, you need to: -> -> 1. Stop the debugging process -> 2. Kill any npm tasks running in the background (see screenshot below) -> 3. Start debugging again - -{% image src="https://github.com/user-attachments/assets/466fb76e-664d-4066-a3f2-0df4d57dd9a4" alt="Stopping background tasks" width="600" /%} - -### Installing the Built Extension - -To install your built extension: - ```bash -code --install-extension "$(ls -1v bin/kilo-code-*.vsix | tail -n1)" +bun run extension ``` -Replace `[version]` with the current version number. +This will build and launch the extension in an isolated VS Code instance. + +### Building the Extension + +From `packages/kilo-vscode/`: + +```bash +bun run compile +bun run package +``` + +Use `bun run compile` when you need a development build and `bun run package` when you need a production extension bundle. ## Testing Kilo Code uses several types of tests to ensure quality: -### Unit Tests +### Repo-Level Checks -Run unit tests with: +From the repo root: ```bash -npm test +bun install +bun run lint +bun run typecheck ``` -This runs both extension and webview tests. +`bun run typecheck` wraps `bun turbo typecheck`. Use `bun turbo typecheck --force` if you need to bypass the Turbo cache. -To run specific test suites: +Do **not** run `bun test` from the repo root. The root test script intentionally exits with failure to prevent accidentally running tests from the wrong package. + +### CLI Checks + +From `packages/opencode/`: ```bash -npm run test:extension # Run only extension tests -npm run test:webview # Run only webview tests +bun run typecheck +bun test +bun test ./path/to/file.test.ts ``` -### End-to-End Tests +Use the root [TESTING.md](https://github.com/Kilo-Org/kilocode/blob/main/TESTING.md) guide for backend/API checks that require `bun dev serve` and `curl`-based requests. -E2E tests verify the extension works correctly within VSCode: +### VS Code Extension Checks -1. Create a `.env.local` file in the root with required API keys: - - ``` - OPENROUTER_API_KEY=sk-or-v1-... - ``` - -2. Run the integration tests: - ```bash - npm run test:integration - ``` - -For more details on E2E tests, see e2e/VSCODE_INTEGRATION_TESTS - -## Linting and Type Checking - -Ensure your code meets our quality standards: +From `packages/kilo-vscode/`: ```bash -npm run lint # Run ESLint -npm run check-types # Run TypeScript type checking +bun run typecheck +bun run lint +bun run test:unit +bun run test +bun run compile +bun run package ``` +### Documentation Checks + +From the repo root: + +```bash +bun run --filter @kilocode/kilo-docs test +bun run --filter @kilocode/kilo-docs build +bun run --filter @kilocode/kilo-docs dev +``` + +For manual documentation validation, run the docs site locally, preview the affected page, and check the changed links and rendered content. + +## Guardrails + +- User-facing changes usually need a changeset. Run `bunx changeset add` or add a file under `.changeset/`. +- After changing server endpoints, run `./script/generate.ts` from the repo root to regenerate `packages/sdk/js/`. +- After adding or changing guarded URLs in `packages/kilo-vscode/`, `packages/kilo-vscode/webview-ui/`, or `packages/opencode/src/`, run `bun run script/extract-source-links.ts` from the repo root. +- When editing shared `packages/opencode/` files, keep changes small and mark Kilo-only edits with `// kilocode_change` for a single line or `// kilocode_change start` / `// kilocode_change end` for a block. Do not add these markers inside `kilocode`-named paths. + ## Git Hooks -This project uses [Husky](https://typicode.github.io/husky/) to manage Git hooks, which automate certain checks before commits and pushes. The hooks are located in the `.husky/` directory. - -### Pre-commit Hook - -Before a commit is finalized, the `.husky/pre-commit` hook runs: - -1. **Branch Check**: Prevents committing directly to the `main` branch. -2. **Type Generation**: Runs `npm run generate-types`. -3. **Type File Check**: Ensures that any changes made to `src/exports/roo-code.d.ts` by the type generation are staged. -4. **Linting**: Runs `lint-staged` to lint and format staged files. - -### Pre-push Hook - -Before changes are pushed to the remote repository, the `.husky/pre-push` hook runs: - -1. **Branch Check**: Prevents pushing directly to the `main` branch. -2. **Compilation**: Runs `npm run compile` to ensure the project builds successfully. -3. **Changeset Check**: Checks if a changeset file exists in `.changeset/` and reminds you to create one using `npm run changeset` if necessary. - -These hooks help maintain code quality and consistency. If you encounter issues with commits or pushes, check the output from these hooks for error messages. +This project uses [Husky](https://typicode.github.io/husky/) to manage Git hooks. The current pre-push hook checks the Bun version against root `package.json` and runs the repo-level typecheck. ## Troubleshooting @@ -189,7 +184,8 @@ These hooks help maintain code quality and consistency. If you encounter issues 1. **Extension not loading**: Check the VSCode Developer Tools (Help > Toggle Developer Tools) for errors 2. **Webview not updating**: Try reloading the window (Developer: Reload Window) -3. **Build errors**: Make sure all dependencies are installed with `npm run install:all` +3. **Build errors**: Make sure all dependencies are installed with `bun install` +4. **Root tests fail immediately**: This is expected. Run package-level tests instead of root `bun test` ### Debugging Tips diff --git a/packages/kilo-docs/pages/contributing/index.md b/packages/kilo-docs/pages/contributing/index.md index a3f17423b64..73f81ea2aa6 100644 --- a/packages/kilo-docs/pages/contributing/index.md +++ b/packages/kilo-docs/pages/contributing/index.md @@ -85,13 +85,23 @@ Guidelines: Skip the changeset only for internal refactors, CI tweaks, test-only changes, or docs that do not affect users. +### Other Guardrails + +- Regenerate `packages/sdk/js/` with `./script/generate.ts` after changing server endpoints. +- Run `bun run script/extract-source-links.ts` after adding or changing guarded URLs in `packages/kilo-vscode/`, `packages/kilo-vscode/webview-ui/`, or `packages/opencode/src/`. +- When editing shared `packages/opencode/` files, keep Kilo changes small and mark Kilo-only edits with `// kilocode_change` for a single line or `// kilocode_change start` / `// kilocode_change end` for a block. Do not add these markers inside `kilocode`-named paths. + ### Testing Your Changes -- Run the test suite: - ```bash - npm test - ``` -- Manually test your changes in the development extension +Use the current Bun commands in the [Development Environment](/docs/contributing/development-environment) guide for repo-level, CLI, backend/API, VS Code extension, and docs checks. + +Key reminders: + +- Do **not** run `bun test` from the repo root. The root test script intentionally exits with failure so tests run from the package that owns them. +- Use the root [TESTING.md](https://github.com/Kilo-Org/kilocode/blob/main/TESTING.md) guide for backend/API validation with `bun dev serve` and `curl`-based requests. +- Regenerate the SDK with `./script/generate.ts` from the repo root after changing server endpoints. +- Manually verify extension behavior with `bun run extension`. +- For manual documentation validation, preview the affected page and check changed links and rendered content. ### Creating a Pull Request @@ -143,14 +153,16 @@ Documentation improvements are highly valued contributions: - Use absolute paths starting from `/docs/` for internal links (except within the same directory) - Don't include `.md` extensions in links -2. Test your documentation changes by running the docs site locally: +2. Test your documentation changes and run the docs site locally from the repo root: ```bash - cd packages/kilo-docs - pnpm install - pnpm dev + bun run --filter @kilocode/kilo-docs test + bun run --filter @kilocode/kilo-docs build + bun run --filter @kilocode/kilo-docs dev ``` + For manual validation, preview the affected page and check changed links and rendered content. + 3. Submit a PR with your documentation changes ## Community Guidelines