skillshelf 0.2.0 → 0.4.0

package/src/commands/mode-surfacing.test.ts

@@ -0,0 +1,110 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, symlink, rm, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run as lsRun } from "./ls.ts";
+import { run as outdatedRun } from "./outdated.ts";
+import { run as updateRun } from "./update.ts";
+import { loadLibrary } from "../core/library.ts";
+import { hashContent } from "../core/crawl.ts";
+import { parseFrontmatter } from "../lib/frontmatter.ts";
+import type { Ctx } from "../types.ts";
+
+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("owned-vs-linked surfacing (friction #7)", () => {
+  let tmp: string;
+  let library: string;
+  let dev: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-mode-")));
+    library = join(tmp, "library");
+    await mkdir(join(library, "owned1"), { recursive: true });
+    await writeFile(join(library, "owned1", "SKILL.md"), "---\nname: owned1\ndescription: o\n---\n\nbody\n");
+    dev = join(tmp, "dev", "devskill");
+    await mkdir(dev, { recursive: true });
+    await writeFile(join(dev, "SKILL.md"), "---\nname: devskill\ndescription: d\n---\n\nbody\n");
+    await symlink(dev, join(library, "devskill"));
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("ls --json carries mode + linkTarget", async () => {
+    const { ctx, json } = makeCtx(library);
+    await lsRun(["--all", "--json"], ctx);
+    const rows = json[0] as Array<{ name: string; mode: string; linkTarget: string | null }>;
+    const owned = rows.find((r) => r.name === "owned1")!;
+    const linked = rows.find((r) => r.name === "devskill")!;
+    expect(owned.mode).toBe("owned");
+    expect(owned.linkTarget).toBeNull();
+    expect(linked.mode).toBe("linked");
+    expect(linked.linkTarget).toBe(dev);
+  });
+
+  test("outdated surfaces a LINKED skill that has NO lock entry", async () => {
+    const { ctx, json } = makeCtx(library);
+    const code = await outdatedRun(["--json"], ctx);
+    expect(code).toBe(0);
+    const rows = (json[0] as { rows: Array<{ name: string; status: string }> }).rows;
+    expect(rows.find((r) => r.name === "devskill")!.status).toBe("linked");
+  });
+
+  test("update reports a LINKED skill (no lock entry) as explicitly skipped", async () => {
+    const { ctx, json } = makeCtx(library);
+    await updateRun(["devskill", "--json"], ctx);
+    const results = (json[0] as { results: Array<{ name: string; outcome: string }> }).results;
+    expect(results.find((r) => r.name === "devskill")!.outcome).toBe("skipped");
+  });
+
+  test("outdated --check-local flags local divergence offline (no network)", async () => {
+    // owned1 tracked with an installedHash that does NOT match the local body.
+    const localBody = parseFrontmatter("---\nname: owned1\n---\n\nbody\n").body;
+    const staleHash = hashContent(localBody + "DIFFERENT");
+    await writeFile(
+      join(library, "shelf.lock.json"),
+      JSON.stringify({
+        version: 1,
+        entries: {
+          owned1: { name: "owned1", source: "github:o/r", ref: "abc", channel: "github", installedAt: "2020-01-01T00:00:00.000Z", localEdits: false, installedHash: staleHash },
+        },
+      }),
+    );
+    const { ctx, json } = makeCtx(library);
+    const code = await outdatedRun(["--check-local", "--json"], ctx);
+    expect(code).toBe(2); // diverged -> non-zero
+    const rows = (json[0] as { rows: Array<{ name: string; status: string }> }).rows;
+    expect(rows.find((r) => r.name === "owned1")!.status).toBe("diverged");
+  });
+
+  test("outdated --check-local reports a matching baseline as current (offline)", async () => {
+    const localBody = parseFrontmatter("---\nname: owned1\n---\n\nbody\n").body;
+    const matchHash = hashContent(localBody);
+    await writeFile(
+      join(library, "shelf.lock.json"),
+      JSON.stringify({
+        version: 1,
+        entries: {
+          owned1: { name: "owned1", source: "github:o/r", ref: "abc", channel: "github", installedAt: "2020-01-01T00:00:00.000Z", localEdits: false, installedHash: matchHash },
+        },
+      }),
+    );
+    const { ctx, json } = makeCtx(library);
+    const code = await outdatedRun(["--check-local", "--json"], ctx);
+    expect(code).toBe(0);
+    const rows = (json[0] as { rows: Array<{ name: string; status: string }> }).rows;
+    expect(rows.find((r) => r.name === "owned1")!.status).toBe("current");
+  });
+});

