comp-gate 0.1.0

package/README.md

@@ -0,0 +1,353 @@
+# testme
+
+Comprehension gate for desktop coding agents. **testme** blocks `git commit` (when enabled) and `git push` to protected branches until you pass a comprehension test describing what changed.
+
+Published on npm as [`comp-gate`](https://www.npmjs.com/package/comp-gate). The CLI command is `comp-gate` (alias: `testme`).
+
+## Quick start
+
+```bash
+npx comp-gate init
+```
+
+The setup wizard detects your desktop agent (Cursor, Claude Code, Windsurf), asks how many questions you want, how difficult they should be, whether to keep agent skills local-only in `.gitignore`, and whether to start with a blank `SUMMARY.md` or generate one from project metadata, then installs the integration.
+
+Non-interactive example:
+
+```bash
+npx comp-gate init --agent cursor --questions 3 --difficulty medium --local-only true --summary blank --yes
+```
+
+### Adopting an existing repository
+
+During `init`, the wizard asks how to set up `SUMMARY.md`:
+
+- **Blank (default)** — empty template; you fill in stack, layout, and conventions once. Best for large or monorepo codebases.
+- **Generate** — drafts `SUMMARY.md` from README, manifests, and top-level folders only (not a full codebase scan).
+
+On repos with **500+ tracked files**, the wizard recommends blank and warns that auto-generation is often shallow or misleading at that scale.
+
+- Large repos: prefer blank — a hand-written map at package/layer granularity beats a shallow auto-draft.
+- Staleness: generated summaries reflect init-time metadata and need manual upkeep.
+- Token efficiency: comp-gate reads `SUMMARY.md` for architecture questions; keep it short and accurate.
+
+See [adopting existing repos](https://github.com/ROrmand/comp-gate/blob/main/docs/adopting-existing-repos.md) for the full guide.
+
+```bash
+npx comp-gate init --summary blank    # default
+npx comp-gate init --summary generate # draft from README + manifests
+```
+
+### What gets installed
+
+**Committed (team-shared):**
+
+- `SUMMARY.md` — stable project map (blank template or generated from project metadata at init)
+- `PROMPTS.md` — session change log (resets after successful push to `main`)
+- `testme.config.json` — question count, difficulty, protected branches
+- `AGENTS.md` — portable workflow section (when selected)
+
+**Local only (gitignored — each developer runs `npx comp-gate init` after clone):**
+
+- `.testme/` — session state and hook scripts
+- `.cursor/skills/testme/`, `.cursor/skills/testing/`, `.claude/skills/testme/`, `.claude/skills/testing/`, `.windsurf/skills/testme/`, `.windsurf/skills/testing/` — agent skills
+- Agent hook configs (`.cursor/hooks.json`, `.claude/settings.json`, `.windsurf/hooks.json`) when testme-only
+
+**Always installed per machine:**
+
+- `.git/hooks/pre-commit` and `pre-push` — blocks commit/push in any terminal
+
+### Supported agents
+
+| Agent | Integration |
+|-------|-------------|
+| Cursor | `.cursor/hooks.json` + `/testme` and `/testing` skills |
+| Claude Code | `.claude/settings.json` PreToolUse hooks + skills |
+| Windsurf | `.windsurf/hooks.json` pre_run_command hooks + skills |
+| AGENTS.md | Portable workflow docs (fallback) |
+
+Git hooks are the universal safety net when agent shell hooks are unavailable (e.g. some Claude Desktop sessions).
+
+## Toggle gating with `/testing`
+
+Use `/testing` in chat (or `npx comp-gate testing`) to turn the comprehension gate on or off **locally** — state is stored in `.testme/config.json` (gitignored), so one developer can pause gating without changing team config.
+
+| Skill / command | Purpose |
+|-----------------|---------|
+| `/testing` | Toggle gate on/off (default) |
+| `npx comp-gate testing on` | Enable gating |
+| `npx comp-gate testing off` | Disable gating (commit/push no longer require `/testme`) |
+| `npx comp-gate testing status` | Show current state with status banner |
+| `/testme` | Run comprehension workflow (only when gate is on) |
+
+When the gate is **off**, hooks allow commit and push without verification. Re-enable before pushing to protected branches in team workflows.
+
+### Status line indicator
+
+For a persistent on/off indicator above the Cursor prompt, add this to `~/.cursor/cli-config.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "sh -c 'cd \"$PWD\" && .testme/hooks/statusline.sh'",
+    "padding": 2
+  }
+}
+```
+
+`npx comp-gate init` installs `.testme/hooks/statusline.sh`, which runs `npx comp-gate statusline`:
+
+- Gate on: `🟢 testme`
+- Gate off: `🔴 testme off`
+
+Running `/testing` also prints an in-chat banner:
+
+```
+┌─────────────────────────┐
+│  testme gate:  ON  🟢   │
+└─────────────────────────┘
+```
+
+## Workflow
+
+```mermaid
+flowchart TD
+    work[Make changes] --> prompts[Update PROMPTS.md]
+    prompts --> gen[npx comp-gate generate]
+    gen --> answer[Answer questions in chat]
+    answer --> write[Agent writes .testme/answers.json]
+    write --> verify[npx comp-gate verify]
+    verify -->|PASS| push[git push origin main]
+    verify -->|FAIL| fix[Fix answers or PROMPTS.md]
+    push --> reset[PROMPTS.md resets via hook]
+```
+
+### 1. Document changes in PROMPTS.md
+
+```markdown
+# Session Changes
+
+## src/auth.ts
+- Added validateToken middleware; checks JWT expiry before route handlers
+```
+
+Write bullets as you work — they become the answer rubric.
+
+### 2. Generate questions
+
+```bash
+npx comp-gate generate
+```
+
+Reads `SUMMARY.md`, `PROMPTS.md`, and git diff only. Produces 3–5 targeted questions in `.testme/session.json`.
+
+### 3. Answer questions (in chat)
+
+Run `/testme` in Cursor. The agent asks each question one at a time in chat — reply in plain messages. The agent writes `.testme/answers.json` from your replies before verifying.
+
+For each question, read only the files listed in that question's `files[]` array if you need to check your answer.
+
+### 4. Verify (semantic grading)
+
+The agent generates reference answers, asks you questions in chat, then grades your replies with an **accuracy score (0–100)** and **alignment** (`low` / `medium` / `high`) per question. Default pass threshold is **70%** accuracy (`passThreshold` in config).
+
+```bash
+npx comp-gate verify
+```
+
+On pass, `.testme/pass.json` is written.
+
+### 5. Push
+
+```bash
+git push origin main
+```
+
+After a successful push, `PROMPTS.md` resets automatically.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `comp-gate init` | Interactive setup wizard: detect agent, configure questions/difficulty, install hooks and skills |
+| `comp-gate init --agent all --yes` | Install all agent integrations without prompts |
+| `comp-gate init --questions 5 --difficulty hard --force` | Override question count and difficulty |
+| `comp-gate hook install-git` | Re-install git `pre-commit` / `pre-push` hooks only |
+| `comp-gate generate` | Generate questions from diff + md files |
+| `comp-gate generate --max-questions 3` | One-off question count override |
+| `comp-gate generate --category runtime,testing` | One-off category filter |
+| `comp-gate detect` | Show auto-detected domain categories |
+| `comp-gate config init` | Create `testme.config.json` with detected defaults |
+| `comp-gate config show` | Print merged config (repo + local overrides) |
+| `comp-gate verify` | Score answers in `.testme/answers.json` |
+| `comp-gate status` | Check if current pass is valid and whether gate is enabled |
+| `comp-gate testing` | Toggle comprehension gate on/off (local) |
+| `comp-gate testing on` / `off` / `status` | Explicitly enable, disable, or show gate state |
+| `comp-gate statusline` | One-line gate status for Cursor status line |
+| `comp-gate reset` | Clear `.testme/` session state |
+
+## Customization
+
+### Protected branches and commit gating
+
+Configure in `testme.config.json`:
+
+```json
+{
+  "protectedBranches": ["main"],
+  "gateCommits": true,
+  "autoProtectCurrentBranch": true
+}
+```
+
+- `protectedBranches` — always-protected branches (e.g. `main`)
+- `autoProtectCurrentBranch` — also gate pushes to whatever branch you have checked out (default `true`)
+- `gateCommits` — when `true`, `git commit` is blocked until `/testme` passes
+
+Blocked push message: `You must run the /testme skill before pushing to 'main'.`
+
+**Terminal blocking:** `npx comp-gate init` installs native git hooks into `.git/hooks/`. The Cursor integrated terminal does **not** run Cursor `beforeShellExecution` hooks — git hooks cover that gap.
+
+### Question count and difficulty
+
+Set during `comp-gate init` or in `testme.config.json`:
+
+| Difficulty | Pass threshold | Alignment required | Categories |
+|------------|----------------|--------------------|------------|
+| easy | 60% | low+ | changeRationale, symbols |
+| medium | 70% | medium+ | balanced + auto-detect |
+| hard | 85% | high only | + architecture, runtime, security |
+
+```json
+{
+  "questions": { "min": 2, "max": 3 },
+  "difficulty": "medium",
+  "passThreshold": 70,
+  "minAlignment": "medium"
+}
+```
+
+### Question count (generate)
+
+Configure in `testme.config.json`:
+
+```json
+{
+  "questions": { "min": 2, "max": 5 }
+}
+```
+
+Local override in `.testme/config.json` (gitignored via `.testme/`):
+
+```json
+{ "questions": { "max": 3 } }
+```
+
+### Category checkboxes
+
+Each category is a boolean in `categories`. Core categories work everywhere; domain categories are auto-suggested when relevant.
+
+| Category | Focus |
+|----------|-------|
+| `changeRationale` | What changed per file and why |
+| `symbols` | What added/changed symbols do |
+| `architecture` | Fit with SUMMARY.md structure |
+| `runtime` | Run, test, deploy impact |
+| `dataStructures` | Algorithms and data structures used |
+| `dependencies` | Package/manifest changes |
+| `testing` | Test coverage and assertions |
+| `errorHandling` | Errors and edge cases |
+| `apiContracts` | API/schema/interface changes |
+| `security` | Auth, validation, secrets |
+| `performance` | Caching, complexity, bottlenecks |
+| `database` | Schema, queries, migrations |
+| `machineLearning` | Training, inference, metrics |
+| `cybersecurity` | Threat model, mitigations |
+| `frontend` | UI components and state |
+| `backend` | Routes, middleware, services |
+| `devops` | CI/CD, containers, infra |
+| `mobile` | Platform-specific behavior |
+| `dataEngineering` | Pipelines, ETL, lineage |
+
+### Project-aware detection
+
+```bash
+npx comp-gate detect
+```
+
+Signals: `SUMMARY.md` `## Domain` section, `package.json`/`pyproject.toml` deps, diff file paths.
+
+**ML example** — `comp-gate detect` enables `machineLearning`; disable `cybersecurity` in config.
+
+**Security example** — enable `cybersecurity` and `security`; leave `machineLearning` false.
+
+```json
+{
+  "autoDetect": true,
+  "categories": {
+    "machineLearning": true,
+    "dataStructures": true,
+    "cybersecurity": false
+  }
+}
+```
+
+Add to `SUMMARY.md`:
+
+```markdown
+## Domain
+
+- Primary: machine learning
+- Focus areas: model training, evaluation metrics, inference API
+```
+
+## Why PROMPTS.md matters
+
+`PROMPTS.md` is the cheap answer key. Agents document changes as they work, so verification doesn't require re-reading full diffs or scanning the codebase. Better bullets → better rubrics → easier pass.
+
+## Token efficiency
+
+- No full-repo scans — only git diff metadata + two md files
+- Configurable question count and categories via `testme.config.json`
+- Semantic grading by default (agent compares your answers to reference answers)
+- Targeted file reads via `files[]` pointers in session
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| Push blocked | Run `/testme` or `npx comp-gate generate` → answer → `verify` |
+| Commit blocked | `gateCommits` is on — run `/testme` before committing |
+| Session stale | Re-run `generate` after new edits |
+| Missing terms | Add clearer bullets to `PROMPTS.md` |
+| Pass invalid | `npx comp-gate status` — diff changed since verify |
+| Gate disabled | Run `/testing` or `npx comp-gate testing on` to re-enable |
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+### Publishing
+
+```bash
+npm login
+npm publish
+```
+
+The package name on npm is `comp-gate` (the unscoped name `testme` is taken by an unrelated package). After publishing, users install with:
+
+```bash
+npx comp-gate init
+```
+
+## Limitations (v1)
+
+- Symbol extraction uses regex (TS/JS/Python/Go patterns) — not a full AST parser
+- Protected branches configurable via `protectedBranches` in `testme.config.json` (`--branch` flag to override)
+- Optional commit gating via `gateCommits: true` in `testme.config.json`
+- Verification is semantic by default (`grading: "semantic"`); legacy keyword mode available

package/dist/agents/agents-md.d.ts

@@ -0,0 +1,2 @@
+export declare function installAgentsMd(cwd: string, created: string[]): void;
+//# sourceMappingURL=agents-md.d.ts.map

package/dist/agents/agents-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-md.d.ts","sourceRoot":"","sources":["../../src/agents/agents-md.ts"],"names":[],"mappings":"AAOA,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAqBpE"}

package/dist/agents/agents-md.js

@@ -0,0 +1,25 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { agentTemplatesDir } from "./shared.js";
+const SECTION_START = "<!-- testme:start -->";
+const SECTION_END = "<!-- testme:end -->";
+export function installAgentsMd(cwd, created) {
+    const sectionPath = path.join(agentTemplatesDir("agents-md"), "section.md");
+    const section = readFileSync(sectionPath, "utf8").trim();
+    const wrapped = `${SECTION_START}\n${section}\n${SECTION_END}`;
+    const targetPath = path.join(cwd, "AGENTS.md");
+    const existing = existsSync(targetPath) ? readFileSync(targetPath, "utf8") : "";
+    if (existing.includes(SECTION_START) && existing.includes(SECTION_END)) {
+        const start = existing.indexOf(SECTION_START);
+        const end = existing.indexOf(SECTION_END) + SECTION_END.length;
+        const updated = `${existing.slice(0, start)}${wrapped}${existing.slice(end)}`;
+        writeFileSync(targetPath, updated.endsWith("\n") ? updated : `${updated}\n`, "utf8");
+        created.push("AGENTS.md (testme section updated)");
+        return;
+    }
+    const header = existing.length > 0 ? "\n\n" : "# Agent Instructions\n\n";
+    const content = existing.length > 0 ? `${existing.replace(/\s*$/, "")}${header}${wrapped}\n` : `${header}${wrapped}\n`;
+    writeFileSync(targetPath, content, "utf8");
+    created.push("AGENTS.md (testme section added)");
+}
+//# sourceMappingURL=agents-md.js.map

package/dist/agents/agents-md.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-md.js","sourceRoot":"","sources":["../../src/agents/agents-md.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,aAAa,GAAG,uBAAuB,CAAC;AAC9C,MAAM,WAAW,GAAG,qBAAqB,CAAC;AAE1C,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,OAAiB;IAC5D,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,WAAW,CAAC,EAAE,YAAY,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAG,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IACzD,MAAM,OAAO,GAAG,GAAG,aAAa,KAAK,OAAO,KAAK,WAAW,EAAE,CAAC;IAE/D,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAEhF,IAAI,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QACvE,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAC9C,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC;QAC/D,MAAM,OAAO,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9E,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,EAAE,MAAM,CAAC,CAAC;QACrF,OAAO,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;QACnD,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,0BAA0B,CAAC;IACzE,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,MAAM,GAAG,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,OAAO,IAAI,CAAC;IACvH,aAAa,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC3C,OAAO,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;AACnD,CAAC"}

package/dist/agents/claude.d.ts

@@ -0,0 +1,2 @@
+export declare function installClaude(cwd: string, created: string[]): void;
+//# sourceMappingURL=claude.d.ts.map

package/dist/agents/claude.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"AAqCA,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAoClE"}

package/dist/agents/claude.js

@@ -0,0 +1,45 @@
+import path from "node:path";
+import { agentTemplatesDir, copySkill, readJson, writeJson } from "./shared.js";
+function mergeHookCommands(existing, incoming) {
+    const merged = [...existing];
+    const seen = new Set(existing.map((hook) => hook.command));
+    for (const hook of incoming) {
+        if (!seen.has(hook.command)) {
+            merged.push(hook);
+            seen.add(hook.command);
+        }
+    }
+    return merged;
+}
+export function installClaude(cwd, created) {
+    const fragmentPath = path.join(agentTemplatesDir("claude"), "settings.fragment.json");
+    const targetPath = path.join(cwd, ".claude", "settings.json");
+    const fragment = readJson(fragmentPath);
+    if (!fragment?.hooks?.PreToolUse) {
+        throw new Error("Missing Claude settings template.");
+    }
+    const existing = readJson(targetPath) ?? { hooks: {} };
+    const preToolUse = [...(existing.hooks?.PreToolUse ?? [])];
+    for (const incoming of fragment.hooks.PreToolUse) {
+        const idx = preToolUse.findIndex((item) => item.matcher === incoming.matcher);
+        if (idx < 0) {
+            preToolUse.push(incoming);
+            continue;
+        }
+        preToolUse[idx] = {
+            ...preToolUse[idx],
+            hooks: mergeHookCommands(preToolUse[idx].hooks, incoming.hooks),
+        };
+    }
+    const merged = {
+        ...existing,
+        hooks: {
+            ...existing.hooks,
+            PreToolUse: preToolUse,
+        },
+    };
+    writeJson(targetPath, merged);
+    created.push(".claude/settings.json (merged)");
+    copySkill("claude", cwd, created);
+}
+//# sourceMappingURL=claude.js.map

package/dist/agents/claude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAmBhF,SAAS,iBAAiB,CACxB,QAA6B,EAC7B,QAA6B;IAE7B,MAAM,MAAM,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;IAC7B,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAE3D,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,OAAiB;IAC1D,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,EAAE,wBAAwB,CAAC,CAAC;IACtF,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,eAAe,CAAC,CAAC;IAC9D,MAAM,QAAQ,GAAG,QAAQ,CAAiB,YAAY,CAAC,CAAC;IAExD,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,CAAC;IAED,MAAM,QAAQ,GAAG,QAAQ,CAAiB,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IACvE,MAAM,UAAU,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,IAAI,EAAE,CAAC,CAAC,CAAC;IAE3D,KAAK,MAAM,QAAQ,IAAI,QAAQ,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;QACjD,MAAM,GAAG,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,KAAK,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC9E,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YACZ,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC1B,SAAS;QACX,CAAC;QAED,UAAU,CAAC,GAAG,CAAC,GAAG;YAChB,GAAG,UAAU,CAAC,GAAG,CAAC;YAClB,KAAK,EAAE,iBAAiB,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC;SAChE,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAmB;QAC7B,GAAG,QAAQ;QACX,KAAK,EAAE;YACL,GAAG,QAAQ,CAAC,KAAK;YACjB,UAAU,EAAE,UAAU;SACvB;KACF,CAAC;IAEF,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC9B,OAAO,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;IAC/C,SAAS,CAAC,QAAQ,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;AACpC,CAAC"}

package/dist/agents/cursor.d.ts

@@ -0,0 +1,2 @@
+export declare function installCursor(cwd: string, created: string[]): void;
+//# sourceMappingURL=cursor.d.ts.map

package/dist/agents/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/agents/cursor.ts"],"names":[],"mappings":"AAcA,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAiClE"}

package/dist/agents/cursor.js

@@ -0,0 +1,28 @@
+import path from "node:path";
+import { agentTemplatesDir, copySkill, mergeJsonArraysByKey, readJson, writeJson, } from "./shared.js";
+export function installCursor(cwd, created) {
+    const templatePath = path.join(agentTemplatesDir("cursor"), "hooks.json");
+    const targetPath = path.join(cwd, ".cursor", "hooks.json");
+    const template = readJson(templatePath);
+    if (!template) {
+        throw new Error("Missing Cursor hooks template.");
+    }
+    const existing = readJson(targetPath);
+    if (!existing) {
+        writeJson(targetPath, template);
+        created.push(".cursor/hooks.json");
+    }
+    else {
+        const merged = {
+            version: existing.version ?? template.version ?? 1,
+            hooks: { ...existing.hooks },
+        };
+        for (const [event, hooks] of Object.entries(template.hooks)) {
+            merged.hooks[event] = mergeJsonArraysByKey(merged.hooks[event] ?? [], hooks, "command");
+        }
+        writeJson(targetPath, merged);
+        created.push(".cursor/hooks.json (merged)");
+    }
+    copySkill("cursor", cwd, created);
+}
+//# sourceMappingURL=cursor.js.map

package/dist/agents/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../src/agents/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EACL,iBAAiB,EACjB,SAAS,EACT,oBAAoB,EACpB,QAAQ,EACR,SAAS,GACV,MAAM,aAAa,CAAC;AAOrB,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,OAAiB;IAC1D,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC,CAAC;IAC1E,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAG,QAAQ,CAAoB,YAAY,CAAC,CAAC;IAE3D,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,MAAM,QAAQ,GAAG,QAAQ,CAAoB,UAAU,CAAC,CAAC;IAEzD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,SAAS,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;QAChC,OAAO,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IACrC,CAAC;SAAM,CAAC;QACN,MAAM,MAAM,GAAsB;YAChC,OAAO,EAAE,QAAQ,CAAC,OAAO,IAAI,QAAQ,CAAC,OAAO,IAAI,CAAC;YAClD,KAAK,EAAE,EAAE,GAAG,QAAQ,CAAC,KAAK,EAAE;SAC7B,CAAC;QAEF,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5D,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,oBAAoB,CACxC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,EACzB,KAAK,EACL,SAAS,CACV,CAAC;QACJ,CAAC;QAED,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAC9B,OAAO,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;IAC9C,CAAC;IAED,SAAS,CAAC,QAAQ,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;AACpC,CAAC"}

package/dist/agents/detect.d.ts

@@ -0,0 +1,4 @@
+import type { AgentDetectionResult, AgentId } from "./types.js";
+export declare function detectAgents(cwd: string, env?: NodeJS.ProcessEnv): AgentDetectionResult;
+export declare function parseAgentList(value: string): AgentId[];
+//# sourceMappingURL=detect.d.ts.map

package/dist/agents/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../src/agents/detect.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAe,MAAM,YAAY,CAAC;AA8B7E,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,oBAAoB,CAsEpG;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,CAavD"}

package/dist/agents/detect.js

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+function addSignal(signals, signal) {
+    const existing = signals.find((s) => s.id === signal.id);
+    if (!existing || (existing.confidence === "medium" && signal.confidence === "high")) {
+        if (existing) {
+            signals.splice(signals.indexOf(existing), 1);
+        }
+        signals.push(signal);
+    }
+}
+function hasRepoSignal(cwd, relativePath) {
+    return existsSync(path.join(cwd, relativePath));
+}
+function agentsMdMentionsTestme(cwd) {
+    const agentsPath = path.join(cwd, "AGENTS.md");
+    if (!existsSync(agentsPath)) {
+        return false;
+    }
+    const content = readFileSync(agentsPath, "utf8").toLowerCase();
+    return (content.includes("testme") ||
+        content.includes("comp-gate") ||
+        content.includes("npx testme") ||
+        content.includes("npx comp-gate"));
+}
+export function detectAgents(cwd, env = process.env) {
+    const signals = [];
+    if (hasRepoSignal(cwd, ".cursor/hooks.json") ||
+        hasRepoSignal(cwd, ".cursor/skills") ||
+        hasRepoSignal(cwd, ".cursor")) {
+        addSignal(signals, {
+            id: "cursor",
+            confidence: hasRepoSignal(cwd, ".cursor/hooks.json") ? "high" : "medium",
+            reason: ".cursor/ configuration found in repo",
+        });
+    }
+    if (hasRepoSignal(cwd, ".claude/settings.json") ||
+        hasRepoSignal(cwd, ".claude/skills") ||
+        hasRepoSignal(cwd, ".claude")) {
+        addSignal(signals, {
+            id: "claude",
+            confidence: hasRepoSignal(cwd, ".claude/settings.json") ? "high" : "medium",
+            reason: ".claude/ configuration found in repo",
+        });
+    }
+    if (hasRepoSignal(cwd, ".windsurf/hooks.json") || hasRepoSignal(cwd, ".windsurf")) {
+        addSignal(signals, {
+            id: "windsurf",
+            confidence: hasRepoSignal(cwd, ".windsurf/hooks.json") ? "high" : "medium",
+            reason: ".windsurf/ configuration found in repo",
+        });
+    }
+    if (agentsMdMentionsTestme(cwd)) {
+        addSignal(signals, {
+            id: "agents-md",
+            confidence: "high",
+            reason: "AGENTS.md already references testme",
+        });
+    }
+    if (env.CURSOR_TRACE_ID || env.CURSOR_SESSION_ID) {
+        addSignal(signals, {
+            id: "cursor",
+            confidence: "medium",
+            reason: "Cursor environment detected",
+        });
+    }
+    if (env.CLAUDE_CODE || env.CLAUDE_SESSION) {
+        addSignal(signals, {
+            id: "claude",
+            confidence: "medium",
+            reason: "Claude Code environment detected",
+        });
+    }
+    const suggested = [...new Set(signals.map((s) => s.id))];
+    const highConfidence = new Set(signals.filter((s) => s.confidence === "high").map((s) => s.id));
+    const ambiguous = suggested.length !== 1 && !(suggested.length === 0 && highConfidence.size === 0);
+    return {
+        signals,
+        suggested: suggested.length > 0 ? suggested : [],
+        ambiguous: suggested.length === 0 || suggested.length > 1,
+    };
+}
+export function parseAgentList(value) {
+    if (value === "all") {
+        return ["cursor", "claude", "windsurf", "agents-md"];
+    }
+    const ids = value.split(",").map((part) => part.trim());
+    const valid = ["cursor", "claude", "windsurf", "agents-md"];
+    for (const id of ids) {
+        if (!valid.includes(id)) {
+            throw new Error(`Unknown agent: ${id}. Use cursor, claude, windsurf, agents-md, or all.`);
+        }
+    }
+    return ids;
+}
+//# sourceMappingURL=detect.js.map

package/dist/agents/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../../src/agents/detect.ts"],"names":[],"mappings":"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"}

package/dist/agents/shared.d.ts

@@ -0,0 +1,9 @@
+export declare function copyIfMissing(source: string, target: string): boolean;
+export declare function copyAlways(source: string, target: string): void;
+export declare function agentTemplatesDir(agent: string): string;
+export declare function mergeJsonArraysByKey<T extends Record<string, unknown>>(existing: T[], incoming: T[], key: keyof T): T[];
+export declare function writeJson(filePath: string, value: unknown): void;
+export declare function readJson<T>(filePath: string): T | null;
+export declare function copySkill(agent: string, cwd: string, created: string[]): void;
+export declare function chmodScripts(dir: string): void;
+//# sourceMappingURL=shared.d.ts.map

package/dist/agents/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/agents/shared.ts"],"names":[],"mappings":"AAIA,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAQrE;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAG/D;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpE,QAAQ,EAAE,CAAC,EAAE,EACb,QAAQ,EAAE,CAAC,EAAE,EACb,GAAG,EAAE,MAAM,CAAC,GACX,CAAC,EAAE,CAaL;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAGhE;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAKtD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAoC7E;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAU9C"}