skillshelf 0.2.0 → 0.3.0

package/src/commands/agents.ts

@@ -0,0 +1,120 @@
+// `skl agents [name]` — the multi-agent deployment matrix: for each known agent
+// (claude, codex, …) and scope (Global / a project), what is each skill's
+// deployment state? Built on the same reality `skl where` inventories. ADR-0008 §7.3.
+//
+//   skl agents              human summary of installed agents + per-agent counts
+//   skl agents --json        full AgentsReport { agents, scopes, deployments }
+//   skl agents <name>        one skill's row across agents × scopes
+
+import type { Ctx } from "../types.ts";
+import { inventoryDeployments } from "../core/deployments.ts";
+import { knownAgentSurfacePaths } from "../core/surfaces.ts";
+import { computeAgentsReport, resolveReadTarget, type DeployState } from "../core/agents.ts";
+
+export const meta = {
+  name: "agents",
+  summary: "Show each skill's deployment state across known agents (claude, codex, …) and scopes",
+  usage: "skl agents [name] [--agent <id>] [--project <dir>] [--json]",
+} as const;
+
+const GLYPH: Record<DeployState, string> = {
+  clean: "✓",
+  source: "⊙",
+  drift: "⚠",
+  copy: "□",
+  dead: "✗",
+  absent: "·",
+};
+
+const LEGEND = "legend: ✓ clean · ⊙ source · ⚠ drift · □ copy · ✗ dead · · absent";
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  try {
+    const rt = resolveReadTarget(argv);
+    if ("error" in rt) {
+      ctx.error(`skl agents: ${rt.error}`);
+      ctx.error("usage: " + meta.usage);
+      return 1;
+    }
+    const json = rt.rest.includes("--json");
+    const name = rt.rest.find((a) => !a.startsWith("--")) ?? null;
+
+    const lib = await ctx.loadLibrary();
+    // Same surface union as `skl where` (+ any --project surfaces for this call) so
+    // the agent matrix sees the same reality and can verify an ad-hoc project deploy.
+    const surfaces = [...ctx.roots, ctx.config.globalCoreTarget, ...knownAgentSurfacePaths(), ...rt.extraSurfaces];
+    const report = await inventoryDeployments(surfaces, ctx.libraryPath, lib);
+    let agentsReport = computeAgentsReport(report);
+
+    // --agent <id> focuses the whole report on that agent: prune the agents list
+    // and the deployments map to just that agent (skills not deployed to it drop).
+    if (rt.agentId) {
+      const id = rt.agentId;
+      const deployments: typeof agentsReport.deployments = {};
+      for (const [skill, byAgent] of Object.entries(agentsReport.deployments)) {
+        if (byAgent[id]) deployments[skill] = { [id]: byAgent[id] };
+      }
+      agentsReport = {
+        agents: agentsReport.agents.filter((a) => a.id === id),
+        scopes: agentsReport.scopes,
+        deployments,
+      };
+    }
+
+    if (json) {
+      if (name !== null) {
+        ctx.json({
+          name,
+          agents: agentsReport.agents,
+          scopes: agentsReport.scopes,
+          deployment: agentsReport.deployments[name] ?? {},
+        });
+        return 0;
+      }
+      ctx.json(agentsReport);
+      return 0;
+    }
+
+    // --- human view ------------------------------------------------------
+    const { agents, scopes, deployments } = agentsReport;
+    if (name !== null) {
+      const byAgent = deployments[name] ?? {};
+      ctx.log(`${name} — deployment across agents:`);
+      for (const a of agents) {
+        const dep = byAgent[a.id];
+        const g = dep?.g ?? "absent";
+        const projects = dep?.p
+          ? Object.entries(dep.p).map(([s, st]) => `${s} ${GLYPH[st]}`).join("  ")
+          : "";
+        const installed = a.installed ? "" : " (not installed)";
+        ctx.log(`  ${a.short.padEnd(10)} ${GLYPH[g]} global·${g}${installed}${projects ? `   ${projects}` : ""}`);
+      }
+      ctx.log("");
+      ctx.log(LEGEND);
+      return 0;
+    }
+
+    ctx.log(`Agents (${agents.filter((a) => a.installed).length} installed) · scopes: ${scopes.join(", ")}`);
+    for (const a of agents) {
+      let clean = 0;
+      let problems = 0;
+      for (const byAgent of Object.values(deployments)) {
+        const dep = byAgent[a.id];
+        if (!dep) continue;
+        const states: DeployState[] = [dep.g ?? "absent", ...Object.values(dep.p ?? {})];
+        for (const st of states) {
+          if (st === "clean" || st === "source") clean++;
+          else if (st !== "absent") problems++;
+        }
+      }
+      const tag = a.installed ? "" : "  (not installed)";
+      ctx.log(`  ${a.short.padEnd(10)} ${a.global}${tag}  —  ${clean} clean, ${problems} need attention`);
+    }
+    ctx.log("");
+    ctx.log(LEGEND);
+    return 0;
+  } catch (err) {
+    ctx.error(`skl agents failed: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}

package/src/commands/drop.ts

@@ -5,12 +5,14 @@
 import { join } from "node:path";
 import type { Ctx } from "../types.ts";
 import { resolveBundle } from "../core/bundle.ts";
+import { findByName } from "../core/library.ts";
+import { parseDeployTarget } from "../core/agents.ts";
 import { isSymlink, realpathOrSelf, realpathOrSelfAsync, removeSymlink } from "../lib/fs.ts";
 
 export const meta = {
   name: "drop",
-  summary: "Remove a bundle's symlinks from ./.claude/skills/",
-  usage: "skl drop <bundle> [--json]",
+  summary: "Remove a bundle's (or skill's) symlinks from an agent's skills dir (default: ./.claude/skills/)",
+  usage: "skl drop <bundle|skill> [--agent <id>] [--global | --project <name>] [--json]",
 } as const;
 
 interface DropResult {
@@ -19,14 +21,17 @@ interface DropResult {
   status: "removed" | "absent" | "skipped";
 }
 
-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("-"));
+    const parsed = parseDeployTarget(argv);
+    if ("error" in parsed) {
+      ctx.error(`skl drop: ${parsed.error}`);
+      ctx.error("usage: " + meta.usage);
+      return 1;
+    }
+    const { positionals, target } = parsed;
+    const bundleName = positionals[0];
 
     if (!bundleName) {
       ctx.error("usage: " + meta.usage);
@@ -36,12 +41,15 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     // Include retired so a bundle that was `use`d (which excludes retired) and a
     // later drop stay symmetric on the active set — we match on the same active set.
     const skills = await ctx.loadLibrary();
-    const bundle = await resolveBundle(
-      skills.filter((s) => !s.retired),
-      bundleName,
-    );
+    const active = skills.filter((s) => !s.retired);
+    // Mirror `use`: resolve a single skill name first, else a bundle, so
+    // `skl drop <skill>` undoes `skl use <skill>` symmetrically.
+    const single = findByName(active, bundleName);
+    const bundle = single
+      ? { name: single.name, skills: [single] }
+      : await resolveBundle(active, bundleName);
 
-    const skillsDir = projectSkillsDir();
+    const skillsDir = target.dir;
     const results: DropResult[] = [];
 
     for (const s of bundle.skills) {
@@ -68,7 +76,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     const removedCount = results.filter((r) => r.status === "removed").length;
 
     if (json) {
-      ctx.json({ bundle: bundle.name, skillsDir, results, removed: removedCount });
+      ctx.json({ bundle: bundle.name, skillsDir, agent: target.agentId, scope: target.scope, results, removed: removedCount });
     } else {
       if (bundle.skills.length === 0) {
         ctx.log(`Bundle '${bundleName}' has no skills; nothing to drop.`);

package/src/commands/import.ts

@@ -19,26 +19,26 @@
 //   --force         overwrite an existing same-named library skill
 //
 // Provenance: these are the user's OWN skills, not third-party — source is null and
-// NO lockfile entry is written (that is `add`'s job). We still create an EMPTY
-// overlay (<name>.shelf.json) so taxonomy can be applied later without clobbering
-// the upstream SKILL.md.
+// NO lockfile entry is written (that is `add`'s job). Import is purely mechanical
+// (move + symlink-back, or --copy); domain tags are applied later by `skl infer`
+// into the central <library>/taxonomy.json, which never touches the SKILL.md body.
 
 import { join, basename, resolve } from "node:path";
 import { existsSync } from "node:fs";
 import { rename, cp, rm } from "node:fs/promises";
-import type { Ctx, Skill } from "../types.ts";
-import { writeOverlay } from "../core/overlay.ts";
+import type { Ctx } from "../types.ts";
 import {
   ensureDir,
   safeSymlink,
   isDirectory,
+  isSymlink,
   realpathOrSelfAsync,
 } from "../lib/fs.ts";
 
 export const meta = {
   name: "import",
   summary: "Adopt your own skill into the library (move + symlink-back, or --copy)",
-  usage: "skl import <name> --from <path> [--copy | --no-link-back] [--as <slug>] [--force] [--json]",
+  usage: "skl import <name> --from <path> [--copy | --no-link-back] [--follow] [--as <slug>] [--force] [--json]",
 } as const;
 
 interface Flags {
@@ -47,6 +47,7 @@ interface Flags {
   as: string | null;
   copy: boolean;
   noLinkBack: boolean;
+  follow: boolean;
   force: boolean;
   json: boolean;
 }
@@ -60,6 +61,7 @@ function parseFlags(argv: string[]): { flags: Flags } | { error: string } {
     as: null,
     copy: false,
     noLinkBack: false,
+    follow: false,
     force: false,
     json: false,
   };
@@ -81,6 +83,8 @@ function parseFlags(argv: string[]): { flags: Flags } | { error: string } {
       flags.copy = true;
     } else if (a === "--no-link-back" || a === "--no-link") {
       flags.noLinkBack = true;
+    } else if (a === "--follow" || a === "--deref") {
+      flags.follow = true;
     } else if (a === "--force") {
       flags.force = true;
     } else if (a === "--json") {
@@ -141,6 +145,12 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     );
     return 1;
   }
+  if (flags.follow && flags.noLinkBack) {
+    ctx.error(
+      "skl import: --follow copies the dereferenced target; it cannot be combined with --no-link-back (a move option)",
+    );
+    return 1;
+  }
 
   // The library name is --as if given, else <name>.
   const targetName = (flags.as ?? flags.name).trim();
@@ -171,6 +181,23 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
       return 1;
     }
 
+    // Symlink safety (option b): a symlinked source dir is refused unless --follow.
+    // Without it, a move would `rename` the LINK (the library would point back at the
+    // target and own no real copy) and a copy would copy the link itself. With
+    // --follow we dereference to the real target and COPY its contents (below).
+    const linkSource = isSymlink(fromPath);
+    if (linkSource && !flags.follow) {
+      const tgt = await realpathOrSelfAsync(fromPath);
+      ctx.error(`skl import: --from is a symlink (${fromPath} -> ${tgt}).`);
+      ctx.error(
+        "Refusing to import a symlink source: a move would relocate the link, not the content.",
+      );
+      ctx.error(
+        "Re-run with --follow (alias --deref) to dereference and copy the target's real contents into the library.",
+      );
+      return 1;
+    }
+
     const libraryPath = ctx.config.libraryPath;
     // Flat, non-semantic layout (ADR-0001): always <library>/<name>/.
     const destDir = join(libraryPath, targetName);
@@ -202,12 +229,15 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
       await rm(destDir, { recursive: true, force: true });
     }
 
-    const mode: "move" | "copy" = flags.copy ? "copy" : "move";
+    // A symlinked source with --follow: copy the dereferenced TARGET's contents
+    // (never move — that would relocate the canonical store the link points at).
+    const srcDir = linkSource ? await realpathOrSelfAsync(fromPath) : fromPath;
+    const mode: "move" | "copy" = linkSource ? "copy" : flags.copy ? "copy" : "move";
     let linkedBack = false;
 
     if (mode === "copy") {
       // Copy into the library; leave the original untouched (no symlink-back).
-      await cp(fromPath, destDir, {
+      await cp(srcDir, destDir, {
         recursive: true,
         force: true,
         filter: (s: string) => basename(s) !== ".git",
@@ -233,26 +263,10 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
       }
     }
 
-    // Empty overlay so taxonomy (domains/bundles) can be applied later via
-    // `skl infer` without touching the upstream SKILL.md. These are the user's own
-    // skills: source/provenance is null and NO lockfile entry is written.
-    const imported: Skill = {
-      name: targetName,
-      description: "",
-      primaryDomain: null,
-      domains: [],
-      path: destDir,
-      bodyPath: join(destDir, "SKILL.md"),
-      refFiles: [],
-      source: null,
-      retired: false,
-      mirrorOf: null,
-      contentHash: "",
-    };
-    const overlayPathStr = join(destDir, `${targetName}.shelf.json`);
-    if (!existsSync(overlayPathStr)) {
-      await writeOverlay(imported, {});
-    }
+    // Import is mechanical: no domain is decided here. Domain tags are applied
+    // later via `skl infer` into the central <library>/taxonomy.json — never into
+    // the upstream SKILL.md. These are the user's own skills: source/provenance is
+    // null and NO lockfile entry is written.
 
     const summary = {
       ok: true,
@@ -261,6 +275,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
       to: destDir,
       mode,
       linkedBack,
+      followed: linkSource,
     };
 
     if (flags.json) {
@@ -268,6 +283,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     } else {
       ctx.log(`imported ${targetName}`);
       ctx.log(`  from:  ${fromPath}`);
+      if (linkSource) ctx.log(`  follow: ${fromPath} -> ${srcDir} (copied target contents)`);
       ctx.log(`  to:    ${destDir}`);
       ctx.log(`  mode:  ${mode}`);
       if (linkedBack) ctx.log(`  link:  ${fromPath} -> ${destDir} (old path still resolves)`);

package/src/commands/infer.ts

@@ -3,8 +3,8 @@
 // Dual-mode, LLM-FREE core:
 //   skl infer --emit                 print {instruction, schema, corpus} for a
 //                                    host agent to reason over (no LLM call here).
-//   skl infer --apply <file.json>    write the agent's proposal into each skill's
-//                                    <name>.shelf.json overlay (never upstream).
+//   skl infer --apply <file.json>    write the agent's proposal into the central
+//                                    taxonomy.json (never upstream SKILL.md).
 //   skl infer --provider openai      API mode: POST the corpus to an
 //                                    OpenAI-compatible endpoint and apply the
 //                                    strict-JSON result automatically.
@@ -164,7 +164,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
         ctx.error("skl infer: proposal contained no assignments");
         return 1;
       }
-      const result = await applyProposal(skills, proposal);
+      const result = await applyProposal(ctx.libraryPath, skills, proposal);
       return reportApply(result, args.json, ctx);
     }
 
@@ -193,7 +193,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
         ctx.error("skl infer: gateway returned no assignments");
         return 1;
       }
-      const result = await applyProposal(skills, inferred.proposal);
+      const result = await applyProposal(ctx.libraryPath, skills, inferred.proposal);
       return reportApply(result, args.json, ctx, prov.config.name, prov.config.model);
     }
 
@@ -227,7 +227,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     ctx.error(
       "skl infer: no inference mode available. Provide one of:\n" +
         "  --emit                 print corpus for a host agent to reason over\n" +
-        "  --apply <file.json>    apply an agent proposal into overlays\n" +
+        "  --apply <file.json>    apply an agent proposal into taxonomy.json\n" +
         `  --provider <name>      call an OpenAI-compatible endpoint (${knownProviders().join(", ")})\n` +
         "  --base-url <url>       call a custom OpenAI-compatible endpoint\n" +
         "(auto-emit only activates inside a Claude Code agent context.)",
@@ -268,7 +268,7 @@ function reportApply(
     ctx.log(`  ${a.name}: ${a.domains.join(", ")}${addedNote}`);
   }
   ctx.log(
-    `Applied ${result.applied.length} overlay update${
+    `Applied ${result.applied.length} taxonomy update${
       result.applied.length === 1 ? "" : "s"
     }.`,
   );

package/src/commands/link.test.ts

@@ -0,0 +1,160 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, readFile, rm, lstat, readlink, realpath } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run } from "./link.ts";
+import type { Ctx } from "../types.ts";
+
+const BODY = "---\nname: cairn\ndescription: a test skill\n---\n\nbody\n";
+
+async function makeSkillDir(parent: string, name: string, body = BODY): Promise<string> {
+  const dir = join(parent, name);
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, "SKILL.md"), body);
+  return dir;
+}
+
+interface Captured {
+  ctx: Ctx;
+  logs: string[];
+  errors: string[];
+  json: unknown[];
+}
+
+/** Minimal Ctx mock — link.run only reads config.libraryPath + log/error/json. */
+function makeCtx(libraryPath: string): Captured {
+  const logs: string[] = [];
+  const errors: string[] = [];
+  const json: unknown[] = [];
+  const ctx = {
+    config: { libraryPath },
+    libraryPath,
+    log: (...a: unknown[]) => logs.push(a.join(" ")),
+    error: (...a: unknown[]) => errors.push(a.join(" ")),
+    json: (v: unknown) => json.push(v),
+  } as unknown as Ctx;
+  return { ctx, logs, errors, json };
+}
+
+describe("skl link --from (LINKED mode)", () => {
+  let tmp: string;
+  let library: string;
+  let devRepo: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-link-")));
+    library = join(tmp, "library");
+    devRepo = join(tmp, "dev");
+    await mkdir(library, { recursive: true });
+    await mkdir(devRepo, { recursive: true });
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("registers a dev-repo skill as a library symlink", async () => {
+    const src = await makeSkillDir(devRepo, "cairn");
+    const { ctx, json } = makeCtx(library);
+    const code = await run(["cairn", "--from", src, "--json"], ctx);
+
+    expect(code).toBe(0);
+    const libEntry = join(library, "cairn");
+    const st = await lstat(libEntry);
+    expect(st.isSymbolicLink()).toBe(true);
+    expect(await realpath(libEntry)).toBe(await realpath(src));
+    expect(json[0]).toMatchObject({ ok: true, name: "cairn", mode: "linked", discarded: false });
+  });
+
+  test("derives the name from the dev-repo dir basename when omitted", async () => {
+    const src = await makeSkillDir(devRepo, "cairn");
+    const { ctx } = makeCtx(library);
+    const code = await run(["--from", src], ctx);
+
+    expect(code).toBe(0);
+    const libEntry = join(library, "cairn");
+    expect((await lstat(libEntry)).isSymbolicLink()).toBe(true);
+    expect(await realpath(libEntry)).toBe(await realpath(src));
+  });
+
+  test("is idempotent — re-running reports 'already'", async () => {
+    const src = await makeSkillDir(devRepo, "cairn");
+    const { ctx } = makeCtx(library);
+    await run(["cairn", "--from", src], ctx);
+
+    const { ctx: ctx2, json } = makeCtx(library);
+    const code = await run(["cairn", "--from", src, "--json"], ctx2);
+    expect(code).toBe(0);
+    expect(json[0]).toMatchObject({ status: "already", mode: "linked" });
+  });
+
+  test("refuses to clobber an existing owned library copy without --force", async () => {
+    await makeSkillDir(library, "cairn"); // a real OWNED copy already in the library
+    const src = await makeSkillDir(devRepo, "cairn");
+    const { ctx, errors } = makeCtx(library);
+
+    const code = await run(["cairn", "--from", src], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("already exists in the library");
+    // unchanged: still a real dir, not a symlink
+    expect((await lstat(join(library, "cairn"))).isSymbolicLink()).toBe(false);
+  });
+
+  test("--force replaces an owned copy with the symlink and reports discarded", async () => {
+    await makeSkillDir(library, "cairn");
+    const src = await makeSkillDir(devRepo, "cairn");
+    const { ctx, json } = makeCtx(library);
+
+    const code = await run(["cairn", "--from", src, "--force", "--json"], ctx);
+    expect(code).toBe(0);
+    expect((await lstat(join(library, "cairn"))).isSymbolicLink()).toBe(true);
+    expect(json[0]).toMatchObject({ discarded: true, mode: "linked" });
+  });
+
+  test("drops a stale lockfile entry so update/outdated skip the now-LINKED skill", async () => {
+    // An owned import existed (real copy + a github lock entry); now convert to LINKED.
+    await makeSkillDir(library, "cairn");
+    await writeFile(
+      join(library, "shelf.lock.json"),
+      JSON.stringify({
+        version: 1,
+        entries: {
+          cairn: { name: "cairn", source: "github:owner/repo", ref: "abc", channel: "github", installedAt: "2020-01-01T00:00:00.000Z", localEdits: false },
+        },
+      }),
+    );
+    const src = await makeSkillDir(devRepo, "cairn");
+    const { ctx } = makeCtx(library);
+
+    const code = await run(["cairn", "--from", src, "--force"], ctx);
+    expect(code).toBe(0);
+    const lock = JSON.parse(await readFile(join(library, "shelf.lock.json"), "utf8"));
+    expect(lock.entries.cairn).toBeUndefined();
+  });
+
+  test("rejects --at and --from together", async () => {
+    const src = await makeSkillDir(devRepo, "cairn");
+    const { ctx, errors } = makeCtx(library);
+    const code = await run(["cairn", "--from", src, "--at", "/tmp/x"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("mutually exclusive");
+  });
+
+  test("refuses a --from source inside the library", async () => {
+    const inside = await makeSkillDir(library, "cairn");
+    const { ctx, errors } = makeCtx(library);
+    const code = await run(["other", "--from", inside], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("inside the library");
+  });
+
+  test("refuses a --from dir with no SKILL.md", async () => {
+    const bare = join(devRepo, "bare");
+    await mkdir(bare, { recursive: true });
+    const { ctx, errors } = makeCtx(library);
+    const code = await run(["bare", "--from", bare], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("no SKILL.md");
+    expect(existsSync(join(library, "bare"))).toBe(false);
+  });
+});