package/src/commands/outdated.test.ts

@@ -0,0 +1,55 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, symlink, rm, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run } from "./outdated.ts";
+import type { Ctx } from "../types.ts";
+
+function makeCtx(libraryPath: string) {
+  const json: unknown[] = [];
+  const ctx = {
+    config: { libraryPath },
+    libraryPath,
+    log: () => {},
+    error: () => {},
+    json: (v: unknown) => json.push(v),
+  } as unknown as Ctx;
+  return { ctx, json };
+}
+
+describe("skl outdated — LINKED entries are reported, not probed (ADR-0004)", () => {
+  let tmp: string;
+  let library: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-outdated-")));
+    library = join(tmp, "library");
+    const dev = join(tmp, "dev", "devskill");
+    await mkdir(library, { recursive: true });
+    await mkdir(dev, { recursive: true });
+    await writeFile(join(dev, "SKILL.md"), "---\nname: devskill\n---\n\nbody\n");
+    await symlink(dev, join(library, "devskill"));
+    await writeFile(
+      join(library, "shelf.lock.json"),
+      JSON.stringify({
+        version: 1,
+        entries: {
+          devskill: { name: "devskill", source: "github:owner/repo", ref: "abc", channel: "github", installedAt: "2020-01-01T00:00:00.000Z", localEdits: false },
+        },
+      }),
+    );
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("a LINKED entry is status 'linked', never counted stale", async () => {
+    const { ctx, json } = makeCtx(library);
+    const code = await run(["--json"], ctx);
+
+    expect(code).toBe(0); // not stale -> exit 0 (no network probe of the dead github ref)
+    const report = json[0] as { stale: number; rows: Array<{ name: string; status: string }> };
+    expect(report.stale).toBe(0);
+    expect(report.rows.find((r) => r.name === "devskill")!.status).toBe("linked");
+  });
+});

package/src/commands/outdated.ts

@@ -6,17 +6,22 @@
 //
 // Read command: supports --json.
 
-import type { Ctx, LockEntry } from "../types.ts";
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import type { Ctx, LockEntry, Skill } from "../types.ts";
 import { readLockfile } from "../core/provenance.ts";
+import { entryMode, entryModeInfo, loadLibrary, findByName } from "../core/library.ts";
+import { hashContent } from "../core/crawl.ts";
+import { parseFrontmatter } from "../lib/frontmatter.ts";
 import { parseStoredSource, latestRef } from "../core/fetch.ts";
 
 export const meta = {
   name: "outdated",
   summary: "Check upstream ref per tracked skill and mark stale ones",
-  usage: "skl outdated [name] [--json]",
+  usage: "skl outdated [name] [--check-local] [--json]",
 } as const;
 
-type Status = "stale" | "current" | "unknown";
+type Status = "stale" | "current" | "unknown" | "linked" | "diverged" | "adopted";
 
 interface Row {
   name: string;
@@ -59,53 +64,196 @@ async function checkEntry(entry: LockEntry): Promise<Row> {
   };
 }
 
