From 7d3e1680bcc9cf1d0cc8cdee25cfc2cf925934d3 Mon Sep 17 00:00:00 2001 From: Derek Pearson Date: Sat, 4 Apr 2026 15:11:01 -0500 Subject: [PATCH 1/3] docs: add build, architecture, and convention sections to AGENTS.md Add sections that were already present in CLAUDE.md but missing from AGENTS.md, bringing the two files into sync: - Build & Test: all npm scripts agents need to run - Architecture: component map of src/ layers - Import Conventions: ESM, .ts extensions, no barrel imports - Test Conventions: Vitest patterns, colocated tests, smoke tests - Tool Development: manifest-driven tool registration pattern Also clean up stray trailing hyphens on blank lines. --- AGENTS.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 62 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2a29f48b..b5ebb470 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,47 @@ # Development Rules +## Build & Test +- `npm run build` - Build (wireit + tsup, ESM) +- `npm run test` - Unit/integration tests (Vitest) +- `npm run test:smoke` - Smoke tests (builds first, serial execution) +- `npm run lint` / `npm run lint:fix` - ESLint +- `npm run format` / `npm run format:check` - Prettier +- `npm run typecheck` - TypeScript type checking (`tsc --noEmit`, plus test config) +- `npm run docs:check` - Validate docs match CLI surface + +## Architecture +ESM TypeScript project (`type: module`). Key layers: + +- `src/cli/` - CLI entrypoint, yargs wiring, daemon routing +- `src/server/` - MCP stdio server, lifecycle, workflow/resource registration +- `src/runtime/` - Config bootstrap, session state, tool catalog assembly +- `src/core/manifest/` - YAML manifest loading, validation, tool module imports +- `src/mcp/tools/` - Tool implementations grouped by workflow (mirrors `manifests/workflows/`) +- `src/mcp/resources/` - MCP resource implementations +- `src/integrations/` - External integrations (Xcode mcpbridge proxy) +- `src/utils/` - Shared helpers (execution, logging, validation, responses) +- `src/visibility/` - Tool/workflow exposure predicates +- `src/daemon/` - Background daemon for persistent sessions +- `src/rendering/` - Output rendering and formatting +- `src/types/` - Shared type definitions + +## Contributing Workflow +1. Create a branch from `main` +2. Make changes following the conventions in this file +3. Run the pre-commit checklist before committing: + ```bash + npm run lint:fix + npm run typecheck + npm run format + npm run build + npm run docs:check + npm test + ``` +4. Update `CHANGELOG.md` under `## [Unreleased]` +5. Update documentation if adding or modifying features +6. Push and create a pull request with a clear description +7. Link any related issues + ## Code Quality - No `any` types unless absolutely necessary - Check node_modules for external API type definitions instead of guessing @@ -8,6 +50,24 @@ - Always ask before removing functionality or code that appears to be intentional - Follow TypeScript best practices +## Import Conventions +- ESM with explicit `.ts` extensions in `src/` (tsup rewrites to `.js` at build) +- No `.js` imports in `src/` (enforced by ESLint) +- No barrel imports from `utils/index` - import from specific submodules (e.g., `src/utils/execution/index.ts`, `src/utils/logging/index.ts`) + +## Test Conventions +- Vitest with colocated `__tests__/` directories using `*.test.ts` +- Smoke tests in `src/smoke-tests/__tests__/` (separate Vitest config, serial execution) +- Use `vi.mock`/`vi.hoisted` for isolation; inject executors and mock file systems +- MCP integration tests use `McpServer`, `InMemoryTransport`, and `Client` +- External dependencies (command execution, file system) must use dependency injection via `createMockExecutor()` / `createMockFileSystemExecutor()` from `src/test-utils/` + +## Tool Development +- Tool manifests in `manifests/tools/*.yaml` define `id`, `module`, `names.mcp` (snake_case), optional `names.cli` (kebab-case), predicates, and annotations +- Workflow manifests in `manifests/workflows/*.yaml` group tools and define exposure rules +- Tool modules export a Zod schema, a pure `*Logic` function, and a `handler` via `createTypedTool` or `createSessionAwareTool` +- Resources export `{ uri, name, description, mimeType, handler }` + ## Commands - NEVER commit unless user asks @@ -48,8 +108,8 @@ Use these sections under `## [Unreleased]`: - NEVER update snapshot fixtures unless asked to do so, these are integration tests, on failure assume code is wrong before questioning the fixture - #### Attribution -- **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/cameroncook/XcodeBuildMCP/issues/123))` -- **External contributions**: `Added feature X ([#456](https://github.com/cameroncook/XcodeBuildMCP/pull/456) by [@username](https://github.com/username))` +- **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/getsentry/XcodeBuildMCP/issues/123))` +- **External contributions**: `Added feature X ([#456](https://github.com/getsentry/XcodeBuildMCP/pull/456) by [@username](https://github.com/username))` ## Test Execution Rules - When running long test suites (snapshot tests, smoke tests), ALWAYS write full output to a log file and read it afterwards. NEVER pipe through `tail` or `grep` directly — that loses output you may need to debug failures. From 6e257f6e843557bd3f64d337ce28148f900862c4 Mon Sep 17 00:00:00 2001 From: Derek Pearson Date: Sat, 4 Apr 2026 15:19:32 -0500 Subject: [PATCH 2/3] docs: update contributing workflow and attribution guidelines in AGENTS.md --- AGENTS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b5ebb470..8faa53c6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,8 +39,9 @@ ESM TypeScript project (`type: module`). Key layers: ``` 4. Update `CHANGELOG.md` under `## [Unreleased]` 5. Update documentation if adding or modifying features -6. Push and create a pull request with a clear description -7. Link any related issues +6. Clone and test against example projects (e.g., `XcodeBuildMCP-iOS-Template`) when changes affect runtime behavior +7. Push and create a pull request with a clear description +8. Link any related issues ## Code Quality - No `any` types unless absolutely necessary From 0846a5311d55fce6dfbf4970994401e420314507 Mon Sep 17 00:00:00 2001 From: Cameron Cooke Date: Sun, 26 Apr 2026 09:02:57 +0100 Subject: [PATCH 3/3] docs: correct AGENTS.md resource shape and integrations description Resource modules only export a handler; uri/name/description/mimeType are declared in manifests/resources/*.yaml. Also rename the integrations layer note to match the actual xcode-tools-bridge directory and trim the typecheck description for consistency. --- AGENTS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8faa53c6..00e8765a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ - `npm run test:smoke` - Smoke tests (builds first, serial execution) - `npm run lint` / `npm run lint:fix` - ESLint - `npm run format` / `npm run format:check` - Prettier -- `npm run typecheck` - TypeScript type checking (`tsc --noEmit`, plus test config) +- `npm run typecheck` - TypeScript type checking (src + test config) - `npm run docs:check` - Validate docs match CLI surface ## Architecture @@ -18,7 +18,7 @@ ESM TypeScript project (`type: module`). Key layers: - `src/core/manifest/` - YAML manifest loading, validation, tool module imports - `src/mcp/tools/` - Tool implementations grouped by workflow (mirrors `manifests/workflows/`) - `src/mcp/resources/` - MCP resource implementations -- `src/integrations/` - External integrations (Xcode mcpbridge proxy) +- `src/integrations/` - External integrations (Xcode tools bridge) - `src/utils/` - Shared helpers (execution, logging, validation, responses) - `src/visibility/` - Tool/workflow exposure predicates - `src/daemon/` - Background daemon for persistent sessions @@ -66,8 +66,8 @@ ESM TypeScript project (`type: module`). Key layers: ## Tool Development - Tool manifests in `manifests/tools/*.yaml` define `id`, `module`, `names.mcp` (snake_case), optional `names.cli` (kebab-case), predicates, and annotations - Workflow manifests in `manifests/workflows/*.yaml` group tools and define exposure rules -- Tool modules export a Zod schema, a pure `*Logic` function, and a `handler` via `createTypedTool` or `createSessionAwareTool` -- Resources export `{ uri, name, description, mimeType, handler }` +- Tool modules export a Zod `schema`, a pure `*Logic` function, and a `handler` built with `createTypedTool` or `createSessionAwareTool` +- Resource modules export a `handler` (and a pure `*Logic` function); `uri`, `name`, `description`, and `mimeType` are declared in `manifests/resources/*.yaml` ## Commands - NEVER commit unless user asks