skillshelf 0.1.0

package/src/commands/drop.ts

@@ -0,0 +1,89 @@
+// `skl drop <bundle>` — remove the symlinks that `skl use <bundle>` created in
+// ./.claude/skills/. Only removes symlinks that actually point at this bundle's
+// skills; never touches real files or links to unrelated skills. Idempotent.
+
+import { join } from "node:path";
+import type { Ctx } from "../types.ts";
+import { resolveBundle } from "../core/bundle.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]",
+} as const;
+
+interface DropResult {
+  name: string;
+  link: string;
+  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("-"));
+
+    if (!bundleName) {
+      ctx.error("usage: " + meta.usage);
+      return 1;
+    }
+
+    // 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 skillsDir = projectSkillsDir();
+    const results: DropResult[] = [];
+
+    for (const s of bundle.skills) {
+      const link = join(skillsDir, s.name);
+
+      if (!isSymlink(link)) {
+        results.push({ name: s.name, link, status: "absent" });
+        continue;
+      }
+
+      // Only remove if the symlink resolves to THIS skill's path. A divergent
+      // link (pointing elsewhere) is left alone.
+      const cur = realpathOrSelf(link);
+      const want = await realpathOrSelfAsync(s.path);
+      if (cur !== want) {
+        results.push({ name: s.name, link, status: "skipped" });
+        continue;
+      }
+
+      const removed = await removeSymlink(link);
+      results.push({ name: s.name, link, status: removed ? "removed" : "absent" });
+    }
+
+    const removedCount = results.filter((r) => r.status === "removed").length;
+
+    if (json) {
+      ctx.json({ bundle: bundle.name, skillsDir, results, removed: removedCount });
+    } else {
+      if (bundle.skills.length === 0) {
+        ctx.log(`Bundle '${bundleName}' has no skills; nothing to drop.`);
+      } else {
+        ctx.log(`Dropping bundle '${bundle.name}' from ${skillsDir}`);
+        for (const r of results) {
+          ctx.log(`  ${r.name}  [${r.status}]`);
+        }
+        ctx.log(`Removed ${removedCount} symlink(s).`);
+      }
+    }
+
+    return 0;
+  } catch (err) {
+    ctx.error(`skl drop failed: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}

package/src/commands/index.ts

@@ -0,0 +1,46 @@
+// `skl index` — regenerate INDEX.md (catalog grouped by primary domain) at
+// the library root, via core/indexgen.
+
+import type { Ctx } from "../types.ts";
+import { writeIndex, generateIndex } from "../core/indexgen.ts";
+
+export const meta = {
+  name: "index",
+  summary: "Regenerate INDEX.md (catalog grouped by domain)",
+  usage: "skl index [--json]",
+} as const;
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  try {
+    const json = argv.includes("--json");
+    const skills = await ctx.loadLibrary();
+
+    const generatedAt = new Date().toISOString();
+    const path = await writeIndex(ctx.config.libraryPath, skills, {
+      generatedAt,
+    });
+
+    const active = skills.filter((s) => !s.retired).length;
+    const retired = skills.length - active;
+
+    if (json) {
+      ctx.json({
+        path,
+        skills: skills.length,
+        active,
+        retired,
+        generatedAt,
+        bytes: generateIndex(skills, { generatedAt }).length,
+      });
+      return 0;
+    }
+
+    ctx.log(
+      `Wrote ${path} (${active} active${retired ? `, ${retired} retired` : ""}).`,
+    );
+    return 0;
+  } catch (err) {
+    ctx.error(`index failed: ${(err as Error).message}`);
+    return 1;
+  }
+}

package/src/commands/infer.ts

@@ -0,0 +1,282 @@
+// `skl infer` — re-run the domain taxonomy pass over the library.
+//
+// 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 --provider openai      API mode: POST the corpus to an
+//                                    OpenAI-compatible endpoint and apply the
+//                                    strict-JSON result automatically.
+//
+// API mode is provider-agnostic. Config resolves (highest precedence first)
+// from CLI flags (--base-url, --model, --provider) > env vars
+// (SKILLSHELF_LLM_BASE_URL / _API_KEY / _MODEL, then OPENAI_* fallbacks) >
+// optional dotenv at $SKILLSHELF_ENV_FILE (default ./.env). --provider is sugar
+// for a default base URL only (openai, openrouter, groq, ollama, custom); the
+// API key always comes from the environment/dotenv.
+//
+// Auto-detect when no explicit mode/provider is given:
+//   - inside a Claude Code agent ($CLAUDECODE) -> default to --emit guidance.
+//   - no agent and no provider                 -> error clearly.
+
+import type { Ctx } from "../types.ts";
+import {
+  buildEmitPayload,
+  normalizeProposal,
+  applyProposal,
+  type ApplyResult,
+} from "../adapters/inference/agent.ts";
+import {
+  resolveProvider,
+  inferViaApi,
+  knownProviders,
+} from "../adapters/inference/api.ts";
+
+export const meta = {
+  name: "infer",
+  summary: "Re-run AI domain taxonomy over the library (emit/apply/provider modes)",
+  usage:
+    "skl infer [--emit | --apply <file.json> | --provider <name>] [--base-url <url>] [--model <id>] [--include-retired] [--json]",
+} as const;
+
+interface Args {
+  emit: boolean;
+  applyFile: string | null;
+  provider: string | null;
+  baseUrl: string | null;
+  model: string | null;
+  includeRetired: boolean;
+  json: boolean;
+}
+
+function parseArgs(argv: string[]): { args: Args } | { error: string } {
+  const args: Args = {
+    emit: false,
+    applyFile: null,
+    provider: null,
+    baseUrl: null,
+    model: null,
+    includeRetired: false,
+    json: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    switch (a) {
+      case "--emit":
+        args.emit = true;
+        break;
+      case "--apply": {
+        const f = argv[++i];
+        if (!f) return { error: "--apply requires a <file.json> path" };
+        args.applyFile = f;
+        break;
+      }
+      case "--provider": {
+        const p = argv[++i];
+        if (!p) return { error: "--provider requires a name" };
+        args.provider = p;
+        break;
+      }
+      case "--base-url": {
+        const b = argv[++i];
+        if (!b) return { error: "--base-url requires a url" };
+        args.baseUrl = b;
+        break;
+      }
+      case "--model": {
+        const m = argv[++i];
+        if (!m) return { error: "--model requires an id" };
+        args.model = m;
+        break;
+      }
+      case "--include-retired":
+        args.includeRetired = true;
+        break;
+      case "--json":
+        args.json = true;
+        break;
+      default:
+        if (a.startsWith("--apply=")) args.applyFile = a.slice("--apply=".length);
+        else if (a.startsWith("--provider=")) args.provider = a.slice("--provider=".length);
+        else if (a.startsWith("--base-url=")) args.baseUrl = a.slice("--base-url=".length);
+        else if (a.startsWith("--model=")) args.model = a.slice("--model=".length);
+        else return { error: `unknown argument: ${a}` };
+    }
+  }
+  return { args };
+}
+
+function isAgentContext(): boolean {
+  return (
+    !!process.env.CLAUDECODE ||
+    !!process.env.CLAUDE_CODE ||
+    !!process.env.CLAUDE_AGENT ||
+    !!process.env.ANTHROPIC_AGENT
+  );
+}
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const parsed = parseArgs(argv);
+  if ("error" in parsed) {
+    ctx.error(`skl infer: ${parsed.error}`);
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  const args = parsed.args;
+
+  // API mode is requested by --provider or --base-url.
+  const apiMode = !!args.provider || !!args.baseUrl;
+
+  // Mutually-exclusive modes (apply / api are explicit and primary).
+  const modeCount =
+    (args.applyFile ? 1 : 0) + (apiMode ? 1 : 0) + (args.emit ? 1 : 0);
+  if (modeCount > 1) {
+    ctx.error("skl infer: choose only one of --emit, --apply, --provider/--base-url");
+    return 1;
+  }
+
+  try {
+    const skills = await ctx.loadLibrary();
+
+    // --- APPLY MODE -------------------------------------------------------
+    if (args.applyFile) {
+      let text: string;
+      try {
+        text = await Bun.file(args.applyFile).text();
+      } catch {
+        ctx.error(`skl infer: cannot read proposal file: ${args.applyFile}`);
+        return 1;
+      }
+      let rawJson: unknown;
+      try {
+        rawJson = JSON.parse(text);
+      } catch (e) {
+        ctx.error(
+          `skl infer: proposal file is not valid JSON: ${
+            e instanceof Error ? e.message : String(e)
+          }`,
+        );
+        return 1;
+      }
+      const proposal = normalizeProposal(rawJson);
+      if (proposal.assignments.length === 0) {
+        ctx.error("skl infer: proposal contained no assignments");
+        return 1;
+      }
+      const result = await applyProposal(skills, proposal);
+      return reportApply(result, args.json, ctx);
+    }
+
+    // --- API MODE (--provider / --base-url) ------------------------------
+    if (apiMode) {
+      const prov = await resolveProvider(args.provider ?? undefined, {
+        base: args.baseUrl ?? undefined,
+        model: args.model ?? undefined,
+      });
+      if ("error" in prov) {
+        ctx.error(`skl infer: ${prov.error}`);
+        return 1;
+      }
+      const { buildCorpus } = await import("../adapters/inference/agent.ts");
+      const corpus = await buildCorpus(skills, { includeRetired: args.includeRetired });
+      if (corpus.skills.length === 0) {
+        ctx.error("skl infer: library is empty — nothing to infer");
+        return 1;
+      }
+      const inferred = await inferViaApi(corpus, prov.config);
+      if ("error" in inferred) {
+        ctx.error(`skl infer: ${inferred.error}`);
+        return 1;
+      }
+      if (inferred.proposal.assignments.length === 0) {
+        ctx.error("skl infer: gateway returned no assignments");
+        return 1;
+      }
+      const result = await applyProposal(skills, inferred.proposal);
+      return reportApply(result, args.json, ctx, prov.config.name, prov.config.model);
+    }
+
+    // --- EMIT MODE (explicit or agent-auto-detect) -----------------------
+    if (args.emit || isAgentContext()) {
+      const payload = await buildEmitPayload(skills, {
+        includeRetired: args.includeRetired,
+      });
+      if (payload.corpus.skills.length === 0) {
+        ctx.error("skl infer: library is empty — nothing to infer");
+        return 1;
+      }
+      // emit is inherently machine output; --json is the same single-line form.
+      if (args.json) {
+        ctx.json(payload);
+      } else {
+        // pretty multi-line for a human/agent reading stdout
+        ctx.log(JSON.stringify(payload, null, 2));
+      }
+      if (!args.emit) {
+        ctx.error(
+          `skl infer: agent context detected — emitted ${payload.corpus.skills.length} skills. ` +
+            "Reason over `corpus`, produce a proposal that matches `schema`, " +
+            "then run: skl infer --apply <file.json>",
+        );
+      }
+      return 0;
+    }
+
+    // --- NO MODE, NO AGENT -> error --------------------------------------
+    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" +
+        `  --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.)",
+    );
+    return 1;
+  } catch (e) {
+    ctx.error(`skl infer: ${e instanceof Error ? e.message : String(e)}`);
+    return 1;
+  }
+}
+
+function reportApply(
+  result: ApplyResult,
+  asJson: boolean,
+  ctx: Ctx,
+  provider?: string,
+  model?: string,
+): number {
+  if (asJson) {
+    ctx.json({
+      ok: true,
+      provider: provider ?? null,
+      model: model ?? null,
+      applied: result.applied,
+      unmatched: result.unmatched,
+      skipped: result.skipped,
+      counts: {
+        applied: result.applied.length,
+        unmatched: result.unmatched.length,
+        skipped: result.skipped.length,
+      },
+    });
+    return 0;
+  }
+  if (provider) ctx.log(`Inference via ${provider}${model ? ` (${model})` : ""}:`);
+  for (const a of result.applied) {
+    const addedNote = a.added.length ? `  (+${a.added.join(", ")})` : "  (no change)";
+    ctx.log(`  ${a.name}: ${a.domains.join(", ")}${addedNote}`);
+  }
+  ctx.log(
+    `Applied ${result.applied.length} overlay update${
+      result.applied.length === 1 ? "" : "s"
+    }.`,
+  );
+  if (result.unmatched.length) {
+    ctx.log(`Unmatched (no such skill): ${result.unmatched.join(", ")}`);
+  }
+  if (result.skipped.length) {
+    ctx.log(`Skipped (no domains proposed): ${result.skipped.join(", ")}`);
+  }
+  return 0;
+}