+/**
+ * A LINKED entry (library/<name> symlinks to an external dev repo) has no tracked
+ * upstream — its own git owns versioning. Report it as such instead of probing a
+ * (possibly stale) github ref (ADR-0004).
+ */
+function linkedRow(entry: LockEntry): Row {
+  return {
+    name: entry.name,
+    channel: "local",
+    source: entry.source,
+    installedRef: entry.ref,
+    latestRef: null,
+    status: "linked",
+    note: "dev repo owns versioning",
+  };
+}
+
+/**
+ * A LINKED library skill with NO lockfile entry (the normal case for `skl link
+ * --from` — it drops any lock entry). Without this, a freshly-linked dev skill is
+ * INVISIBLE to outdated, giving an agent zero positive evidence its dev repo is the
+ * canonical source. Surface it as a `linked` row regardless.
+ */
+/**
+ * An ADOPTED entry (`skl track`/`skl migrate`): provenance is known but the upstream
+ * baseline was NEVER verified against real upstream (the recorded ref may be empty and
+ * the installedHash describes the LOCAL copy only). Reporting it as stale/current off the
+ * empty ref would be a lie, so surface it as `adopted` and do NOT network-probe (ADR-0011).
+ */
+function adoptedRow(entry: LockEntry): Row {
+  return {
+    name: entry.name,
+    channel: entry.channel,
+    source: entry.source,
+    installedRef: entry.ref || "-",
+    latestRef: null,
+    status: "adopted",
+    note: "provenance adopted; baseline unverified — run `skl update` to reconcile",
+  };
+}
+
+function linkedRowFromName(name: string, linkTarget: string | null): Row {
+  return {
+    name,
+    channel: "local",
+    source: linkTarget ?? "(dev repo)",
+    installedRef: "-",
+    latestRef: null,
+    status: "linked",
+    note: "dev repo owns versioning",
+  };
+}
+
+/**
+ * Offline (no network) divergence check for an OWNED tracked skill: compare the local
+ * SKILL.md body hash to the baseline recorded at install/update time
+ * (lockfile.installedHash). Answers "have I locally edited this?" without probing
+ * upstream — usable on a plane / in CI with no creds.
+ */
+function checkEntryLocal(entry: LockEntry, library: Skill[], libraryPath: string): Row {
+  const skill = findByName(library, entry.name);
+  const bodyPath = skill?.bodyPath ?? join(libraryPath, entry.name, "SKILL.md");
+  let localHash: string | null = null;
+  try {
+    if (existsSync(bodyPath)) {
+      const raw = readFileSync(bodyPath, "utf8");
+      localHash = hashContent(parseFrontmatter(raw).body);
+    }
+  } catch {
+    /* leave null */
+  }
+  const base = {
+    name: entry.name,
+    channel: entry.channel,
+    source: entry.source,
+    installedRef: entry.ref,
+    latestRef: null,
+  };
+  if (entry.installedHash == null) {
+    return { ...base, status: "unknown", note: "no recorded baseline (installed before hash tracking) — re-run `skl update` to record one" };
+  }
+  if (localHash == null) {
+    return { ...base, status: "unknown", note: "local SKILL.md unreadable" };
+  }
+  return localHash === entry.installedHash
+    ? { ...base, status: "current", note: "matches installed baseline (offline)" }
+    : { ...base, status: "diverged", note: "local body diverged from installed baseline (offline)" };
+}
+
 export async function run(argv: string[], ctx: Ctx): Promise<number> {
   const json = argv.includes("--json");
+  const checkLocal = argv.includes("--check-local");
   const nameArg = argv.find((a) => !a.startsWith("-")) ?? null;
+  const libraryPath = ctx.config.libraryPath;
 
   try {
-    const lock = await readLockfile(ctx.config.libraryPath);
+    const lock = await readLockfile(libraryPath);
     let entries = Object.values(lock.entries);
     if (nameArg) entries = entries.filter((e) => e.name === nameArg);
     entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 
-    if (entries.length === 0) {
+    // Load the library so we can (a) hash local bodies for --check-local and
+    // (b) surface LINKED skills that have NO lock entry — the normal `skl link
+    // --from` case — which would otherwise be invisible here.
+    const library = await loadLibrary(libraryPath);
+
+    const rows = await Promise.all(
+      entries.map((e) =>
+        entryMode(libraryPath, e.name) === "linked"
+          ? Promise.resolve(linkedRow(e))
+          : e.adopted === true
+            ? // An adopted entry has an unverified (often empty) baseline — never probe
+              // upstream off it; report it as `adopted` so `update` reconciles (ADR-0011).
+              // --check-local still does the offline body-vs-baseline compare below.
+              checkLocal
+              ? Promise.resolve(checkEntryLocal(e, library, libraryPath))
+              : Promise.resolve(adoptedRow(e))
+            : checkLocal
+              ? Promise.resolve(checkEntryLocal(e, library, libraryPath))
+              : checkEntry(e),
+      ),
+    );
+
+    // Augment: LINKED library skills not already represented by a lock entry get a
+    // `linked` row, so a freshly-shelved dev skill shows positive evidence.
+    const known = new Set(rows.map((r) => r.name));
+    for (const s of library) {
+      if (known.has(s.name)) continue;
+      if (nameArg && s.name !== nameArg) continue;
+      const info = entryModeInfo(libraryPath, s.name);
+      if (info.mode === "linked") rows.push(linkedRowFromName(s.name, info.linkTarget));
+    }
+    rows.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+    if (rows.length === 0) {
       if (json) ctx.json({ ok: true, checked: 0, stale: 0, rows: [] });
       else if (nameArg) ctx.log(`no tracked skill named "${nameArg}"`);
       else ctx.log("no tracked third-party skills (lockfile is empty)");
       return 0;
     }
 
-    const rows = await Promise.all(entries.map((e) => checkEntry(e)));
     const stale = rows.filter((r) => r.status === "stale");
+    const diverged = rows.filter((r) => r.status === "diverged");
 
     if (json) {
       ctx.json({
         ok: true,
         checked: rows.length,
         stale: stale.length,
+        diverged: diverged.length,
         rows,
       });
     } else {
       for (const r of rows) {
-        const mark = r.status === "stale" ? "STALE  " : r.status === "current" ? "current" : "unknown";
+        const mark =
+          r.status === "stale" ? "STALE   "
+            : r.status === "diverged" ? "DIVERGED"
+              : r.status === "current" ? "current "
+                : r.status === "linked" ? "linked  "
+                  : r.status === "adopted" ? "adopted "
+                    : "unknown ";
         const refInfo =
-          r.status === "stale"
-            ? `${shortRef(r.installedRef)} -> ${shortRef(r.latestRef ?? "")}`
-            : r.status === "current"
-              ? shortRef(r.installedRef)
-              : `${shortRef(r.installedRef)} (${r.note})`;
-        const extra = r.note && r.status !== "unknown" ? `  [${r.note}]` : "";
+          r.status === "linked"
+            ? r.note
+            : r.status === "adopted"
+              ? r.note
+              : r.status === "stale"
+                ? `${shortRef(r.installedRef)} -> ${shortRef(r.latestRef ?? "")}`
+                : r.status === "diverged"
+                  ? r.note
+                  : r.status === "current"
+                    ? shortRef(r.installedRef) + (checkLocal ? " (offline)" : "")
+                    : `${shortRef(r.installedRef)} (${r.note})`;
+        const extra =
+          r.note && !["unknown", "linked", "diverged", "adopted"].includes(r.status) ? `  [${r.note}]` : "";
         ctx.log(`${mark}  ${r.name.padEnd(28)} ${r.channel.padEnd(15)} ${refInfo}${extra}`);
       }
       ctx.log("");
-      ctx.log(`${rows.length} tracked, ${stale.length} stale.`);
-      if (stale.length > 0) {
-        ctx.log(`run \`skl update [name]\` to re-pull (overlays are preserved).`);
+      if (checkLocal) {
+        ctx.log(`${rows.length} tracked, ${diverged.length} locally diverged (offline check — no upstream probed).`);
+        if (diverged.length > 0) ctx.log("re-run \`skl update [name]\` to see the upstream diff, or \`--force\` to overwrite.");
+      } else {
+        ctx.log(`${rows.length} tracked, ${stale.length} stale.`);
+        if (stale.length > 0) ctx.log(`run \`skl update [name]\` to re-pull (domain tags are preserved).`);
       }
     }
-    // Non-zero exit when stale skills exist, so agents/CI can branch on it.
-    return stale.length > 0 ? 2 : 0;
+    // Non-zero exit when stale (or, offline, locally-diverged) skills exist, so
+    // agents/CI can branch on it.
+    const flagged = checkLocal ? diverged.length : stale.length;
+    return flagged > 0 ? 2 : 0;
   } catch (err) {
     ctx.error("outdated: failed:", err instanceof Error ? err.message : String(err));
     return 1;

package/src/commands/projects.test.ts

@@ -0,0 +1,85 @@
+// `skl projects [add|rm|ls]` verb (ADR-0010 §5a). Drives the real ctx through an
+// isolated SKILLSHELF_CONFIG so the JSON shapes the GUI/bridge bind to are pinned.
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadContext } from "../config.ts";
+import { run as projectsRun } from "./projects.ts";
+import type { Ctx } from "../types.ts";
+
+describe("skl projects verb", () => {
+  let tmp: string;
+  let cfg: string;
+
+  async function makeCtx(): Promise<{ ctx: Ctx; json: unknown[]; logs: string[] }> {
+    const json: unknown[] = [];
+    const logs: string[] = [];
+    const ctx = await loadContext({ env: { SKILLSHELF_CONFIG: cfg } as NodeJS.ProcessEnv });
+    ctx.json = (v: unknown) => json.push(v);
+    ctx.log = (...a: unknown[]) => logs.push(a.join(" "));
+    ctx.error = () => {};
+    return { ctx, json, logs };
+  }
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(join(tmpdir(), "skl-projects-cmd-"));
+    cfg = join(tmp, "config.json");
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("ls --json on an empty registry returns {projects:[]}", async () => {
+    const { ctx, json } = await makeCtx();
+    const code = await projectsRun(["ls", "--json"], ctx);
+    expect(code).toBe(0);
+    expect(json[0]).toEqual({ projects: [] });
+  });
+
+  test("default verb (no args) is ls", async () => {
+    const { ctx, json } = await makeCtx();
+    const code = await projectsRun(["--json"], ctx);
+    expect(code).toBe(0);
+    expect(json[0]).toEqual({ projects: [] });
+  });
+
+  test("add persists and reports the updated list", async () => {
+    const { ctx, json } = await makeCtx();
+    const code = await projectsRun(["add", "/tmp/webapp", "--json"], ctx);
+    expect(code).toBe(0);
+    expect(json[0]).toEqual({ projects: ["/tmp/webapp"], added: true });
+
+    // a fresh ctx reads it back from disk
+    const { ctx: ctx2, json: json2 } = await makeCtx();
+    await projectsRun(["ls", "--json"], ctx2);
+    expect(json2[0]).toEqual({ projects: ["/tmp/webapp"] });
+  });
+
+  test("rm removes a persisted project", async () => {
+    const { ctx } = await makeCtx();
+    await projectsRun(["add", "/tmp/webapp"], ctx);
+    const { ctx: ctx2, json } = await makeCtx();
+    const code = await projectsRun(["rm", "/tmp/webapp", "--json"], ctx2);
+    expect(code).toBe(0);
+    expect(json[0]).toEqual({ projects: [], removed: true });
+  });
+
+  test("rm on a non-registered path reports removed:false", async () => {
+    const { ctx, json } = await makeCtx();
+    const code = await projectsRun(["rm", "/tmp/nope", "--json"], ctx);
+    expect(code).toBe(0);
+    expect(json[0]).toEqual({ projects: [], removed: false });
+  });
+
+  test("add without a path errors", async () => {
+    const { ctx } = await makeCtx();
+    expect(await projectsRun(["add"], ctx)).toBe(1);
+  });
+
+  test("unknown verb errors", async () => {
+    const { ctx } = await makeCtx();
+    expect(await projectsRun(["frobnicate"], ctx)).toBe(1);
+  });
+});

package/src/commands/projects.ts

@@ -0,0 +1,80 @@
+// `skl projects [add|rm|ls] [path]` — manage the persisted NAV projects list
+// (ADR-0010 §5a). This is navigation state only: a persisted project becomes a
+// selectable scope in the management UI even before anything is deployed into it.
+// It is NEVER deployment truth — cell/count state is always derived from reality
+// (`skl agents`/`skl where`), so an added-but-empty project shows all-absent cells.
+//
+//   skl projects [ls] [--json]   list the persisted nav projects (default verb)
+//   skl projects add <path>      add a project dir (expands ~, absolutizes, de-dupes)
+//   skl projects rm <path>       remove a project dir (matched by resolved path)
+//
+// The GUI's `+ Add project` persists through this verb behind the Tauri bridge.
+
+import type { Ctx } from "../types.ts";
+
+export const meta = {
+  name: "projects",
+  summary: "Manage the persisted nav projects shown as scopes in the UI (add/rm/ls)",
+  usage: "skl projects [ls|add <path>|rm <path>] [--json]",
+} as const;
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const json = argv.includes("--json");
+  const rest = argv.filter((a) => a !== "--json");
+  const verb = rest[0] && !rest[0].startsWith("-") ? rest[0] : "ls";
+
+  if (verb === "ls") {
+    const unknown = rest.slice(verb === rest[0] ? 1 : 0).find((a) => a.startsWith("-"));
+    if (unknown) return usageError(ctx, `unknown argument: ${unknown}`);
+    const projects = ctx.config.projects;
+    if (json) {
+      ctx.json({ projects });
+      return 0;
+    }
+    if (projects.length === 0) {
+      ctx.log("No nav projects configured.");
+      ctx.log("Add one with:  skl projects add <path>");
+      return 0;
+    }
+    ctx.log(`Nav projects (${projects.length}):`);
+    for (const p of projects) ctx.log(`  ${p}`);
+    return 0;
+  }
+
+  if (verb === "add") {
+    const path = rest[1];
+    if (!path || path.startsWith("-")) return usageError(ctx, "add requires a path");
+    const projects = await ctx.addProject(path);
+    if (json) {
+      ctx.json({ projects, added: true });
+      return 0;
+    }
+    ctx.log(`Added project. Nav projects (${projects.length}):`);
+    for (const p of projects) ctx.log(`  ${p}`);
+    return 0;
+  }
+
+  if (verb === "rm") {
+    const path = rest[1];
+    if (!path || path.startsWith("-")) return usageError(ctx, "rm requires a path");
+    const { projects, removed } = await ctx.removeProject(path);
+    if (json) {
+      ctx.json({ projects, removed });
+      return 0;
+    }
+    ctx.log(removed ? "Removed project." : "No matching project (nothing removed).");
+    if (projects.length > 0) {
+      ctx.log(`Nav projects (${projects.length}):`);
+      for (const p of projects) ctx.log(`  ${p}`);
+    }
+    return 0;
+  }
+
+  return usageError(ctx, `unknown verb: ${verb}`);
+}
+
+function usageError(ctx: Ctx, msg: string): number {
+  ctx.error(`skl projects: ${msg}`);
+  ctx.error(`usage: ${meta.usage}`);
+  return 1;
+}