skillshelf 0.2.0 → 0.4.0

package/src/commands/refresh.ts

@@ -0,0 +1,133 @@
+// `skl refresh` — re-sync THIS project's ./.claude/skills/ symlinks to current library
+// reality. The idempotent re-`use` was already the de-facto re-sync; this names it.
+//
+// For every managed symlink in the project skills dir:
+//   - resolves to a library skill that still exists  -> repoint at its current path
+//     (repairs a relocated library: SKILLSHELF_LIBRARY moved, absolute link stale)
+//   - the same-named library skill no longer exists   -> prune (renamed/removed/retired)
+//   - points somewhere unrelated (not a library skill) -> left untouched
+//
+// Deliberately does NOT expand bundles (that would guess intent) — to pick up NEW
+// members of a bundle, re-run `skl use <bundle>` (also idempotent).
+//
+//   skl refresh [--dry-run] [--json]
+
+import { join, resolve, isAbsolute, dirname } from "node:path";
+import { readdir, readlink } from "node:fs/promises";
+import type { Ctx, Skill } from "../types.ts";
+import { activeSkills } from "../core/library.ts";
+import {
+  pathExists,
+  isSymlink,
+  realpathOrSelf,
+  realpathOrSelfAsync,
+  safeSymlink,
+  removeSymlink,
+} from "../lib/fs.ts";
+
+/** Direct entry names in a dir that are symlinks — INCLUDING dead ones (which
+ *  listDirNames drops because they don't resolve to a directory). */
+async function symlinkNames(dir: string): Promise<string[]> {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries.filter((e) => e.isSymbolicLink()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+export const meta = {
+  name: "refresh",
+  summary: "Re-sync this project's .claude/skills symlinks to current library reality",
+  usage: "skl refresh [--dry-run] [--json]",
+} as const;
+
+type Action = "repointed" | "ok" | "pruned" | "foreign";
+
+interface Outcome {
+  name: string;
+  action: Action;
+}
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const json = argv.includes("--json");
+  const dryRun = argv.includes("--dry-run");
+  const skillsDir = join(process.cwd(), ".claude", "skills");
+
+  try {
+    const skills = activeSkills(await ctx.loadLibrary());
+    const byName = new Map<string, Skill>(skills.map((s) => [s.name, s]));
+    // Two library prefixes: realpath (resolves /tmp -> /private/tmp etc.) and the
+    // plain resolved path. A DEAD link's target can't be realpath'd, so we match its
+    // raw readlink target against either form to decide if it pointed into the library.
+    const libPrefixes = [realpathOrSelf(ctx.libraryPath), resolve(ctx.libraryPath)].map((p) =>
+      p.endsWith("/") ? p : p + "/",
+    );
+
+    const outcomes: Outcome[] = [];
+    if (pathExists(skillsDir)) {
+      for (const name of await symlinkNames(skillsDir)) {
+        const link = join(skillsDir, name);
+        if (!isSymlink(link)) continue; // only manage symlinks; never touch real files
+        const skill = byName.get(name);
+
+        if (skill) {
+          // The same-named library skill exists: ensure the link points at it.
+          const cur = realpathOrSelf(link);
+          const want = await realpathOrSelfAsync(skill.path);
+          if (cur === want) {
+            outcomes.push({ name, action: "ok" });
+          } else {
+            if (!dryRun) await safeSymlink(skill.path, link, { force: true });
+            outcomes.push({ name, action: "repointed" });
+          }
+          continue;
+        }
+
+        // No same-named library skill. Read the RAW target to decide if it pointed
+        // into the library (renamed/removed -> prune) or somewhere unrelated (leave).
+        const raw = await readlink(link).catch(() => null);
+        const targetAbs = raw == null ? "" : isAbsolute(raw) ? raw : resolve(dirname(link), raw);
+        // Strictly UNDER the library (a per-skill entry) — a link to the library ROOT
+        // itself was never a skill deployment, so leave it as `foreign` rather than prune.
+        const pointsIntoLibrary = libPrefixes.some((pre) => targetAbs.startsWith(pre));
+
+        if (pointsIntoLibrary) {
+          // Was a library skill (link still resolves into the library tree) but no
+          // active skill of this name remains — renamed/removed/retired. Prune.
+          if (!dryRun) await removeSymlink(link, { force: true });
+          outcomes.push({ name, action: "pruned" });
+        } else {
+          outcomes.push({ name, action: "foreign" });
+        }
+      }
+    }
+
+    const count = (a: Action) => outcomes.filter((o) => o.action === a).length;
+    if (json) {
+      ctx.json({
+        dryRun,
+        skillsDir,
+        outcomes,
+        repointed: count("repointed"),
+        pruned: count("pruned"),
+        ok: count("ok"),
+      });
+      return 0;
+    }
+
+    if (outcomes.length === 0) {
+      ctx.log(`No managed symlinks in ${skillsDir} — nothing to refresh.`);
+      return 0;
+    }
+    const verb = dryRun ? "would" : "did";
+    ctx.log(`Refresh ${skillsDir}:`);
+    for (const o of outcomes) ctx.log(`  ${o.name}  [${o.action}]`);
+    ctx.log("");
+    ctx.log(`${count("repointed")} repointed, ${count("pruned")} pruned, ${count("ok")} already current (${verb} apply).`);
+    return 0;
+  } catch (err) {
+    ctx.error(`skl refresh: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}

package/src/commands/remediation.test.ts

@@ -0,0 +1,149 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, symlink, rm, realpath } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { remediate } from "./where.ts";
+import { run as refreshRun } from "./refresh.ts";
+import { run as statusRun } from "./status.ts";
+import { isSymlink, realpathOrSelf } from "../lib/fs.ts";
+import { loadLibrary } from "../core/library.ts";
+import { inventoryDeployments, remediationFor } from "../core/deployments.ts";
+import type { Ctx, DeploymentSite } from "../types.ts";
+
+function site(partial: Partial<DeploymentSite> & Pick<DeploymentSite, "name" | "path" | "kind">): DeploymentSite {
+  return { surface: "/surface", target: null, inLibrary: false, drift: false, ...partial };
+}
+
+function makeCtx(libraryPath: string) {
+  const json: unknown[] = [];
+  const ctx = {
+    config: { libraryPath },
+    libraryPath,
+    loadLibrary: () => loadLibrary(libraryPath),
+    log: () => {},
+    error: () => {},
+    json: (v: unknown) => json.push(v),
+  } as unknown as Ctx;
+  return { ctx, json };
+}
+
+describe("where remediation + refresh + status drift (friction #6)", () => {
+  let tmp: string;
+  let library: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-rem-")));
+    library = join(tmp, "library");
+    await mkdir(join(library, "alpha"), { recursive: true });
+    await writeFile(join(library, "alpha", "SKILL.md"), "---\nname: alpha\ndescription: a\n---\n\nbody\n");
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("--prune removes dead links only; copies stay manual", async () => {
+    const surface = join(tmp, "surface");
+    await mkdir(surface, { recursive: true });
+    await symlink(join(tmp, "gone"), join(surface, "deadlink"));
+    const dead = site({ name: "deadlink", path: join(surface, "deadlink"), kind: "dead" });
+    const copy = site({ name: "alpha", path: join(surface, "alpha"), kind: "copy", inLibrary: true, drift: false });
+
+    const outcomes = await remediate([dead, copy], library, { fix: false, dryRun: false });
+    expect(outcomes.find((o) => o.name === "deadlink")!.action).toBe("remove-dead");
+    expect(outcomes.find((o) => o.name === "deadlink")!.applied).toBe(true);
+    expect(existsSync(join(surface, "deadlink"))).toBe(false);
+    // under --prune a dedupe-able copy is left as manual
+    expect(outcomes.find((o) => o.name === "alpha")!.action).toBe("manual");
+  });
+
+  test("--fix dedupes a content-identical copy into a library symlink", async () => {
+    const surface = join(tmp, "surface");
+    await mkdir(join(surface, "alpha"), { recursive: true });
+    await writeFile(join(surface, "alpha", "SKILL.md"), "---\nname: alpha\ndescription: a\n---\n\nbody\n");
+    const copy = site({ name: "alpha", path: join(surface, "alpha"), kind: "copy", inLibrary: true, drift: false });
+
+    const outcomes = await remediate([copy], library, { fix: true, dryRun: false });
+    expect(outcomes[0]!.action).toBe("dedupe-copy");
+    expect(isSymlink(join(surface, "alpha"))).toBe(true);
+    expect(realpathOrSelf(join(surface, "alpha"))).toBe(realpathOrSelf(join(library, "alpha")));
+  });
+
+  test("--fix never auto-resolves a drifted copy or a foreign link", async () => {
+    const drifted = site({ name: "alpha", path: "/s/alpha", kind: "copy", inLibrary: true, drift: true });
+    const foreign = site({ name: "beta", path: "/s/beta", kind: "foreign-link", target: "/elsewhere" });
+    const outcomes = await remediate([drifted, foreign], library, { fix: true, dryRun: true });
+    expect(outcomes.every((o) => o.action === "manual")).toBe(true);
+    expect(outcomes.every((o) => !o.applied)).toBe(true);
+  });
+
+  test("--dry-run reports without mutating", async () => {
+    const surface = join(tmp, "surface");
+    await mkdir(surface, { recursive: true });
+    await symlink(join(tmp, "gone"), join(surface, "deadlink"));
+    const dead = site({ name: "deadlink", path: join(surface, "deadlink"), kind: "dead" });
+    const outcomes = await remediate([dead], library, { fix: true, dryRun: true });
+    expect(outcomes[0]!.applied).toBe(false);
+    expect(isSymlink(join(surface, "deadlink"))).toBe(true); // still there
+  });
+
+  test("refresh prunes a stale link whose library skill is gone, leaves foreign links", async () => {
+    const proj = join(tmp, "proj");
+    const skillsDir = join(proj, ".claude", "skills");
+    await mkdir(skillsDir, { recursive: true });
+    await symlink(join(library, "alpha"), join(skillsDir, "alpha")); // valid
+    await symlink(join(library, "ghost"), join(skillsDir, "ghost")); // dead, was-library
+    await symlink("/foreign/x", join(skillsDir, "foreign")); // foreign
+
+    const prev = process.cwd();
+    process.chdir(proj);
+    try {
+      const { ctx, json } = makeCtx(library);
+      await refreshRun(["--json"], ctx);
+      const out = json[0] as { outcomes: Array<{ name: string; action: string }> };
+      const by = Object.fromEntries(out.outcomes.map((o) => [o.name, o.action]));
+      expect(by.alpha).toBe("ok");
+      expect(by.ghost).toBe("pruned");
+      expect(by.foreign).toBe("foreign");
+      expect(existsSync(join(skillsDir, "ghost"))).toBe(false);
+      expect(isSymlink(join(skillsDir, "foreign"))).toBe(true);
+    } finally {
+      process.chdir(prev);
+    }
+  });
+
+  test("a copy with identical body but a CUSTOMIZED description is drift, not dedupe-able", async () => {
+    // the load-bearing `description` differs while the body is byte-identical —
+    // `where --fix` must NOT silently replace it with a symlink (data loss).
+    const surface = join(tmp, "surface");
+    await mkdir(join(surface, "alpha"), { recursive: true });
+    await writeFile(
+      join(surface, "alpha", "SKILL.md"),
+      "---\nname: alpha\ndescription: CUSTOMIZED trigger text\n---\n\nbody\n", // same body, diff description
+    );
+    const lib = await loadLibrary(library);
+    const report = await inventoryDeployments([surface], library, lib);
+    const alpha = report.sites.find((s) => s.surface === surface && s.name === "alpha")!;
+    expect(alpha.kind).toBe("copy");
+    expect(alpha.drift).toBe(true); // description difference counts as drift
+    expect(remediationFor(alpha)).toBe("manual"); // never auto-deduped
+  });
+
+  test("status flags an unmanaged real copy (drift-prone)", async () => {
+    const proj = join(tmp, "proj2");
+    const skillsDir = join(proj, ".claude", "skills");
+    await mkdir(join(skillsDir, "realcopy"), { recursive: true });
+    await writeFile(join(skillsDir, "realcopy", "SKILL.md"), "---\nname: realcopy\n---\n\nx\n");
+
+    const prev = process.cwd();
+    process.chdir(proj);
+    try {
+      const { ctx, json } = makeCtx(library);
+      await statusRun(["--json"], ctx);
+      const out = json[0] as { unmanaged: Array<{ name: string }> };
+      expect(out.unmanaged.map((u) => u.name)).toContain("realcopy");
+    } finally {
+      process.chdir(prev);
+    }
+  });
+});

package/src/commands/rename.test.ts

@@ -0,0 +1,121 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, symlink, rm as fsRm, realpath, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run as renameRun } from "./rename.ts";
+import { loadLibrary } from "../core/library.ts";
+import type { Ctx } from "../types.ts";
+
+function makeCtx(libraryPath: string) {
+  const json: unknown[] = [];
+  const errors: string[] = [];
+  const ctx = {
+    config: { libraryPath },
+    libraryPath,
+    loadLibrary: () => loadLibrary(libraryPath),
+    log: () => {},
+    error: (...a: unknown[]) => errors.push(a.join(" ")),
+    json: (v: unknown) => json.push(v),
+  } as unknown as Ctx;
+  return { ctx, json, errors };
+}
+
+describe("skl rename — atomic slug move (friction #5)", () => {
+  let tmp: string;
+  let library: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-rename-")));
+    library = join(tmp, "library");
+    await mkdir(join(library, "alpha"), { recursive: true });
+    await writeFile(join(library, "alpha", "SKILL.md"), "---\nname: alpha\ndescription: a\n---\n\nbody\n");
+    await writeFile(join(library, "taxonomy.json"), JSON.stringify({ version: 1, skills: { alpha: ["bio"] } }));
+    await writeFile(
+      join(library, "shelf.lock.json"),
+      JSON.stringify({ version: 1, entries: { alpha: { name: "alpha", source: "github:o/r", ref: "x", channel: "github", installedAt: "2020-01-01T00:00:00.000Z", localEdits: false } } }),
+    );
+  });
+  afterEach(async () => {
+    await fsRm(tmp, { recursive: true, force: true });
+  });
+
+  test("moves dir + frontmatter + taxonomy + lock together", async () => {
+    const { ctx } = makeCtx(library);
+    const code = await renameRun(["alpha", "alpha2", "--json"], ctx);
+    expect(code).toBe(0);
+
+    expect(existsSync(join(library, "alpha"))).toBe(false);
+    expect(existsSync(join(library, "alpha2"))).toBe(true);
+
+    const fm = await readFile(join(library, "alpha2", "SKILL.md"), "utf8");
+    expect(fm).toContain("name: alpha2");
+
+    const tax = JSON.parse(await readFile(join(library, "taxonomy.json"), "utf8"));
+    expect(tax.skills.alpha2).toEqual(["bio"]);
+    expect(tax.skills.alpha).toBeUndefined();
+
+    const lock = JSON.parse(await readFile(join(library, "shelf.lock.json"), "utf8"));
+    expect(lock.entries.alpha2.name).toBe("alpha2");
+    expect(lock.entries.alpha).toBeUndefined();
+  });
+
+  test("refuses an existing target name", async () => {
+    await mkdir(join(library, "beta"), { recursive: true });
+    await writeFile(join(library, "beta", "SKILL.md"), "---\nname: beta\n---\n\nb\n");
+    const { ctx, errors } = makeCtx(library);
+    const code = await renameRun(["alpha", "beta"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("already exists");
+  });
+
+  test("refuses a missing source", async () => {
+    const { ctx, errors } = makeCtx(library);
+    const code = await renameRun(["ghost", "x"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("not in the library");
+  });
+
+  test("renames a RETIRED skill in place (stays under _retired/)", async () => {
+    // retire alpha by moving it into _retired/
+    await mkdir(join(library, "_retired"), { recursive: true });
+    const { rename: fsRename } = await import("node:fs/promises");
+    await fsRename(join(library, "alpha"), join(library, "_retired", "alpha"));
+
+    const { ctx, json } = makeCtx(library);
+    const code = await renameRun(["alpha", "alpha2", "--json"], ctx);
+    expect(code).toBe(0);
+    expect((json[0] as { wasRetired: boolean }).wasRetired).toBe(true);
+    expect(existsSync(join(library, "_retired", "alpha2", "SKILL.md"))).toBe(true);
+    expect(existsSync(join(library, "_retired", "alpha"))).toBe(false);
+    expect(existsSync(join(library, "alpha2"))).toBe(false); // did NOT escape to active
+  });
+
+  test("refuses a path-traversal <old> name", async () => {
+    const victim = join(tmp, "victim");
+    await mkdir(victim, { recursive: true });
+    const { ctx, errors } = makeCtx(library);
+    const code = await renameRun(["../victim", "stolen"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("path separators");
+    expect(existsSync(victim)).toBe(true);
+    expect(existsSync(join(library, "stolen"))).toBe(false);
+  });
+
+  test("a LINKED entry rekeys metadata but leaves the dev-repo SKILL.md untouched", async () => {
+    const dev = join(tmp, "dev", "linked");
+    await mkdir(dev, { recursive: true });
+    await writeFile(join(dev, "SKILL.md"), "---\nname: linked\n---\n\nbody\n");
+    await symlink(dev, join(library, "linked"));
+
+    const { ctx, json } = makeCtx(library);
+    const code = await renameRun(["linked", "linked2", "--json"], ctx);
+    expect(code).toBe(0);
+    expect((json[0] as { frontmatterRewritten: boolean }).frontmatterRewritten).toBe(false);
+    // dev-repo body is NOT rewritten (we must not edit the dev repo)
+    const devFm = await readFile(join(dev, "SKILL.md"), "utf8");
+    expect(devFm).toContain("name: linked");
+    // library symlink now lives under the new name, still resolving to the dev repo
+    expect(existsSync(join(library, "linked2", "SKILL.md"))).toBe(true);
+  });
+});

package/src/commands/rename.ts

@@ -0,0 +1,64 @@
+// `skl rename <old> <new>` (alias `skl mv`) — rename a skill's slug, moving every
+// coupled piece of state together in ONE op: the library dir, the SKILL.md
+// frontmatter `name:`, the taxonomy key, and the lockfile key. A hand `mv` alone
+// leaves a half-renamed skill (dir=new, frontmatter/taxonomy=old) — the exact
+// multi-file-consistency hazard the dogfood pass hit.
+//
+//   skl rename <old> <new> [--json]
+//
+// Does NOT repoint external deploy symlinks (they point at the old library path);
+// re-run `skl use` in affected projects (or `skl where` to find stragglers) after.
+
+import type { Ctx } from "../types.ts";
+import { renameSkill, reindexLibrary } from "../core/lifecycle.ts";
+
+export const meta = {
+  name: "rename",
+  summary: "Rename a skill slug atomically (dir + frontmatter + taxonomy + lock)",
+  usage: "skl rename <old> <new> [--json]",
+} as const;
+
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const json = argv.includes("--json");
+  const positional = argv.filter((a) => !a.startsWith("--"));
+  const unknownFlag = argv.find((a) => a.startsWith("--") && a !== "--json");
+  if (unknownFlag) {
+    ctx.error(`skl rename: unknown argument: ${unknownFlag}`);
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  const [from, to] = positional;
+  if (!from || !to) {
+    ctx.error("skl rename: an <old> and a <new> name are required");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  if (!SLUG_RE.test(to)) {
+    ctx.error(`skl rename: invalid name "${to}" — use lowercase letters, digits, and hyphens`);
+    return 1;
+  }
+  if (from === to) {
+    ctx.error("skl rename: <old> and <new> are the same");
+    return 1;
+  }
+
+  try {
+    const result = await renameSkill(ctx.libraryPath, from, to);
+    await reindexLibrary(ctx.libraryPath);
+    if (json) {
+      ctx.json({ ok: true, ...result });
+    } else {
+      ctx.log(`renamed ${from} -> ${to}`);
+      if (result.frontmatterRewritten) ctx.log("  rewrote SKILL.md frontmatter name:");
+      if (result.taxonomyMoved) ctx.log("  moved taxonomy entry");
+      if (result.lockMoved) ctx.log("  moved lockfile entry");
+      ctx.log("  note: deploy symlinks pointing at the old name are now stale — re-run `skl use` (or `skl where`).");
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(`skl rename: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}

package/src/commands/retag.ts

@@ -0,0 +1,58 @@
+// `skl retag <old-domain> <new-domain>` — deterministically rename a domain across
+// the WHOLE library taxonomy (every skill tagged <old> becomes <new>). This is the
+// pure rename the AI `infer` pass can't promise (it re-reasons every tag); retag
+// touches nothing but the named domain. Fixes a domain typo in one pass instead of a
+// hand-edit of taxonomy.json or a silently-failing `sed` loop over frontmatter.
+//
+//   skl retag <old-domain> <new-domain> [--json]
+
+import type { Ctx } from "../types.ts";
+import { renameDomainAcrossLibrary } from "../core/taxonomy.ts";
+import { reindexLibrary } from "../core/lifecycle.ts";
+
+export const meta = {
+  name: "retag",
+  summary: "Rename a domain across the whole library taxonomy (deterministic)",
+  usage: "skl retag <old-domain> <new-domain> [--json]",
+} as const;
+
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const json = argv.includes("--json");
+  const positional = argv.filter((a) => !a.startsWith("--"));
+  const unknownFlag = argv.find((a) => a.startsWith("--") && a !== "--json");
+  if (unknownFlag) {
+    ctx.error(`skl retag: unknown argument: ${unknownFlag}`);
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  const [oldDomain, newDomain] = positional;
+  if (!oldDomain || !newDomain) {
+    ctx.error("skl retag: an <old-domain> and a <new-domain> are required");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  if (!SLUG_RE.test(newDomain)) {
+    ctx.error(`skl retag: invalid domain "${newDomain}" — use lowercase letters, digits, and hyphens`);
+    return 1;
+  }
+
+  try {
+    const changed = await renameDomainAcrossLibrary(ctx.libraryPath, oldDomain, newDomain);
+    if (changed.length > 0) await reindexLibrary(ctx.libraryPath);
+
+    if (json) {
+      ctx.json({ ok: true, from: oldDomain, to: newDomain, changed });
+    } else if (changed.length === 0) {
+      ctx.log(`No skills tagged '${oldDomain}' in the taxonomy — nothing to rename.`);
+    } else {
+      ctx.log(`retagged '${oldDomain}' -> '${newDomain}' across ${changed.length} skill(s):`);
+      for (const n of changed) ctx.log(`  ${n}`);
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(`skl retag: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}

package/src/commands/retire.ts

@@ -0,0 +1,39 @@
+// `skl retire <name>` — soft-delete a skill into <library>/_retired/<name>/. The
+// read layer already renders retired skills (struck-through in INDEX.md, "(retired)"
+// in `ls --all`, excluded from bundles/deploys) but had no WRITE primitive to enter
+// that state — forcing a hand `mkdir _retired && mv`. This is the reversible first
+// step of the removal lifecycle (retire -> optionally `rm`); undo with `skl unretire`.
+//
+//   skl retire <name> [--json]
+
+import type { Ctx } from "../types.ts";
+import { retireSkill, reindexLibrary } from "../core/lifecycle.ts";
+
+export const meta = {
+  name: "retire",
+  summary: "Soft-delete a skill into library/_retired/ (reversible; excluded from deploys)",
+  usage: "skl retire <name> [--json]",
+} as const;
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const json = argv.includes("--json");
+  const name = argv.find((a) => !a.startsWith("--"));
+  if (!name) {
+    ctx.error("skl retire: a <name> is required");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  try {
+    const dest = await retireSkill(ctx.libraryPath, name);
+    await reindexLibrary(ctx.libraryPath);
+    if (json) ctx.json({ ok: true, name, retiredTo: dest });
+    else {
+      ctx.log(`retired ${name} -> _retired/${name}`);
+      ctx.log("  (excluded from bundles/deploys; restore with `skl unretire`, purge with `skl rm`)");
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(`skl retire: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}