diff --git a/AGENTS.md b/AGENTS.md index 7a3eaa02e..b1164cf79 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,7 @@ See [docs/architecture.mermaid](docs/architecture.mermaid) for a visual architec - `src/cli.ts`: one-shot CLI adapter for setup, diagnostics, analysis, and decompilation. - `src/config.ts`: Zod-validated parsing of environment configuration into `AppConfig`. - `src/domain/`: pure, side-effect-free modules. `errors.ts` (tagged error algebra), `result.ts` (`Result`/`ok`/`err`), `hopperValues.ts` (boundary parsers for Hopper JSON), `symbolAnalysis.ts` (Swift/ObjC name parsing). -- `src/contracts/`: caller-visible schemas for 31 direct, 8 enhanced, and 3 session tools; `enhancedInputs.ts` owns enhanced input parsing. +- `src/contracts/`: caller-visible schemas for 33 direct, 10 enhanced, 5 native, 2 artifact, and 18 session tools; `enhancedInputs.ts` owns enhanced input parsing. - `src/hopper/`: Hopper launch and Unix-socket protocol mechanics. `BridgeLauncher.ts` spawns the Hopper app with the in-process bridge, `HopperClient.ts` correlates request/response over the socket with timeouts and cancellation, `protocol.ts` frames bridge messages. - `bridge/hopper_bridge.py`: runs inside Hopper and adapts declared operations to Hopper's public Python API. Hopper's bundled MCP server is not used. - `src/application/`: shared CLI/MCP session composition, setup and diagnostics, and the 8 enhanced workflows. @@ -34,7 +34,7 @@ See [docs/architecture.mermaid](docs/architecture.mermaid) for a visual architec - `npm run jscpd`: detect duplicate code blocks. - `npm run scan:todos`: scan for TODO, FIXME, and HACK markers. - `npm run verify:hopper`: build and run the real-Hopper verifier with two distinct binaries. -- `npm run verify:package`: pack and test the CLI, setup transaction, skill, and 42-tool target-free MCP server in an isolated environment. +- `npm run verify:package`: pack and test the CLI, setup transaction, skill, and 68-tool target-free MCP server in an isolated environment. - `npm run docs:generate`: generate API documentation from JSDoc comments into `docs/api/` using TypeDoc. - `npm run config:print -- /path/to/binary`: print an MCP server config with absolute paths. - `HOPPER_TARGET_PATH=/path/to/binary npm start`: launch Hopper and run the built stdio MCP server. @@ -54,7 +54,7 @@ Use ESM TypeScript, two-space indentation, and Prettier defaults. Keep compiler ## Testing Guidelines -Name tests `*.test.ts`. Use Vitest and production seams (`tests/fixtures/`) rather than module mocks. Domain tests assert pure behavior; adapter tests use the fake launcher/socket; MCP tests connect with the beta.3 client. Preserve the 31 direct, 8 enhanced, and 3 session tool inventory (42 total). Cover malformed input, cancellation, timeouts, process exit, concurrency, limits, and clean shutdown. Real Hopper claims cannot be replaced by mocks — use `npm run verify:hopper` with two distinct binaries for end-to-end verification. +Name tests `*.test.ts`. Use Vitest and production seams (`tests/fixtures/`) rather than module mocks. Domain tests assert pure behavior; adapter tests use the fake launcher/socket; MCP tests connect with the beta.3 client. Preserve the 33 direct, 10 enhanced, 5 native, 2 artifact, and 18 session tool inventory (68 total). Cover malformed input, cancellation, timeouts, process exit, concurrency, limits, and clean shutdown. Real Hopper claims cannot be replaced by mocks — use `npm run verify:hopper` with two distinct binaries for end-to-end verification. ## Commit & Pull Request Guidelines diff --git a/docs/architecture.mermaid b/docs/architecture.mermaid index 7eb648e5c..d2dbe281b 100644 --- a/docs/architecture.mermaid +++ b/docs/architecture.mermaid @@ -1,6 +1,6 @@ graph TD subgraph "Entry Points" - CLI["src/cli.ts
One-shot CLI adapter
setup, diagnostics, analysis, decompilation"] + CLI["src/cli.ts
One-shot CLI adapter
setup, diagnostics, analysis, inventory, extraction"] MAIN["src/main.ts
MCP stdio server adapter
config, session, process lifetime"] DISPATCH["scripts/rea.mjs
Executable dispatcher
routes mcp / one-shot"] end @@ -18,12 +18,17 @@ graph TD HOPPER["src/hopper/
Hopper launch & Unix-socket protocol
BridgeLauncher, HopperClient, protocol"] end + subgraph "Provider Adapters" + ARTIFACTS["src/artifacts/
Directory, ZIP/APK/IPA, ASAR, Mach-O slices
safe transactional output"] + NATIVE["src/native/
Bounded native macOS semantic inspection"] + end + subgraph "Contracts Layer" - CONTRACTS["src/contracts/
Caller-visible tool schemas
31 direct, 8 enhanced, 3 session tools"] + CONTRACTS["src/contracts/
Caller-visible tool schemas
33 direct, 10 enhanced, 5 native, 2 artifact, 18 session"] end subgraph "Domain Layer" - DOMAIN["src/domain/
Pure side-effect-free modules
errors, Result, hopperValues, symbolAnalysis"] + DOMAIN["src/domain/
Pure side-effect-free modules
errors, Result, evidence, artifactGraph, residualUnknowns"] end subgraph "Configuration" @@ -43,9 +48,14 @@ graph TD SERVER --> CONTRACTS SERVER --> APP APP --> HOPPER + APP --> ARTIFACTS + APP --> NATIVE HOPPER --> BRIDGE APP --> DOMAIN CONTRACTS --> DOMAIN HOPPER --> DOMAIN + ARTIFACTS --> DOMAIN + NATIVE --> DOMAIN TESTS -.-> MAIN TESTS -.-> HOPPER + TESTS -.-> ARTIFACTS