skillshelf 0.1.0

package/src/commands/update.ts

@@ -0,0 +1,267 @@
+// skl update [name] — re-pull the upstream SKILL.md body for tracked skills.
+//
+// Invariants (the whole point of this command):
+//   - The overlay (<name>.shelf.json) is NEVER touched: taxonomy/bundles survive.
+//   - Only the upstream body (SKILL.md + bundled reference files) is replaced.
+//   - If the LOCAL body diverged from the previously-installed upstream (the user
+//     hand-edited it), DO NOT clobber. Show a diff and skip, unless --force.
+//   - Bundled reference files are refreshed alongside SKILL.md.
+//
+// Read-ish/destructive command. Supports --json for a structured report; --dry-run
+// to preview without writing; --force to overwrite diverged local edits.
+
+import { join, basename } from "node:path";
+import { existsSync } from "node:fs";
+import { cp, rm, readdir } from "node:fs/promises";
+import type { Ctx, LockEntry } from "../types.ts";
+import { readLockfile, recordEntry } from "../core/provenance.ts";
+import {
+  parseStoredSource,
+  fetchSource,
+  cleanupStaging,
+  readSkillBody,
+  unifiedDiff,
+} from "../core/fetch.ts";
+import { hashContent } from "../core/crawl.ts";
+import { parseFrontmatter } from "../lib/frontmatter.ts";
+import { loadLibrary, findByName } from "../core/library.ts";
+
+export const meta = {
+  name: "update",
+  summary: "Re-pull upstream body, preserve overlay, diff if local body diverged",
+  usage: "skl update [name] [--force] [--dry-run] [--json]",
+} as const;
+
+type Outcome = "updated" | "uptodate" | "diverged" | "skipped" | "error";
+
+interface Result {
+  name: string;
+  source: string;
+  channel: string;
+  fromRef: string;
+  toRef: string | null;
+  outcome: Outcome;
+  note: string;
+  diff?: string;
+}
+
+/** Body text after frontmatter, for content comparison/hash. */
+function bodyOf(text: string): string {
+  return parseFrontmatter(text).body;
+}
+
+/** Replace SKILL.md + bundled reference files from upstream; preserve overlay/lock. */
+async function applyUpstream(destDir: string, upstreamDir: string, name: string): Promise<void> {
+  const PRESERVE = new Set([`${name}.shelf.json`, "shelf.lock.json"]);
+  // Remove existing upstream-managed files (everything except overlay/lock/.git).
+  let entries: Awaited<ReturnType<typeof readdir>> = [];
+  try {
+    entries = await readdir(destDir, { withFileTypes: true });
+  } catch {
+    /* dest may not exist yet */
+  }
+  for (const e of entries) {
+    if (PRESERVE.has(e.name) || e.name === ".git") continue;
+    await rm(join(destDir, e.name), { recursive: true, force: true });
+  }
+  // Copy fresh upstream content (minus its .git).
+  await cp(upstreamDir, destDir, {
+    recursive: true,
+    force: true,
+    filter: (s: string) => basename(s) !== ".git",
+  });
+}
+
+async function updateOne(
+  ctx: Ctx,
+  entry: LockEntry,
+  destDir: string,
+  opts: { force: boolean; dryRun: boolean },
+): Promise<Result> {
+  const parsed = parseStoredSource(entry.source);
+  const fetched = await fetchSource(parsed);
+  if (!fetched.ok) {
+    await cleanupStaging(fetched.staging);
+    return {
+      name: entry.name,
+      source: entry.source,
+      channel: entry.channel,
+      fromRef: entry.ref,
+      toRef: null,
+      outcome: "error",
+      note: fetched.error,
+    };
+  }
+
+  try {
+    const upstreamText = await readSkillBody(fetched.skillDir);
+    const localPath = join(destDir, "SKILL.md");
+    const localText = existsSync(localPath) ? await Bun.file(localPath).text() : "";
+
+    const upstreamBody = bodyOf(upstreamText);
+    const localBody = bodyOf(localText);
+
+    const upstreamHash = hashContent(upstreamBody);
+    const localHash = hashContent(localBody);
+
+    // Already current: local body matches upstream and ref unchanged.
+    if (localHash === upstreamHash && fetched.ref === entry.ref) {
+      return {
+        name: entry.name,
+        source: entry.source,
+        channel: entry.channel,
+        fromRef: entry.ref,
+        toRef: fetched.ref,
+        outcome: "uptodate",
+        note: "already at latest upstream body",
+      };
+    }
+
+    // True 3-way divergence: did the USER hand-edit the local body since install?
+    // Compare against installedHash (the upstream body recorded at install/update
+    // time) — NOT against current upstream, so a normal upstream-moved-forward
+    // update is applied, and only genuine local edits are protected.
+    // Legacy entries without installedHash fall back to the localEdits flag.
+    const userEdited =
+      entry.installedHash != null
+        ? localHash !== entry.installedHash
+        : entry.localEdits === true;
+    const localDiverged = userEdited && localHash !== upstreamHash;
+    if (localDiverged && !opts.force) {
+      const diff = await unifiedDiff(
+        localText,
+        upstreamText,
+        `${entry.name} (local)`,
+        `${entry.name} (upstream ${fetched.ref.slice(0, 10)})`,
+      );
+      return {
+        name: entry.name,
+        source: entry.source,
+        channel: entry.channel,
+        fromRef: entry.ref,
+        toRef: fetched.ref,
+        outcome: "diverged",
+        note: "local body diverged from upstream; not clobbering (use --force to overwrite)",
+        diff,
+      };
+    }
+
+    if (opts.dryRun) {
+      return {
+        name: entry.name,
+        source: entry.source,
+        channel: entry.channel,
+        fromRef: entry.ref,
+        toRef: fetched.ref,
+        outcome: "updated",
+        note: opts.force && localDiverged ? "would overwrite diverged local body (dry-run)" : "would update (dry-run)",
+      };
+    }
+
+    // Apply: replace body + ref files, preserve overlay/lock.
+    await applyUpstream(destDir, fetched.skillDir, entry.name);
+
+    // Update lockfile ref + record the new installed body hash + clear localEdits
+    // (the on-disk body now equals upstream again, so we are pristine).
+    const updatedEntry: LockEntry = {
+      ...entry,
+      ref: fetched.ref,
+      installedAt: new Date().toISOString(),
+      localEdits: false,
+      installedHash: upstreamHash,
+    };
+    await recordEntry(ctx.config.libraryPath, updatedEntry);
+
+    return {
+      name: entry.name,
+      source: entry.source,
+      channel: entry.channel,
+      fromRef: entry.ref,
+      toRef: fetched.ref,
+      outcome: "updated",
+      note: opts.force && localDiverged ? "overwrote diverged local body" : "upstream body re-pulled; overlay preserved",
+    };
+  } catch (err) {
+    return {
+      name: entry.name,
+      source: entry.source,
+      channel: entry.channel,
+      fromRef: entry.ref,
+      toRef: fetched.ref,
+      outcome: "error",
+      note: err instanceof Error ? err.message : String(err),
+    };
+  } finally {
+    await cleanupStaging(fetched.staging);
+  }
+}
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const json = argv.includes("--json");
+  const force = argv.includes("--force");
+  const dryRun = argv.includes("--dry-run");
+  const nameArg = argv.find((a) => !a.startsWith("-")) ?? null;
+
+  try {
+    const lock = await readLockfile(ctx.config.libraryPath);
+    let entries = Object.values(lock.entries);
+    if (nameArg) entries = entries.filter((e) => e.name === nameArg);
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+    if (entries.length === 0) {
+      if (json) ctx.json({ ok: true, updated: 0, diverged: 0, results: [] });
+      else if (nameArg) ctx.error(`no tracked skill named "${nameArg}"`);
+      else ctx.log("no tracked third-party skills (lockfile is empty)");
+      return nameArg && !json ? 1 : 0;
+    }
+
+    // Resolve on-disk dirs via the library so renames/domain folders are honored.
+    const library = await loadLibrary(ctx.config.libraryPath);
+
+    const results: Result[] = [];
+    for (const entry of entries) {
+      const skill = findByName(library, entry.name);
+      const destDir = skill?.path ?? join(ctx.config.libraryPath, entry.name);
+      results.push(await updateOne(ctx, entry, destDir, { force, dryRun }));
+    }
+
+    const updated = results.filter((r) => r.outcome === "updated").length;
+    const diverged = results.filter((r) => r.outcome === "diverged").length;
+    const errored = results.filter((r) => r.outcome === "error").length;
+
+    if (json) {
+      ctx.json({ ok: errored === 0, updated, diverged, errors: errored, results });
+    } else {
+      for (const r of results) {
+        const tag =
+          r.outcome === "updated"
+            ? "updated  "
+            : r.outcome === "uptodate"
+              ? "current  "
+              : r.outcome === "diverged"
+                ? "DIVERGED "
+                : r.outcome === "error"
+                  ? "ERROR    "
+                  : "skipped  ";
+        ctx.log(`${tag}  ${r.name.padEnd(28)} ${r.note}`);
+        if (r.outcome === "diverged" && r.diff) {
+          ctx.log("");
+          ctx.log(r.diff.trimEnd());
+          ctx.log("");
+        }
+      }
+      ctx.log("");
+      ctx.log(
+        `${results.length} tracked, ${updated} updated, ${diverged} diverged${errored ? `, ${errored} error(s)` : ""}.`,
+      );
+      if (diverged > 0) ctx.log("re-run with --force to overwrite diverged local bodies.");
+    }
+
+    // Non-zero if any error or any unresolved divergence (blocks CI/agents).
+    if (errored > 0) return 1;
+    return diverged > 0 ? 2 : 0;
+  } catch (err) {
+    ctx.error("update: failed:", err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+}

package/src/commands/use.ts

@@ -0,0 +1,100 @@
+// `skl use <bundle>` — symlink every skill in a bundle into ./.claude/skills/
+// so Claude Code can natively hot-load them. Idempotent: re-running re-points
+// links without error. Reports what was linked (and is JSON-parseable on --json).
+
+import { join } from "node:path";
+import type { Ctx } from "../types.ts";
+import { resolveBundle } from "../core/bundle.ts";
+import { activeSkills } from "../core/library.ts";
+import { safeSymlink, isSymlink, realpathOrSelf, realpathOrSelfAsync } from "../lib/fs.ts";
+
+export const meta = {
+  name: "use",
+  summary: "Symlink a bundle's skills into ./.claude/skills/ (hot-loads)",
+  usage: "skl use <bundle> [--json]",
+} as const;
+
+interface LinkResult {
+  name: string;
+  target: string;
+  link: string;
+  status: "linked" | "already" | "conflict";
+}
+
+/** Project skills dir for the cwd. */
+function projectSkillsDir(): string {
+  return join(process.cwd(), ".claude", "skills");
+}
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  try {
+    const json = argv.includes("--json");
+    const bundleName = argv.find((a) => !a.startsWith("-"));
+
+    if (!bundleName) {
+      ctx.error("usage: " + meta.usage);
+      return 1;
+    }
+
+    const skills = await ctx.loadLibrary();
+    const bundle = await resolveBundle(activeSkills(skills), bundleName);
+
+    if (bundle.skills.length === 0) {
+      if (json) {
+        ctx.json({ bundle: bundleName, linked: [], skillsDir: projectSkillsDir(), error: "empty-bundle" });
+      } else {
+        ctx.error(`No active skills match bundle '${bundleName}'.`);
+      }
+      return 1;
+    }
+
+    const skillsDir = projectSkillsDir();
+    const results: LinkResult[] = [];
+
+    for (const s of bundle.skills) {
+      const link = join(skillsDir, s.name);
+      const target = s.path;
+      let status: LinkResult["status"] = "linked";
+
+      // Determine prior state for accurate reporting before we touch it.
+      if (isSymlink(link)) {
+        const cur = realpathOrSelf(link);
+        const want = await realpathOrSelfAsync(target);
+        if (cur === want) status = "already";
+      } else if (await pathTakenNonLink(link)) {
+        // A real (non-symlink) file/dir occupies the slot — don't clobber it.
+        results.push({ name: s.name, target, link, status: "conflict" });
+        continue;
+      }
+
+      await safeSymlink(target, link);
+      results.push({ name: s.name, target, link, status });
+    }
+
+    const conflicts = results.filter((r) => r.status === "conflict");
+
+    if (json) {
+      ctx.json({ bundle: bundle.name, skillsDir, linked: results });
+    } else {
+      ctx.log(`Bundle '${bundle.name}' -> ${skillsDir}`);
+      for (const r of results) {
+        const tag =
+          r.status === "linked" ? "linked" : r.status === "already" ? "ok" : "SKIP (real file present)";
+        ctx.log(`  ${r.name}  [${tag}]`);
+      }
+      ctx.log("");
+      ctx.log("Reminder: add '.claude/skills/' to this project's .gitignore so these symlinks aren't committed.");
+    }
+
+    return conflicts.length > 0 ? 1 : 0;
+  } catch (err) {
+    ctx.error(`skl use failed: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}
+
+/** True if linkPath exists as a real (non-symlink) entry. */
+async function pathTakenNonLink(linkPath: string): Promise<boolean> {
+  const { existsSync } = await import("node:fs");
+  return existsSync(linkPath) && !isSymlink(linkPath);
+}

package/src/config.ts

@@ -0,0 +1,107 @@
+// Configuration resolution + Ctx construction.
+// Library path resolution order:
+//   1. env SKILLSHELF_LIBRARY
+//   2. ~/.skillshelf/config.json  { "library": "...", "globalCore": "..." }
+//   3. default ~/.skillshelf/library
+// Global-core symlink target defaults to ~/.claude/skills.
+
+import { homedir } from "node:os";
+import { join, resolve, isAbsolute } from "node:path";
+import { existsSync } from "node:fs";
+import type { Config, ConfigFile, Ctx, Skill } from "./types.ts";
+
+export const DEFAULT_CONFIG_FILE = join(homedir(), ".skillshelf", "config.json");
+export const DEFAULT_LIBRARY = join(homedir(), ".skillshelf", "library");
+export const DEFAULT_GLOBAL_CORE = join(homedir(), ".claude", "skills");
+
+function expandHome(p: string): string {
+  if (p === "~") return homedir();
+  if (p.startsWith("~/")) return join(homedir(), p.slice(2));
+  return p;
+}
+
+function abs(p: string): string {
+  const e = expandHome(p);
+  return isAbsolute(e) ? e : resolve(e);
+}
+
+async function readConfigFile(file: string): Promise<ConfigFile | null> {
+  if (!existsSync(file)) return null;
+  try {
+    const text = await Bun.file(file).text();
+    const parsed = JSON.parse(text) as ConfigFile;
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the full Config (library path + global-core target + provenance).
+ * `configFilePath` override is mainly for tests.
+ */
+export async function resolveConfig(opts: {
+  env?: NodeJS.ProcessEnv;
+  configFilePath?: string;
+} = {}): Promise<Config> {
+  const env = opts.env ?? process.env;
+  const configFilePath = opts.configFilePath ?? DEFAULT_CONFIG_FILE;
+
+  const fileCfg = await readConfigFile(configFilePath);
+  const usedConfigFile = fileCfg ? configFilePath : null;
+
+  let libraryPath: string;
+  let source: Config["source"];
+
+  const envLib = env.SKILLSHELF_LIBRARY;
+  if (envLib && envLib.trim() !== "") {
+    libraryPath = abs(envLib.trim());
+    source = "env";
+  } else if (fileCfg?.library && fileCfg.library.trim() !== "") {
+    libraryPath = abs(fileCfg.library.trim());
+    source = "config";
+  } else {
+    libraryPath = DEFAULT_LIBRARY;
+    source = "default";
+  }
+
+  const globalCoreTarget =
+    env.SKILLSHELF_GLOBAL_CORE && env.SKILLSHELF_GLOBAL_CORE.trim() !== ""
+      ? abs(env.SKILLSHELF_GLOBAL_CORE.trim())
+      : fileCfg?.globalCore && fileCfg.globalCore.trim() !== ""
+        ? abs(fileCfg.globalCore.trim())
+        : DEFAULT_GLOBAL_CORE;
+
+  return { libraryPath, globalCoreTarget, configFile: usedConfigFile, source };
+}
+
+/**
+ * Build the execution Ctx handed to every command's run().
+ * `loadLibrary` is lazily wired to avoid a circular import at module load.
+ */
+export async function loadContext(opts: {
+  env?: NodeJS.ProcessEnv;
+  configFilePath?: string;
+} = {}): Promise<Ctx> {
+  const config = await resolveConfig(opts);
+
+  const ctx: Ctx = {
+    config,
+    libraryPath: config.libraryPath,
+    loadLibrary: async (): Promise<Skill[]> => {
+      const { loadLibrary } = await import("./core/library.ts");
+      return loadLibrary(config.libraryPath);
+    },
+    log: (...args: unknown[]) => {
+      console.log(...args);
+    },
+    json: (value: unknown) => {
+      console.log(JSON.stringify(value));
+    },
+    error: (...args: unknown[]) => {
+      console.error(...args);
+    },
+  };
+
+  return ctx;
+}

package/src/core/bundle.ts

@@ -0,0 +1,62 @@
+// Bundles = tag queries over domains[]. Resolving a bundle yields every skill
+// tagged with the bundle's domain (regardless of physical folder). Plus explicit
+// overlay bundle membership.
+
+import type { Bundle, Skill } from "../types.ts";
+import { overlayBundles } from "./overlay.ts";
+
+/**
+ * Resolve a single bundle name against the library. A skill is in the bundle if:
+ *   - its `domains[]` contains the bundle name, OR
+ *   - its overlay `bundles[]` lists the bundle name.
+ * Retired skills are excluded by default.
+ */
+export async function resolveBundle(
+  skills: Skill[],
+  bundleName: string,
+  opts: { includeRetired?: boolean } = {},
+): Promise<Bundle> {
+  const name = bundleName.trim();
+  const matched: Skill[] = [];
+  for (const s of skills) {
+    if (s.retired && !opts.includeRetired) continue;
+    if (s.domains.includes(name)) {
+      matched.push(s);
+      continue;
+    }
+    const ob = await overlayBundles(s);
+    if (ob.includes(name)) matched.push(s);
+  }
+  matched.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  return { name, skills: matched };
+}
+
+/**
+ * List every available bundle (one per distinct domain tag) with its resolved
+ * skills. Useful for `skl ls` with no argument and the trigger-bridge menu.
+ */
+export async function listBundles(
+  skills: Skill[],
+  opts: { includeRetired?: boolean } = {},
+): Promise<Bundle[]> {
+  const names = new Set<string>();
+  for (const s of skills) {
+    if (s.retired && !opts.includeRetired) continue;
+    for (const d of s.domains) names.add(d);
+    for (const b of await overlayBundles(s)) names.add(b);
+  }
+  const bundles: Bundle[] = [];
+  for (const name of [...names].sort()) {
+    bundles.push(await resolveBundle(skills, name, opts));
+  }
+  return bundles;
+}
+
+/** Synchronous resolve when overlays were already merged into domains[]. */
+export function resolveBundleSync(skills: Skill[], bundleName: string): Bundle {
+  const name = bundleName.trim();
+  const matched = skills
+    .filter((s) => !s.retired && s.domains.includes(name))
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  return { name, skills: matched };
+}

package/src/core/core.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+import { join } from "node:path";
+import { loadLibrary, searchSkills, findByName } from "./library.ts";
+import { findDuplicates, driftedGroups } from "./dedupe.ts";
+import { resolveBundle } from "./bundle.ts";
+import { generateIndex } from "./indexgen.ts";
+
+const FIXTURES = join(import.meta.dir, "..", "..", "fixtures", "library");
+
+describe("core against fixtures", () => {
+  test("loads all skills with overlays + provenance + mirrors + retired", async () => {
+    const lib = await loadLibrary(FIXTURES);
+    expect(lib.length).toBe(12);
+
+    const retired = lib.filter((s) => s.retired).map((s) => s.name);
+    expect(retired).toContain("old-deseq-helper");
+
+    const mirror = lib.find((s) => s.mirrorOf);
+    expect(mirror?.name).toBe("commit-push");
+    expect(mirror?.primaryDomain).toBe("coding");
+
+    const thirdParty = findByName(lib, "xhs-title");
+    expect(thirdParty?.source?.source).toBe(
+      "github:dontbesilent2025/dbskill@skills/xhs-title",
+    );
+    // overlay added green-card domain
+    expect(thirdParty?.domains).toContain("green-card");
+
+    const qc = findByName(lib, "rnaseq-qc");
+    expect(qc?.refFiles.length).toBe(1);
+  });
+
+  test("detects drifted duplicate scrna-cluster + identical commit-push mirror", async () => {
+    const lib = await loadLibrary(FIXTURES);
+    const groups = findDuplicates(lib);
+    const drifted = driftedGroups(groups).map((g) => g.name);
+    expect(drifted).toContain("scrna-cluster");
+
+    const commit = groups.find((g) => g.name === "commit-push");
+    expect(commit?.identical).toBe(true);
+  });
+
+  test("bundle resolves by domain + overlay membership", async () => {
+    const lib = await loadLibrary(FIXTURES);
+    const bio = await resolveBundle(lib, "bioinfo");
+    expect(bio.skills.map((s) => s.name)).toContain("rnaseq-qc");
+    expect(bio.skills.some((s) => s.retired)).toBe(false);
+
+    const gc = await resolveBundle(lib, "green-card");
+    const names = gc.skills.map((s) => s.name);
+    expect(names).toContain("eb1a-evidence");
+    expect(names).toContain("xhs-title"); // via overlay union
+  });
+
+  test("search ranks name match high", async () => {
+    const lib = await loadLibrary(FIXTURES);
+    const res = searchSkills(lib, "commit");
+    expect(res[0]?.name).toBe("commit-push");
+  });
+
+  test("generateIndex groups by domain and lists retired", async () => {
+    const lib = await loadLibrary(FIXTURES);
+    const md = generateIndex(lib, { generatedAt: "FIXED" });
+    expect(md).toContain("## bioinfo");
+    expect(md).toContain("## _retired");
+    expect(md).toContain("old-deseq-helper");
+  });
+});