skillshelf 0.6.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillshelf",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Agent-first skill registry + manager for Claude Code and compatible agents.",
   "type": "module",
   "license": "MIT",

package/src/commands/outdated.test.ts

@@ -2,7 +2,7 @@ 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 { run, mapLimit } from "./outdated.ts";
 import type { Ctx } from "../types.ts";
 
 function makeCtx(libraryPath: string) {
@@ -53,3 +53,149 @@ describe("skl outdated — LINKED entries are reported, not probed (ADR-0004)",
     expect(report.rows.find((r) => r.name === "devskill")!.status).toBe("linked");
   });
 });
+
+async function git(cwd: string, args: string[]): Promise<void> {
+  const p = Bun.spawn(["git", ...args], {
+    cwd,
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: "t",
+      GIT_AUTHOR_EMAIL: "t@t",
+      GIT_COMMITTER_NAME: "t",
+      GIT_COMMITTER_EMAIL: "t@t",
+    },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  await p.exited;
+}
+
+async function gitOut(cwd: string, args: string[]): Promise<string> {
+  const p = Bun.spawn(["git", ...args], { cwd, stdout: "pipe", stderr: "pipe" });
+  const out = await new Response(p.stdout).text();
+  await p.exited;
+  return out.trim();
+}
+
+// Regression: an OWNED github/git entry whose upstream HEAD has advanced past the
+// installed ref MUST surface as "stale". This is the online ref-compare path
+// (classify step 7) that was dead code while checkEntry fed localHash:null — every
+// online row collapsed to "current" and `outdated` could never flag an update
+// (and the UI ↑ badge, keyed off status==="stale", never lit). Uses the git: channel
+// over a real LOCAL repo so the "latest ref" probe is offline (`git ls-remote <path>`).
+describe("skl outdated — online ref-compare flags a moved upstream as stale", () => {
+  let tmp: string;
+  let library: string;
+  let upstream: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-outdated-stale-")));
+    library = join(tmp, "library");
+    upstream = join(tmp, "upstream");
+    await mkdir(join(upstream, "skills", "foo"), { recursive: true });
+    await writeFile(
+      join(upstream, "skills", "foo", "SKILL.md"),
+      "---\nname: foo\ndescription: foo skill\n---\n\nFOO BODY\n",
+    );
+    await git(upstream, ["init", "-q"]);
+    await git(upstream, ["add", "-A"]);
+    await git(upstream, ["commit", "-q", "-m", "v1"]);
+    const ref1 = await gitOut(upstream, ["rev-parse", "HEAD"]);
+
+    // Library copy of foo (readable body → a real localHash) pinned to ref1.
+    await mkdir(join(library, "foo"), { recursive: true });
+    await writeFile(
+      join(library, "foo", "SKILL.md"),
+      "---\nname: foo\ndescription: foo skill\n---\n\nFOO BODY\n",
+    );
+    await writeFile(
+      join(library, "shelf.lock.json"),
+      JSON.stringify({
+        version: 1,
+        entries: {
+          foo: {
+            name: "foo",
+            source: `git:${upstream}#skills/foo`,
+            ref: ref1,
+            channel: "git",
+            installedAt: "2020-01-01T00:00:00.000Z",
+            localEdits: false,
+          },
+        },
+      }),
+    );
+
+    // Advance upstream HEAD past ref1 — the repo moved on since install.
+    await writeFile(join(upstream, "skills", "foo", "note.txt"), "changed\n");
+    await git(upstream, ["add", "-A"]);
+    await git(upstream, ["commit", "-q", "-m", "v2"]);
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("an owned entry whose upstream HEAD advanced is status 'stale' (exit 2)", async () => {
+    const { ctx, json } = makeCtx(library);
+    const code = await run(["--json"], ctx);
+
+    expect(code).toBe(2); // stale exists → non-zero so CI/agents can branch on it
+    const report = json[0] as {
+      stale: number;
+      rows: Array<{ name: string; status: string }>;
+    };
+    expect(report.stale).toBe(1);
+    expect(report.rows.find((r) => r.name === "foo")!.status).toBe("stale");
+  });
+});
+
+// The concurrency bound is the fix for the "unknown storm" — firing one network
+// probe per skill all at once dropped 59/87 probes to transient failures. These
+// pin the three invariants the storm fix relies on: peak in-flight <= limit, every
+// item runs once, and output order matches input (rows must not scramble).
+describe("mapLimit — bounded-concurrency probe pool", () => {
+  test("never runs more than `limit` tasks concurrently", async () => {
+    let inflight = 0;
+    let peak = 0;
+    const items = Array.from({ length: 20 }, (_, i) => i);
+    await mapLimit(items, 4, async () => {
+      inflight++;
+      peak = Math.max(peak, inflight);
+      await new Promise((r) => setTimeout(r, 5));
+      inflight--;
+      return null;
+    });
+    expect(peak).toBeLessThanOrEqual(4);
+    expect(peak).toBeGreaterThan(1); // genuinely parallel, not accidentally serialized
+  });
+
+  test("preserves input order regardless of completion order", async () => {
+    // Later items finish FIRST (descending delay); output must still be by index.
+    const out = await mapLimit([40, 30, 20, 10], 4, async (ms, i) => {
+      await new Promise((r) => setTimeout(r, ms));
+      return `${i}:${ms}`;
+    });
+    expect(out).toEqual(["0:40", "1:30", "2:20", "3:10"]);
+  });
+
+  test("runs every item exactly once", async () => {
+    const seen: number[] = [];
+    const items = Array.from({ length: 15 }, (_, i) => i);
+    const out = await mapLimit(items, 6, async (n) => {
+      seen.push(n);
+      return n * 2;
+    });
+    expect(out).toEqual(items.map((n) => n * 2));
+    expect([...seen].sort((a, b) => a - b)).toEqual(items);
+  });
+
+  test("limit exceeding the list length still resolves all; empty list is empty", async () => {
+    expect(await mapLimit([1, 2, 3], 100, async (n) => n + 1)).toEqual([2, 3, 4]);
+    expect(await mapLimit([], 6, async (n: number) => n)).toEqual([]);
+  });
+
+  test("limit <= 0 is clamped to 1 (no undefined holes), still processes all", async () => {
+    const out = await mapLimit([1, 2, 3], 0, async (n) => n * 10);
+    expect(out).toEqual([10, 20, 30]);
+    expect(out.every((v) => v !== undefined)).toBe(true);
+  });
+});

package/src/commands/outdated.ts

@@ -36,7 +36,27 @@ export interface OutdatedRow {
   note: string;
 }
 
-async function checkEntry(entry: LockEntry): Promise<OutdatedRow> {
+/**
+ * Hash the on-disk SKILL.md body (frontmatter-stripped) of a tracked skill, or null when
+ * the file is missing/unreadable. The online check MUST feed this into classify: with
+ * localHash==null the classifier short-circuits to "unknown" (reconcile.ts step 4) and
+ * NEVER reaches the ref-compare (step 7), so `outdated` could never surface a stale skill
+ * — the ref-compare was dead code and the UI ↑ badge (keys off status==="stale") never lit.
+ */
+function localBodyHash(name: string, library: Skill[], libraryPath: string): string | null {
+  const skill = findByName(library, name);
+  const bodyPath = skill?.bodyPath ?? join(libraryPath, name, "SKILL.md");
+  try {
+    if (existsSync(bodyPath)) {
+      return hashContent(parseFrontmatter(readFileSync(bodyPath, "utf8")).body);
+    }
+  } catch {
+    /* leave null */
+  }
+  return null;
+}
+
+async function checkEntry(entry: LockEntry, library: Skill[], libraryPath: string): Promise<OutdatedRow> {
   const parsed = parseStoredSource(entry.source);
   const res = await latestRef(parsed);
   if (!res.ok) {
@@ -51,14 +71,16 @@ async function checkEntry(entry: LockEntry): Promise<OutdatedRow> {
     };
   }
   const latest = res.ref;
-  // Ref-only online view (no upstream body fetched): classify maps to stale/current
-  // off the ref compare. Same surface word as before; the disambiguation is internal.
+  // Ref-only online view (no upstream body fetched): classify maps to stale/current off
+  // the ref compare (step 7) — but only if a real localHash is supplied (else the step-4
+  // localHash==null guard returns "unknown" before the ref compare is ever reached).
+  const localHash = localBodyHash(entry.name, library, libraryPath);
   const verdict = classify({
     adopted: false,
     mode: "owned",
     installedHash: entry.installedHash ?? null,
     localEdits: entry.localEdits,
-    localHash: null,
+    localHash,
     upstreamHash: null,
     installedRef: entry.ref,
     latestRef: latest,
@@ -70,8 +92,16 @@ async function checkEntry(entry: LockEntry): Promise<OutdatedRow> {
     source: entry.source,
     installedRef: entry.ref,
     latestRef: latest,
-    status: verdict === "stale" ? "stale" : "current",
-    note: entry.localEdits ? "has local edits" : "",
+    // Map the verdict explicitly: an unreadable local body yields "unknown" (localHash
+    // null → classify step 4), NOT a falsely-reassuring "current". Only a real ref-compare
+    // (readable body) produces stale/current.
+    status: verdict === "stale" ? "stale" : verdict === "unknown" ? "unknown" : "current",
+    note:
+      verdict === "unknown"
+        ? "local SKILL.md missing/unreadable — cannot compare against upstream"
+        : entry.localEdits
+          ? "has local edits"
+          : "",
   };
 }
 
@@ -180,6 +210,38 @@ function checkEntryLocal(entry: LockEntry, library: Skill[], libraryPath: string
     : { ...base, status: "current", note: "matches installed baseline (offline)" };
 }
 
+/**
+ * Resolve an array through an async fn with BOUNDED concurrency, preserving input order.
+ * `outdated` probes an upstream ref per tracked skill; firing one `git ls-remote` for the
+ * WHOLE lockfile at once (unbounded Promise.all) opens dozens of simultaneous TLS handshakes
+ * that a flaky network / connection cap turns into a storm of transient "unable to access"
+ * failures — every one collapsing to status "unknown". A small pool caps in-flight probes so
+ * they succeed instead of overwhelming the transport (a failed probe degrades to "unknown",
+ * not a retry — a status check must not hang on a flaky host).
+ *
+ * `fn` MUST resolve (never reject): a rejection would tear down the pool via Promise.all
+ * while sibling workers keep running (risking an unhandled rejection). Every current caller
+ * branch is throw-free by contract; a future throwing `fn` must catch internally.
+ */
+export async function mapLimit<T, R>(
+  items: T[],
+  limit: number,
+  fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  const out: R[] = new Array(items.length);
+  let next = 0;
+  async function worker(): Promise<void> {
+    for (let i = next++; i < items.length; i = next++) {
+      out[i] = await fn(items[i]!, i);
+    }
+  }
+  // Clamp to >=1 worker: a limit of 0 (or negative) would spawn none, leaving `out` full
+  // of undefined holes. min() with items.length avoids spawning idle workers.
+  const workerCount = Math.max(1, Math.min(limit, items.length));
+  await Promise.all(Array.from({ length: workerCount }, () => worker()));
+  return out;
+}
+
 export async function run(argv: string[], ctx: Ctx): Promise<number> {
   const json = argv.includes("--json");
   const checkLocal = argv.includes("--check-local");
@@ -197,21 +259,24 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     // --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),
-      ),
+    // Bounded concurrency (not an unbounded Promise.all): the online checkEntry path
+    // makes a network probe per skill, and firing all of them at once storms the transport
+    // into transient failures (→ status "unknown"). Offline branches (linked/adopted/
+    // --check-local) resolve instantly and cost nothing extra under the pool.
+    const PROBE_CONCURRENCY = 6;
+    const rows = await mapLimit(entries, PROBE_CONCURRENCY, (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, library, libraryPath),
     );
 
     // Augment: LINKED library skills not already represented by a lock entry get a

package/src/core/fetch.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+import { isTransientGitError, fetchRepo, parseSource, cleanupStaging } from "./fetch.ts";
+
+// The retry gate for cloneWithRetry/lsRemoteWithRetry. Getting this wrong is
+// costly in BOTH directions: a definitive failure classed transient burns 3
+// attempts on a 404/auth that can never succeed; a real transient classed
+// definitive fails a whole `skl update --repo` run on one network blip.
+describe("isTransientGitError — retry gate", () => {
+  test("the observed LibreSSL handshake blip is transient (retry)", () => {
+    // The exact fault that failed all 35 skills in one dry-run this session.
+    expect(
+      isTransientGitError(
+        "fatal: unable to access 'https://github.com/owner/repo.git/': LibreSSL SSL_connect: SSL_ERROR_SYSCALL in connection to github.com:443",
+      ),
+    ).toBe(true);
+  });
+
+  test.each([
+    "fatal: unable to access '...': Failed to connect to github.com port 443: Connection reset by peer",
+    "fatal: unable to access '...': Could not resolve host: github.com",
+    "error: RPC failed; curl 92 HTTP/2 stream 0 was not closed cleanly",
+    "fatal: the remote end hung up unexpectedly\nfatal: early EOF",
+    "fatal: unable to access '...': Operation timed out after 30001 milliseconds",
+    "fatal: the remote end hung up unexpectedly",
+    "fatal: protocol error: bad pack header",
+    "error: unexpected disconnect while reading sideband packet",
+    "kex_exchange_identification: Connection closed by remote host",
+  ])("transient network fault → retry: %s", (stderr) => {
+    expect(isTransientGitError(stderr)).toBe(true);
+  });
+
+  test.each([
+    "fatal: repository 'https://github.com/owner/gone.git/' not found",
+    "remote: Repository not found.",
+    "fatal: Authentication failed for 'https://github.com/owner/private.git/'",
+    "fatal: unable to access '...': The requested URL returned error: 404",
+    "fatal: unable to access '...': The requested URL returned error: 403",
+    "remote: Permission denied",
+  ])("definitive failure → fail fast (no retry): %s", (stderr) => {
+    expect(isTransientGitError(stderr)).toBe(false);
+  });
+
+  test("a 404 that also says 'unable to access' still fails fast (guard wins)", () => {
+    // "unable to access" is a transient signal, but the 404 must veto it — else
+    // a missing repo would be retried 3× for nothing.
+    expect(
+      isTransientGitError(
+        "fatal: unable to access '...': The requested URL returned error: 404",
+      ),
+    ).toBe(false);
+  });
+
+  test("empty / unrecognized stderr is not treated as transient", () => {
+    expect(isTransientGitError("")).toBe(false);
+    expect(isTransientGitError("fatal: something totally novel")).toBe(false);
+  });
+});
+
+// Integration guard for the retry loop's fail-fast path: a clone of a nonexistent
+// local repo fails with a DEFINITIVE error ("does not appear to be a git repository"),
+// so cloneWithRetry must NOT burn 3 attempts on it — it returns quickly with ok:false.
+// (The happy path of cloneWithRetry/lsRemoteWithRetry is exercised by the update
+// rename/orphan test and the outdated online-stale test over real local repos.)
+describe("fetchRepo — non-transient clone failure fails fast", () => {
+  test("a missing local git repo returns ok:false without retry churn", async () => {
+    const started = performance.now();
+    const res = await fetchRepo(parseSource("git:/no/such/skillshelf/repo/xyz"));
+    const elapsedMs = performance.now() - started;
+
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.error).toContain("git clone failed");
+      await cleanupStaging(res.staging);
+    }
+    // 3 transient retries would add ~0.9s of backoff; fail-fast stays well under that.
+    expect(elapsedMs).toBeLessThan(800);
+  });
+});

package/src/core/fetch.ts

@@ -579,6 +579,39 @@ function localCloneUrl(localPath: string): string {
   return pathToFileURL(isAbsolute(localPath) ? localPath : resolve(localPath)).href;
 }
 
+/**
+ * A `git clone` failure worth retrying: a TRANSIENT network/TLS fault, not a definitive
+ * one (repo not found / auth / 404) which will never succeed and must fail fast. The
+ * definitive-failure guard is checked FIRST so a "unable to access … 404" is never mistaken
+ * for the transient "unable to access … SSL_ERROR_SYSCALL" handshake blip.
+ */
+export function isTransientGitError(stderr: string): boolean {
+  if (/not found|does not (exist|appear)|repository not found|authentication failed|\b40[134]\b|permission denied|invalid username or password/i.test(stderr)) {
+    return false;
+  }
+  return /ssl_error|ssl_connect|\btls\b|gnutls|connection reset|connection timed out|could not resolve host|recv failure|send failure|unable to access|early eof|rpc failed|temporary failure|operation timed out|connection refused|failed to connect|timed out|remote end hung up|protocol error|unexpected disconnect|kex_exchange_identification|connection closed by remote/i.test(stderr);
+}
+
+/**
+ * `git clone --depth 1` with a bounded retry on TRANSIENT network/TLS faults. A single
+ * flaky handshake (observed: LibreSSL `SSL_ERROR_SYSCALL`) otherwise fails an ENTIRE `skl
+ * update --repo` run — the repo is cloned once for the whole group, so one blip reports
+ * "error" for every skill in it. Non-transient failures fail fast (one attempt). The partial
+ * checkout dir is removed between attempts so the re-clone starts from a clean slate.
+ */
+async function cloneWithRetry(cloneTarget: string, checkout: string): Promise<RunResult> {
+  const MAX_ATTEMPTS = 3;
+  let last: RunResult = { ok: false, code: -1, stdout: "", stderr: "" };
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    last = await run(["git", "clone", "--depth", "1", cloneTarget, checkout]);
+    if (last.ok) return last;
+    if (attempt === MAX_ATTEMPTS || !isTransientGitError(last.stderr)) return last;
+    await rm(checkout, { recursive: true, force: true }).catch(() => {});
+    await new Promise((resolve) => setTimeout(resolve, 300 * attempt));
+  }
+  return last;
+}
+
 /**
  * Clone a github/git source ONCE into a fresh staging dir and capture HEAD. Shared
  * by the single-skill fetch (fetchGithub/fetchGit) and the repo-wide fetchRepo so a
@@ -609,7 +642,7 @@ async function cloneToStaging(
   }
 
   const checkout = join(staging, "repo");
-  const clone = await run(["git", "clone", "--depth", "1", cloneTarget, checkout]);
+  const clone = await cloneWithRetry(cloneTarget, checkout);
   if (!clone.ok) {
     return {
       ok: false,
@@ -786,7 +819,10 @@ export async function latestGithubRef(parsed: ParsedSource): Promise<RefResult>
     }
   }
 
-  // Fallback: ls-remote default HEAD.
+  // Fallback: ls-remote default HEAD. NOT retried — this is a status probe (one per
+  // skill under `outdated`'s bounded pool); a transient blip degrades to "unknown" (cheap,
+  // re-runnable) rather than retrying with backoff, which would make a single hung probe
+  // blow a caller's time budget. Retry is reserved for the expensive clone path.
   if (await hasBinary("git")) {
     const url = `https://github.com/${parsed.owner}/${parsed.repo}.git`;
     const r = await run(["git", "ls-remote", url, "HEAD"]);