@spardutti/claude-skills 2.59.1 → 2.60.0

package/bin/cli.mjs

@@ -8,13 +8,13 @@ import { dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { fetchSkills, fetchCommands, fetchAgents } from "../lib/github.mjs";
 import { promptSkillSelection, promptCommandSelection, promptRemoval } from "../lib/prompt.mjs";
-import { installSkills, installCommands, installRequiredAgents } from "../lib/install.mjs";
+import { installSkills, installCommands, installRequiredAgents, withRequiredCommands } from "../lib/install.mjs";
 import { makeLocalSource } from "../lib/local.mjs";
 import { runPostInstall } from "../lib/post-install.mjs";
 import { runSync, runSyncAll } from "../lib/sync.mjs";
 import {
   readManifest, writeManifest, computeOrphans, computeRemovals, scanInstalled, removeArtifacts,
-  MANIFEST_FILE,
+  catalogIds, MANIFEST_FILE,
 } from "../lib/manifest.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -104,7 +104,7 @@ async function main() {
   let installedAgents = [];
   if (commands.length > 0) {
     console.log();
-    selectedCommands = await promptCommandSelection(commands, manifest?.commands ?? []);
+    selectedCommands = withRequiredCommands(await promptCommandSelection(commands, manifest?.commands ?? []), commands);
     if (selectedCommands.length > 0) {
       console.log();
       await installCommands(selectedCommands);
@@ -141,6 +141,7 @@ async function main() {
     skills: selectedSkills.map((s) => s.dirName),
     commands: selectedCommands.map((c) => c.fileName),
     agents: installedAgents.map((a) => a.fileName),
+    known: catalogIds(catalog),
   });
 
   const parts = [];

package/hooks/registry.mjs

@@ -71,7 +71,11 @@ function stale() {
     if (!syms.length) say("extend_by names no symbol — write names like `AimStrategy`");
     const code = files.filter((f) => insideLocation(e, f) && !f.endsWith(REGISTRY_SUFFIX))
       .map((f) => readFileSync(join(root, f), "utf8")).join("\n");
-    for (const s of syms) if (!uses(code, s)) say(`${s} from extend_by is not found in ${e.location}`);
+    for (const s of syms) {
+      // A plain word like `first` matches `var first = enemies[0]`; `Aim.first` only matches real use.
+      if (/^[a-z][a-z0-9]*$/.test(s)) say(`\`${s}\` is too common a word to prove use — name its owner, like \`Owner.${s}\``);
+      else if (!s.split(".").every((part) => uses(code, part))) say(`${s} from extend_by is not found in ${e.location}`);
+    }
   }
   if (problems.length) fail(problems);
 }

package/hooks/ship-log.mjs

@@ -57,20 +57,21 @@ function finalize(dir, path, record, tag, status, reason, at) {
 }
 
 function prOf(branch) {
-  const r = spawnSync("gh", ["pr", "list", "--head", branch, "--state", "all", "--json", "number,createdAt", "--limit", "1"], { encoding: "utf8" });
+  const r = spawnSync("gh", ["pr", "list", "--head", branch, "--state", "all", "--json", "number,createdAt,state", "--limit", "1"], { encoding: "utf8" });
   try { return r.status === 0 ? JSON.parse(r.stdout)[0] : undefined; } catch { return undefined; }
 }
 
 // Agents skip the `pr` call, so a log whose branch has a PR by now is closed at that PR.
 // A PR older than the log was only updated by it, so that log ends at its own last event.
+// A long-lived branch like dev keeps its merged PRs, so an old one that is not open is not this log's.
 function closeOpened(dir, app) {
   const open = join(dir, "open");
   for (const f of existsSync(open) ? readdirSync(open).filter((n) => n.startsWith(`${app}__`)) : []) {
     const path = join(open, f), record = JSON.parse(readFileSync(path, "utf8"));
     if (!record.gate.length && !record.findings.length) continue;
     const pr = prOf(record.branch);
-    if (!pr) continue;
-    const opened = pr.createdAt >= record.started;
+    const opened = pr && pr.createdAt >= record.started;
+    if (!pr || (!opened && pr.state !== "OPEN")) continue;
     finalize(dir, path, Object.assign(record, { pr: pr.number }), `pr${pr.number}`,
       opened ? "pr-opened" : "pr-updated", null, opened ? pr.createdAt : lastEvent(record));
   }

package/lib/frontmatter.mjs

@@ -16,7 +16,7 @@
 export function parseFrontmatter(content, fallbackName) {
   const match = content.match(/^---\n([\s\S]*?)\n---/);
   if (!match) {
-    return { name: fallbackName, description: "", category: "General", requiresAgents: [] };
+    return { name: fallbackName, description: "", category: "General", requiresAgents: [], requiresCommands: [] };
   }
   const block = match[1];
 
@@ -33,6 +33,7 @@ export function parseFrontmatter(content, fallbackName) {
     description: pick("description"),
     category: pick("category") || "General",
     requiresAgents: parseAgentList(pick("requires-agents")),
+    requiresCommands: parseAgentList(pick("requires-commands")),
   };
 }
 

package/lib/github.mjs

@@ -154,8 +154,8 @@ export function fetchCommands() {
     entryFilter: (e) => e.type === "file" && e.name.endsWith(".md"),
     buildRawUrl: (file) => `${RAW_COMMANDS_BASE}/${file.name}`,
     mapEntry: (file, content) => {
-      const { name, description, category, requiresAgents } = parseFrontmatter(content, file.name.replace(/\.md$/, ""));
-      return { fileName: file.name, name, description, category, requiresAgents, content };
+      const { name, description, category, requiresAgents, requiresCommands } = parseFrontmatter(content, file.name.replace(/\.md$/, ""));
+      return { fileName: file.name, name, description, category, requiresAgents, requiresCommands, content };
     },
   });
 }

