skillshelf 0.2.0 → 0.4.0

package/src/commands/ls.ts

@@ -1,16 +1,49 @@
 // `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 { statSync } from "node:fs";
+import type { Ctx, Skill, Provenance } from "../types.ts";
+import { activeSkills, entryModeInfo } from "../core/library.ts";
 import { resolveBundle } from "../core/bundle.ts";
+import { inventoryDeployments } from "../core/deployments.ts";
+import { knownAgentSurfacePaths } from "../core/surfaces.ts";
+import { isCleanSite } from "../core/agents.ts";
 
 export const meta = {
   name: "ls",
   summary: "One-line listing of the library, or one bundle",
-  usage: "skl ls [bundle] [--all] [--json]",
+  usage: "skl ls [bundle] [--all] [--sort modified|name|domain|deploys|source] [--json]",
 } as const;
 
+const SORT_FIELDS = ["modified", "name", "domain", "deploys", "source"] as const;
+type SortField = (typeof SORT_FIELDS)[number];
+
+/** Sort a copy of skills by a report field (modified/deploys descending). */
+function sortSkills(skills: Skill[], field: SortField, deployCounts: Map<string, number>): Skill[] {
+  const primary = (s: Skill) => s.primaryDomain ?? s.domains[0] ?? "_unclassified";
+  const mtimes =
+    field === "modified" ? new Map(skills.map((s) => [s.name, fileTimes(s.bodyPath).modifiedAt])) : null;
+  return skills.slice().sort((a, b) => {
+    if (field === "name") return a.name.localeCompare(b.name);
+    if (field === "domain") return primary(a).localeCompare(primary(b)) || a.name.localeCompare(b.name);
+    if (field === "source") {
+      const sa = a.source ? "vendored" : "local";
+      const sb = b.source ? "vendored" : "local";
+      return sa.localeCompare(sb) || a.name.localeCompare(b.name);
+    }
+    if (field === "deploys") {
+      return (deployCounts.get(b.name) ?? 0) - (deployCounts.get(a.name) ?? 0) || a.name.localeCompare(b.name);
+    }
+    // modified — most-recent first; null/untracked last.
+    const am = mtimes!.get(a.name) ?? null;
+    const bm = mtimes!.get(b.name) ?? null;
+    if (!am && !bm) return a.name.localeCompare(b.name);
+    if (!am) return 1;
+    if (!bm) return -1;
+    return bm.localeCompare(am);
+  });
+}
+
 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() + "…";
@@ -29,46 +62,130 @@ function emitHuman(ctx: Ctx, skills: Skill[]): void {
   }
 }
 
