clud-bug 0.5.3 → 0.5.5

package/README.md

@@ -36,16 +36,22 @@ The naturalist arrives at your repo, surveys the habitat, and assembles a field
 4. **Writes** the chosen specimens to `.claude/skills/<name>/SKILL.md` (Claude Code auto-loads them in the GitHub Action).
 5. **Drafts the field kit** at `.github/workflows/clud-bug-review.yml` with your project description filled in and the right permissions/tool allowlist for `gh pr comment` to actually post.
 6. **Briefs other agents** by adding a `<!-- clud-bug-start -->` block to `AGENTS.md` (creating it if missing — it's the cross-tool canonical), and idempotently to `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, `.cursorrules`, `.windsurfrules`, `.clinerules`, `.continuerules`, and `.cursor/rules/*.md` where they already exist. Re-runs replace the prior block in place. Files you didn't already have are left uncreated — no proliferating stubs.
+7. **Offers to enable `required_conversation_resolution`** on your default branch. Clud Bug auto-resolves its own review threads when fixes land — but that only gates merges when conversation-resolution is required. Init detects the current state via `gh`, prompts to enable (auto-yes with `--accept-all`), and degrades to an advisory message if you lack admin perms / `gh` isn't installed / the branch has no base protection rule. Pass `--no-set-protection` to skip the prompt entirely — for repos that manage branch protection via ruleset or org policy.
 
 ## CLI options
 
 ```
 npx clud-bug init [options]
 
-  --offline       Skip skills.sh; install only the bundled baseline skills.
-  --accept-all,-y Accept the recommended skill set without prompting.
-  --commit        git add + commit the generated files when done.
-  --help,-h       Show help.
+  --offline             Skip skills.sh; install only the bundled baseline skills.
+  --accept-all,-y       Accept the recommended skill set (and the
+                        branch-protection prompt) without prompting.
+  --no-set-protection   Skip the prompt that offers to enable
+                        required_conversation_resolution on the default
+                        branch. For repos that manage branch protection
+                        via ruleset or org policy.
+  --commit              git add + commit the generated files when done.
+  --help,-h             Show help.
 ```
 
 ## Staying up to date
@@ -182,6 +188,26 @@ After install:
 3. Within ~2 min, Clud Bug should post a comment flagging it.
 4. If no comment: check the **Actions** tab logs. Look for `gh pr comment` invocations and any "Resource not accessible by integration" errors (usually a permissions issue or a fork PR).
 
+### Reading a review
+
+Every Clud Bug review opens with a status line that tells you exactly what changed since the previous pass — particularly useful on re-review after you push a fix:
+
+```
+## 🐛 Clud Bug review
+
+**This round:** 0 critical · 1 minor · 3 resolved from prior · 0 still open
+
+### Findings
+…
+```
+
+- **critical** — new critical findings in this review (these are what strict mode gates on)
+- **minor** — non-critical findings (suggestions / nits)
+- **resolved from prior** — prior unresolved threads the bot just cleared because it verified your fix in the diff
+- **still open** — prior threads whose issue is still standing
+
+Same format every time; zero values are always present so the line is easy to scan and parse.
+
 ## Manual install (advanced)
 
 If you don't want to use the CLI, you can install a generic workflow by hand:

package/bin/clud-bug.js

@@ -16,6 +16,7 @@ import { computeAuditFileSet, renderAuditHeader } from '../lib/audit.js';
 import { runUpdate } from '../lib/update.js';
 import { getPendingWorkflowEdits, makeBranchName, git as gitCmd } from '../lib/edit-workflow.js';
 import { applyToRepo as applyAgentDocs } from '../lib/agents-md.js';
+import { detectRepo, detectDefaultBranch, getProtectionState, enableConversationResolution } from '../lib/branch-protection.js';
 
 const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const TEMPLATES = join(PKG_ROOT, 'templates');
@@ -25,6 +26,7 @@ function parseArgs(argv) {
   const args = {
     _: [], offline: false, acceptAll: false, commit: false, help: false, version: false,
     since: null, changedIn: null, scopes: [], out: null,
+    setProtection: true,
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -37,6 +39,7 @@ function parseArgs(argv) {
     else if (a === '--changed-in') args.changedIn = argv[++i];
     else if (a === '--scope') args.scopes.push(argv[++i]);
     else if (a === '--out') args.out = argv[++i];
+    else if (a === '--no-set-protection') args.setProtection = false;
     else args._.push(a);
   }
   return args;
@@ -64,6 +67,10 @@ Options:
   --offline             Skip skills.sh; pin only the bundled baseline specimens.
   --accept-all,-y       Accept the recommended specimens without prompting.
   --commit              git add + commit the generated kit when done (init only).
+  --no-set-protection   Skip the prompt that offers to enable
+                        required_conversation_resolution on the default
+                        branch (init only). Use for repos that manage
+                        branch protection via ruleset or org policy.
   --since <date>        Audit only files changed in commits after <date> (git date string).
   --changed-in <dur>    Audit only files changed in the past <dur>: 7d, 2w, 1mo, 1y. (audit only)
   --scope <glob>        Limit audit to files matching <glob>; repeatable. (audit only)
@@ -236,6 +243,13 @@ async function runInit(args) {
     spawnSync('git', ['commit', '-m', 'Add clud-bug 🐛 — a field guide to specimens crawling your code'], { cwd, stdio: 'inherit' });
   }
 
+  // Offer to enable required_conversation_resolution on the default
+  // branch. clud-bug auto-resolves its own review threads when fixes
+  // land — without this setting, that doesn't gate merges. Skipped on
+  // --no-set-protection for repos that manage protection via ruleset
+  // or org policy.
+  await runInitBranchProtection(args);
+
   log('');
   log('Field kit assembled. Next:');
   log('  1. Set ANTHROPIC_API_KEY in your repo secrets:');
@@ -278,6 +292,114 @@ async function promptForSkills(recommended) {
   }
 }
 
+// Branch-protection setup step at the end of `clud-bug init`.
+// Offers to enable required_conversation_resolution on the default
+// branch via gh API. Skipped cleanly when --no-set-protection is
+// passed. Failure modes (no admin perms, no base protection rule,
+// network error) all degrade to advisory log messages — they never
+// fail the init run.
+//
+// gh and prompt are injectable for tests (defaults to spawning real
+// gh + reading from real stdin).
+async function runInitBranchProtection(args, { gh, prompt } = {}) {
+  if (!args.setProtection) {
+    log('');
+    log('🐛 Branch protection: skipped (--no-set-protection).');
+    return;
+  }
+  log('');
+  log('🐛 Branch protection');
+
+  // Detect repo + default branch. If gh isn't installed or the local
+  // dir isn't a github repo, treat as advisory and move on.
+  let owner, repo, branch;
+  try {
+    ({ owner, repo } = await detectRepo({ gh }));
+    branch = await detectDefaultBranch({ owner, repo, gh });
+  } catch (err) {
+    log(`  Could not detect repo/branch (${err.message.split('\n')[0]}). Skipping.`);
+    log('  You can enable it manually: gh api -X POST repos/<owner>/<repo>/branches/<default>/protection/required_conversation_resolution');
+    return;
+  }
+
+  log(`  Default branch: ${branch}`);
+
+  // Inspect current state.
+  const current = await getProtectionState({ owner, repo, branch, gh });
+  if (current.state === 'enabled') {
+    log('  required_conversation_resolution: already on — your repo is all set.');
+    return;
+  }
+  if (current.state === 'forbidden') {
+    log('  Could not read branch protection (no admin perms). Ask the repo owner to enable required_conversation_resolution, or re-run with --no-set-protection to silence this prompt.');
+    return;
+  }
+  if (current.state === 'unknown') {
+    log(`  Could not read branch protection (${current.reason}). Skipping.`);
+    return;
+  }
+
+  // Short-circuit on no-protection BEFORE prompting. The single-flag
+  // POST endpoint requires a base protection rule on the branch — if
+  // there's none, enableConversationResolution would just 404. Skip
+  // the prompt and go straight to the actionable guidance (set up
+  // basic protection first, then re-run).
+  if (current.state === 'no-protection') {
+    log('  required_conversation_resolution: not set (no base protection rule on this branch)');
+    log('  Cannot enable yet: this branch has no base protection rule.');
+    log(`    Set one up first: Settings → Branches → Add rule for ${branch}`);
+    log('    Then re-run clud-bug init (or toggle the setting in the GUI).');
+    return;
+  }
+
+  // current.state is 'disabled'.
+  log('  required_conversation_resolution: not set');
+
+  // Decide whether to prompt.
+  let shouldEnable;
+  if (args.acceptAll) {
+    // --accept-all is a real side-effect flag here: it flips a
+    // merge-gating repo setting. Make that explicit in the log so
+    // CI users running `clud-bug init --accept-all` see exactly
+    // what's happening instead of silently noticing later.
+    log('  --accept-all: will enable required_conversation_resolution. Pass --no-set-protection to skip.');
+    shouldEnable = true;
+  } else {
+    const ask = prompt ?? (async (q) => {
+      const rl = createInterface({ input, output });
+      try { return await rl.question(q); } finally { rl.close(); }
+    });
+    log('');
+    log('  Clud Bug auto-resolves its own review threads when fixes land.');
+    log('  Without required_conversation_resolution, that doesn\'t actually gate merges.');
+    const answer = await ask(`  Enable required_conversation_resolution on ${branch}? [Y/n] `);
+    shouldEnable = !['n', 'no'].includes(answer.trim().toLowerCase());
+  }
+
+  if (!shouldEnable) {
+    log('  Skipped. Re-run with --accept-all or set it manually anytime.');
+    return;
+  }
+
+  const result = await enableConversationResolution({ owner, repo, branch, gh });
+  if (result.ok) {
+    log('  ✓ Enabled required_conversation_resolution.');
+    return;
+  }
+  if (result.state === 'no-protection') {
+    log('  Cannot enable: this branch has no base protection rule. Set up basic branch protection first:');
+    log(`    Settings → Branches → Add rule for ${branch}`);
+    log('  Then re-run clud-bug init (or just toggle the setting in the GUI).');
+    return;
+  }
+  if (result.state === 'forbidden') {
+    log('  Cannot enable: you do not have admin permissions on this repository.');
+    log('  Ask the repo owner to enable it, or re-run with --no-set-protection to silence this prompt.');
+    return;
+  }
+  log(`  Cannot enable (${result.reason}). You can enable it manually anytime.`);
+}
+
 async function runList(_args) {
   const skillsDir = join(process.cwd(), '.claude', 'skills');
   const groups = await listInstalled(skillsDir);

package/lib/branch-protection.js

@@ -0,0 +1,113 @@
+// Helpers for managing `required_conversation_resolution` on the default
+// branch via the `gh` CLI. Factored out so `runInit` can call this without
+// embedding `spawnSync` boilerplate, and so tests can swap a mock for the
+// real `gh` invocation.
+//
+// Why `gh` rather than direct fetch(): clud-bug already depends on `gh`
+// being installed and authenticated (workflows use `gh pr comment`, edit
+// workflows use `gh pr create`). Reusing it inherits the user's auth
+// instead of asking them to set up another token.
+//
+// API endpoints used:
+//   GET /repos/{owner}/{repo}
+//     → .default_branch
+//   GET /repos/{owner}/{repo}/branches/{branch}/protection
+//     → .required_conversation_resolution.enabled (true/false), OR 404 if
+//       the branch has no protection rule at all.
+//   POST /repos/{owner}/{repo}/branches/{branch}/protection/required_conversation_resolution
+//     → enables the single flag without touching other settings. This is
+//       a real single-flag endpoint; we don't have to GET-merge-PUT the
+//       full protection JSON.
+
+import { spawn } from 'node:child_process';
+
+// Default `gh` invoker: spawns `gh <args>` and resolves with
+// { code, stdout, stderr }. Tests pass a function with the same shape.
+function defaultGh(args, { stdin } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('gh', args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+    child.on('error', reject);
+    child.on('close', (code) => resolve({ code, stdout, stderr }));
+    if (stdin) child.stdin.end(stdin);
+    else child.stdin.end();
+  });
+}
+
+// Returns { owner, repo } from the local git remote. Uses
+// `gh repo view --json owner,name` so it doesn't depend on parsing URLs.
+export async function detectRepo({ gh = defaultGh } = {}) {
+  const { code, stdout, stderr } = await gh(['repo', 'view', '--json', 'owner,name']);
+  if (code !== 0) {
+    throw new Error(`gh repo view failed (${code}): ${stderr.trim() || '(no stderr)'}`);
+  }
+  const parsed = JSON.parse(stdout);
+  return { owner: parsed.owner.login, repo: parsed.name };
+}
+
+// Returns the default branch name (e.g. "main", "master", "trunk").
+export async function detectDefaultBranch({ owner, repo, gh = defaultGh } = {}) {
+  const { code, stdout, stderr } = await gh(['api', `repos/${owner}/${repo}`, '--jq', '.default_branch']);
+  if (code !== 0) {
+    throw new Error(`Could not read default_branch for ${owner}/${repo}: ${stderr.trim() || stdout.trim()}`);
+  }
+  return stdout.trim();
+}
+
+// Inspects the current required_conversation_resolution state. Returns
+// one of:
+//   { state: 'enabled' }
+//   { state: 'disabled' }
+//   { state: 'no-protection' }   // branch has no protection rule at all
+//   { state: 'forbidden' }       // user lacks admin perms
+//   { state: 'unknown', reason }  // any other failure mode
+//
+// The reason this returns a discriminated union rather than throwing is
+// that runInit decides what to do based on the state: each value above
+// has a different user-facing message and follow-up action.
+export async function getProtectionState({ owner, repo, branch, gh = defaultGh } = {}) {
+  const { code, stdout, stderr } = await gh([
+    'api',
+    `repos/${owner}/${repo}/branches/${branch}/protection`,
+    '--jq', '.required_conversation_resolution.enabled // false',
+  ]);
+  if (code === 0) {
+    return { state: stdout.trim() === 'true' ? 'enabled' : 'disabled' };
+  }
+  // gh prints HTTP details to stderr. Look for the markers we recognize.
+  // We deliberately key on 403 / 'Forbidden' / 'Resource not accessible'
+  // rather than the bare word 'admin' — gh's error vocabulary can mention
+  // 'admin' in unrelated contexts (administrator@…, admin api endpoint,
+  // future error copy) and we don't want to misclassify those as
+  // permission failures.
+  const blob = `${stdout}\n${stderr}`;
+  if (/404|Branch not protected|Not Found/i.test(blob)) return { state: 'no-protection' };
+  if (/403|Forbidden|Resource not accessible/i.test(blob)) return { state: 'forbidden' };
+  return { state: 'unknown', reason: stderr.trim() || stdout.trim() || `gh exited ${code}` };
+}
+
+// Enables the single flag via the dedicated endpoint. Doesn't touch any
+// other protection settings. Returns { ok: true } on success or
+// { ok: false, state, reason } using the same state taxonomy as
+// getProtectionState() so callers can produce a consistent message.
+export async function enableConversationResolution({ owner, repo, branch, gh = defaultGh } = {}) {
+  const { code, stdout, stderr } = await gh([
+    'api', '-X', 'POST',
+    `repos/${owner}/${repo}/branches/${branch}/protection/required_conversation_resolution`,
+  ]);
+  if (code === 0) return { ok: true };
+  // Match the same precise alternatives as getProtectionState — no bare
+  // 'admin' fallback to avoid misclassifying unrelated error messages
+  // that happen to contain the word.
+  const blob = `${stdout}\n${stderr}`;
+  if (/404|Branch not protected|Not Found/i.test(blob)) {
+    return { ok: false, state: 'no-protection', reason: 'Branch has no base protection rule; enable basic branch protection first.' };
+  }
+  if (/403|Forbidden|Resource not accessible/i.test(blob)) {
+    return { ok: false, state: 'forbidden', reason: 'You do not have admin permissions on this repository.' };
+  }
+  return { ok: false, state: 'unknown', reason: stderr.trim() || stdout.trim() || `gh exited ${code}` };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clud-bug",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Claude PR review with project-aware skills. CLI installs a working GitHub Actions workflow and curates skills from skills.sh.",
   "homepage": "https://cludbug.dev",
   "bugs": "https://github.com/thrillmot/clud-bug/issues",

package/templates/workflow-py.yml.tmpl

@@ -113,6 +113,40 @@ jobs:
 
               ## 🐛 Clud Bug review
 
+            Immediately after the H2 header — on the next non-empty
+            line — emit a status block in this exact format:
+
+              **This round:** N critical · N minor · N resolved from prior · N still open
+
+            This applies to BOTH the bare "## 🐛 Clud Bug review" header
+            and the strict-mode variants ("— critical findings" /
+            "— clean"). The status line goes on the next non-empty line
+            regardless of which header you used. Do not omit the H2
+            header variant in strict mode just to fit the status line —
+            the strict-mode gate reads the H2 line and would break.
+
+            The four counters (always include all four, even when 0 —
+            fixed format is grep-able and lets agents reading the
+            comment parse it deterministically):
+              • critical            — count of NEW critical findings
+                                      in this review (the ones strict
+                                      mode gates on)
+              • minor               — count of non-critical findings
+                                      (suggestions / nits / observations)
+              • resolved from prior — count of prior unresolved threads
+                                      YOU (claude[bot]) just resolved on
+                                      this pass via resolveReviewThread
+                                      (the loop-closing signal — this
+                                      tells the author the bot read
+                                      their fixes)
+              • still open          — count of prior unresolved threads
+                                      whose issue still stands AFTER
+                                      this pass
+
+            On a first-time review, "resolved from prior" and "still
+            open" are both 0. On follow-up reviews after a fix-push,
+            "resolved from prior" should typically be positive.
+
             Post it via:
               gh pr comment "$PR_NUMBER" --body "<your review>"
 

package/templates/workflow-ts.yml.tmpl

@@ -114,6 +114,40 @@ jobs:
 
               ## 🐛 Clud Bug review
 
+            Immediately after the H2 header — on the next non-empty
+            line — emit a status block in this exact format:
+
+              **This round:** N critical · N minor · N resolved from prior · N still open
+
+            This applies to BOTH the bare "## 🐛 Clud Bug review" header
+            and the strict-mode variants ("— critical findings" /
+            "— clean"). The status line goes on the next non-empty line
+            regardless of which header you used. Do not omit the H2
+            header variant in strict mode just to fit the status line —
+            the strict-mode gate reads the H2 line and would break.
+
+            The four counters (always include all four, even when 0 —
+            fixed format is grep-able and lets agents reading the
+            comment parse it deterministically):
+              • critical            — count of NEW critical findings
+                                      in this review (the ones strict
+                                      mode gates on)
+              • minor               — count of non-critical findings
+                                      (suggestions / nits / observations)
+              • resolved from prior — count of prior unresolved threads
+                                      YOU (claude[bot]) just resolved on
+                                      this pass via resolveReviewThread
+                                      (the loop-closing signal — this
+                                      tells the author the bot read
+                                      their fixes)
+              • still open          — count of prior unresolved threads
+                                      whose issue still stands AFTER
+                                      this pass
+
+            On a first-time review, "resolved from prior" and "still
+            open" are both 0. On follow-up reviews after a fix-push,
+            "resolved from prior" should typically be positive.
+
             Post it via:
               gh pr comment "$PR_NUMBER" --body "<your review>"
 

package/templates/workflow.yml.tmpl

@@ -134,6 +134,40 @@ jobs:
 
               ## 🐛 Clud Bug review
 
+            Immediately after the H2 header — on the next non-empty
+            line — emit a status block in this exact format:
+
+              **This round:** N critical · N minor · N resolved from prior · N still open
+
+            This applies to BOTH the bare "## 🐛 Clud Bug review" header
+            and the strict-mode variants ("— critical findings" /
+            "— clean"). The status line goes on the next non-empty line
+            regardless of which header you used. Do not omit the H2
+            header variant in strict mode just to fit the status line —
+            the strict-mode gate reads the H2 line and would break.
+
+            The four counters (always include all four, even when 0 —
+            fixed format is grep-able and lets agents reading the
+            comment parse it deterministically):
+              • critical            — count of NEW critical findings
+                                      in this review (the ones strict
+                                      mode gates on)
+              • minor               — count of non-critical findings
+                                      (suggestions / nits / observations)
+              • resolved from prior — count of prior unresolved threads
+                                      YOU (claude[bot]) just resolved on
+                                      this pass via resolveReviewThread
+                                      (the loop-closing signal — this
+                                      tells the author the bot read
+                                      their fixes)
+              • still open          — count of prior unresolved threads
+                                      whose issue still stands AFTER
+                                      this pass
+
+            On a first-time review, "resolved from prior" and "still
+            open" are both 0. On follow-up reviews after a fix-push,
+            "resolved from prior" should typically be positive.
+
             Post it via:
               gh pr comment "$PR_NUMBER" --body "<your review>"