clud-bug 0.7.0-rc.11 → 0.7.0-rc.13

package/dist/cli/hooks.d.ts

@@ -0,0 +1,40 @@
+/** Stable marker embedded in our hook's prompt so re-runs replace it in place. */
+export declare const CLUD_BUG_HOOK_MARKER = "clud-bug-local-review";
+/**
+ * Build the `prompt` of the Claude Code `type: agent` commit-review hook,
+ * pinned to the clud-bug VERSION that scaffolded it. Pinning matters: a bare
+ * `npx clud-bug` resolves to the `latest` dist-tag, which can predate the
+ * `review-prompt` verb (e.g. while v0.7 is prerelease on `next`); `@${version}`
+ * guarantees the verb exists. `clud-bug update` refreshes the pin in place.
+ *
+ * Rather than baking a static recipe (which would drift from the repo's
+ * skills/config), it tells the subagent to run `clud-bug review-prompt` — the
+ * engine-driven verb that emits a recipe tailored to THIS repo's resolved plan
+ * — and follow it. The recipe is generated fresh at commit time, always current.
+ */
+export declare function buildCommitReviewPrompt(version: string): string;
+/** One Claude Code hook entry: a tool matcher plus its hook list. */
+export interface HookMatcherEntry {
+    matcher?: string;
+    hooks: Array<Record<string, unknown>>;
+}
+/** Minimal shape of the `.claude/settings.json` we read + merge into. */
+export interface ClaudeSettings {
+    hooks?: Record<string, HookMatcherEntry[]>;
+    [key: string]: unknown;
+}
+/**
+ * Builds the PostToolUse entry that spawns the commit-review subagent: a native
+ * `type: agent` hook that is backgrounded (`async`), surfaces findings
+ * (`asyncRewake`), and fires only on `git commit` (`if`).
+ */
+export declare function buildLocalReviewHook(recipe: string): HookMatcherEntry;
+/**
+ * Merges the clud-bug commit-review hook into an existing `.claude/settings.json`
+ * object. **Idempotent** (replaces any prior clud-bug entry rather than
+ * duplicating) and **non-clobbering** (preserves every other top-level key,
+ * every other event, and every other hook). Tolerates a missing/malformed
+ * `existing` value.
+ */
+export declare function mergeLocalReviewHook(existing: unknown, recipe: string): ClaudeSettings;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/cli/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/cli/hooks.ts"],"names":[],"mappings":"AAcA,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,0BAA0B,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAkB/D;AAED,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvC;AAED,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAC3C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAcrE;AAUD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CAwBtF"}

package/dist/cli/hooks.js