-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,
-  }));
+/** Stat-derived timestamps for a skill's SKILL.md (ISO-8601), null if unavailable. */
+function fileTimes(bodyPath: string): { modifiedAt: string | null; createdAt: string | null } {
+  try {
+    const st = statSync(bodyPath);
+    const created = st.birthtimeMs > 0 ? st.birthtime : null;
+    return {
+      modifiedAt: st.mtime.toISOString(),
+      createdAt: created ? created.toISOString() : null,
+    };
+  } catch {
+    return { modifiedAt: null, createdAt: null };
+  }
+}
+
+function toJson(
+  skills: Skill[],
+  libraryPath: string,
+  deployCounts: Map<string, number>,
+): unknown {
+  return skills.map((s) => {
+    const { mode, linkTarget } = entryModeInfo(libraryPath, s.name);
+    const { modifiedAt, createdAt } = fileTimes(s.bodyPath);
+    return {
+      name: s.name,
+      description: s.description,
+      primaryDomain: s.primaryDomain,
+      domains: s.domains,
+      path: s.path,
+      retired: s.retired,
+      mode,
+      linkTarget,
+      // ADR-0008 §7.1 additions: a string source (UI maps "vendored"/"local"),
+      // a human origin label (the real upstream, NOT a hard-coded channel),
+      // stat timestamps, and the count of clean deployment sites.
+      source: s.source ? "vendored" : "local",
+      origin: originLabel(s.source),
+      channel: s.source ? s.source.channel : null,
+      modifiedAt,
+      createdAt,
+      deployCount: deployCounts.get(s.name) ?? 0,
+    };
+  });
+}
+
+/**
+ * Short, human display of a vendored skill's real upstream origin, e.g.
+ * "jimliu/baoyu-skills" from "github:jimliu/baoyu-skills@skills/baoyu-translate".
+ * Null for hand-written (local) skills. Replaces the UI's old hard-coded
+ * "dbskill" label so the table tells the truth about where a skill came from.
+ */
+function originLabel(prov: Provenance | null): string | null {
+  if (!prov) return null;
+  const stripped = prov.source.replace(/@.*$/, ""); // drop @subpath
+  const colon = stripped.indexOf(":");
+  const repo = colon >= 0 ? stripped.slice(colon + 1) : stripped; // drop channel:
+  return repo || prov.channel || "vendored";
+}
+
+/** Count clean (`linked`) deployment sites per skill across all surfaces. */
+async function deployCountsFor(ctx: Ctx, lib: Skill[]): Promise<Map<string, number>> {
+  const counts = new Map<string, number>();
+  try {
+    const surfaces = [...ctx.roots, ctx.config.globalCoreTarget, ...knownAgentSurfacePaths()];
+    const report = await inventoryDeployments(surfaces, ctx.libraryPath, lib);
+    for (const site of report.sites) {
+      // "clean" = the ✓ states in `skl where` (linked OR canonical source), shared
+      // with the agents matrix via isCleanSite so the Deploys column agrees with it.
+      if (isCleanSite(site)) counts.set(site.name, (counts.get(site.name) ?? 0) + 1);
+    }
+  } catch {
+    // deployment scan is best-effort enrichment; ls still returns the library.
+  }
+  return counts;
 }
 
 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("--"));
+    // Extract `--sort <field>` and its value so the value isn't taken as a bundle.
+    const sortIdx = argv.indexOf("--sort");
+    const sortField = sortIdx >= 0 ? argv[sortIdx + 1] : undefined;
+    if (sortField !== undefined && !SORT_FIELDS.includes(sortField as SortField)) {
+      ctx.error(`ls: --sort expects one of: ${SORT_FIELDS.join(", ")}`);
+      return 1;
+    }
+    const consumed = new Set<number>();
+    if (sortIdx >= 0) {
+      consumed.add(sortIdx);
+      consumed.add(sortIdx + 1);
+    }
+    const positional = argv.filter((a, i) => !a.startsWith("--") && !consumed.has(i));
     const bundleName = positional[0];
 
     const skills = await ctx.loadLibrary();
