clud-bug 0.6.29 → 0.6.30

package/bin/clud-bug.js

@@ -33,6 +33,10 @@ function parseArgs(argv) {
     repo: null, pr: null, limit: null, json: false,
     // 0.0.O (v0.6.22): `clud-bug render` reads its payload from stdin.
     stdin: false,
+    // v0.6.30: cross-review aggregation read source for `usage --health`.
+    // Defaults to true (artifact mode); `--no-artifacts` forces local
+    // .clud-bug.json read (matches v0.6.28 behavior).
+    artifacts: true,
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -53,6 +57,7 @@ function parseArgs(argv) {
     else if (a === '--json') args.json = true;
     else if (a === '--stdin') args.stdin = true;
     else if (a === '--health') args.health = true;
+    else if (a === '--no-artifacts') args.artifacts = false;
     else args._.push(a);
   }
   return args;
@@ -80,13 +85,18 @@ Commands:
                         rate, 30-day rolling \$/LOC trend, per-repo/per-model
                         distributions, and outliers (> 2x org median).
                         Use --pr / --repo / --since / --limit / --json to filter.
-  usage --health        Deterministic skill-health dashboard (v0.6.28). Reads
-                        \`.claude/skills/.clud-bug.json\` usage block + renders
-                        archive-candidate / stale / new / healthy status per skill.
-                        Read-only — no automation acts on the output. Humans
-                        decide which skills to prune. v0.6.29 wires the workflow
-                        post-step that auto-writes per-review deltas; v0.6.30
-                        will aggregate across runs into the dashboard read path.
+  usage --health        Deterministic skill-health dashboard. Renders archive-
+                        candidate / stale / new / healthy status per skill, applying
+                        the v0.6.28 thresholds (citations==0 + loads>=5 → archive
+                        candidate; last cited >60d → stale; etc.). Read-only —
+                        humans decide what to prune.
+                        Read source (v0.6.30): by default, walks
+                        \`clud-bug-skill-usage-pr-*\` workflow artifacts uploaded
+                        by every clud-bug-review run and accumulates them into
+                        one org-level snapshot. Pass \`--repo owner/name\` to
+                        target a specific repo; otherwise infers from the local
+                        git remote. \`--no-artifacts\` falls back to reading the
+                        local \`.claude/skills/.clud-bug.json\` (v0.6.28 behavior).
   eval                  Run the golden-set regression gate against the rendered review
                         prompt (must-contain / must-not-contain / byte-budget). Same as
                         \`node --test test/prompts.eval.test.js\` but works from any cwd.
@@ -985,39 +995,119 @@ async function runUsage(args) {
 // v0.6.28 — `clud-bug usage --health` implementation. Reads the local
 // .claude/skills/.clud-bug.json usage block, applies deterministic
 // thresholds, renders a read-only dashboard. No I/O beyond the JSON
-// read. Workflow integration that POPULATES the usage block ships in
-// v0.6.29; today this command is the consumer half of the contract.
-async function runUsageHealth(_args) {
-  const fs = await import('node:fs/promises');
-  const path = await import('node:path');
+// read.
+//
+// v0.6.30 — read accumulated usage from workflow artifacts (uploaded
+// by v0.6.29's post-step). Defaults to artifact mode when --repo is
+// passed OR an `owner/name` can be inferred from `git remote`. Falls
+// back to the local-file path otherwise. The `--no-artifacts` flag
+// forces the v0.6.28 local-only behavior (handy for tests + offline).
+async function runUsageHealth(args) {
   const { assessSkillHealth, formatHealthDashboard } = await import('../lib/skill-usage.js');
 
-  const jsonPath = path.resolve(process.cwd(), '.claude', 'skills', '.clud-bug.json');
+  // Decide read source. Priority: explicit --no-artifacts → local;
+  // explicit --repo OR inferred owner/repo → artifacts; else local.
+  const wantArtifacts = args.artifacts !== false;
+  let ownerRepo = null;
+  if (wantArtifacts) {
+    ownerRepo = args.repo || await inferOwnerRepoFromGit();
+  }
 
-  let parsed;
+  let usage;
+  let source;
+  if (wantArtifacts && ownerRepo) {
+    const result = await loadUsageFromArtifacts(ownerRepo, args);
+    if (result) {
+      usage = result.usage;
+      source = `${result.artifactCount} artifact${result.artifactCount === 1 ? '' : 's'} from ${ownerRepo}`;
+    }
+  }
+
+  // Fallback to local .clud-bug.json (v0.6.28 behavior).
+  if (usage == null) {
+    const localResult = await loadUsageFromLocalFile();
+    if (localResult == null) {
+      // Both paths failed. The local helper has already written its
+      // own stderr explanation; we just exit.
+      process.exit(1);
+    }
+    usage = localResult;
+    source = `local .clud-bug.json`;
+  }
+
+  const rows = assessSkillHealth(usage, new Date());
+  process.stdout.write(formatHealthDashboard(rows) + '\n');
+
+  // Exit code semantics: 0 (informational). The dashboard is read-only;
+  // archive-candidates being present is NOT a failure mode — humans
+  // decide. CI gates should NOT block on this.
+  ok(`skill health: ${rows.length} skill${rows.length === 1 ? '' : 's'} tracked (source: ${source})`);
+}
+
+// Helpers split out from runUsageHealth so the two read paths are
+// independently testable + composable in future commands.
+
+async function loadUsageFromArtifacts(ownerRepo, args) {
+  const { fetchUsageArtifacts, aggregateUsageStream } = await import('../lib/skill-usage.js');
+  const [owner, repo] = ownerRepo.split('/');
+  if (!owner || !repo) {
+    process.stderr.write(`clud-bug usage --health: --repo must be in owner/name form, got "${ownerRepo}".\n`);
+    return null;
+  }
+  const since = parseSinceArg(args.since);
+  let artifacts;
+  try {
+    artifacts = await fetchUsageArtifacts({ owner, repo, since });
+  } catch (err) {
+    process.stderr.write(`::notice::clud-bug usage --health: artifact fetch failed (${err.message}) — falling back to local .clud-bug.json\n`);
+    return null;
+  }
+  if (artifacts.length === 0) {
+    process.stderr.write(`::notice::clud-bug usage --health: no skill-usage artifacts found in ${ownerRepo} — falling back to local .clud-bug.json\n`);
+    return null;
+  }
+  return {
+    usage: aggregateUsageStream(artifacts),
+    artifactCount: artifacts.length,
+  };
+}
+
+async function loadUsageFromLocalFile() {
+  const fs = await import('node:fs/promises');
+  const path = await import('node:path');
+  const jsonPath = path.resolve(process.cwd(), '.claude', 'skills', '.clud-bug.json');
   try {
     const raw = await fs.readFile(jsonPath, 'utf-8');
-    parsed = JSON.parse(raw);
+    const parsed = JSON.parse(raw);
+    return (parsed && parsed.usage) ? parsed.usage : {};
   } catch (err) {
     if (err.code === 'ENOENT') {
       process.stderr.write(
         `clud-bug usage --health: no .claude/skills/.clud-bug.json found in ${process.cwd()}.\n` +
-        `Run \`npx clud-bug init\` first to install the catalog state.\n`
+        `Run \`npx clud-bug init\` first OR pass --repo owner/name to read from workflow artifacts.\n`
       );