@@ -0,0 +1,105 @@
+// Wave 6b — Claude Code `type: agent` commit-review hook scaffolding.
+//
+// `clud-bug init --with-hooks` writes a native Claude Code hook that, on every
+// `git commit` the agent makes, spawns a clud-bug review SUBAGENT in the same
+// session — so it runs on the session's subscription (no API key), in the
+// background (the commit never blocks), and surfaces findings back to the agent.
+//
+// The model (see the Wave 6b plan): clud-bug supplies the *recipe* (the
+// agent-hook `prompt`); Claude Code runs it as a subagent. This is the dynamic,
+// always-on counterpart to the `/clud-bug-review` slash command.
+//
+// `type: agent` hooks are documented as experimental; the same outcome is
+// reachable via a `type: command` hook + `additionalContext` if the API shifts.
+/** Stable marker embedded in our hook's prompt so re-runs replace it in place. */
+export const CLUD_BUG_HOOK_MARKER = 'clud-bug-local-review';
+/**
+ * Build the `prompt` of the Claude Code `type: agent` commit-review hook,
+ * pinned to the clud-bug VERSION that scaffolded it. Pinning matters: a bare
+ * `npx clud-bug` resolves to the `latest` dist-tag, which can predate the
+ * `review-prompt` verb (e.g. while v0.7 is prerelease on `next`); `@${version}`
+ * guarantees the verb exists. `clud-bug update` refreshes the pin in place.
+ *
+ * Rather than baking a static recipe (which would drift from the repo's
+ * skills/config), it tells the subagent to run `clud-bug review-prompt` — the
+ * engine-driven verb that emits a recipe tailored to THIS repo's resolved plan
+ * — and follow it. The recipe is generated fresh at commit time, always current.
+ */
+export function buildCommitReviewPrompt(version) {
+    return `<!-- ${CLUD_BUG_HOOK_MARKER} v1 -->
+You are clud-bug's local commit review, running as a background subagent on this
+session's own subscription (no extra auth — you have git, gh, and file access).
+
+Step 1 — get your review recipe from clud-bug's engine:
+
+    npx clud-bug@${version} review-prompt --trigger commit
+
+That prints a structured review recipe tailored to THIS repo's skills + config (a
+fast single pass for a commit). If that command isn't available, run the repo's
+installed clud-bug CLI's \`review-prompt --trigger commit\` instead.
+
+Step 2 — follow that recipe exactly: review the commit that was just made against
+the skills it names, and surface any findings back into the session so they can be
+fixed. A clean commit needs only a one-line note.
+
+Keep it tight — this is the commit-time safety net; the deeper review runs at PR time.`;
+}
+/**
+ * Builds the PostToolUse entry that spawns the commit-review subagent: a native
+ * `type: agent` hook that is backgrounded (`async`), surfaces findings
+ * (`asyncRewake`), and fires only on `git commit` (`if`).
+ */
+export function buildLocalReviewHook(recipe) {
+    return {
+        matcher: 'Bash',
+        hooks: [
+            {
+                type: 'agent',
+                if: 'Bash(git commit *)',
+                async: true,
+                asyncRewake: true,
+                timeout: 180,
+                prompt: recipe,
+            },
+        ],
+    };
+}
+function isOurHook(h) {
+    return typeof h?.['prompt'] === 'string' && h['prompt'].includes(CLUD_BUG_HOOK_MARKER);
+}
+function isCludBugReviewEntry(entry) {
+    return !!entry && Array.isArray(entry.hooks) && entry.hooks.some(isOurHook);
+}
+/**
+ * Merges the clud-bug commit-review hook into an existing `.claude/settings.json`
+ * object. **Idempotent** (replaces any prior clud-bug entry rather than
+ * duplicating) and **non-clobbering** (preserves every other top-level key,
+ * every other event, and every other hook). Tolerates a missing/malformed
+ * `existing` value.
+ */
+export function mergeLocalReviewHook(existing, recipe) {
+    const base = existing && typeof existing === 'object' ? { ...existing } : {};
+    const hooks = { ...(base.hooks ?? {}) };
+    const priorPost = Array.isArray(hooks.PostToolUse) ? hooks.PostToolUse : [];
+    // Preserve every non-clud-bug hook — including any the user co-located INSIDE
+    // our own matcher entry: drop only the hook(s) carrying our marker, never the
+    // whole entry.
+    const ours = buildLocalReviewHook(recipe);
+    const otherEntries = [];
+    const coLocatedUserHooks = [];
+    for (const entry of priorPost) {
+        if (isCludBugReviewEntry(entry)) {
+            for (const h of entry.hooks)
+                if (!isOurHook(h))
+                    coLocatedUserHooks.push(h);
+        }
+        else {
+            otherEntries.push(entry);
+        }
+    }
+    const ourEntry = coLocatedUserHooks.length > 0 ? { ...ours, hooks: [...coLocatedUserHooks, ...ours.hooks] } : ours;
+    hooks.PostToolUse = [...otherEntries, ourEntry];
+    base.hooks = hooks;
+    return base;
+}
+//# sourceMappingURL=hooks.js.map

