Imported from krrr/sparkle-cli (AGENTS.md). Install upstream with npx skills add krrr/sparkle-cli. Copyright stays with the author.

Sparkle CLI Project Context

Sparkle CLI is a fork of Gemini CLI (terminal-based AI agent).

Project Overview

• Main Technologies:
  • Runtime: Node.js (>=20.0.0, recommended ~20.19.0 for development)
  • Language: TypeScript
  • UI Framework: React (using Ink for CLI rendering)
  • Testing: Vitest
  • Bundling: esbuild
  • Linting/Formatting: ESLint, Prettier
• Architecture: Monorepo structure using npm workspaces.
  • packages/cli: User-facing terminal UI, input processing, and display rendering.
  • packages/core: Backend logic, Sparkle API orchestration, prompt construction, and tool execution.
  • packages/a2a-server: Experimental Agent-to-Agent server.
  • packages/sdk: Programmatic SDK for embedding Sparkle CLI capabilities.
  • packages/devtools: Integrated developer tools (Network/Console inspector).
  • packages/test-utils: Shared test utilities and test rig.
  • packages/vscode-ide-companion: VS Code extension pairing with the CLI.

Building and Running

• Install Dependencies: npm install
• Build All: npm run build:all (Builds packages, sandbox, and VS Code companion)
• Build Packages: npm run build
• Run in Development: npm run start
• Run in Debug Mode: npm run debug (Enables Node.js inspector)
• Bundle Project: npm run bundle
• Clean Artifacts: npm run clean

Testing and Quality

• Test Commands:
  • Unit (All): npm run test
  • Integration (E2E): npm run test:e2e

  • NOTE: Please run the memory and perf tests locally only if you are implementing changes related to those test areas. Otherwise skip these tests locally and rely on CI to run them on nightly builds.

  • Memory (Nightly): npm run test:memory (Runs memory regression tests against baselines. Excluded from preflight, run nightly.)
  • Performance (Nightly): npm run test:perf (Runs CPU performance regression tests against baselines. Excluded from preflight, run nightly.)
  • Workspace-Specific: npm test -w <pkg> -- <path> (Note: <path> must be relative to the workspace root, e.g., -w sparkle-cli-core -- src/routing/modelRouterService.test.ts)
• Full Validation: npm run preflight (Heaviest check; runs clean, install, build, lint, type check, and tests. Recommended before submitting PRs. Due to its long runtime, only run this at the very end of a code implementation task. If it fails, use faster, targeted commands (e.g., npm run test, npm run lint, or workspace-specific tests) to iterate on fixes before re-running preflight. For simple, non-code changes like documentation or prompting updates, skip preflight at the end of the task and wait for PR validation.)
• Individual Checks: npm run lint / npm run format / npm run typecheck

Development Conventions

• Contributions: Follow the process outlined in CONTRIBUTING.md.
• Commit Messages: Follow the Conventional Commits standard.
• Imports: Use specific imports and avoid restricted relative imports between packages (enforced by ESLint).
• License Headers: For all new source code files (.ts, .tsx, .js), include the Apache-2.0 license header with the current year. (e.g., Copyright 2026 Google LLC). This is enforced by ESLint.

Testing Conventions

• Environment Variables: When testing code that depends on environment variables, use vi.stubEnv('NAME', 'value') in beforeEach and vi.unstubAllEnvs() in afterEach. Avoid modifying process.env directly as it can lead to test leakage and is less reliable. To "unset" a variable, use an empty string vi.stubEnv('NAME', '').

Documentation

• Always use the docs-writer skill when you are asked to write, edit, or review any documentation.
• Documentation is located in the docs/ directory.
• Suggest documentation updates when code changes render existing documentation obsolete or incomplete.