-      process.exit(1);
+      return null;
     }
     process.stderr.write(`clud-bug usage --health: failed to parse .clud-bug.json: ${err.message}\n`);
-    process.exit(1);
+    return null;
   }
+}
 
-  const usage = parsed && parsed.usage ? parsed.usage : {};
-  const rows = assessSkillHealth(usage, new Date());
-  process.stdout.write(formatHealthDashboard(rows) + '\n');
+async function inferOwnerRepoFromGit() {
+  // `gh repo view --json nameWithOwner` reads the current dir's git
+  // remote AND respects gh's config. Returns null on non-git dirs.
+  const result = await ghJson(['repo', 'view', '--json', 'nameWithOwner']);
+  return result && result.nameWithOwner ? result.nameWithOwner : null;
+}
 
-  // Exit code semantics: 0 (informational). The dashboard is read-only;
-  // archive-candidates being present is NOT a failure mode — humans
-  // decide. CI gates should NOT block on this.
-  ok(`skill health: ${rows.length} skill${rows.length === 1 ? '' : 's'} tracked`);
+function parseSinceArg(since) {
+  if (!since) return null;
+  if (since instanceof Date) return since;
+  const m = String(since).match(/^(\d+)([dwmy])$/);
+  if (!m) return null;
+  const n = Number(m[1]);
+  const unitMs = { d: 86400e3, w: 7 * 86400e3, m: 30 * 86400e3, y: 365 * 86400e3 }[m[2]];
+  return new Date(Date.now() - n * unitMs);
 }
 
 // limit to 100 to avoid pagination explosions.