package/dist/cli/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/cli/hooks.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,0EAA0E;AAC1E,iFAAiF;AACjF,EAAE;AACF,wEAAwE;AACxE,gFAAgF;AAChF,iEAAiE;AACjE,EAAE;AACF,0EAA0E;AAC1E,gFAAgF;AAEhF,kFAAkF;AAClF,MAAM,CAAC,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,OAAO,QAAQ,oBAAoB;;;;;;mBAMlB,OAAO;;;;;;;;;;uFAU6D,CAAC;AACxF,CAAC;AAcD;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,OAAO;QACL,OAAO,EAAE,MAAM;QACf,KAAK,EAAE;YACL;gBACE,IAAI,EAAE,OAAO;gBACb,EAAE,EAAE,oBAAoB;gBACxB,KAAK,EAAE,IAAI;gBACX,WAAW,EAAE,IAAI;gBACjB,OAAO,EAAE,GAAG;gBACZ,MAAM,EAAE,MAAM;aACf;SACF;KACF,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,CAAsC;IACvD,OAAO,OAAO,CAAC,EAAE,CAAC,QAAQ,CAAC,KAAK,QAAQ,IAAK,CAAC,CAAC,QAAQ,CAAY,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC;AACrG,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAmC;IAC/D,OAAO,CAAC,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAiB,EAAE,MAAc;IACpE,MAAM,IAAI,GACR,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAI,QAA2B,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACtF,MAAM,KAAK,GAAuC,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;IAC5E,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;IAE5E,8EAA8E;IAC9E,8EAA8E;IAC9E,eAAe;IACf,MAAM,IAAI,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,YAAY,GAAuB,EAAE,CAAC;IAC5C,MAAM,kBAAkB,GAAmC,EAAE,CAAC;IAC9D,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,CAAC;QAC9B,IAAI,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;YAChC,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK;gBAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;oBAAE,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC7E,CAAC;aAAM,CAAC;YACN,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GACZ,kBAAkB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,CAAC,GAAG,kBAAkB,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACpG,KAAK,CAAC,WAAW,GAAG,CAAC,GAAG,YAAY,EAAE,QAAQ,CAAC,CAAC;IAChD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACnB,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAmOA,iBAAe,IAAI,kBA4BlB;AA45DD,OAAO,EAAE,IAAI,EAAE,CAAC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAmPA,iBAAe,IAAI,kBA6BlB;AAm8DD,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/dist/cli/main.js

