@agents-dev/cli 0.7.7

package/AGENTS.md

@@ -0,0 +1,400 @@
+# AGENTS.md
+
+Instructions for AI coding agents working on the `@agents-dev/cli` project.
+
+## Project Overview
+
+**@agents-dev/cli** is a CLI tool that provides a practical standard layer for multi-LLM development. It solves the configuration fragmentation problem by syncing MCP servers, skills, and instructions across multiple AI coding tools (Codex, Claude Code, Gemini CLI, Cursor, Copilot, Antigravity) from a single source of truth.
+
+**Key Principle:** One `.agents/` folder syncs to all tools. Add an MCP server once, it appears everywhere.
+
+## Tech Stack
+
+- **Language:** TypeScript (strict mode)
+- **Runtime:** Node.js 20+
+- **Build:** tsc (TypeScript compiler)
+- **Tests:** Vitest
+- **CLI Framework:** Commander.js
+- **Prompts:** @clack/prompts
+- **Package Manager:** npm
+
+## Project Structure
+
+```
+agents/
+├── src/
+│   ├── cli.ts                    # CLI entry point
+│   ├── commands/                 # Command implementations
+│   │   ├── start.ts             # Setup wizard
+│   │   ├── sync.ts              # Config sync
+│   │   ├── mcp-add.ts           # Add MCP server
+│   │   └── ...
+│   ├── core/                     # Core logic
+│   │   ├── sync.ts              # Sync orchestration
+│   │   ├── mcp.ts               # MCP management
+│   │   ├── renderers.ts         # Tool-specific config generators
+│   │   ├── trust.ts             # Codex trust management
+│   │   └── ...
+│   ├── integrations/             # Tool integrations
+│   │   ├── codex.ts
+│   │   ├── claude.ts
+│   │   ├── cursor.ts
+│   │   └── ...
+│   └── types.ts                  # TypeScript types
+├── tests/                        # Test files
+│   ├── *.test.ts                # Unit tests
+│   └── *.integration.test.ts    # Integration tests
+├── templates/                    # Scaffold templates
+│   └── agents/                  # .agents/ directory templates
+├── docs/                         # Public documentation
+└── bin/agents                    # CLI wrapper script
+```
+
+## Development Workflow
+
+### Setup
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+### Development Commands
+
+```bash
+npm run dev -- <command>          # Run CLI in dev mode
+npm run build                     # Compile TypeScript
+npm test                          # Run all tests
+npm test tests/sync.test.ts       # Run specific test
+npm test -- --watch               # Watch mode
+npm run lint                      # Run ESLint
+```
+
+### Testing
+
+- **Unit tests:** Test individual functions in isolation
+- **Integration tests:** Test full command flows with temp directories
+- Use `mkdtemp` for temporary test directories
+- Always clean up in `afterEach` hooks
+- Mock external CLI calls when appropriate
+
+### Code Style
+
+- **TypeScript strict mode** is enabled
+- Follow existing patterns and conventions
+- Use descriptive variable names
+- Add JSDoc comments for exported functions
+- Keep functions focused (single responsibility)
+- Prefer pure functions where possible
+
+## Key Concepts
+
+### 1. Project Structure (`core/project.ts`)
+
+Projects have:
+- `.agents/agents.json` — MCP servers, shared config
+- `.agents/local.json` — Secrets (gitignored)
+- `.agents/skills/` — Reusable workflows
+- `.agents/generated/` — Auto-generated files (gitignored)
+- `AGENTS.md` — Instructions for all tools
+
+### 2. Sync Process (`core/sync.ts`)
+
+1. Read `.agents/agents.json` and `.agents/local.json`
+2. Merge configs (local overrides shared)
+3. Generate tool-specific configs via renderers
+4. Write atomically (temp file + rename)
+5. Acquire sync lock to prevent race conditions
+
+### 3. Renderers (`core/renderers.ts`)
+
+Each tool has a renderer that converts `.agents/agents.json` to tool-specific format:
+- **Codex:** TOML (`.codex/config.toml`)
+- **Claude:** JSON (`.claude/mcp.json`)
+- **Gemini:** JSON (`.gemini/settings.json`)
+- **Cursor:** JSON (`.cursor/mcp.json`)
+- **Copilot:** JSON (`.vscode/mcp.json`)
+- **Antigravity:** JSON (`.antigravity/mcp.json`)
+
+### 4. MCP Server Management (`core/mcp.ts`)
+
+MCP servers have:
+- **Transport:** `stdio` (command-based) or `http`/`sse` (URL-based)
+- **Config:** command, args, env, headers
+- **Secrets:** Stored in `.agents/local.json`
+- **Validation:** Keys must be shell-safe (env) or HTTP token format (headers)
+
+### 5. Trust Management (`core/trust.ts`)
+
+Codex requires explicit trust per project. We:
+- Check trust state via `codex trust list`
+- Set trust via `codex trust set --path <project>`
+- Store trust in Codex global config
+
+### 6. File Safety (`core/fs.ts`)
+
+Critical operations use atomic writes:
+- Write to temp file
+- Rename to target (atomic on most filesystems)
+- Prevents data corruption if process crashes
+
+## Common Tasks
+
+### Adding a New Command
+
+1. Create `src/commands/your-command.ts`
+2. Export async function matching command signature
+3. Register in `src/cli.ts` with Commander
+4. Add tests in `tests/your-command.test.ts`
+5. Update README.md command reference
+6. Update CHANGELOG.md
+
+### Adding a New Tool Integration
+
+1. Create `src/integrations/your-tool.ts`
+2. Implement integration interface (id, name, paths)
+3. Add renderer in `src/core/renderers.ts`
+4. Register in `src/integrations/registry.ts`
+5. Add sync logic in `src/core/sync.ts`
+6. Add tests
+7. Update README supported tools table
+
+### Fixing a Bug
+
+1. Write a failing test that reproduces the bug
+2. Fix the bug
+3. Verify test passes
+4. Add edge case tests
+5. Update CHANGELOG.md (## Unreleased > ### Fixed)
+
+### Adding a Feature
+
+1. Discuss in GitHub issue first (if major)
+2. Write tests for new behavior
+3. Implement feature
+4. Update documentation
+5. Update CHANGELOG.md (## Unreleased > ### Added)
+
+## Important Patterns
+
+### Error Handling
+
+```typescript
+// Throw descriptive errors
+throw new Error(`MCP server "${name}" not found in .agents/agents.json`)
+
+// User-facing errors should be clear and actionable
+console.error(`Error: Invalid env key "${key}". Use format: [A-Za-z_][A-Za-z0-9_]*`)
+process.exitCode = 1
+```
+
+### File Operations
+
+```typescript
+// Always use atomic writes for critical files
+import { writeJsonAtomic } from './core/fs.js'
+
+await writeJsonAtomic(path, data)
+```
+
+### External CLI Calls
+
+```typescript
+// Use spawnSync for external commands
+import { spawnSync } from 'node:child_process'
+
+const result = spawnSync('codex', ['trust', 'list'], {
+  encoding: 'utf-8',
+  stdio: ['ignore', 'pipe', 'pipe']
+})
+
+if (result.status !== 0) {
+  // Handle error
+}
+```
+
+### Temp Directories in Tests
+
+```typescript
+import { mkdtemp, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+
+describe('my test', () => {
+  const tempDirs: string[] = []
+
+  afterEach(async () => {
+    await Promise.all(tempDirs.map(dir => rm(dir, { recursive: true, force: true })))
+    tempDirs.length = 0
+  })
+
+  it('does something', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'agents-test-'))
+    tempDirs.push(dir)
+    // test logic
+  })
+})
+```
+
+## Testing Guidelines
+
+### What to Test
+
+- ✅ All public functions
+- ✅ Error conditions
+- ✅ Edge cases (empty arrays, null values, etc.)
+- ✅ Integration flows (full command execution)
+- ✅ File I/O (read/write operations)
+- ❌ Don't test third-party libraries
+
+### Test Structure
+
+```typescript
+describe('feature', () => {
+  it('should do X when Y', () => {
+    // Arrange
+    const input = { ... }
+
+    // Act
+    const result = myFunction(input)
+
+    // Assert
+    expect(result).toBe(expected)
+  })
+})
+```
+
+### Flaky Tests
+
+If a test is flaky (timing-dependent):
+- Increase timeout: `it('test', { timeout: 10000 }, async () => { ... })`
+- Add retry logic if appropriate
+- Mock external dependencies that cause flakiness
+
+## Release Process
+
+(For maintainers only - see `.docs-internal/PUBLISHING.md`)
+
+1. Update CHANGELOG.md
+2. Bump version: `npm version patch|minor|major`
+3. Build and test: `npm run build && npm test`
+4. Publish: `npm publish --access public`
+5. Create GitHub release with tag
+
+## Common Pitfalls
+
+### 1. Forgetting Atomic Writes
+
+**Wrong:**
+```typescript
+await writeFile(path, JSON.stringify(data))
+```
+
+**Right:**
+```typescript
+await writeJsonAtomic(path, data)
+```
+
+### 2. Not Cleaning Up Temp Dirs in Tests
+
+Always use `afterEach` to clean up, or tests will leave garbage in `/tmp`.
+
+### 3. Hardcoding Paths
+
+**Wrong:**
+```typescript
+const codexConfig = '/Users/me/.codex/config.toml'
+```
+
+**Right:**
+```typescript
+import { getCodexConfigPath } from './core/paths.js'
+const codexConfig = getCodexConfigPath()
+```
+
+### 4. Not Validating User Input
+
+Always validate:
+- MCP server names (no spaces, special chars)
+- Env keys (shell-safe format)
+- Header keys (HTTP token format)
+- File paths (absolute, not relative)
+
+### 5. Assuming External CLIs Are Available
+
+Check if CLI is installed before calling:
+```typescript
+const result = spawnSync('codex', ['--version'], { encoding: 'utf-8' })
+if (result.status !== 0) {
+  console.warn('Codex CLI not found. Skipping Codex integration.')
+  return
+}
+```
+
+## Security Considerations
+
+- **Secrets** are stored in `.agents/local.json` (gitignored)
+- Never log secrets to console
+- Use `--secret-env` and `--secret-header` flags for sensitive values
+- Validate all user input (especially paths and shell commands)
+- Don't execute arbitrary code from config files
+
+## Performance Tips
+
+- Use `sync --check` for drift detection (faster than full sync)
+- Use `status --fast` to skip slow external CLI probes
+- Cache external CLI results when appropriate
+- Use `Promise.all()` for parallel operations
+
+## Documentation Standards
+
+When updating docs:
+- Keep README.md concise (high-level overview)
+- Put details in `docs/` files
+- Use code examples for clarity
+- Include expected output
+- Add troubleshooting sections
+
+## Git Workflow
+
+```bash
+# Create feature branch
+git checkout -b feature/my-feature
+
+# Make changes, commit
+git add .
+git commit -m "feat: add new feature"
+
+# Push and create PR
+git push origin feature/my-feature
+```
+
+**Commit Message Format:**
+- `feat:` — New feature
+- `fix:` — Bug fix
+- `docs:` — Documentation
+- `test:` — Tests
+- `refactor:` — Code refactoring
+- `chore:` — Maintenance
+
+## Questions?
+
+- Check existing code for patterns
+- Read tests for examples
+- Ask in GitHub Discussions
+- Open an issue if stuck
+
+## Key Files Reference
+
+- **Entry point:** `src/cli.ts`
+- **Sync logic:** `src/core/sync.ts`
+- **MCP management:** `src/core/mcp.ts`, `src/core/mcpCrud.ts`
+- **Renderers:** `src/core/renderers.ts`
+- **Types:** `src/types.ts`
+- **File I/O:** `src/core/fs.ts`
+- **Paths:** `src/core/paths.ts`
+
+---
+
+**Remember:** The goal is to make multi-LLM development simple. Every feature should reduce friction, not add complexity.

package/CHANGELOG.md

@@ -0,0 +1,297 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.7.7] - 2026-02-07
+
+### Added
+
+- `agents status --fast` to skip external CLI probes for quicker status checks.
+- `agents doctor --fix-dry-run` to preview automatic fixes without mutating project files.
+- Sync lock handling for `.agents/generated/sync.lock` to guard against concurrent sync runs.
+- New shell-style argument tokenizer for interactive `agents mcp add` argument input.
+- New test suites:
+  - `tests/status.command.test.ts`
+  - `tests/sync-lock.integration.test.ts`
+  - `tests/shell-words.test.ts`
+
+### Changed
+
+- npm package publishing is now stricter and reproducible via:
+  - `prepack` build hook
+  - explicit `files` whitelist in `package.json`
+- CI matrix now validates Node.js `20` and `22` across Linux, macOS, and Windows.
+- Interactive `agents mcp add` now parses quoted/escaped args reliably instead of naive whitespace splitting.
+- README command reference updated for `status --fast` and `doctor --fix-dry-run`.
+- CLI version bumped to `0.7.7`.
+
+### Fixed
+
+- Reduced sync race conditions by introducing project-local sync lock acquisition before writes.
+- URL-based MCP import now uses timeout + retry behavior, improving resilience to transient network failures.
+
+## [0.7.6] - 2026-02-05
+
+### Added
+
+- `agents mcp test --runtime` and `--runtime-timeout-ms` for best-effort live MCP health checks via Claude, Gemini, and Cursor CLIs.
+- Doctor now validates syntax for generated/materialized configs:
+  - TOML: `.agents/generated/codex.config.toml`, `.codex/config.toml`
+  - JSON: generated/materialized Gemini/Copilot/Cursor/Antigravity/Claude payloads
+- New test suites:
+  - `tests/mcp-test-runtime.integration.test.ts`
+  - `tests/cursor-sync.integration.test.ts`
+  - `tests/doctor.integration.test.ts`
+  - `tests/sync-validation.integration.test.ts`
+
+### Changed
+
+- Codex renderer now includes URL-based MCP servers (`http` and legacy `sse`) instead of skipping non-stdio servers.
+- Codex TOML output now quotes env/header keys safely and writes HTTP headers under `http_headers`.
+- `agents mcp test` output now includes runtime details when `--runtime` is used.
+- Cursor status parsing recognizes connection failures as an explicit `error` state.
+- Cursor auto-approval sync no longer retries enable loops for `unknown/error` runtime statuses, improving idempotency.
+- CLI version bumped to `0.7.6`.
+
+### Fixed
+
+- Prevented invalid env/header keys from producing broken Codex TOML:
+  - fail-fast validation in `mcp add` and `mcp import`
+  - fail-fast validation during `agents sync` for existing bad configs
+- `agents doctor` now reports invalid MCP env/header keys as errors.
+- Eliminated repeated `cursor-local-approval` drift in `agents sync --check` when Cursor reports persistent connection errors.
+
+## [0.7.5] - 2026-02-05
+
+### Fixed
+
+- Resolved stale Claude MCP leftovers (`agents__*`) surviving across reset/start cycles.
+- Sync now reconciles with actual `claude mcp list` managed entries before applying changes, so orphaned servers are removed automatically.
+
+### Added
+
+- New Claude CLI parser utility:
+  - `src/core/claudeCli.ts`
+- New tests:
+  - `tests/claude-cli.test.ts`
+
+### Changed
+
+- Increased timeout for MCP commands integration test to stabilize environments where local CLI probes are slower.
+- CLI version bumped to `0.7.5`.
+
+## [0.7.4] - 2026-02-05
+
+### Fixed
+
+- `agents mcp add https://mcpservers.org/servers/appcontext-dev` now imports successfully.
+- Import parser now handles MCP snippets provided as plain `<pre><code>...</code></pre>` blocks without a `language-json` class.
+
+### Added
+
+- Import payload support for direct name->server maps:
+  - `{ "appcontext": { "url": "http://localhost:7777/sse", "type": "sse" } }`
+
+### Changed
+
+- `parseImportedServers` error/help text now documents the plain map payload shape.
+- CLI version bumped to `0.7.4`.
+
+## [0.7.3] - 2026-02-05
+
+### Fixed
+
+- Resolved a regression where `agents mcp add/import` could fail during sync with:
+  - `Invalid environment variable value ... contains potentially dangerous characters`
+- Placeholder values like `${GITHUB_TOKEN}` and real API keys containing punctuation now sync correctly to CLI integrations.
+- Validation now blocks only control characters (the command runner uses `spawnSync` without a shell).
+
+### Added
+
+- New tests for MCP env/header validation behavior:
+  - `tests/mcp-validation.test.ts`
+
+### Changed
+
+- CLI version bumped to `0.7.3`.
+
+## [0.7.2] - 2026-02-05
+
+### Added
+
+- Interactive secret prompt during MCP import for template token/key values (for example `${GITHUB_TOKEN}`, `ghp_xxxx`):
+  - asks immediately during `agents mcp import` / URL-driven `agents mcp add`
+  - accepts Enter to skip and configure later
+  - keeps placeholders in `.agents/agents.json`
+  - stores only provided values in `.agents/local.json`
+
+### Changed
+
+- `splitServerSecrets` now supports placeholder-only secret keys/indexes without forcing local secret values.
+- README clarifies Antigravity CLI naming (`antigravity`) and the new import-time secret prompt flow.
+- CLI version bumped to `0.7.2`.
+
+## [0.7.1] - 2026-02-05
+
+### Added
+
+- URL import fallback for `mcpservers.org` pages without JSON snippets:
+  - detects linked GitHub repo
+  - fetches README
+  - extracts MCP JSON/JSONC code blocks automatically
+
+### Changed
+
+- `agents mcp import --file` now gives a clear validation error when a URL is passed (`--file` is local path only, use `--url` for websites).
+- URL import error message now points users to the correct flows (`--url` for JSON pages, or explicit `--json` / `--file` snippets).
+
+### Fixed
+
+- `agents mcp add <mcpservers-url>` now works for pages like `cameroncooke/xcodebuildmcp` that previously failed extraction with “Could not extract MCP JSON payload from URL”.
+
+## [0.7.0] - 2026-02-05
+
+### Added
+
+- `agents status --verbose` for full files/probes breakdown while default output is compact.
+- `agents mcp doctor` alias for `agents mcp test`.
+- New Cursor CLI parser helper (`src/core/cursorCli.ts`) for robust MCP status parsing.
+
+### Changed
+
+- CLI version bumped to `0.7.0`.
+- `agents start` preflight now shows only actionable warnings (missing tools), reducing setup noise.
+- Warning output across commands is now compacted and deduplicated.
+- Cursor sync now self-heals approval drift: it checks `cursor-agent mcp list` and re-enables non-ready servers.
+- Antigravity payload now includes both `servers` and `mcpServers` for compatibility.
+- Status probe output is more reliable for Cursor (handles terminal control sequences correctly).
+
+### Fixed
+
+- Claude MCP sync no longer emits repeated "already exists in local config" warnings for already-managed servers.
+
+## [0.6.0] - 2026-02-05
+
+### Added
+
+- New `agents mcp` toolkit for project-local MCP lifecycle:
+  - `agents mcp list`
+  - `agents mcp add`
+  - `agents mcp import` (strict JSON/JSONC from file/inline/stdin/URL)
+  - `agents mcp remove`
+  - `agents mcp test`
+- New MCP core helpers:
+  - `src/core/mcpValidation.ts`
+  - `src/core/mcpCrud.ts`
+  - `src/core/mcpImport.ts`
+  - `src/core/mcpSecrets.ts`
+- New MCP-focused test suites:
+  - `tests/mcp-import.test.ts`
+  - `tests/mcp-crud.test.ts`
+  - `tests/mcp-secrets.test.ts`
+  - `tests/mcp-commands.integration.test.ts`
+  - `tests/mcp-test.integration.test.ts`
+
+### Changed
+
+- CLI version bumped to `0.6.0`
+- `agents mcp add <https://...>` now auto-detects URL input and delegates to import flow
+- `agents status` now includes MCP totals and local override counts
+- `agents doctor` now warns about unresolved MCP placeholders and likely secret literals in `.agents/agents.json`
+- Sync security checks now reuse shared MCP validation helpers
+
+## [0.5.0] - 2026-02-05
+
+### Added
+
+- New compact `.agents` format:
+  - `.agents/agents.json`
+  - `.agents/local.json`
+  - `.agents/skills/*/SKILL.md`
+  - `.agents/generated/*`
+- Managed VS Code hiding for tool directories via `.vscode/settings.json` (JSONC merge)
+- VS Code settings state tracking in `.agents/generated/vscode.settings.state.json`
+- New test suite: `tests/vscode-settings.test.ts`
+
+### Changed
+
+- Root `AGENTS.md` is now canonical
+- MCP registry is now project-local (no global catalog dependency)
+- `agents start` simplified to project-local setup defaults
+- Skills bridges now include Gemini (`.gemini/skills`) in addition to Claude and Cursor
+
+### Removed
+
+- `.agents/project.json`
+- `.agents/mcp/selection.json`
+- `.agents/mcp/local.json`
+- `.agents/AGENTS.md`
+- Global catalog/preset flow
+
+## [0.4.1] - 2026-02-05
+
+### Fixed
+
+- **CRITICAL**: Fixed `namesToRemove` bug in Claude MCP sync ([src/core/sync.ts:277](src/core/sync.ts#L277))
+  - Previously used `union` of current and desired servers instead of `difference`
+  - This caused ALL servers (both current and desired) to be removed and re-added
+  - Now correctly removes only servers that exist in current but not in desired
+
+- **CRITICAL**: Added error handling for `JSON.parse` operations
+  - [src/core/fs.ts:25](src/core/fs.ts#L25): Now provides helpful error messages when JSON parsing fails
+  - [src/core/sync.ts:194](src/core/sync.ts#L194): Added handling for empty/invalid generated configs
+  - [src/core/sync.ts:198-202](src/core/sync.ts#L198): Now warns about corrupted files instead of silently ignoring them
+
+### Security
+
+- Added server name validation to prevent command injection attacks
+  - Server names must only contain alphanumeric characters, hyphens, underscores, colons, and dots
+  - Prevents path traversal attempts with `..`
+  - Applied to both Claude and Cursor sync operations
+
+- Added environment variable and header value validation
+  - Validates values in `addClaudeServer` before using them in CLI commands
+  - Rejects values containing shell metacharacters: `` ` $ \ ; | & < > ( ) { } [ ] ! ``
+  - Rejects values containing control characters
+
+### Added
+
+- New test suite: `tests/validation.test.ts`
+  - Tests JSON parsing error handling with invalid and empty JSON files
+
+- New test suite: `tests/real-project-mcp.test.ts`
+  - Validates real MCP configuration (dogfooding)
+  - Checks for `.claude` directory and settings
+  - Queries `claude mcp list` to verify agents-managed servers
+  - Provides informational output about project MCP status
+  - Helps catch configuration drift and ensures tests run against real-world setups
+
+- Added 10 new tests (total: 24 tests, up from 14)
+
+### Changed
+
+- Improved error messages for JSON parsing failures
+  - Now includes file path and specific parse error
+  - Distinguishes between file-not-found and corrupted file errors
+
+## [0.4.0] - 2026-02-04
+
+### Added
+
+- Cursor and Antigravity support
+- Complete onboarding with sync hub
+- Trust flow for Codex
+
+### Changed
+
+- Bootstrap v1 with multi-tool MCP sync
+- Improved integration handling
+
+## [Earlier versions]
+
+See git history for changes before 0.4.0.