package/lib/install.mjs

@@ -43,6 +43,18 @@ export function installAgents(agents, targetDir = process.cwd()) {
   return installFlat(agents, "agents", targetDir);
 }
 
+// A command that names another in `requires-commands` breaks without it, so it comes along.
+export function withRequiredCommands(selected, catalogCommands) {
+  const out = [...selected];
+  for (let i = 0; i < out.length; i++) {
+    for (const name of out[i].requiresCommands ?? []) {
+      const dep = catalogCommands.find((c) => c.name === name);
+      if (dep && !out.some((c) => c.fileName === dep.fileName)) out.push(dep);
+    }
+  }
+  return out;
+}
+
 export async function installRequiredAgents(selectedCommands, availableAgents, targetDir = process.cwd()) {
   const requiredNames = new Set(
     selectedCommands.flatMap((c) => c.requiresAgents ?? [])

package/lib/local.mjs

@@ -39,8 +39,8 @@ export function makeLocalSource(root) {
       for (const f of await listDir(join(root, "commands"))) {
         if (!f.isFile() || !f.name.endsWith(".md")) continue;
         const content = await readFile(join(root, "commands", f.name), "utf-8");
-        const { name, description, category, requiresAgents } = parseFrontmatter(content, f.name.replace(/\.md$/, ""));
-        out.push({ fileName: f.name, name, description, category, requiresAgents, content });
+        const { name, description, category, requiresAgents, requiresCommands } = parseFrontmatter(content, f.name.replace(/\.md$/, ""));
+        out.push({ fileName: f.name, name, description, category, requiresAgents, requiresCommands, content });
       }
       return out;
     },

package/lib/manifest.mjs

@@ -17,6 +17,7 @@ export async function readManifest(targetDir = process.cwd()) {
       commands: data.commands ?? [],
       agents: data.agents ?? [],
       custom: data.custom ?? [],
+      known: data.known ?? null,
     };
   } catch {
     return null; // no manifest — a pre-manifest project or a fresh install
@@ -25,9 +26,10 @@ export async function readManifest(targetDir = process.cwd()) {
 
 // Record exactly what the CLI has installed. This is the CLI's source of truth —
 // it never deletes anything not listed here. `custom` is the user's own gated skills, carried over untouched.
-export async function writeManifest(targetDir, { catalogVersion, skills, commands, agents }) {
+export async function writeManifest(targetDir, { catalogVersion, skills, commands, agents, known }) {
   await mkdir(join(targetDir, ".claude"), { recursive: true });
-  const custom = (await readManifest(targetDir))?.custom ?? [];
+  const previous = await readManifest(targetDir);
+  const custom = previous?.custom ?? [];
   const data = {
     catalogVersion,
     installedAt: new Date().toISOString(),
@@ -35,10 +37,16 @@ export async function writeManifest(targetDir, { catalogVersion, skills, command
     commands: [...new Set(commands)].sort(),
     agents: [...new Set(agents)].sort(),
     custom,
+    known: [...new Set(known ?? previous?.known ?? [])].sort(),
   };
   await writeFile(manifestPath(targetDir), JSON.stringify(data, null, 2) + "\n");
 }
 
+// Every skill and command in the catalog, so the next sync can name what is new since.
+export function catalogIds(catalog) {
+  return [...catalog.skills.map((s) => s.dirName), ...catalog.commands.map((c) => c.fileName)];
+}
+
 // Manifest entries that no longer exist in the current catalog (renamed or removed upstream).
 export function computeOrphans(manifest, catalog) {
   if (!manifest) return { skills: [], commands: [], agents: [] };

package/lib/sync.mjs

@@ -2,13 +2,27 @@ import chalk from "chalk";
 import { existsSync } from "node:fs";
 import { readdir } from "node:fs/promises";
 import { join, basename } from "node:path";
-import { installSkills, installCommands, installRequiredAgents } from "./install.mjs";
+import { installSkills, installCommands, installRequiredAgents, withRequiredCommands } from "./install.mjs";
 import { setupHook } from "./setup-hook.mjs";
 import { setupClaudeMd } from "./setup-claude-md.mjs";
-import { readManifest, writeManifest, computeOrphans, removeArtifacts, MANIFEST_FILE } from "./manifest.mjs";
+import { readManifest, writeManifest, computeOrphans, removeArtifacts, catalogIds, MANIFEST_FILE } from "./manifest.mjs";
 
 const SEARCH_DEPTH = 5;
 
+// Sync installs only what was picked, so a new skill or command would otherwise go unseen.
+function announceNew(manifest, catalog, have) {
+  if (!manifest.known) return;
+  const known = new Set(manifest.known);
+  const fresh = [
+    ...catalog.skills.map((s) => ({ id: s.dirName, label: s.name, about: s.description })),
+    ...catalog.commands.map((c) => ({ id: c.fileName, label: `/${c.name}`, about: c.description })),
+  ].filter((x) => !known.has(x.id) && !have.has(x.id));
+  if (fresh.length === 0) return;
+  console.log();
+  for (const x of fresh) console.log(`  ${chalk.cyan("new")} ${chalk.bold(x.label)} — ${x.about.split(" — ")[0].slice(0, 100)}`);
+  console.log(chalk.dim("  Run the CLI without --sync to pick any of them."));
+}
+
 // Re-install everything the manifest records (refreshed to the latest catalog),
 // refresh hooks the project already has, and prune anything removed upstream.
 export async function runSync(dir, catalog, version) {
@@ -25,17 +39,21 @@ export async function runSync(dir, catalog, version) {
   }
 
   const skills = catalog.skills.filter((s) => manifest.skills.includes(s.dirName));
-  const commands = catalog.commands.filter((c) => manifest.commands.includes(c.fileName));
+  const picked = catalog.commands.filter((c) => manifest.commands.includes(c.fileName));
+  const commands = withRequiredCommands(picked, catalog.commands);
+  for (const c of commands.slice(picked.length)) console.log(`  ${chalk.green("+")} Added ${chalk.bold(`/${c.name}`)} — a command you have needs it.`);
   if (skills.length > 0) { console.log(); await installSkills(skills, dir); }
   if (commands.length > 0) { console.log(); await installCommands(commands, dir); }
   const { installed } = await installRequiredAgents(commands, catalog.agents, dir);
   if (existsSync(join(dir, ".claude", "hooks", "skill-gate.sh"))) { console.log(); await setupHook(dir); await setupClaudeMd(dir); }
+  announceNew(manifest, catalog, new Set([...skills.map((s) => s.dirName), ...commands.map((c) => c.fileName)]));
 
   await writeManifest(dir, {
     catalogVersion: version,
     skills: skills.map((s) => s.dirName),
     commands: commands.map((c) => c.fileName),
     agents: installed.map((a) => a.fileName),
+    known: catalogIds(catalog),
   });
   console.log(`\n  ${chalk.green("✔")} ${chalk.bold(`Synced to catalog v${version}.`)}\n`);
   return true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.59.1",
+  "version": "2.60.0",
   "description": "Guardrails for Claude Code — best-practice skills, planning commands, and delivery gates.",
   "type": "module",
   "repository": {