|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +## Scope |
| 4 | + |
| 5 | +These instructions apply to the entire repository. This project is a deliberately small, dependency-free-at-runtime VS Code extension; prefer focused changes over new layers, frameworks, or abstractions. |
| 6 | + |
| 7 | +## Project Contract |
| 8 | + |
| 9 | +- The extension opens a fresh side terminal and sends the user-configured Kimi command. |
| 10 | +- The default command is `kimi`; official updates use `kimi upgrade`. |
| 11 | +- The active editor's workspace is preferred, followed by the first open workspace. |
| 12 | +- The launch command must come from user-level configuration only. Never consume workspace or workspace-folder values for executable commands. |
| 13 | +- Terminal execution must remain blocked while `vscode.workspace.isTrusted` is false, even when the command is invoked programmatically. |
| 14 | +- The runtime must remain transparent: no hidden child processes, installers, downloads, telemetry, terminal-output inspection, or credential handling. |
| 15 | +- Do not change the existing design, icons, or media assets unless the task explicitly requests it. Never run `npm run generate:icon` during unrelated work. |
| 16 | + |
| 17 | +## Repository Map |
| 18 | + |
| 19 | +- `src/extension.ts`: VS Code integration, commands, trust check, and terminal creation. |
| 20 | +- `src/command-utils.ts`: pure helpers; keep this module independent of the VS Code runtime where practical. |
| 21 | +- `test/command-utils.test.js`: helper behavior and security-boundary tests. |
| 22 | +- `test/metadata.test.js`: manifest, documentation, workflow, and package-contract tests. |
| 23 | +- `test/integration/`: Extension Host smoke test. |
| 24 | +- `media/`: Marketplace and toolbar artwork; preserve format, dimensions, transparency, and appearance. |
| 25 | +- `out/`, `.vscode-test/`, `node_modules/`, and `*.vsix`: generated or downloaded artifacts; do not commit them. |
| 26 | + |
| 27 | +## Required Workflow |
| 28 | + |
| 29 | +1. Read the relevant source, tests, manifest, and documentation before editing. |
| 30 | +2. Check `git status` and preserve unrelated user changes in dirty worktrees. |
| 31 | +3. Keep security and behavior invariants covered by targeted tests. |
| 32 | +4. Run the smallest relevant checks while iterating. |
| 33 | +5. Before handoff, run `npm run check`, `npm run check:security`, and `git diff --check`. |
| 34 | +6. Inspect `npm run package:list` when package contents change. Build a VSIX only when requested or when validating release behavior. |
| 35 | + |
| 36 | +Use `npm ci --ignore-scripts` for a clean, reproducible install. Do not replace `package-lock.json` with another package-manager lockfile. |
| 37 | + |
| 38 | +## Coding Standards |
| 39 | + |
| 40 | +- Use strict TypeScript and the existing ESM-style source imports compiled with `NodeNext`. |
| 41 | +- Keep runtime behavior in `extension.ts` and reusable decision logic in pure, directly testable helpers. |
| 42 | +- Prefer VS Code APIs over Node filesystem, process, or shell APIs. |
| 43 | +- Do not add production dependencies unless the functionality cannot reasonably be implemented with the VS Code or JavaScript standard APIs. |
| 44 | +- Preserve LF endings, two-space indentation, single quotes, trailing commas, and semicolons. Biome is authoritative for source and test formatting. |
| 45 | +- Avoid duplicated constants and command IDs; keep manifest contributions, implementation, tests, and documentation synchronized. |
| 46 | +- Handle errors at the user boundary with actionable messages, without logging secrets or full sensitive paths. |
| 47 | + |
| 48 | +## Security and Secrets |
| 49 | + |
| 50 | +- Treat any terminal command as code execution. Keep the Workspace Trust guard and the user-level-only configuration resolution together with regression tests. |
| 51 | +- Never read executable commands from `.vscode/settings.json`, workspace files, environment files, or repository content. |
| 52 | +- Do not add API keys, tokens, publisher credentials, `.env` files, or real user paths. Use redacted examples only. |
| 53 | +- The launcher does not own Kimi authentication. Direct users to official Kimi login and configuration documentation. |
| 54 | +- Keep GitHub workflow permissions minimal and pin actions to full commit SHAs with the release tag in a same-line comment. |
| 55 | +- `pull_request_target` workflows must never check out or execute pull-request code with write permissions. |
| 56 | + |
| 57 | +## Tests and Compatibility |
| 58 | + |
| 59 | +- Add unit tests for helper edge cases and metadata tests for public contract changes. |
| 60 | +- Keep `@types/vscode` pinned to the minimum version declared by `engines.vscode`. |
| 61 | +- The integration runner accepts `VSCODE_TEST_VERSION`; CI covers stable VS Code on Windows, Linux, and macOS plus the minimum supported VS Code on Linux. |
| 62 | +- Never weaken tests merely to make a change pass. Update brittle exact assertions only when the public contract intentionally changes. |
| 63 | + |
| 64 | +## Documentation and Releases |
| 65 | + |
| 66 | +- Update `README.md` for requirements, settings, commands, environment behavior, build, or release changes. |
| 67 | +- Add user-visible changes to the `Unreleased` section of `CHANGELOG.md`. |
| 68 | +- For a release, keep versions synchronized in `package.json`, `package-lock.json`, and `CITATION.cff`; update metadata tests when appropriate. |
| 69 | +- A `v<version>` tag triggers the GitHub release workflow. Do not create tags, push, publish, or upload Marketplace packages unless explicitly authorized. |
| 70 | +- Maintain the unofficial-project and trademark disclaimer. Do not imply endorsement by Moonshot AI or Kimi. |
| 71 | + |
| 72 | +## Dependency Policy |
| 73 | + |
| 74 | +- Confirm a dependency is used before adding it; prefer development-only tooling when runtime code does not need the package. |
| 75 | +- Review direct and transitive changes in `package-lock.json`, run the high-severity audit, and avoid forced major upgrades. |
| 76 | +- The absence of `.github/dependabot.yml` is intentional: periodic version-update PRs were disabled. Do not reintroduce them without maintainer approval; Dependabot security alerts are managed in repository settings. |
0 commit comments