package/src/commands/init.ts

@@ -0,0 +1,124 @@
+// `skl init` — first-run setup:
+//   1. ensure ~/.skillshelf/ exists and write a config.json (library + globalCore)
+//      unless one already exists (never clobbers without --force).
+//   2. ensure the library dir exists.
+//   3. symlink the thin global-core skills (bundle "global-core") into the
+//      global-core target (~/.claude/skills) so they auto-trigger every session.
+// Idempotent. Safe to re-run.
+
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+import type { Ctx } from "../types.ts";
+import { DEFAULT_CONFIG_FILE } from "../config.ts";
+import { resolveBundle } from "../core/bundle.ts";
+import { activeSkills } from "../core/library.ts";
+import {
+  ensureDir,
+  safeSymlink,
+  isSymlink,
+  realpathOrSelf,
+  realpathOrSelfAsync,
+} from "../lib/fs.ts";
+
+export const meta = {
+  name: "init",
+  summary: "Set up ~/.skillshelf config + library and link the global-core skills",
+  usage: "skl init [--force] [--json]",
+} as const;
+
+const GLOBAL_CORE_BUNDLE = "global-core";
+
+interface CoreLink {
+  name: string;
+  target: string;
+  link: string;
+  status: "linked" | "already" | "conflict";
+}
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  try {
+    const json = argv.includes("--json");
+    const force = argv.includes("--force");
+
+    const configFile = DEFAULT_CONFIG_FILE;
+    const libraryPath = ctx.config.libraryPath;
+    const globalCoreTarget = ctx.config.globalCoreTarget;
+
+    // 1. config dir + file
+    await ensureDir(dirname(configFile));
+    let configWritten = false;
+    if (!existsSync(configFile) || force) {
+      const body = JSON.stringify({ library: libraryPath, globalCore: globalCoreTarget }, null, 2) + "\n";
+      await Bun.write(configFile, body);
+      configWritten = true;
+    }
+
+    // 2. library dir
+    await ensureDir(libraryPath);
+
+    // 3. link global-core skills
+    let skills: Awaited<ReturnType<Ctx["loadLibrary"]>> = [];
+    try {
+      skills = await ctx.loadLibrary();
+    } catch {
+      skills = [];
+    }
+    const bundle = await resolveBundle(activeSkills(skills), GLOBAL_CORE_BUNDLE);
+
+    const coreLinks: CoreLink[] = [];
+    if (bundle.skills.length > 0) {
+      await ensureDir(globalCoreTarget);
+      for (const s of bundle.skills) {
+        const link = join(globalCoreTarget, s.name);
+        const target = s.path;
+        let status: CoreLink["status"] = "linked";
+
+        if (isSymlink(link)) {
+          const cur = realpathOrSelf(link);
+          const want = await realpathOrSelfAsync(target);
+          if (cur === want) status = "already";
+        } else if (existsSync(link)) {
+          // Real file already there — leave it alone.
+          coreLinks.push({ name: s.name, target, link, status: "conflict" });
+          continue;
+        }
+
+        await safeSymlink(target, link);
+        coreLinks.push({ name: s.name, target, link, status });
+      }
+    }
+
+    const conflicts = coreLinks.filter((l) => l.status === "conflict");
+
+    if (json) {
+      ctx.json({
+        configFile,
+        configWritten,
+        libraryPath,
+        globalCoreTarget,
+        globalCoreBundle: GLOBAL_CORE_BUNDLE,
+        coreLinks,
+      });
+    } else {
+      ctx.log("skillshelf initialized.");
+      ctx.log(`  config:      ${configFile}${configWritten ? " (written)" : " (kept existing)"}`);
+      ctx.log(`  library:     ${libraryPath}`);
+      ctx.log(`  global-core: ${globalCoreTarget}`);
+      if (bundle.skills.length === 0) {
+        ctx.log(`  (no skills tagged '${GLOBAL_CORE_BUNDLE}' yet — nothing to link)`);
+      } else {
+        ctx.log(`  linked ${coreLinks.length} global-core skill(s):`);
+        for (const l of coreLinks) {
+          const tag =
+            l.status === "linked" ? "linked" : l.status === "already" ? "ok" : "SKIP (real file present)";
+          ctx.log(`    ${l.name}  [${tag}]`);
+        }
+      }
+    }
+
+    return conflicts.length > 0 ? 1 : 0;
+  } catch (err) {
+    ctx.error(`skl init failed: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}

package/src/commands/ls.ts

@@ -0,0 +1,80 @@
+// `skl ls [bundle]` — one-line listing of the whole library, or a single
+// bundle (tag query). Excludes retired by default; `--all` includes them.
+
+import type { Ctx, Skill } from "../types.ts";
+import { activeSkills } from "../core/library.ts";
+import { resolveBundle } from "../core/bundle.ts";
+
+export const meta = {
+  name: "ls",
+  summary: "One-line listing of the library, or one bundle",
+  usage: "skl ls [bundle] [--all] [--json]",
+} as const;
+
+function oneLine(desc: string, max = 100): string {
+  const flat = desc.replace(/\s+/g, " ").trim();
+  return flat.length <= max ? flat : flat.slice(0, max - 1).trimEnd() + "…";
+}
+
+function emitHuman(ctx: Ctx, skills: Skill[]): void {
+  if (skills.length === 0) {
+    ctx.log("(no skills)");
+    return;
+  }
+  for (const s of skills) {
+    const tag = s.retired ? " (retired)" : "";
+    const dom =
+      s.primaryDomain && !s.retired ? ` [${s.primaryDomain}]` : "";
+    ctx.log(`${s.name}${dom}${tag} — ${oneLine(s.description)}`);
+  }
+}
+
+function toJson(skills: Skill[]): unknown {
+  return skills.map((s) => ({
+    name: s.name,
+    description: s.description,
+    primaryDomain: s.primaryDomain,
+    domains: s.domains,
+    path: s.path,
+    retired: s.retired,
+  }));
+}
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  try {
+    const json = argv.includes("--json");
+    const all = argv.includes("--all");
+    const positional = argv.filter((a) => !a.startsWith("--"));
+    const bundleName = positional[0];
+
+    const skills = await ctx.loadLibrary();
+
+    if (bundleName) {
+      const bundle = await resolveBundle(skills, bundleName, {
+        includeRetired: all,
+      });
+      if (json) {
+        ctx.json({ bundle: bundle.name, skills: toJson(bundle.skills) });
+        return 0;
+      }
+      if (bundle.skills.length === 0) {
+        ctx.log(`Bundle "${bundle.name}" has no skills.`);
+        return 0;
+      }
+      ctx.log(`# ${bundle.name} (${bundle.skills.length})`);
+      emitHuman(ctx, bundle.skills);
+      return 0;
+    }
+
+    const listed = all ? skills : activeSkills(skills);
+    if (json) {
+      ctx.json(toJson(listed));
+      return 0;
+    }
+    emitHuman(ctx, listed);
+    return 0;
+  } catch (err) {
+    ctx.error(`ls failed: ${(err as Error).message}`);
+    return 1;
+  }
+}