package/lib/skill-usage.js

@@ -260,3 +260,173 @@ export function formatHealthDashboard(rows) {
   lines.push('  healthy           = cited within 60 days');
   return lines.join('\n');
 }
+
+// ---------------------------------------------------------------------------
+// v0.6.30 — cross-review aggregation
+//
+// The v0.6.29 workflow post-step uploads `.clud-bug.json` as a per-PR
+// artifact named `clud-bug-skill-usage-pr-<N>` (90-day retention). This
+// section walks the artifact stream + accumulates into one dashboard read.
+//
+// Artifact persistence design choice (recap from v0.6.29): we picked
+// artifacts over commit-back-to-main because commit-back required
+// `contents: write` permission expansion — v0.6.23 hit a regression
+// from a similar expansion. Artifacts are GitHub-native, zero perm
+// widening, zero commit noise. v0.6.30 reads them back here.
+// ---------------------------------------------------------------------------
+
+/**
+ * Default `gh` runner — spawns the local gh CLI. Tests inject a mock.
+ *
+ * The runner has two methods:
+ *   - json(args): returns parsed JSON stdout, or null on error.
+ *   - run(args): returns {code, stdout, stderr}. For commands that
+ *     download files etc. — no JSON parsing.
+ */
+async function defaultGhJson(args) {
+  const { spawn } = await import('node:child_process');
+  return new Promise((resolve) => {
+    const child = spawn('gh', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.on('error', () => resolve(null));
+    child.on('close', (code) => {
+      if (code !== 0) return resolve(null);
+      try { resolve(JSON.parse(stdout)); } catch { resolve(null); }
+    });
+  });
+}
+
+async function defaultGhRun(args) {
+  const { spawn } = await import('node:child_process');
+  return new Promise((resolve) => {
+    const child = spawn('gh', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+    child.on('error', () => resolve({ code: 1, stdout: '', stderr: 'gh not on PATH' }));
+    child.on('close', (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+export const DEFAULT_GH_RUNNER = {
+  json: defaultGhJson,
+  run: defaultGhRun,
+};
+
+/**
+ * Fetch all per-PR skill-usage artifacts from a repo. Each artifact is
+ * downloaded to a temp dir, its `.clud-bug.json` is parsed, and the
+ * usage block is returned.
+ *
+ * @param {object} opts
+ * @param {string} opts.owner - GitHub repo owner.
+ * @param {string} opts.repo - GitHub repo name.
+ * @param {Date|null} opts.since - Filter to artifacts created on/after this date.
+ * @param {object} opts.ghRunner - Injected gh CLI runner (see DEFAULT_GH_RUNNER).
+ *
+ * @returns {Promise<{prNumber: number, artifactId: number, usage: object, fetchedAt: string}[]>}
+ */
+export async function fetchUsageArtifacts({ owner, repo, since = null, ghRunner = DEFAULT_GH_RUNNER }) {
+  if (!owner || !repo) {
+    throw new Error('fetchUsageArtifacts: owner + repo are required');
+  }
+
+  // List artifacts in one call. We deliberately do NOT use `--paginate`:
+  // `gh api --paginate --jq <expr>` applies the jq filter to EACH page
+  // independently and concatenates the outputs with newlines, which
+  // produces `[...]\n[...]` — invalid as a single JSON document.
+  // `JSON.parse` returns null and the dashboard silently shows nothing
+  // for repos with >30 artifacts (default page size). Caught by
+  // clud-bug-review on PR #127.
+  //
+  // `?per_page=100` covers up to 100 artifacts in one call. The 90-day
+  // artifact retention means most repos won't hit that ceiling (>100
+  // PR reviews in 90 days = >1/day sustained). If a future repo
+  // saturates this, paginate manually in v0.6.31+ (per_page=100 +
+  // explicit `?page=N` loop, parse each response as JSON, concatenate).
+  const list = await ghRunner.json([
+    'api',
+    `repos/${owner}/${repo}/actions/artifacts?per_page=100`,
+    '--jq',
+    '[.artifacts[] | select(.name | startswith("clud-bug-skill-usage-pr-")) | select(.expired == false) | {id, name, workflow_run_id: .workflow_run.id, created_at}]',
+  ]);
+
+  // `--jq '[...]'` wraps the stream into a single array. If the runner
+  // returns null (404, no auth, etc.), bail to empty list.
+  if (!Array.isArray(list)) return [];
+
+  const filtered = since
+    ? list.filter((a) => new Date(a.created_at) >= since)
+    : list;
+
+  const fs = await import('node:fs/promises');
+  const path = await import('node:path');
+  const os = await import('node:os');
+
+  const results = [];
+  for (const art of filtered) {
+    const prMatch = art.name.match(/^clud-bug-skill-usage-pr-(\d+)$/);
+    if (!prMatch) continue;
+    const prNumber = Number(prMatch[1]);
+
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'clud-bug-art-'));
+    try {
+      const dl = await ghRunner.run([
+        'run', 'download', String(art.workflow_run_id),
+        '-R', `${owner}/${repo}`,
+        '-n', art.name,
+        '-D', tmpDir,
+      ]);
+      if (dl.code !== 0) continue;
+
+      // The workflow uploaded `.clud-bug.json` (single file under the
+      // path key). `gh run download -D <dir>` writes it to the dest as
+      // `<dir>/.clud-bug.json` (preserves the source path).
+      const jsonPath = path.join(tmpDir, '.clud-bug.json');
+      let parsed;
+      try {
+        const raw = await fs.readFile(jsonPath, 'utf-8');
+        parsed = JSON.parse(raw);
+      } catch {
+        continue; // artifact corrupted or layout unexpected
+      }
+      const usage = parsed && parsed.usage ? parsed.usage : {};
+      results.push({
+        prNumber,
+        artifactId: art.id,
+        usage,
+        fetchedAt: art.created_at,
+      });
+    } finally {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Reduce an array of per-PR artifact records into a single accumulated
+ * usage block by left-folding `mergeSkillUsage` over them, ordered by
+ * `fetchedAt` ascending so the last_cited timestamp is deterministic.
+ *
+ * Because `mergeSkillUsage` is commutative for loads + citations counts
+ * AND keeps the LATEST timestamp it sees as last_cited (we sort
+ * ascending so newest wins on the final pass), out-of-order input
+ * produces an identical result.
+ *
+ * @param {{usage: object, fetchedAt: string}[]} artifacts
+ * @returns {object} accumulated usage block, shape matches mergeSkillUsage output
+ */
+export function aggregateUsageStream(artifacts) {
+  if (!Array.isArray(artifacts) || artifacts.length === 0) return {};
+  const sorted = [...artifacts].sort(
+    (a, b) => new Date(a.fetchedAt) - new Date(b.fetchedAt)
+  );
+  return sorted.reduce(
+    (acc, art) => mergeSkillUsage(acc, art.usage || {}, art.fetchedAt),
+    {}
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clud-bug",
-  "version": "0.6.29",
+  "version": "0.6.30",
   "description": "Skill-driven Claude PR review. Ship a brand-voice skill, get brand reviews. Each finding cites the skill that motivated it. CLI installs the workflow + a baseline kit; add more from skills.sh.",
   "homepage": "https://cludbug.dev",
   "bugs": "https://github.com/thrillmade/clud-bug/issues",

package/templates/workflow-py.yml.tmpl

@@ -363,7 +363,7 @@ jobs:
       # Strict-mode gate — composite action; see workflow.yml.tmpl for design notes.
       - name: Strict mode — fail check on critical findings
         if: success()
-        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.29
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.30
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           # v0.6.22 / 0.0.O: summary now posted by github-actions[bot].

package/templates/workflow-ts.yml.tmpl

@@ -363,7 +363,7 @@ jobs:
       # Strict-mode gate — composite action; see workflow.yml.tmpl for design notes.
       - name: Strict mode — fail check on critical findings
         if: success()
-        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.29
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.30
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           # v0.6.22 / 0.0.O: summary now posted by github-actions[bot].

package/templates/workflow.yml.tmpl

@@ -627,7 +627,7 @@ jobs:
       # Letting the action's own failure fail the check is louder and right.
       - name: Strict mode — fail check on critical findings
         if: success()
-        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.29
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.30
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           # v0.6.22 / 0.0.O: the summary is now posted by the workflow