+    // deployCounts needed for --json, or to sort by deploys.
+    const deployCounts =
+      json || sortField === "deploys"
+        ? await deployCountsFor(ctx, skills)
+        : new Map<string, number>();
+    const applySort = (list: Skill[]) =>
+      sortField ? sortSkills(list, sortField as SortField, deployCounts) : list;
 
     if (bundleName) {
       const bundle = await resolveBundle(skills, bundleName, {
         includeRetired: all,
       });
+      const rows = applySort(bundle.skills);
       if (json) {
-        ctx.json({ bundle: bundle.name, skills: toJson(bundle.skills) });
+        ctx.json({ bundle: bundle.name, skills: toJson(rows, ctx.libraryPath, deployCounts) });
         return 0;
       }
-      if (bundle.skills.length === 0) {
+      if (rows.length === 0) {
         ctx.log(`Bundle "${bundle.name}" has no skills.`);
         return 0;
       }
-      ctx.log(`# ${bundle.name} (${bundle.skills.length})`);
-      emitHuman(ctx, bundle.skills);
+      ctx.log(`# ${bundle.name} (${rows.length})`);
+      emitHuman(ctx, rows);
       return 0;
     }
 
-    const listed = all ? skills : activeSkills(skills);
+    const listed = applySort(all ? skills : activeSkills(skills));
     if (json) {
-      ctx.json(toJson(listed));
+      ctx.json(toJson(listed, ctx.libraryPath, deployCounts));
       return 0;
     }
     emitHuman(ctx, listed);

package/src/commands/migrate.test.ts

@@ -0,0 +1,157 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, rm, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run as migrateRun } from "./migrate.ts";
+import { readLockfile } from "../core/provenance.ts";
+import type { Ctx } from "../types.ts";
+
+function makeCtx(libraryPath: string) {
+  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 };
+}
+
+async function addLibSkill(library: string, name: string, body = "body") {
+  await mkdir(join(library, name), { recursive: true });
+  await writeFile(join(library, name, "SKILL.md"), `---\nname: ${name}\ndescription: d\n---\n\n${body}\n`);
+}
+
+// A fake vendor (.agents/.skill-lock.json) fixture covering every mapping branch.
+function vendorLock() {
+  return {
+    version: 3,
+    skills: {
+      // github with a subpath dir → github:owner/repo@dir
+      ghskill: {
+        source: "owner/repo",
+        sourceType: "github",
+        sourceUrl: "https://github.com/owner/repo",
+        skillPath: "skills/ghskill/SKILL.md",
+        skillFolderHash: "treesha-not-skl-hash",
+        installedAt: "2024-01-01T00:00:00.000Z",
+        ref: "main",
+      },
+      // github, NOT in the library → report only
+      ghmissing: {
+        source: "owner/other",
+        sourceType: "github",
+        sourceUrl: "https://github.com/owner/other",
+        skillPath: "SKILL.md",
+        skillFolderHash: "abc",
+        installedAt: "2024-01-01T00:00:00.000Z",
+      },
+      // git source → git:<url>#dir
+      gitskill: {
+        source: "ignored",
+        sourceType: "git",
+        sourceUrl: "/some/local/repo",
+        skillPath: "sub/gitskill/SKILL.md",
+        skillFolderHash: "def",
+        installedAt: "2024-01-01T00:00:00.000Z",
+      },
+      // local → not trackable
+      localskill: {
+        source: "localskill",
+        sourceType: "local",
+        sourceUrl: "/here",
+        skillPath: "SKILL.md",
+        skillFolderHash: "ghi",
+        installedAt: "2024-01-01T00:00:00.000Z",
+      },
+    },
+  };
+}
+
+describe("skl migrate — bulk-adopt from a vendor lock", () => {
+  let tmp: string;
+  let library: string;
+  let vendorPath: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-migrate-")));
+    library = join(tmp, "library");
+    await mkdir(library, { recursive: true });
+    // ghskill, gitskill, localskill exist in the library; ghmissing does NOT.
+    await addLibSkill(library, "ghskill");
+    await addLibSkill(library, "gitskill");
+    await addLibSkill(library, "localskill");
+    vendorPath = join(tmp, ".skill-lock.json");
+    await writeFile(vendorPath, JSON.stringify(vendorLock(), null, 2));
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("tracks in-library github/git skills, reports missing, flags local as not trackable", async () => {
+    const { ctx, json } = makeCtx(library);
+    const code = await migrateRun(["--from", vendorPath, "--json"], ctx);
+    expect(code).toBe(0);
+
+    const r = json[0] as {
+      counts: { tracked: number; skipped: number; notInLibrary: number; notTrackable: number };
+      tracked: Array<{ name: string; source: string }>;
+      notInLibrary: Array<{ name: string; source: string }>;
+      notTrackable: Array<{ name: string; sourceType: string }>;
+    };
+    expect(r.counts.tracked).toBe(2);
+    expect(r.counts.notInLibrary).toBe(1);
+    expect(r.counts.notTrackable).toBe(1);
+
+    const lock = await readLockfile(library);
+    // github subpath mapped to the @-convention.
+    expect(lock.entries.ghskill!.source).toBe("github:owner/repo@skills/ghskill");
+    expect(lock.entries.ghskill!.adopted).toBe(true);
+    // vendor tree-sha is NOT reused as installedHash; vendor branch is NOT the ref.
+    expect(lock.entries.ghskill!.installedHash).not.toBe("treesha-not-skl-hash");
+    expect(lock.entries.ghskill!.ref).toBe("");
+    // git source mapped to git:<url>#dir.
+    expect(lock.entries.gitskill!.source).toBe("git:/some/local/repo#sub/gitskill");
+
+    // missing skill is reported with an `skl add` line, never installed.
+    expect(r.notInLibrary[0]!.name).toBe("ghmissing");
+    expect(lock.entries.ghmissing).toBeUndefined();
+
+    // local skill is not trackable (no lock entry).
+    expect(r.notTrackable[0]!.name).toBe("localskill");
+    expect(lock.entries.localskill).toBeUndefined();
+  });
+
+  test("--dry-run previews without writing", async () => {
+    const { ctx, json } = makeCtx(library);
+    const code = await migrateRun(["--from", vendorPath, "--dry-run", "--json"], ctx);
+    expect(code).toBe(0);
+    expect((json[0] as { counts: { tracked: number } }).counts.tracked).toBe(2);
+    // No entries written.
+    expect(Object.keys((await readLockfile(library)).entries)).toHaveLength(0);
+  });
+
+  test("skips already-tracked skills unless --force", async () => {
+    // First pass tracks ghskill + gitskill.
+    await migrateRun(["--from", vendorPath], makeCtx(library).ctx);
+    // Second pass should skip both as already-tracked.
+    const { ctx, json } = makeCtx(library);
+    const code = await migrateRun(["--from", vendorPath, "--json"], ctx);
+    expect(code).toBe(0);
+    const r = json[0] as { counts: { tracked: number; skipped: number } };
+    expect(r.counts.tracked).toBe(0);
+    expect(r.counts.skipped).toBe(2);
+  });
+
+  test("rejects a non-vendor lock file", async () => {
+    const notVendor = join(tmp, "not-vendor.json");
+    await writeFile(notVendor, JSON.stringify({ version: 1, entries: {} }));
+    const { ctx, errors } = makeCtx(library);
+    const code = await migrateRun(["--from", notVendor], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("not a recognized vendor");
+  });
+});

package/src/commands/migrate.ts

@@ -0,0 +1,260 @@
+// `skl migrate [--from <path>]` — bulk-adopt provenance from a VENDOR skill lock
+// (e.g. ~/.agents/.skill-lock.json) for skills ALREADY in your library (ADR-0011).
+//
+//   skl migrate [--from <path>] [--dry-run] [--resolve] [--force] [--json]
+//
+// A thin adapter over `track`: it reads a foreign (vendor) lockfile, maps each vendor
+// entry to an `skl` source, and — for skills already in the library — calls the same
+// `trackOne` logic `skl track` uses. It NEVER installs/downloads: a skill not in the
+// library is REPORTED ONLY (with the `skl add <src>` line to bring it in). The vendor's
+// own hashes/refs are NOT reused (a vendor tree-SHA is not skl's body sha256, and a
+// vendor branch is not a commit) — so every adopted entry is `adopted: true` unless
+// --resolve verifies it.
+//
+// Buckets: ✓ tracked · ⊘ skipped (already tracked) · ⚠ not in library · (not trackable).
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import type { Ctx } from "../types.ts";
+import { loadLibrary, findByName } from "../core/library.ts";
+import { readLockfile } from "../core/provenance.ts";
+import { trackOne } from "./track.ts";
+
+export const meta = {
+  name: "migrate",
+  summary: "Bulk-adopt provenance from a vendor skill-lock for skills already in your library",
+  usage: "skl migrate [--from <path>] [--dry-run] [--resolve] [--force] [--json]",
+} as const;
+
+/** The default vendor lock location (the `agents`/`skills` CLI convention). */
+function defaultVendorLock(): string {
+  return join(homedir(), ".agents", ".skill-lock.json");
+}
+
+/** One entry in the vendor lock (the shape we adapt from). */
+interface VendorEntry {
+  source?: string;
+  sourceType?: "github" | "git" | "local" | "well-known" | string;
+  sourceUrl?: string;
+  skillPath?: string;
+  skillFolderHash?: string;
+  installedAt?: string;
+  ref?: string;
+}
+
+interface VendorLock {
+  version?: number;
+  skills?: Record<string, VendorEntry>;
+}
+
+interface Flags {
+  from: string | null;
+  dryRun: boolean;
+  resolve: boolean;
+  force: boolean;
+  json: boolean;
+}
+
+function parseFlags(argv: string[]): { flags: Flags } | { error: string } {
+  const flags: Flags = { from: null, dryRun: false, resolve: false, force: false, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--from") {
+      const v = argv[++i];
+      if (v === undefined) return { error: "--from requires a <path>" };
+      flags.from = v;
+    } else if (a.startsWith("--from=")) {
+      flags.from = a.slice("--from=".length);
+    } else if (a === "--dry-run") {
+      flags.dryRun = true;
+    } else if (a === "--resolve") {
+      flags.resolve = true;
+    } else if (a === "--force") {
+      flags.force = true;
+    } else if (a === "--json") {
+      flags.json = true;
+    } else if (a.startsWith("--")) {
+      return { error: `unknown argument: ${a}` };
+    } else {
+      return { error: `unexpected argument: ${a}` };
+    }
+  }
+  return { flags };
+}
+
+/** True if the parsed JSON looks like the vendor lock format (signature detection). */
+function isVendorLock(parsed: unknown): parsed is VendorLock {
+  if (!parsed || typeof parsed !== "object") return false;
+  const p = parsed as Record<string, unknown>;
+  if (p.version !== 3) return false;
+  if (!p.skills || typeof p.skills !== "object") return false;
+  // Carry the vendor signature: at least one entry with a skillFolderHash.
+  const skills = p.skills as Record<string, unknown>;
+  return Object.values(skills).some(
+    (e) => e && typeof e === "object" && "skillFolderHash" in (e as object),
+  );
+}
+
+/** POSIX dirname of a skillPath ("dir/SKILL.md" -> "dir"; "SKILL.md" -> ""). */
+function skillDir(skillPath: string | undefined): string {
+  if (!skillPath) return "";
+  const norm = skillPath.replace(/\\/g, "/").replace(/\/+$/, "");
+  const i = norm.lastIndexOf("/");
+  return i >= 0 ? norm.slice(0, i) : "";
+}
+
+/**
+ * Map a vendor entry to an `skl` source string, or null when it's not trackable.
+ *   github      → `github:owner/repo` (+ `@<dir>` if skillPath has a dir)
+ *   git         → `git:<sourceUrl>` (+ `#<dir>`)
+ *   local/well-known → null (no upstream to track)
+ * NOTE: the vendor `ref` (a branch) and `skillFolderHash` (a tree SHA) are deliberately
+ * NOT propagated — they are not skl's commit ref / body sha256.
+ */
+function mapVendorSource(entry: VendorEntry): string | null {
+  const dir = skillDir(entry.skillPath);
+  const type = entry.sourceType;
+  if (type === "github") {
+    if (!entry.source) return null;
+    return `github:${entry.source}${dir ? `@${dir}` : ""}`;
+  }
+  if (type === "git") {
+    if (!entry.sourceUrl) return null;
+    return `git:${entry.sourceUrl}${dir ? `#${dir}` : ""}`;
+  }
+  // local / well-known → not trackable (no upstream baseline).
+  return null;
+}
+
+interface TrackedRow { name: string; source: string; ref: string; adopted: boolean; note: string }
+interface SkippedRow { name: string; reason: string }
+interface MissingRow { name: string; source: string }
+interface NotTrackableRow { name: string; sourceType: string }
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const parsed = parseFlags(argv);
+  if ("error" in parsed) {
+    ctx.error(`skl migrate: ${parsed.error}`);
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  const flags = parsed.flags;
+  const fromPath = flags.from && flags.from.trim() !== "" ? flags.from.trim() : defaultVendorLock();
+  const libraryPath = ctx.config.libraryPath;
+
+  try {
+    if (!existsSync(fromPath)) {
+      ctx.error(`skl migrate: vendor lock not found: ${fromPath}`);
+      ctx.error("Point at one with --from <path>, or install skills via the vendor CLI first.");
+      return 1;
+    }
+
+    let vendorParsed: unknown;
+    try {
+      vendorParsed = JSON.parse(await Bun.file(fromPath).text());
+    } catch (err) {
+      ctx.error(`skl migrate: could not parse ${fromPath}: ${err instanceof Error ? err.message : String(err)}`);
+      return 1;
+    }
+    if (!isVendorLock(vendorParsed)) {
+      ctx.error(`skl migrate: ${fromPath} is not a recognized vendor skill-lock (expected {version:3, skills:{…}}).`);
+      return 1;
+    }
+    const vendorSkills = vendorParsed.skills ?? {};
+
+    const library = await loadLibrary(libraryPath);
+    const lock = await readLockfile(libraryPath);
+
+    const tracked: TrackedRow[] = [];
+    const skipped: SkippedRow[] = [];
+    const missing: MissingRow[] = [];
+    const notTrackable: NotTrackableRow[] = [];
+
+    // Stable iteration order by name.
+    const names = Object.keys(vendorSkills).sort();
+    for (const name of names) {
+      const entry = vendorSkills[name]!;
+      const source = mapVendorSource(entry);
+      if (source === null) {
+        notTrackable.push({ name, sourceType: entry.sourceType ?? "unknown" });
+        continue;
+      }
+
+      const inLibrary = Boolean(findByName(library, name));
+      if (!inLibrary) {
+        // REPORT ONLY — migrate never installs/downloads.
+        missing.push({ name, source });
+        continue;
+      }
+
+      // Already tracked → skip unless --force.
+      if (lock.entries[name] && !flags.force) {
+        skipped.push({ name, reason: "already tracked" });
+        continue;
+      }
+
+      if (flags.dryRun) {
+        tracked.push({ name, source, ref: "", adopted: true, note: "would track (dry-run)" });
+        continue;
+      }
+
+      const res = await trackOne(libraryPath, library, {
+        name,
+        source,
+        resolve: flags.resolve,
+        force: flags.force,
+      });
+      if (res.ok) {
+        tracked.push({ name, source: res.source, ref: res.ref, adopted: res.adopted, note: res.note });
+      } else {
+        // A guard tripped at track time (e.g. LINKED, source didn't round-trip) — surface it.
+        skipped.push({ name, reason: res.reason });
+      }
+    }
+
+    if (flags.json) {
+      ctx.json({
+        ok: true,
+        action: "migrate",
+        from: fromPath,
+        dryRun: flags.dryRun,
+        counts: {
+          tracked: tracked.length,
+          skipped: skipped.length,
+          notInLibrary: missing.length,
+          notTrackable: notTrackable.length,
+        },
+        tracked,
+        skipped,
+        notInLibrary: missing,
+        notTrackable,
+      });
+      return 0;
+    }
+
+    ctx.log(`migrate from ${fromPath}${flags.dryRun ? " (dry-run)" : ""}:`);
+    ctx.log("");
+    for (const r of tracked) {
+      ctx.log(`  ✓ tracked      ${r.name.padEnd(28)} ${r.source}${r.adopted ? "  (adopted)" : ""}${r.note ? `  — ${r.note}` : ""}`);
+    }
+    for (const r of skipped) {
+      ctx.log(`  ⊘ skipped      ${r.name.padEnd(28)} ${r.reason}`);
+    }
+    for (const r of missing) {
+      ctx.log(`  ⚠ not in library  ${r.name.padEnd(25)} bring it in: skl add ${r.source}`);
+    }
+    for (const r of notTrackable) {
+      ctx.log(`  · not trackable ${r.name.padEnd(27)} sourceType=${r.sourceType} (no upstream)`);
+    }
+    ctx.log("");
+    ctx.log(
+      `✓ tracked ${tracked.length} · ⊘ skipped ${skipped.length} (already tracked) · ⚠ not in library ${missing.length} · not trackable ${notTrackable.length}`,
+    );
+    if (missing.length > 0) ctx.log("Skills not in your library were only reported — `skl add <src>` to install them, then re-run migrate.");
+    return 0;
+  } catch (err) {
+    ctx.error(`skl migrate: failed: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}