skillrepo 4.4.0 → 4.5.0

package/src/lib/npm-update-check.mjs

@@ -0,0 +1,366 @@
+/**
+ * npm-registry self-staleness checker (#1554, part of epic #1552).
+ *
+ * The CLI ships with no self-staleness detection today. This module adds
+ * a daily-cached check against `https://registry.npmjs.org/skillrepo/latest`
+ * so a stale `npx skillrepo`/global install gets nudged toward an upgrade
+ * after the primary command completes. The nudge is a HINT, not a feature:
+ * every failure mode (network error, non-2xx, parse failure, timeout,
+ * read-only FS) returns null and never throws.
+ *
+ * Design contract
+ * ---------------
+ *
+ * 1. **Fire-and-forget at the call site.** `bin/skillrepo.mjs` invokes
+ *    this module after `await COMMANDS[command].run(rest)` returns and
+ *    races the promise with `setTimeout(0)`. On a cache HIT the checker
+ *    resolves before the timer fires and the nudge is emitted before
+ *    the binary exits. On a cache MISS the timer wins and the in-flight
+ *    fetch is left running in the background — it has its own 2s
+ *    timeout, writes the cache on completion, and lets the NEXT
+ *    invocation use it. The user's command output appears before the
+ *    process exits; the residual fetch happens in parallel.
+ *
+ * 2. **Silent failure mode.** No "couldn't reach npm." Users opening a
+ *    Network tab to debug a CLI command don't want a second unrelated
+ *    request explained. If the check can't complete, the user sees no
+ *    artifact at all.
+ *
+ * 3. **24h positive cache, 1h negative cache.** A successful read pins
+ *    the answer for 24 hours — npm publishes are rare enough that more
+ *    frequent polling is just rude. A failed read pins for 1 hour so a
+ *    transient outage doesn't blind the CLI for a full day; AND
+ *    `checkedAt` still updates on failure so we don't hammer a broken
+ *    endpoint every command in the meantime.
+ *
+ * 4. **Kill switches.** `SKILLREPO_NO_UPDATE_CHECK=1` is the explicit
+ *    opt-out. `process.env.CI === "true"` auto-disables (GitHub Actions,
+ *    GitLab CI, CircleCI, and most other vendors set this). Both are
+ *    checked before any network or cache I/O.
+ *
+ * 5. **JSON suppression at the binary level.** The checker itself does
+ *    NOT inspect `argv` for `--json`; that's the dispatcher's job.
+ *    When a parent command was invoked with `--json`, the dispatcher
+ *    skips calling `checkForCliUpdate` entirely so we never inject text
+ *    into a structured stream — not even on stderr, because some tools
+ *    (notably ts-node + Vitest hooks) read both streams.
+ *
+ * 6. **Live version comparison on the read path.** The cache records
+ *    `currentCliVersion` so a stale cache from a previous binary
+ *    doesn't keep nudging the user after they upgrade. The render-time
+ *    comparison is `latestPublishedVersion` vs. the LIVE version
+ *    (`io.currentVersion`), not the cached one — the cached value is
+ *    only used to validate freshness.
+ *
+ * 7. **Windows compat.** All paths use `path.join`; never separator
+ *    concatenation. The cache directory is created with
+ *    `mkdir { recursive: true }` so Windows drive-letter roots work
+ *    identically to POSIX `~/.claude/...`.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import semver from "semver";
+
+import { globalNpmVersionCheckPath } from "./paths.mjs";
+
+/** Endpoint that resolves npm's `dist-tags.latest` for `skillrepo`. */
+export const NPM_LATEST_URL = "https://registry.npmjs.org/skillrepo/latest";
+
+/** Hard cap on the fetch. Network calls slower than this are treated as a no-result. */
+export const FETCH_TIMEOUT_MS = 2000;
+
+/** Cache TTL on a successful fetch (24 hours). */
+export const POSITIVE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** Cache TTL on a failed fetch (1 hour) — fast retry without hammering. */
+export const NEGATIVE_TTL_MS = 60 * 60 * 1000;
+
+/**
+ * Cache file location — delegated to `paths.mjs` so every CLI-written
+ * path lives in a single registry. Tests inject via `sandbox-home.mjs`
+ * (which sets both HOME and USERPROFILE so `homedir()` reads sandbox
+ * locations on POSIX AND Windows), not by mocking this function.
+ *
+ * Kept as a re-export rather than a direct import in callers so the
+ * test boundary stays consistent with the module's other public API.
+ */
+export function cachePath() {
+  return globalNpmVersionCheckPath();
+}
+
+/** Current cache schema. Bump only when fields change incompatibly. */
+export const CACHE_SCHEMA_VERSION = 1;
+
+/**
+ * Try to read and parse the cache file. Returns null on any failure
+ * (missing file, malformed JSON, wrong schemaVersion, missing required
+ * field). The caller treats null as "cache miss" and proceeds to fetch.
+ *
+ * This intentionally does NOT differentiate between "no cache yet" and
+ * "cache exists but is unusable" — both lead to the same recovery path.
+ */
+function readCache() {
+  let raw;
+  try {
+    raw = readFileSync(cachePath(), "utf-8");
+  } catch {
+    return null;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  if (!parsed || typeof parsed !== "object") return null;
+  if (parsed.schemaVersion !== CACHE_SCHEMA_VERSION) return null;
+  if (typeof parsed.checkedAt !== "string") return null;
+  if (typeof parsed.currentCliVersion !== "string") return null;
+  if (typeof parsed.fetchOk !== "boolean") return null;
+  // latestPublishedVersion may be null when fetchOk: false; both shapes
+  // are valid cache entries.
+  if (
+    parsed.latestPublishedVersion !== null &&
+    typeof parsed.latestPublishedVersion !== "string"
+  ) {
+    return null;
+  }
+
+  return parsed;
+}
+
+/**
+ * Persist the cache. Best-effort: read-only filesystems (Docker layers,
+ * some CI snapshots) cause writeFileSync to throw EROFS/EACCES, which
+ * we swallow. The user still sees the nudge on this run (if applicable);
+ * they just won't get a cached answer next time.
+ */
+function writeCache(entry, io) {
+  const target = cachePath();
+  const dir = dirname(target);
+  const writeFn = io.writeFile;
+  const mkdirFn = io.mkdir;
+  const existsFn = io.exists;
+
+  try {
+    if (!existsFn(dir)) {
+      mkdirFn(dir, { recursive: true });
+    }
+    writeFn(target, JSON.stringify(entry, null, 2) + "\n", "utf-8");
+  } catch {
+    // Read-only FS or permission denied — silently give up. The user's
+    // primary command output already showed; we will not interrupt it
+    // with a cache-write warning. Next invocation will re-fetch.
+  }
+}
+
+/**
+ * Decide whether a cache entry is still fresh given the CURRENT live
+ * version. Two gates must pass:
+ *
+ *   1. The cache must have been written by the same CLI version that's
+ *      running now. If the user upgraded between calls, the cached
+ *      `latestPublishedVersion` may now be the version they're running
+ *      — discarding the entry forces a re-check so we don't nudge the
+ *      user to upgrade to the same version they just installed.
+ *   2. `checkedAt` must be within the appropriate TTL — positive for
+ *      successful fetches, negative for failed ones.
+ *
+ * Returns true when the cache is reusable; false means re-fetch.
+ */
+function isCacheFresh(entry, currentVersion, now) {
+  if (entry.currentCliVersion !== currentVersion) return false;
+  const checkedAtMs = Date.parse(entry.checkedAt);
+  if (!Number.isFinite(checkedAtMs)) return false;
+  const ageMs = now - checkedAtMs;
+  const ttl = entry.fetchOk ? POSITIVE_TTL_MS : NEGATIVE_TTL_MS;
+  return ageMs < ttl && ageMs >= 0;
+}
+
+/**
+ * Fetch `/skillrepo/latest` from the npm registry with a 2-second hard
+ * timeout. Returns the parsed `version` string on success, null on any
+ * failure (network, non-2xx, parse, abort).
+ *
+ * The `/latest` shortcut returns the version manifest for `dist-tags.latest`
+ * — about 1.5 KB on the wire. The User-Agent identifies the CLI so npm's
+ * abuse tooling can rate-limit us specifically if we ever misbehave.
+ *
+ * Accept header note: the issue spec called for
+ * `application/vnd.npm.install-v1+json`, but the npm registry returns
+ * HTTP 406 for that media type on the `/latest` endpoint — the install
+ * manifest type is only valid against the FULL packument
+ * (`/skillrepo`), which is ~10x larger. `application/json` is the
+ * documented accept for the `/latest` shortcut and is what `npm view`
+ * itself uses under the hood. Verified via curl on 2026-05-19. The
+ * issue body should be updated to reflect this; tracked in the PR.
+ */
+async function fetchLatestVersion(currentVersion, fetchImpl) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetchImpl(NPM_LATEST_URL, {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+        "User-Agent": `skillrepo-cli/${currentVersion} (+https://skillrepo.dev)`,
+      },
+      signal: controller.signal,
+    });
+    if (!res || !res.ok) return null;
+    let body;
+    try {
+      body = await res.json();
+    } catch {
+      return null;
+    }
+    if (!body || typeof body !== "object") return null;
+    if (typeof body.version !== "string" || body.version.length === 0) {
+      return null;
+    }
+    // Validate semver shape upfront — a malformed version from a
+    // compromised mirror should not surface to the user as a nudge.
+    if (!semver.valid(body.version)) return null;
+    return body.version;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+/**
+ * Style helpers — duplicated from bin/skillrepo.mjs to keep this module
+ * standalone (a CLI nudge module that pulls in the dispatcher's helpers
+ * would create a cycle). `bold`/`dim` mirror the existing http.mjs:248
+ * pattern.
+ */
+function dim(s) {
+  return process.stderr.isTTY && !process.env.NO_COLOR ? `\x1b[2m${s}\x1b[0m` : s;
+}
+function bold(s) {
+  return process.stderr.isTTY && !process.env.NO_COLOR ? `\x1b[1m${s}\x1b[0m` : s;
+}
+
+/**
+ * Render the nudge to stderr. Two lines, indented to match the
+ * dispatcher's error/help shape. Never throws — if stderr is closed
+ * (e.g. parent pipe shut down) the write call's exception is swallowed
+ * at the call site so a failing nudge can't break the user's flow.
+ */
+function emitNudge(currentVersion, latestVersion, stderrWrite) {
+  const line1 = dim(
+    `  A newer ${bold("skillrepo")} is available: ${currentVersion} → ${latestVersion}`,
+  );
+  const line2 = dim(`  Upgrade: ${bold("npm install -g skillrepo@latest")}`);
+  try {
+    stderrWrite(`\n${line1}\n${line2}\n`);
+  } catch {
+    // Closed stream. Nothing to do.
+  }
+}
+
+/**
+ * Are the kill switches set? Centralized so the bin layer and any
+ * test fixtures share the same view of "should we even bother."
+ */
+export function updateCheckDisabledByEnv() {
+  const explicit = process.env.SKILLREPO_NO_UPDATE_CHECK;
+  if (explicit && explicit !== "0" && explicit.toLowerCase() !== "false") {
+    return true;
+  }
+  if (process.env.CI === "true") return true;
+  return false;
+}
+
+/**
+ * Main entry point.
+ *
+ * @param {object} params
+ * @param {string} params.currentVersion - The CLI's own version
+ *   (`getCliVersion()` from the dispatcher).
+ * @param {object} [params.io] - I/O dependency injection. Production
+ *   callers pass nothing and get Node built-ins; tests inject mocks.
+ *   Shape:
+ *   - `fetch`: fetch impl (default `globalThis.fetch`)
+ *   - `now`: () => number, ms since epoch (default `Date.now`)
+ *   - `writeFile`/`mkdir`/`exists`: fs primitives for the cache write
+ *     path. Reads use real `fs` directly (no injection seam) — tests
+ *     redirect the read path via `sandbox-home.mjs` instead.
+ *     (defaults from `node:fs`)
+ *   - `stderrWrite`: (s) => void (default `process.stderr.write`)
+ *
+ * @returns {Promise<{ nudged: boolean, reason?: string }>} Resolves
+ *   with a tiny status object — tests assert on it directly. Production
+ *   callers ignore the return value.
+ */
+export async function checkForCliUpdate({ currentVersion, io = {} } = {}) {
+  if (updateCheckDisabledByEnv()) {
+    return { nudged: false, reason: "disabled" };
+  }
+  if (typeof currentVersion !== "string" || !semver.valid(currentVersion)) {
+    // Defensive: a malformed live version is a programming error
+    // upstream. Don't try to compare against random strings.
+    return { nudged: false, reason: "invalid-current-version" };
+  }
+
+  const resolvedIo = {
+    fetch: io.fetch ?? globalThis.fetch,
+    now: io.now ?? Date.now,
+    writeFile: io.writeFile ?? writeFileSync,
+    mkdir: io.mkdir ?? mkdirSync,
+    exists: io.exists ?? existsSync,
+    stderrWrite: io.stderrWrite ?? ((s) => process.stderr.write(s)),
+  };
+
+  if (typeof resolvedIo.fetch !== "function") {
+    // Node < 18 has no global fetch. The CLI's minimum is 18 (README),
+    // so this should never fire — but a missing fetch isn't a user-
+    // visible failure either.
+    return { nudged: false, reason: "no-fetch" };
+  }
+
+  const now = resolvedIo.now();
+  const cache = readCache();
+  let latestVersion = null;
+
+  if (cache && isCacheFresh(cache, currentVersion, now)) {
+    // Fresh cache. Reuse its latestPublishedVersion (which may be null
+    // for a negative cache hit — in which case we don't nudge).
+    latestVersion = cache.latestPublishedVersion;
+  } else {
+    // Cache miss / stale / version mismatch. Try the network. The
+    // fetch has its own 2-second AbortController; the dispatcher's
+    // `Promise.race` with `setTimeout(0)` means we return synchronously
+    // either way — but the fetch keeps running in the background so
+    // the cache lands and the NEXT invocation can use it.
+    latestVersion = await fetchLatestVersion(currentVersion, resolvedIo.fetch);
+    const entry = {
+      schemaVersion: CACHE_SCHEMA_VERSION,
+      checkedAt: new Date(now).toISOString(),
+      currentCliVersion: currentVersion,
+      latestPublishedVersion: latestVersion,
+      fetchOk: latestVersion !== null,
+    };
+    writeCache(entry, resolvedIo);
+  }
+
+  if (!latestVersion) {
+    return { nudged: false, reason: "no-result" };
+  }
+
+  // Compare against the LIVE current version, not the cached
+  // currentCliVersion. The cached value was only used to gate freshness;
+  // the user is running THIS binary now, and that's what they need a
+  // nudge relative to.
+  if (!semver.gt(latestVersion, currentVersion)) {
+    return { nudged: false, reason: "up-to-date" };
+  }
+
+  emitNudge(currentVersion, latestVersion, resolvedIo.stderrWrite);
+  return { nudged: true };
+}

