clud-bug 0.7.0-rc.2 → 0.7.0-rc.21

package/src/cli/configure-github.ts

@@ -0,0 +1,329 @@
+// `clud-bug configure-github` CLI command — applies the SPEC §7 canonical
+// branch protection ruleset to a target repo.
+//
+// External users installing the App expect "best practice branch protection"
+// applied automatically. This command lets them opt in offline + dry-run
+// safely BEFORE the App's auto-setup runs server-side. Same core logic
+// powers both paths (the App imports `applyCanonicalRuleset` from
+// clud-bug/core; this CLI passes a `gh api`-wrapping adapter so users
+// don't need `@octokit/rest` on their machine).
+//
+// Usage:
+//
+//   clud-bug configure-github <owner>/<repo>
+//   clud-bug configure-github <owner>/<repo> --dry-run
+//   clud-bug configure-github <owner>/<repo> --branch develop
+//
+// Auth ladder:
+//
+//   1. `GITHUB_TOKEN` env var (CI-friendly, no `gh` install required)
+//   2. `gh auth token` (developer workstation default)
+//
+// If neither produces a token, exits 1 with a recovery message.
+
+import { spawn, spawnSync } from 'node:child_process';
+import {
+  applyCanonicalRuleset,
+  loadCanonicalV1,
+  type OctokitLike,
+  type ApplyResult,
+} from '../core/configure-github.js';
+
+export interface RunConfigureGithubOptions {
+  /** "owner/repo" target — required. */
+  target?: string | null;
+  /** Target branch (default `main`). */
+  branch?: string;
+  /** Render diff only; skip PATCH calls. */
+  dryRun?: boolean;
+  /** Suppress progress chatter; emit only the final `ok` summary. */
+  quiet?: boolean;
+  /** Emit the SPEC §3.23.1 status payload as JSON instead of key-colon-value. */
+  json?: boolean;
+  /** Resolver for the GitHub token (tests pass a stub). */
+  resolveToken?: () => Promise<string | null>;
+  /** Octokit factory (tests inject a fake; defaults to the gh-adapter). */
+  octokitFactory?: (token: string) => OctokitLike;
+  /** Stdout writer (tests capture). */
+  stdout?: (msg: string) => void;
+  /** Stderr writer (tests capture). */
+  stderr?: (msg: string) => void;
+}
+
+const HELP = `clud-bug configure-github — apply SPEC §7 canonical branch protection.
+
+Usage:
+  clud-bug configure-github <owner>/<repo> [options]
+
+Options:
+  --dry-run         Compute diff and print it, but do NOT call PATCH endpoints.
+  --branch <name>   Target branch (default: main).
+  --quiet,-q        Suppress progress chatter; emit only the final summary.
+  --json            Emit the status payload as JSON (machine consumption).
+  --help,-h         Show this help.
+
+Auth (resolved in order):
+  1. GITHUB_TOKEN env var (CI-friendly)
+  2. \`gh auth token\` (developer workstation)
+
+Exit codes:
+  0  success or already-canonical
+  1  auth missing, PATCH error, or unrecoverable transport failure
+  2  CLI usage error (missing target, bad flag)
+`;
+
+/** Resolved outcome of a configure-github run, for the §3.23.1 status payload. */
+export interface ConfigureSummary {
+  owner: string;
+  repo: string;
+  /** True when the repo already matches canonical-v1 (idempotent no-op). */
+  alreadyCanonical: boolean;
+  /** True when this was a --dry-run (no PATCH calls made). */
+  dryRun: boolean;
+  /** Number of changes (applied, or pending for dry-run; 0 for a no-op). */
+  changes: number;
+}
+
+/**
+ * SPEC §3.23.1 (NORMATIVE): emit a single-line status payload carrying
+ * `alreadyCanonical` + `rulesetVersion` as named fields — JSON for machine
+ * consumption, key-colon-value for humans.
+ */
+export function formatConfigureSummary(summary: ConfigureSummary, json: boolean): string {
+  const { owner, repo, alreadyCanonical, dryRun, changes } = summary;
+  if (json) {
+    return (
+      JSON.stringify({ owner, repo, alreadyCanonical, rulesetVersion: 'v1', dryRun, changes }) + '\n'
+    );
+  }
+  if (alreadyCanonical) {
+    return `ok configure-github: owner: ${owner} repo: ${repo} alreadyCanonical: true rulesetVersion: v1\n`;
+  }
+  const plural = changes === 1 ? '' : 's';
+  if (dryRun) {
+    return `ok configure-github: dry-run on ${owner}/${repo} — ${changes} change${plural} pending\n`;
+  }
+  return `ok configure-github: ${owner}/${repo} converged to canonical-v1 (${changes} change${plural})\n`;
+}
+
+/**
+ * Entry point — wired into `clud-bug.js` dispatch. Returns a Node-style
+ * exit code so the dispatcher can `process.exit()` deterministically. We
+ * don't call `process.exit` ourselves so tests can drive the function
+ * without taking down the harness.
+ */
+export async function runConfigureGithub(
+  options: RunConfigureGithubOptions,
+): Promise<number> {
+  const {
+    target,
+    branch = 'main',
+    dryRun = false,
+    quiet = false,
+    json = false,
+    resolveToken = defaultResolveToken,
+    octokitFactory = ghCliOctokit,
+    stdout = (msg) => process.stdout.write(msg),
+    stderr = (msg) => process.stderr.write(msg),
+  } = options;
+
+  if (!target) {
+    stderr(HELP);
+    return 2;
+  }
+  const match = /^([^/]+)\/([^/]+)$/.exec(target);
+  if (!match) {
+    stderr(
+      `clud-bug configure-github: target must be in owner/repo form, got "${target}".\n`,
+    );
+    return 2;
+  }
+  const [, owner, repo] = match as unknown as [unknown, string, string];
+
+  const token = await resolveToken();
+  if (!token) {
+    stderr(
+      'clud-bug configure-github: no GitHub token found.\n' +
+        '  Set GITHUB_TOKEN, or install + auth gh: brew install gh && gh auth login\n',
+    );
+    return 1;
+  }
+
+  if (!quiet) {
+    stdout(
+      `\u{1F41B} configure-github: applying canonical-v1 ruleset to ${owner}/${repo} (branch=${branch})\n`,
+    );
+  }
+
+  // Single-call orchestration: the CLI previously called
+  // applyCanonicalRuleset twice in apply mode (dry-run first to display the
+  // planned changes, then a real call to apply). That two-read pattern
+  // opened a TOCTOU window — concurrent changes between the two reads
+  // could make the displayed list diverge from the actually-applied list,
+  // and the dry-run cost a redundant API round-trip every time. Drop the
+  // preview-first read: pass `dryRun` straight through. The function's
+  // idempotency contract (returns `alreadyCanonical: true` + empty changes
+  // on a no-op) means we don't need a separate "look before you leap"
+  // call. Users who want preview semantics run `--dry-run` first as a
+  // distinct invocation — idiomatic CLI behavior. Surfaced by PR #166
+  // reviewer (CTO follow-up 2026-06-17).
+  const octokit = octokitFactory(token);
+  let result: ApplyResult;
+  try {
+    result = await applyCanonicalRuleset(octokit, {
+      owner,
+      repo,
+      branch,
+      dryRun,
+    });
+  } catch (err) {
+    stderr(
+      `clud-bug configure-github: ${dryRun ? 'failed to read current state' : 'PATCH failed'}: ${stringifyError(err)}\n`,
+    );
+    return 1;
+  }
+
+  if (result.alreadyCanonical) {
+    if (!quiet) stdout('  No changes — repo already matches canonical-v1.\n');
+    stdout(formatConfigureSummary({ owner, repo, alreadyCanonical: true, dryRun, changes: 0 }, json));
+    return 0;
+  }
+
+  if (!quiet) {
+    const verb = dryRun ? 'Planned' : 'Applied';
+    stdout(`  ${verb} changes (${result.changes.length}):\n`);
+    for (const c of result.changes) stdout(`    - ${c}\n`);
+  }
+
+  if (dryRun) {
+    stdout(formatConfigureSummary({ owner, repo, alreadyCanonical: false, dryRun: true, changes: result.changes.length }, json));
+    return 0;
+  }
+
+  stdout(formatConfigureSummary({ owner, repo, alreadyCanonical: false, dryRun: false, changes: result.changes.length }, json));
+  return 0;
+}
+
+/**
+ * Auth ladder: env var first, then `gh auth token`. Surfaces a token
+ * string on success or `null` if neither source has one (caller prints
+ * the recovery hint).
+ */
+async function defaultResolveToken(): Promise<string | null> {
+  const fromEnv = process.env.GITHUB_TOKEN?.trim();
+  if (fromEnv) return fromEnv;
+  const result = spawnSync('gh', ['auth', 'token'], { encoding: 'utf8' });
+  if (result.status === 0) {
+    const tok = result.stdout.trim();
+    if (tok) return tok;
+  }
+  return null;
+}
+
+/**
+ * Builds an `OctokitLike` instance backed by `gh api` shell-outs. This
+ * lets us satisfy the structural interface without pulling in
+ * `@octokit/rest` as a runtime dep (~200KB). The App passes its real
+ * Octokit instance instead.
+ */
+export function ghCliOctokit(token: string): OctokitLike {
+  // We pass GITHUB_TOKEN through the spawn env so gh's API surface picks
+  // it up consistently whether the user supplied env or gh auth.
+  const env = { ...process.env, GITHUB_TOKEN: token };
+
+  function ghApi<T>(
+    method: 'GET' | 'PUT' | 'PATCH' | 'POST',
+    path: string,
+    body?: unknown,
+  ): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const args: string[] = ['api', '-X', method];
+      if (body !== undefined) {
+        args.push('--input', '-');
+      }
+      args.push(path);
+      // Add an Accept header so 404s return the structured error, not a
+      // friendlier shell hint. The wrapping err.message detection in
+      // `isBranchNotProtected` keys on the structured form.
+      args.push('-H', 'Accept: application/vnd.github+json');
+      const child = spawn('gh', args, {
+        env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      let stdout = '';
+      let stderr = '';
+      child.stdout!.on('data', (d: Buffer) => {
+        stdout += d.toString();
+      });
+      child.stderr!.on('data', (d: Buffer) => {
+        stderr += d.toString();
+      });
+      child.on('error', reject);
+      child.on('close', (code) => {
+        if (code !== 0) {
+          const httpMatch = /HTTP (\d{3})/.exec(stderr);
+          const status = httpMatch ? Number(httpMatch[1]) : undefined;
+          const err = new Error(
+            (stderr.trim() || stdout.trim() || `gh api exited ${code}`).slice(
+              0,
+              500,
+            ),
+          ) as Error & { status?: number };
+          if (status !== undefined) err.status = status;
+          reject(err);
+          return;
+        }
+        try {
+          resolve(stdout ? (JSON.parse(stdout) as T) : ({} as T));
+        } catch (parseErr) {
+          reject(parseErr);
+        }
+      });
+      if (body !== undefined) {
+        child.stdin!.end(JSON.stringify(body));
+      } else {
+        child.stdin!.end();
+      }
+    });
+  }
+
+  return {
+    repos: {
+      async getBranchProtection({ owner, repo, branch }) {
+        const data = await ghApi<unknown>(
+          'GET',
+          `/repos/${owner}/${repo}/branches/${branch}/protection`,
+        );
+        return { data: data as Awaited<ReturnType<OctokitLike['repos']['getBranchProtection']>>['data'] };
+      },
+      async updateBranchProtection({ owner, repo, branch, ...rest }) {
+        return ghApi(
+          'PUT',
+          `/repos/${owner}/${repo}/branches/${branch}/protection`,
+          rest,
+        );
+      },
+      async get({ owner, repo }) {
+        const data = await ghApi<unknown>(
+          'GET',
+          `/repos/${owner}/${repo}`,
+        );
+        return { data: data as Awaited<ReturnType<OctokitLike['repos']['get']>>['data'] };
+      },
+      async update({ owner, repo, ...rest }) {
+        return ghApi('PATCH', `/repos/${owner}/${repo}`, rest);
+      },
+    },
+  };
+}
+
+function stringifyError(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+
+/**
+ * Re-exported so callers can preload the ruleset (e.g. for a `--show-ruleset`
+ * flag in future). Currently exists for parity with the App's pattern.
+ */
+export { loadCanonicalV1 };

package/src/cli/hooks.ts

@@ -0,0 +1,155 @@
+// Wave 6b (rc.17 fix) — Claude Code `type: command` commit-review hook scaffolding.
+//
+// `clud-bug init --with-hooks` writes a native Claude Code hook that, on every
+// `git commit`, runs clud-bug's review recipe ON THIS SESSION'S SUBSCRIPTION
+// (no API key), in the background (the commit never blocks).
+//
+// WHY `type: command`, NOT `type: agent`: a Claude Code `type: agent` hook
+// spawns a subagent restricted to Read/Grep/Glob — it has NO Bash and the tool
+// set is not configurable (see code.claude.com/docs/en/hooks: "spawn a subagent
+// that can use tools like Read, Grep, and Glob"). The original Wave 6b hook used
+// `type: agent` and told the subagent to run `npx clud-bug review-prompt` — a
+// Bash CLI call an agent hook can never make — so the review NEVER ran for
+// anyone. A `type: command` hook CAN run the CLI: it fetches the engine's recipe
+// and surfaces it to the session via exit-2 (`asyncRewake`), so the MAIN agent —
+// which has Bash, git, gh, and the subscription — performs the review. The hook
+// exits 0 on any failure, so a review that can't run is a quiet no-op and the
+// commit is NEVER blocked.
+
+/** Stable marker embedded in our hook so re-runs — and upgrades from the old,
+ * broken `type: agent` hook — replace it in place. */
+export const CLUD_BUG_HOOK_MARKER = 'clud-bug-local-review';
+
+/**
+ * Build the shell `command` of the commit-review hook. Pins to a FLOATING npm
+ * dist-tag (`next` by default) rather than an exact version, so every repo's hook
+ * auto-fetches the latest review recipe — no per-release re-pin rollout. (The
+ * original exact-pin guarded against a `latest` that predated the `review-prompt`
+ * verb; that verb now ships in every channel, so floating is safe + frictionless.)
+ * Max mode is advisory, so "always newest recipe" is the right default for a
+ * review tool. `pin` is overridable for a repo that wants a frozen, exact version.
+ *
+ * The command, in order:
+ *   1. Idempotency — skip if this exact HEAD was already surfaced (avoids a
+ *      re-review on an amend-with-no-change or a double-fire). The reviewed SHA
+ *      is recorded under `.git/` (untracked), reusing the "last-reviewed-sha"
+ *      idea the hosted bot uses on PR comments.
+ *   2. Fetch a fresh recipe tailored to THIS repo: `review-prompt --trigger
+ *      commit` (an instruction recipe — `git show HEAD` + the skills + the
+ *      report format — NOT raw data; it is meant to be FOLLOWED by an agent).
+ *   3. Surface it to the session by printing it and `exit 2`, so `asyncRewake`
+ *      shows it to the main agent as a system reminder. The agent then reviews
+ *      the commit on the session subscription.
+ *   4. Any failure or empty output → `exit 0` (quiet; the commit is never blocked).
+ */
+export function buildCommitReviewCommand(pin: string = 'next'): string {
+  return [
+    // Marker as a `#` comment (NOT a `:` no-op) so its free text can never break
+    // `sh` — a paren / quote / `$` in the marker line would be a syntax error
+    // under `: ...`. The dogfood caught this. `isOurHook` finds the marker here.
+    `# ${CLUD_BUG_HOOK_MARKER} v2 — clud-bug commit review on the session subscription`,
+    // Belt-and-suspenders gate. The `if: Bash(git commit *)` / `Bash(logmind log *)`
+    // field filters at the platform on Claude Code >= 2.1.85; OLDER CC ignores
+    // `if` and would fire this on EVERY Bash call (a review recipe after every
+    // command). Command hooks get the event JSON on stdin — re-check it here. If
+    // stdin is empty (a CC that doesn't pipe it), fall through and trust `if`.
+    `ev=$(cat 2>/dev/null)`,
+    `if [ -n "$ev" ]; then case "$ev" in *'git commit'*|*'logmind log'*) ;; *) exit 0 ;; esac; fi`,
+    `sha=$(git rev-parse HEAD 2>/dev/null) || exit 0`,
+    `gitdir=$(git rev-parse --git-dir 2>/dev/null) || exit 0`,
+    `marker="$gitdir/clud-bug-last-commit-review"`,
+    `[ "$(cat "$marker" 2>/dev/null)" = "$sha" ] && exit 0`,
+    // H4 — one retry on a transient npx/network blip (a stale lock, a slow
+    // registry) before giving up, so a hiccup doesn't silently skip the review.
+    // `|| recipe=` clears it on a NON-ZERO exit so partial/error stdout from a
+    // mid-run crash (or an old npm warning on stdout) is never mistaken for a
+    // valid recipe — only a clean, exit-0 run surfaces.
+    `recipe=$(npx clud-bug@${pin} review-prompt --trigger commit 2>/dev/null) || recipe=`,
+    `if [ -z "$recipe" ]; then sleep 1; recipe=$(npx clud-bug@${pin} review-prompt --trigger commit 2>/dev/null) || recipe=; fi`,
+    // H4 — when the recipe still can't be fetched, leave a diagnostic marker so a
+    // FAILED review is distinguishable from a CLEAN one (a clean review surfaces
+    // the recipe + the agent reports clean). Never blocks the commit.
+    `if [ -z "$recipe" ]; then printf '%s' "$sha" > "$gitdir/clud-bug-review-skipped" 2>/dev/null || true; exit 0; fi`,
+    `printf '%s' "$sha" > "$marker" 2>/dev/null || true`,
+    `printf '%s\\n\\n%s\\n' "clud-bug commit review (max mode — on this session's subscription): a commit was just made. Follow this recipe now — review that commit against the skills it names and surface any findings." "$recipe"`,
+    `exit 2`,
+  ].join('\n');
+}
+
+/** 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 runs the commit-review command: a native
+ * `type: command` hook, backgrounded (`async`), surfacing the recipe back to the
+ * session (`asyncRewake` + exit 2), firing only on `git commit` (`if`).
+ */
+export function buildLocalReviewHook(command: string): HookMatcherEntry {
+  const base = { type: 'command', async: true, asyncRewake: true, timeout: 180, command } as const;
+  return {
+    matcher: 'Bash',
+    hooks: [
+      { ...base, if: 'Bash(git commit *)' },
+      // thrillmade repos (and any logmind user) commit via `logmind log`, which
+      // wraps `git commit` inside its own binary — so the Bash tool call is
+      // `logmind log ...`, which `Bash(git commit *)` never matches. Fire on it
+      // too, or max mode never triggers in a logmind repo. The idempotency
+      // SHA-marker means whichever path runs, a commit is reviewed exactly once.
+      { ...base, if: 'Bash(logmind log *)' },
+    ],
+  };
+}
+
+function isOurHook(h: Record<string, unknown> | undefined): boolean {
+  // Match our marker in `command` (current `type: command` hook) OR `prompt`
+  // (the old, broken `type: agent` hook) so a re-install / `clud-bug update`
+  // replaces either in place.
+  const field = h?.['command'] ?? h?.['prompt'];
+  return typeof field === 'string' && field.includes(CLUD_BUG_HOOK_MARKER);
+}
+
+function isCludBugReviewEntry(entry: HookMatcherEntry | undefined): boolean {
+  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 — including the old
+ * `type: agent` one — rather than duplicating) and **non-clobbering** (preserves
+ * every other top-level key, event, and hook). Tolerates a missing/malformed
+ * `existing` value.
+ */
+export function mergeLocalReviewHook(existing: unknown, command: string): ClaudeSettings {
+  const base: ClaudeSettings =
+    existing && typeof existing === 'object' ? { ...(existing as ClaudeSettings) } : {};
+  const hooks: Record<string, HookMatcherEntry[]> = { ...(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(command);
+  const otherEntries: HookMatcherEntry[] = [];
+  const coLocatedUserHooks: Array<Record<string, unknown>> = [];
+  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: HookMatcherEntry =
+    coLocatedUserHooks.length > 0 ? { ...ours, hooks: [...coLocatedUserHooks, ...ours.hooks] } : ours;
+  hooks.PostToolUse = [...otherEntries, ourEntry];
+  base.hooks = hooks;
+  return base;
+}

package/src/cli/index.ts

@@ -99,3 +99,9 @@ export {
   type UpdateSkippedRecord,
   type RunUpdateResult,
 } from './update.js';
+
+export {
+  runConfigureGithub,
+  ghCliOctokit,
+  type RunConfigureGithubOptions,
+} from './configure-github.js';