clud-bug 0.4.1 → 0.5.0

package/bin/clud-bug.js

@@ -107,7 +107,13 @@ async function runInit(args) {
   log(`    search terms:     ${signals.searchTerms.join(', ') || '(none)'}`);
 
   const baseline = await loadBaseline(BASELINE_DIR);
-  log(`    baseline kit:     ${baseline.length} specimens`);
+  const fromAgentSkills = baseline.filter((s) => s._source === 'agent-skills').length;
+  const sourceLabel = baseline.length === 0
+    ? ''
+    : fromAgentSkills === baseline.length ? ' (from thrillmot/agent-skills)'
+    : fromAgentSkills === 0               ? ' (bundled fallback)'
+                                          : ` (${fromAgentSkills} from agent-skills, ${baseline.length - fromAgentSkills} bundled)`;
+  log(`    baseline kit:     ${baseline.length} specimens${sourceLabel}`);
 
   let curated = [];
   let searched = [];

package/lib/skills.js

@@ -1,11 +1,26 @@
 import { mkdir, writeFile, readdir, readFile, rm, stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
 
 const API_BASE = 'https://skills.sh/api/v1';
 const MAX_SKILLS = 8;
 const MANIFEST_FILE = '.clud-bug.json';
 const MANIFEST_VERSION = 1;
 
+// Canonical home for clud-bug's baseline skills.
+// PINNED TO A COMMIT SHA, NOT `main`. This re-couples the trust boundary
+// to clud-bug releases: a compromised commit on agent-skills@main cannot
+// silently land in users' Claude review skills mid-cycle. To roll new
+// skill content, bump BASELINE_SKILLS_REF below in the same clud-bug PR
+// that ships the corresponding bundled fallback update.
+// See thrillmot/agent-skills — skills.sh `skills/<name>/SKILL.md` layout.
+const BASELINE_SKILLS_REF = '977e439ec861860351239ed89dd56edcd48cbf6b';
+const AGENT_SKILLS_BASE = process.env.CLUD_BUG_AGENT_SKILLS_BASE
+  ?? `https://raw.githubusercontent.com/thrillmot/agent-skills/${BASELINE_SKILLS_REF}/skills`;
+const SKILL_FETCH_TIMEOUT_MS = 5000;
+const SKILL_CACHE_TTL_MS = 24 * 60 * 60 * 1000;   // 24h
+
 export class SkillsClient {
   constructor({ fetch = globalThis.fetch, base, userAgent = 'clud-bug' } = {}) {
     this.fetch = fetch;
@@ -78,7 +93,34 @@ export function rankAndCap(curated, searched, baseline, cap = MAX_SKILLS) {
   return out;
 }
 
-export async function loadBaseline(baselineDir) {
+// Loads the baseline skills, preferring the pinned thrillmot/agent-skills
+// commit and falling back to the bundled npm-package copy on any fetch failure.
+// Returns the same shape as before, plus a `_source` of either 'agent-skills'
+// or 'bundled' so the CLI can report which path was used.
+//
+// Options:
+//   - fetch     — injectable for tests (defaults to globalThis.fetch)
+//   - cacheDir  — where to cache fetched SKILL.md files (defaults to
+//                 ~/.cache/clud-bug/skills/, skipped if null)
+export async function loadBaseline(baselineDir, opts = {}) {
+  const fetchImpl = opts.fetch ?? globalThis.fetch;
+  const cacheDir = opts.cacheDir === null ? null
+    : (opts.cacheDir ?? join(homedir(), '.cache', 'clud-bug', 'skills'));
+
+  // First, enumerate the bundled baseline skills (source of truth for which
+  // names exist). Then fetch each in parallel — sequential awaits would
+  // stack timeouts (3 baselines × 5s = 15s before fallback when offline).
+  const bundled = await readBundled(baselineDir);
+  const remotes = await Promise.all(
+    bundled.map((s) => tryFetchSkill(s.name, fetchImpl, cacheDir)),
+  );
+  return bundled.map((skill, i) => remotes[i]
+    ? { ...skill, content: remotes[i], _source: 'agent-skills' }
+    : { ...skill, _source: 'bundled' });
+}
+
+// Reads the bundled baseline from the npm-package directory.
+async function readBundled(baselineDir) {
   const skills = [];
   let entries;
   try {
@@ -92,7 +134,7 @@ export async function loadBaseline(baselineDir) {
     skills.push({
       source: 'clud-bug-baseline',
       name: entry.name.replace(/\.md$/, ''),
-      description: '(bundled baseline)',
+      description: '(baseline)',
       installs: 0,
       kind: 'baseline',
       content,
@@ -101,6 +143,65 @@ export async function loadBaseline(baselineDir) {
   return skills;
 }
 
+// Try to read from cache, then fall back to network. Returns the SKILL.md
+// content string on success, null on any failure (caller falls back to bundled).
+async function tryFetchSkill(name, fetchImpl, cacheDir) {
+  // Cache lookup first.
+  if (cacheDir) {
+    const cached = await readFromCache(cacheDir, name);
+    if (cached !== null) return cached;
+  }
+
+  // Network fetch with timeout covering BOTH the connection AND the body
+  // read (clearTimeout in finally guarantees the timer doesn't keep the
+  // event loop alive for up to 5s past a failed CLI run).
+  const url = `${AGENT_SKILLS_BASE}/${encodeURIComponent(name)}/SKILL.md`;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), SKILL_FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetchImpl(url, { signal: ctrl.signal });
+    if (!res.ok) return null;
+    const content = await res.text();
+    if (!content || !content.trim()) return null;
+    if (cacheDir) await writeToCache(cacheDir, name, content);
+    return content;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function readFromCache(cacheDir, name) {
+  const path = cachePath(cacheDir, name);
+  try {
+    const st = await stat(path);
+    if (Date.now() - st.mtimeMs > SKILL_CACHE_TTL_MS) return null;
+    return await readFile(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+async function writeToCache(cacheDir, name, content) {
+  try {
+    await mkdir(cacheDir, { recursive: true });
+    await writeFile(cachePath(cacheDir, name), content);
+  } catch {
+    // Cache write failures are non-fatal — we already have the content.
+  }
+}
+
+function cachePath(cacheDir, name) {
+  // Include AGENT_SKILLS_BASE in the hash so different upstream URLs (e.g.
+  // a fork via CLUD_BUG_AGENT_SKILLS_BASE, or a different pinned SHA after
+  // a clud-bug release) get different cache entries. Otherwise switching
+  // bases would silently return the previously-cached content from a
+  // different upstream — cross-base cache poisoning.
+  const hash = createHash('sha256').update(`${AGENT_SKILLS_BASE}\n${name}`).digest('hex').slice(0, 16);
+  return join(cacheDir, `${hash}.md`);
+}
+
 export async function writeSkills(targetDir, skills, client) {
   await mkdir(targetDir, { recursive: true });
   const written = [];

package/lib/update.js

@@ -21,6 +21,7 @@ export async function runUpdate({
   baselineDir,
   ourVersion,
   refreshRemote = false,
+  loadBaselineOpts,    // forwarded to loadBaseline (e.g. for tests: { fetch, cacheDir: null })
 } = {}) {
   if (!cwd || !templatesDir || !baselineDir || !ourVersion) {
     throw new Error('runUpdate requires cwd, templatesDir, baselineDir, ourVersion');
@@ -51,7 +52,7 @@ export async function runUpdate({
   }
 
   // 3. Refresh baseline skills (always controlled by clud-bug).
-  const baseline = await loadBaseline(baselineDir);
+  const baseline = await loadBaseline(baselineDir, loadBaselineOpts);
   for (const skill of baseline) {
     const skillPath = join(skillsDir, sanitize(skill.name), 'SKILL.md');
     await maybeWrite(skillPath, skill.content, changed, unchanged, `baseline ${skill.name}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clud-bug",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "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",