package/src/lib/paths.mjs

@@ -28,6 +28,16 @@ export const vscodeMcpJson = () => join(cwd(), ".vscode", "mcp.json");
 export const globalConfigPath = () => join(homedir(), ".claude", "skillrepo", "config.json");
 export const globalLastSyncPath = () => join(homedir(), ".claude", "skillrepo", ".last-sync");
 
+/**
+ * npm-registry self-staleness check cache (#1554). Separate file from
+ * `.last-sync` — different concern (CLI's own version vs. library
+ * content state) and a schema bump in one must not gate the other.
+ * Lives under the same `~/.claude/skillrepo/` directory so cleanup
+ * stays simple (rm -rf the parent removes both).
+ */
+export const globalNpmVersionCheckPath = () =>
+  join(homedir(), ".claude", "skillrepo", ".npm-version-check");
+
 // ── Skill placement targets ────────────────────────────────────────────
 //
 // Per-vendor placement decisions live in `agent-registry.mjs`. This

package/src/lib/placement-walk.mjs

@@ -0,0 +1,285 @@
+/**
+ * Walk on-disk skill placements and compute SHAs (#1555).
+ *
+ * Read-side counterpart of `file-write.mjs`: given a set of detected
+ * vendor keys, enumerate the skill directories each vendor's
+ * placement target contains and compute the same SHA pair that
+ * `runSync` persists in `.last-sync` v2. The output feeds `drift.mjs`
+ * for per-skill state classification.
+ *
+ * Design notes
+ * ------------
+ *
+ * - **One walk per unique target.** Cohort vendors (cursor, windsurf,
+ *   gemini, codex, cline, copilot) all share `agentsProject`. Walking
+ *   the parent dir N times — once per detected cohort vendor — would
+ *   read every file N times. Instead, we walk each unique target
+ *   ONCE and expand the result to one entry per (vendor, scope,
+ *   skill) combination.
+ *
+ * - **POSIX path normalization for hashing.** `filesSha256` is the
+ *   SHA-256 of a sorted `<path>|<sha>` projection. The path component
+ *   MUST be forward-slash-separated to match what the server-side
+ *   hashing produces (and what `crypto-shas.mjs` documents). Disk
+ *   paths on Windows have backslashes; we normalize at the
+ *   computation boundary, not in the data shape.
+ *
+ * - **Project scope only in v1.** The spec defers `--global` to a
+ *   future flag. This module walks each detected vendor's
+ *   `projectTarget` exclusively. When the global flag lands, add a
+ *   `scopes` parameter that defaults to `["project"]`.
+ *
+ * - **Errors degrade gracefully.** A skill directory we can't read
+ *   (permission error, broken symlink, partial file) produces an
+ *   entry with `present: true` and `skillMdSha256: null` /
+ *   `filesSha256: null`. The drift classifier treats null SHAs as
+ *   `edited` — conservative, surfaces the issue to the user without
+ *   crashing the command.
+ *
+ * - **`.tmp/` and `.old/` are skipped.** These are crashed-write
+ *   artifacts handled by `cleanupOrphans` in `file-write.mjs`. They
+ *   are not skill directories.
+ */
+
+import { existsSync, readdirSync, readFileSync, lstatSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+import { computeSkillShas } from "./crypto-shas.mjs";
+import { resolvePlacementRoot } from "./file-write.mjs";
+import { getAgentByKey } from "./agent-registry.mjs";
+
+/**
+ * @typedef {Object} LocalPlacement
+ * @property {string} vendorKey         - Canonical agent key from agent-registry.
+ * @property {"project"} scope          - Always "project" in v1.
+ * @property {string} target            - PlacementTarget enum value.
+ * @property {string} skillName         - Directory name on disk.
+ * @property {boolean} present          - Always true for entries returned here.
+ * @property {string | null} skillMdSha256
+ * @property {string | null} filesSha256
+ */
+
+/**
+ * Walk every detected vendor's project placement and return a Map
+ * keyed by `"<vendorKey>::project::<skillName>"` for O(1) lookup
+ * from `list.mjs`.
+ *
+ * Each unique placement TARGET is walked exactly once. Detected
+ * vendors that map to the same target share the walk's results.
+ *
+ * @param {string[]} detectedVendorKeys
+ * @returns {Map<string, LocalPlacement>}
+ */
+export function walkDetectedPlacements(detectedVendorKeys) {
+  if (!Array.isArray(detectedVendorKeys) || detectedVendorKeys.length === 0) {
+    return new Map();
+  }
+
+  // Group detected vendors by their projectTarget. A vendor with a
+  // null projectTarget (no documented project-scope placement) is
+  // dropped from this map — there's nothing to walk.
+  /** @type {Map<string, string[]>} */
+  const targetToVendors = new Map();
+  for (const key of detectedVendorKeys) {
+    const entry = getAgentByKey(key);
+    if (!entry || !entry.projectTarget) continue;
+    const target = entry.projectTarget;
+    if (!targetToVendors.has(target)) targetToVendors.set(target, []);
+    targetToVendors.get(target).push(key);
+  }
+
+  /** @type {Map<string, LocalPlacement>} */
+  const result = new Map();
+  for (const [target, vendorKeys] of targetToVendors) {
+    const skillsAtTarget = walkPlacementTarget(target);
+    for (const skill of skillsAtTarget) {
+      for (const vendorKey of vendorKeys) {
+        const key = `${vendorKey}::project::${skill.skillName}`;
+        result.set(key, {
+          vendorKey,
+          scope: "project",
+          target,
+          skillName: skill.skillName,
+          present: true,
+          skillMdSha256: skill.skillMdSha256,
+          filesSha256: skill.filesSha256,
+        });
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Walk a single placement target's PARENT directory and return one
+ * entry per skill subdirectory found. Exposed for tests and for
+ * callers that need a single-target view.
+ *
+ * Output shape: `{ skillName, skillMdSha256, filesSha256 }[]`. The
+ * vendor/scope expansion happens in `walkDetectedPlacements`.
+ *
+ * @param {string} target - PlacementTarget enum value.
+ * @returns {{ skillName: string, skillMdSha256: string | null, filesSha256: string | null }[]}
+ */
+export function walkPlacementTarget(target) {
+  let parentDir;
+  try {
+    parentDir = resolvePlacementRoot(target);
+  } catch {
+    // Unknown target — surface as no placements rather than throwing.
+    // Defensive: detect-agents + agent-registry should never produce
+    // an unknown target, but if they ever do we don't want `list` to
+    // crash.
+    return [];
+  }
+
+  if (!existsSync(parentDir)) return [];
+
+  /** @type {string[]} */
+  let entries;
+  try {
+    entries = readdirSync(parentDir);
+  } catch {
+    return [];
+  }
+
+  /** @type {{ skillName: string, skillMdSha256: string | null, filesSha256: string | null }[]} */
+  const out = [];
+  for (const entry of entries) {
+    // Skip crashed-write artifacts handled by cleanupOrphans.
+    if (entry.endsWith(".tmp") || entry.endsWith(".old")) continue;
+
+    const skillDir = join(parentDir, entry);
+    let stat;
+    try {
+      // lstatSync (not statSync) so a symlink-to-directory at the
+      // placements root is rejected here, not recursed into. A
+      // circular symlink would otherwise crash `list` with a stack
+      // overflow from infinite recursion in walkSkillDirRecursive.
+      stat = lstatSync(skillDir);
+    } catch {
+      continue;
+    }
+    if (stat.isSymbolicLink()) continue;
+    if (!stat.isDirectory()) continue;
+
+    const shas = computeShasFromDir(skillDir);
+    out.push({
+      skillName: entry,
+      skillMdSha256: shas.skillMdSha256,
+      filesSha256: shas.filesSha256,
+    });
+  }
+  return out;
+}
+
+/**
+ * Read every file in `skillDir` and compute the same SHA pair that
+ * `runSync` persists. On ANY file-read failure (permission, broken
+ * symlink, truncated file), returns null SHAs — the caller treats
+ * this as `edited` (conservative). Returning null is intentional:
+ * we cannot honestly claim `current` on data we couldn't read.
+ *
+ * @param {string} skillDir
+ * @returns {{ skillMdSha256: string | null, filesSha256: string | null }}
+ */
+function computeShasFromDir(skillDir) {
+  /** @type {{ path: string, content: string }[]} */
+  const files = [];
+  let readError = false;
+  walkSkillDirRecursive(skillDir, skillDir, files, (err) => {
+    if (err) readError = true;
+  });
+
+  if (readError || files.length === 0) {
+    return { skillMdSha256: null, filesSha256: null };
+  }
+
+  try {
+    return computeSkillShas(files);
+  } catch {
+    // computeSkillShas only throws on bad input shape. We constructed
+    // the input ourselves, so a throw indicates a programming error
+    // we can't recover from — but treat as null SHAs rather than
+    // crashing the user's `list` command.
+    return { skillMdSha256: null, filesSha256: null };
+  }
+}
+
+/**
+ * Recursive directory walk that populates a flat `{path, content}[]`
+ * array, with paths POSIX-normalized relative to `skillDir`. Errors
+ * on individual entries are reported through the `onError` callback
+ * (the caller flips a `readError` boolean to discard the partial
+ * accum and return null SHAs) but the walk CONTINUES with the
+ * remaining siblings.
+ *
+ * The continue-not-return choice matters: a `readdirSync` listing of
+ * [unreadable, readable1, readable2] would previously bail on entry
+ * 0 and never see entries 1 and 2. Setting `readError` once and
+ * still walking the rest gives the caller correct behavior (null
+ * SHAs from the gate at `computeShasFromDir`) and produces a
+ * deterministic outcome that doesn't depend on `readdirSync`
+ * ordering. The accum is partially populated when `readError` is
+ * true but the gate in `computeShasFromDir` discards it.
+ *
+ * Depth is not capped — agentskills.io spec mandates files at most
+ * one level deep from SKILL.md (`scripts/foo.sh`, `references/bar.md`)
+ * but the CLI doesn't reject a deeper tree. If the user has hand-
+ * authored a deeper structure, we hash it faithfully.
+ */
+function walkSkillDirRecursive(rootDir, currentDir, accum, onError) {
+  let entries;
+  try {
+    entries = readdirSync(currentDir);
+  } catch (err) {
+    // Can't list this directory at all — flag the error and bail
+    // out of this level (no entries to walk). The outer caller
+    // continues with whatever siblings the parent dir contains.
+    onError(err);
+    return;
+  }
+
+  for (const entry of entries) {
+    const fullPath = join(currentDir, entry);
+    let stat;
+    try {
+      // lstatSync (not statSync) is load-bearing here. statSync
+      // follows symlinks, which means:
+      //   1. A symlink-to-directory passes isDirectory() and
+      //      walkSkillDirRecursive recurses into it. A circular
+      //      symlink (e.g. `references/loop -> .`) infinite-loops
+      //      and crashes the process with a stack overflow.
+      //   2. A symlink-to-file passes isFile() and readFileSync
+      //      reads the target — potentially OUTSIDE the skill dir.
+      //      Not a privilege escalation (we only read what the user
+      //      can read), but a principle-of-least-surprise violation.
+      // The agentskills.io spec does not define symlinks as valid
+      // skill content. Skip them.
+      stat = lstatSync(fullPath);
+    } catch (err) {
+      onError(err);
+      continue;
+    }
+    if (stat.isSymbolicLink()) continue;
+    if (stat.isDirectory()) {
+      walkSkillDirRecursive(rootDir, fullPath, accum, onError);
+      continue;
+    }
+    if (!stat.isFile()) continue; // skip sockets / pipes / etc.
+
+    let content;
+    try {
+      content = readFileSync(fullPath, "utf8");
+    } catch (err) {
+      onError(err);
+      continue;
+    }
+    // POSIX-normalize the path so SHA computation matches what the
+    // server produces. On POSIX, `sep` is "/" and this is a no-op;
+    // on Windows, `sep` is "\\" and we convert.
+    const posixRelPath =
+      sep === "/" ? relative(rootDir, fullPath) : relative(rootDir, fullPath).split(sep).join("/");
+    accum.push({ path: posixRelPath, content });
+  }
+}