@@ -26,6 +26,7 @@ import { writeSkills, writeSkill, loadBaseline, readManifest, writeManifest, rem
 import { computeAuditFileSet } from './audit.js';
 import { renderAuditHeader } from '../core/audit.js';
 import { runUpdate } from './update.js';
+import { runReviewPrompt } from './review-prompt.js';
 import { getPendingWorkflowEdits, makeBranchName, git as gitCmd } from './edit-workflow.js';
 import { applyToRepo as applyAgentDocs } from './agents-md.js';
 import { detectRepo, detectDefaultBranch, getProtectionState, enableConversationResolution } from './branch-protection.js';
@@ -59,6 +60,7 @@ function parseArgs(argv) {
         // .claude/commands/clud-bug-review.md so `/clud-bug-review` works in a
         // Claude Code session (reviews the current PR with the session's tokens).
         withLocalReview: false,
+        withHooks: false,
         // v0.7.0-rc.4: `clud-bug configure-github` flags.
         // --dry-run prints the diff but skips PATCH; --branch overrides "main".
         dryRun: false,
@@ -106,10 +108,16 @@ function parseArgs(argv) {
             args.withSkdd = true;
         else if (a === '--with-local-review')
             args.withLocalReview = true;
+        else if (a === '--with-hooks')
+            args.withHooks = true;
         else if (a === '--dry-run')
             args.dryRun = true;
         else if (a === '--branch')
             args.branch = argv[++i];
+        else if (a === '--trigger')
+            args.trigger = argv[++i];
+        else if (a === '--diff-size')
+            args.diffSizeBytes = Number(argv[++i]);
         else
             args._.push(a);
     }
@@ -200,6 +208,11 @@ Commands:
                         Required env vars: GH_TOKEN, ANTHROPIC_API_KEY,
                         REPO ("owner/name"), PR_NUMBER. Output: JSON
                         \`{actions, verifierCallCount, shouldRequestChanges}\`.
+  review-prompt         Emit the local-review recipe — the structured prompt a
+                        Claude Code agent/hook runs to review the current diff on
+                        the session's own subscription. Plans via the shared
+                        engine: --trigger commit (default) → a fast single pass;
+                        push/pr → the full multi-pass plan. Prints to stdout.
 
 Options:
   --offline             Skip skills.sh; pin only the bundled baseline specimens.
@@ -209,6 +222,11 @@ Options:
                         \`/clud-bug-review\` works in a Claude Code session —
                         reviews the current branch's PR using that session's
                         own tokens (no hosted App, no extra auth).
+  --with-hooks          (init) Also scaffold a native Claude Code \`type: agent\`
+                        commit-review hook into .claude/settings.json — on every
+                        \`git commit\` the agent makes, a backgrounded clud-bug
+                        review subagent runs on the session's subscription.
+                        Implies --with-local-review. Off by default.
   --quiet,-q            Token-frugal mode for agent invocations. Suppresses
                         progress chatter; emits exactly one final
                         \`ok <key-value>\` summary line per command. Errors
@@ -221,6 +239,7 @@ Options:
   --dry-run             Print the canonical-v1 diff without PATCH-ing
                         (configure-github only).
   --branch <name>       Target branch for configure-github (default: main).
+  --trigger <ctx>       review-prompt context: commit (default) | push | pr.
   --repo <owner/name>   Restrict \`usage\` to a single repo. Default: all repos
                         with clud-bug-review.yml in the gh user's auth scope.
   --pr <N>              Restrict \`usage\` to a single PR.
@@ -268,6 +287,7 @@ async function main() {
         case 'select-review-event': return runSelectReviewEvent(args);
         case 'post-inline-threads': return runPostInlineThreads(args);
         case 'resolve-threads': return runResolveThreads(args);
+        case 'review-prompt': return runReviewPrompt(args);
         default:
             process.stderr.write(`Unknown command: ${cmd || '(none)'}\n\n${HELP}`);
             process.exit(2);
@@ -1147,6 +1167,11 @@ async function runInit(args) {
     // Claude Code session — the agent reviews the current branch's open PR using
     // THAT session's own tokens (Max or API), no hosted App or new auth required.
     // `.claude/` is already in the --commit add-list below, so it's staged too.
+    // `--with-hooks` implies `--with-local-review` — the auto hook and the manual
+    // `/clud-bug-review` command are complementary (the hook auto-runs the engine
+    // recipe on each commit; the command runs it on demand against the PR).
+    if (args.withHooks)
+        args.withLocalReview = true;
     if (args.withLocalReview) {
         const commandPath = join(cwd, '.claude', 'commands', 'clud-bug-review.md');
         await mkdir(dirname(commandPath), { recursive: true });
@@ -1154,6 +1179,42 @@ async function runInit(args) {
         await writeFile(commandPath, commandContent);
         log(`    wrote ${rel(cwd, commandPath)}`);
     }
+    // v0.7.0 (Wave 6b): optional native commit-review hook. Merges a Claude Code
+    // `type: agent` PostToolUse hook into `.claude/settings.json` (preserving any
+    // existing settings + hooks) that, on every `git commit` the agent makes,
+    // spawns a clud-bug review subagent on the session's subscription, in the
+    // background — the hook's prompt runs `clud-bug review-prompt` and follows it.
+    if (args.withHooks) {
+        const { mergeLocalReviewHook, buildCommitReviewPrompt } = await import('./hooks.js');
+        const hookPrompt = buildCommitReviewPrompt(await readPkgVersion());
+        const settingsPath = join(cwd, '.claude', 'settings.json');
+        await mkdir(dirname(settingsPath), { recursive: true });
+        // Read-then-parse so we can tell "no file yet" (fresh merge) from "file
+        // exists but is invalid JSON" (leave it ALONE — never clobber user content).
+        let raw;
+        try {
+            raw = await readFile(settingsPath, 'utf8');
+        }
+        catch {
+            raw = undefined; // no settings.json yet → fresh
+        }
+        let existing;
+        let proceed = true;
+        if (raw !== undefined) {
+            try {
+                existing = JSON.parse(raw);
+            }
+            catch {
+                proceed = false;
+                log(`    skipped ${rel(cwd, settingsPath)} (existing file is not valid JSON; left untouched)`);
+            }
+        }
+        if (proceed) {
+            const merged = mergeLocalReviewHook(existing, hookPrompt);
+            await writeFile(settingsPath, JSON.stringify(merged, null, 2) + '\n');
+            log(`    wrote ${rel(cwd, settingsPath)} (commit-review hook)`);
+        }
+    }
     // Stamp the manifest. Sets strictMode: true ONLY on fresh installs —
     // a manifest that's never been touched by clud-bug init/update has no
     // lastUpdate field. Existing v0.3.x advisory installs (where strictMode