skillrepo 4.3.0 → 4.5.0

package/src/commands/list.mjs

@@ -1,21 +1,36 @@
 /**
- * `skillrepo list` (#679).
+ * `skillrepo list` — list library skills with per-row local drift state (#1555).
  *
- * Lists the authenticated account's library contents. Default output
- * is a human-readable table via `cli-table3`. `--json` flag prints
- * the raw metadata array for piping into `jq` or other tools.
+ * Historically (#679) this only showed the server-side library. As of
+ * #1555 the table adds a `Local` column showing how each skill's
+ * on-disk placement stacks up against the library + last-sync
+ * baseline: `current` / `stale` / `missing` / `edited`. A footer
+ * reports the library-level ETag state ("library in sync" vs
+ * "library has changed since last sync").
  *
- * Calls GET /api/v1/library and ignores the inlined file content —
- * we only need metadata for display. There is no metadata-only
- * endpoint; reading the full library payload is the cost of reusing
- * the same route the sync engine uses.
+ * Pipeline:
+ *   1. `getLibrary` returns the current registry skills + ETag.
+ *   2. `readLastSync` reads the v2 `.last-sync` map (per-skill SHAs +
+ *      versions) for the on-disk-vs-synced comparison.
+ *   3. `detectAgents` identifies which vendors actually have footprint
+ *      on this machine / in this project — we only report drift
+ *      against vendors the user uses.
+ *   4. `walkDetectedPlacements` reads each detected vendor's
+ *      placement dir and computes SHAs from disk.
+ *   5. `computeSkillState` + `rollupState` from `drift.mjs` turn the
+ *      three axes into a per-vendor state and a per-skill rollup.
  *
  * Flags:
- *   --json           Pipe-friendly JSON output
- *   --key/--url      Override credentials
+ *   --json           Pipe-friendly JSON output (bare array preserved
+ *                    from #679 — purely additive: new `state` and
+ *                    `placements[]` fields per item, no top-level
+ *                    wrapper).
+ *   --key/--url      Override credentials.
  *
- * No --global / --agent flags — `list` is a library-state inspector,
- * not a writer.
+ * No `--global`, `--detail`, `--vendor`, or `--include-extra` flags
+ * in v1 — YAGNI per the epic's decisions log. Project-scope
+ * placement only; extra-on-disk skills (in placement but not in
+ * library) are hidden by default.
  */
 
 import Table from "cli-table3";
@@ -23,6 +38,11 @@ import Table from "cli-table3";
 import { getLibrary } from "../lib/http.mjs";
 import { resolveFlags } from "../lib/cli-config.mjs";
 import { formatIdentifier } from "../lib/identifier.mjs";
+import { readLastSync } from "../lib/sync.mjs";
+import { detectAgents } from "../lib/detect-agents.mjs";
+import { walkDetectedPlacements } from "../lib/placement-walk.mjs";
+import { getAgentByKey } from "../lib/agent-registry.mjs";
+import { computeSkillState, rollupState, SKILL_STATE } from "../lib/drift.mjs";
 
 /**
  * Run `list`. Throws CliError on any failure.
@@ -36,59 +56,165 @@ export async function runList(argv, io = {}) {
   const stdout = io.stdout ?? process.stdout;
   const flags = resolveFlags(argv);
 
-  const result = await getLibrary(flags.serverUrl, flags.apiKey);
+  const libraryResponse = await getLibrary(flags.serverUrl, flags.apiKey);
 
-  // `list` does not care about removals or sync state — we just want
-  // the current set. Skills are returned by the same endpoint as the
-  // sync, but with full file content we discard.
-  //
   // Defensive guard: `list` calls getLibrary without an If-None-Match
   // header so it can't legitimately receive a 304 today. But getLibrary's
   // contract documents `notModified: true` as a possible return shape,
   // and a future refactor that adds caching at this layer could
-  // accidentally start sending the header. Treat `result.skills` as
-  // possibly empty rather than possibly undefined.
-  const skills = Array.isArray(result.skills) ? result.skills : [];
+  // accidentally start sending the header.
+  const skills = Array.isArray(libraryResponse.skills) ? libraryResponse.skills : [];
+
+  // Detect agents + walk placements regardless of skill count — we
+  // need this info for both the table and the JSON shape.
+  const detected = detectAgents().filter((d) => d.detected);
+
+  // Pre-resolve the detected vendor entries ONCE. `getAgentByKey` is
+  // O(N) over the registry; doing this per-skill across 50+ skills
+  // was wasted work. We also filter to vendors with a non-null
+  // projectTarget here so the per-skill loop only iterates vendors
+  // that actually contribute a placement.
+  const detectedVendorEntries = detected
+    .map((d) => getAgentByKey(d.key))
+    .filter((entry) => entry !== null && entry.projectTarget !== null);
+  const detectedKeys = detectedVendorEntries.map((e) => e.key);
+
+  const placementsMap = walkDetectedPlacements(detectedKeys);
+
+  // Read `.last-sync` ONCE. Direct map access on the parsed
+  // `skills` payload — no per-skill helper indirection — for both
+  // wasted-I/O reasons (N reads of the same file otherwise) AND
+  // a within-run snapshot-consistency window (a concurrent
+  // `skillrepo update` writing the file mid-list would otherwise
+  // produce inconsistent classifications across skills in the
+  // same render).
+  const lastSync = readLastSync();
+  const lastSyncSkillsMap =
+    lastSync && lastSync.skills && typeof lastSync.skills === "object"
+      ? lastSync.skills
+      : {};
+
+  // Build the augmented per-skill state for every library skill. This
+  // is the canonical shape both the table renderer and JSON formatter
+  // project from.
+  const augmented = skills.map((skill) =>
+    augmentSkill(skill, detectedVendorEntries, placementsMap, lastSyncSkillsMap),
+  );
 
   if (flags.json) {
-    stdout.write(JSON.stringify(formatJson(skills), null, 2) + "\n");
+    stdout.write(JSON.stringify(formatJson(augmented), null, 2) + "\n");
     return;
   }
 
-  if (skills.length === 0) {
+  if (augmented.length === 0) {
     stdout.write(
       "\n  Your library is empty.\n  Use `skillrepo add <@owner/name>` to add a skill.\n\n",
     );
     return;
   }
 
-  printTable(skills, stdout);
+  printTable(augmented, detected, stdout);
+  printFooter(augmented, libraryResponse.etag, lastSync, stdout, canUseGlyphs(stdout));
 }
 
+// ── Per-skill augmentation ─────────────────────────────────────────────
+
 /**
- * Read the column width from the active output stream, falling back
- * to process.stdout's TTY column count if the injected stream
- * doesn't carry one (e.g., a test capture stream), then to a 100-col
- * default for non-TTY contexts. Reading from `out.columns` first
- * means a future test that injects a stream advertising a specific
- * width will be honored.
+ * Compute `state` (rollup) + `placements[]` for a library skill.
+ *
+ * For each detected vendor (pre-resolved by the caller) look up the
+ * on-disk placement and the last-sync baseline, classify the state,
+ * and emit a placement entry. Then roll the per-vendor states up to
+ * a single `state` for the table column.
+ *
+ * Baseline lookups go through the caller-provided `lastSyncSkillsMap`
+ * to avoid re-reading `.last-sync` per skill — both a wasted-I/O
+ * concern and a within-run snapshot consistency concern (an
+ * in-flight `skillrepo update` could otherwise change the file
+ * between our N reads).
+ *
+ * @param {object} skill - Library skill from `getLibrary` response.
+ * @param {import("../lib/agent-registry.mjs").AgentEntry[]} detectedVendorEntries
+ *   Pre-resolved registry entries for the detected vendors that
+ *   contribute a project placement. Computed once in `runList` so
+ *   the registry lookup doesn't happen per skill.
+ * @param {Map<string, import("../lib/placement-walk.mjs").LocalPlacement>} placementsMap
+ * @param {Record<string, import("../lib/sync.mjs").SyncedSkillEntry>} lastSyncSkillsMap
+ *   The `skills` map from `.last-sync` v2, captured once before the
+ *   per-skill loop. Lookup is a direct dictionary access, not a
+ *   re-read of the file.
  */
-function streamColumns(out) {
-  if (out && typeof out.columns === "number" && out.columns > 0) {
-    return out.columns;
+function augmentSkill(skill, detectedVendorEntries, placementsMap, lastSyncSkillsMap) {
+  const baselineKey = `${skill.owner}/${skill.name}`;
+  const baseline = validateBaselineShape(lastSyncSkillsMap[baselineKey]);
+  const placements = [];
+
+  for (const entry of detectedVendorEntries) {
+    const placementKey = `${entry.key}::project::${skill.name}`;
+    const onDisk = placementsMap.get(placementKey) ?? null;
+
+    const localPlacement = onDisk
+      ? {
+          present: true,
+          skillMdSha256: onDisk.skillMdSha256,
+          filesSha256: onDisk.filesSha256,
+        }
+      : { present: false, skillMdSha256: null, filesSha256: null };
+
+    const state = computeSkillState({
+      libraryVersion: skill.version ?? null,
+      lastSyncEntry: baseline,
+      localPlacement,
+    });
+
+    placements.push({
+      vendor: entry.key,
+      scope: "project",
+      state,
+      // `localVersion` is the version that was synced (from
+      // `.last-sync`) — NOT a version pulled from on-disk
+      // frontmatter, which the spec doesn't mandate. When there's no
+      // baseline, this is null and the `state` will already be
+      // `missing`, so the field is honest about what we know.
+      localVersion: baseline?.version ?? null,
+    });
   }
-  if (process.stdout.columns && process.stdout.columns > 0) {
-    return process.stdout.columns;
+
+  const state = rollupState(placements.map((p) => p.state));
+
+  return { ...skill, state, placements };
+}
+
+/**
+ * Reject a `.last-sync` entry that's missing required string fields.
+ * A tampered or partially-written entry returns null, which
+ * `computeSkillState` treats as "no baseline → missing" — the
+ * conservative verdict for cache state we can't trust.
+ */
+function validateBaselineShape(entry) {
+  if (!entry || typeof entry !== "object") return null;
+  if (
+    typeof entry.version !== "string" ||
+    typeof entry.skillMdSha256 !== "string" ||
+    typeof entry.filesSha256 !== "string"
+  ) {
+    return null;
   }
-  return 100;
+  return entry;
 }
 
+// ── JSON formatter ─────────────────────────────────────────────────────
+
 /**
- * Strip file content and reduce to the JSON shape that scripts care
- * about. Kept stable as a public-ish contract for `--json` consumers.
+ * Pipe-friendly bare array, additive on top of the #679 shape.
+ * Existing scripts that read `[0].owner`, etc. keep working. New
+ * fields: `state` (rollup) and `placements[]` (per-vendor truth).
+ *
+ * The footer never appears in JSON — `list --json` is consumed by
+ * scripts, and the ETag-state footer is a human-only signal.
  */
-function formatJson(skills) {
-  return skills
+function formatJson(augmented) {
+  return augmented
     .slice()
     .sort(sortByOwnerAndName)
     .map((s) => ({
@@ -98,17 +224,34 @@ function formatJson(skills) {
       description: s.description,
       updatedAt: s.updatedAt,
       filesIncomplete: s.filesIncomplete ?? false,
+      state: s.state,
+      placements: s.placements,
     }));
 }
 
-function printTable(skills, out) {
-  const sorted = skills.slice().sort(sortByOwnerAndName);
+// ── Human-output rendering ─────────────────────────────────────────────
+
+function printTable(augmented, detected, out) {
+  const useGlyphs = canUseGlyphs(out);
+
+  // "Detected:" line uses displayName for polish. Empty when no
+  // vendors detected; that situation also produces all-`missing`
+  // states, which the footer covers.
+  if (detected.length > 0) {
+    const detectedLabel = detected
+      .map((d) => `${d.displayName} (project)`)
+      .join(", ");
+    out.write(`\n  Detected: ${detectedLabel}\n`);
+  } else {
+    out.write(
+      "\n  No agents detected in this project — drift cannot be reported.\n",
+    );
+  }
+
+  const sorted = augmented.slice().sort(sortByOwnerAndName);
 
-  // cli-table3 supports word wrapping but we manually truncate
-  // descriptions so the table stays readable on standard 80-col
-  // terminals. The full description is available via --json.
   const table = new Table({
-    head: ["Skill", "Version", "Updated", "Description"],
+    head: ["Skill", "Library", "Local", "Updated", "Description"],
     colWidths: computeColWidths(streamColumns(out)),
     wordWrap: true,
     style: { head: ["bold"] },
@@ -118,26 +261,156 @@ function printTable(skills, out) {
     table.push([
       formatIdentifier(s),
       s.version || "—",
+      renderLocalCell(s.state, useGlyphs),
       formatRelativeDate(s.updatedAt),
       truncate(s.description || "", 60),
     ]);
   }
 
   out.write("\n" + table.toString() + "\n\n");
-  out.write(`  ${sorted.length} skill${sorted.length === 1 ? "" : "s"} in your library.\n\n`);
+
+  const driftCount = sorted.filter((s) => s.state !== SKILL_STATE.CURRENT).length;
+  if (driftCount === 0) {
+    out.write(
+      `  ${sorted.length} skill${sorted.length === 1 ? "" : "s"} in your library.\n`,
+    );
+  } else {
+    out.write(
+      `  ${sorted.length} skill${sorted.length === 1 ? "" : "s"} in your library. ` +
+        `${driftCount} need${driftCount === 1 ? "s" : ""} attention.\n`,
+    );
+  }
+}
+
+/**
+ * Library footer — answers "is my local copy in sync with the
+ * registry's manifest right now?" Distinct from per-row drift,
+ * which answers "is each individual skill's on-disk content
+ * current?"
+ *
+ * Four cases — order matters for the "least confusing precedence":
+ *
+ *   - No `.last-sync` at all → "no sync history." The user has
+ *     never run `update`; per-row drift is all `missing` anyway.
+ *     A clear "you need to run update" line is the right message.
+ *
+ *   - ETag matches AND every skill is current → fully in sync.
+ *     The reassuring case.
+ *
+ *   - ETag matches BUT some rows show drift → library hasn't
+ *     changed but local placements have. User ran update at some
+ *     point but then either edited files or has missing
+ *     placements. "Library in sync, run update to refresh"
+ *     reflects this without lying about what's wrong.
+ *
+ *   - ETag differs → library has new content since last sync.
+ *     "Library has changed, run update."
+ *
+ * The footer NEVER appears in `--json` output (caller already
+ * handles that in `runList`).
+ */
+function printFooter(augmented, libraryEtag, lastSync, out, useGlyphs) {
+  if (augmented.length === 0) return; // Empty-library branch already wrote its own message.
+
+  // Match the renderLocalCell glyph/ASCII policy. Pre-#1555 the footer
+  // used Unicode unconditionally even when the table fell back to
+  // ASCII for non-TTY / NO_COLOR. Inconsistency made piped output
+  // half-styled.
+  const ok = useGlyphs ? "✓" : "[ok]";
+  const warn = useGlyphs ? "⚠" : "[!]";
+
+  const driftCount = augmented.filter((s) => s.state !== SKILL_STATE.CURRENT).length;
+
+  if (!lastSync || !lastSync.etag) {
+    out.write(
+      "\n  No sync history on this machine — run `skillrepo update` to fetch your skills.\n\n",
+    );
+    return;
+  }
+
+  const etagMatches =
+    typeof libraryEtag === "string" && libraryEtag !== "" && libraryEtag === lastSync.etag;
+
+  if (etagMatches && driftCount === 0) {
+    out.write(`\n  ${ok} library in sync — local skills up to date.\n\n`);
+    return;
+  }
+
+  if (etagMatches && driftCount > 0) {
+    out.write(
+      `\n  ${warn} library in sync — but ${driftCount} skill${
+        driftCount === 1 ? "" : "s"
+      } show${driftCount === 1 ? "s" : ""} local drift.\n` +
+        "    Run `skillrepo update` to refresh.\n\n",
+    );
+    return;
+  }
+
+  // ETag differs (or one side is missing the etag — treat as differs,
+  // since we can't claim sync).
+  out.write(
+    `\n  ${warn} library has changed since last sync — run \`skillrepo update\`.\n\n`,
+  );
+}
+
+// ── Rendering helpers ──────────────────────────────────────────────────
+
+/** Glyphs vs ASCII tokens, per NO_COLOR / non-TTY. */
+function canUseGlyphs(stream) {
+  if (process.env.NO_COLOR) return false;
+  // `isTTY` is undefined on capture streams; treat as "no TTY → ASCII"
+  // since CI and pipe consumers would otherwise see escape codes /
+  // glyphs they can't render uniformly.
+  return stream && stream.isTTY === true;
+}
+
+function renderLocalCell(state, useGlyphs) {
+  switch (state) {
+    case SKILL_STATE.CURRENT:
+      return useGlyphs ? "✓" : "OK";
+    case SKILL_STATE.STALE:
+      return useGlyphs ? "⚠ stale" : "STALE";
+    case SKILL_STATE.MISSING:
+      return useGlyphs ? "✗ miss" : "MISS";
+    case SKILL_STATE.EDITED:
+      return useGlyphs ? "✎ edit" : "EDIT";
+    default:
+      return useGlyphs ? "?" : "?";
+  }
+}
+
+/**
+ * Read the column width from the active output stream, falling back
+ * to process.stdout's TTY column count if the injected stream
+ * doesn't carry one (e.g., a test capture stream), then to a 100-col
+ * default for non-TTY contexts.
+ */
+function streamColumns(out) {
+  if (out && typeof out.columns === "number" && out.columns > 0) {
+    return out.columns;
+  }
+  if (process.stdout.columns && process.stdout.columns > 0) {
+    return process.stdout.columns;
+  }
+  return 100;
 }
 
 function computeColWidths(terminalColumns) {
-  // Cap at 120 so the table doesn't get unreadably wide on
-  // ultra-wide terminals; floor at 100 so the description still has
-  // room when the terminal is narrower than typical.
+  // Cap at 120 so the table doesn't get unreadably wide on ultra-
+  // wide terminals; floor at 100 so the description still has room.
+  // The Local column is fixed-width (10 chars — biggest glyph cell
+  // is "✎ edit" plus padding).
   const total = terminalColumns > 60 ? Math.min(terminalColumns, 120) : 100;
-  // Skill ~30, version ~10, updated ~14, description gets the rest
-  const skillCol = 32;
-  const versionCol = 12;
-  const updatedCol = 14;
-  const descCol = Math.max(20, total - skillCol - versionCol - updatedCol - 6); // -6 for borders
-  return [skillCol, versionCol, updatedCol, descCol];
+  const skillCol = 30;
+  const libraryCol = 10;
+  const localCol = 10;
+  const updatedCol = 12;
+  // -8 accounts for the 6 between-column borders
+  const descCol = Math.max(
+    20,
+    total - skillCol - libraryCol - localCol - updatedCol - 8,
+  );
+  return [skillCol, libraryCol, localCol, updatedCol, descCol];
 }
 
 function truncate(s, n) {
@@ -164,7 +437,6 @@ function formatRelativeDate(iso) {
   if (days < 7) return `${days}d ago`;
   const weeks = Math.floor(days / 7);
   if (weeks < 26) return `${weeks}w ago`;
-  // Older than ~6 months: fall back to a date
   return new Date(iso).toISOString().slice(0, 10);
 }
 

package/src/lib/config.mjs

@@ -174,6 +174,12 @@ export function writeConfig(config) {
   for (const key of ["accountSlug", "accountId", "userId"]) {
     if (config[key] !== undefined) merged[key] = config[key];
   }
+  // Telemetry opt-in/out flag (#1539). Persisted only when the caller
+  // explicitly sets it — omitting means "no preference recorded,"
+  // which the telemetry module treats as "enabled" (opt-out default).
+  if (typeof config.telemetry === "boolean") {
+    merged.telemetry = config.telemetry;
+  }
 
   // Atomic write via temp-file + rename. Matches the file-write.mjs
   // pattern: the config file is never in a half-written state, so

package/src/lib/crypto-shas.mjs

@@ -0,0 +1,131 @@
+/**
+ * Skill-content SHA helpers (#1553 — `.last-sync` v2).
+ *
+ * Two flavors of SHA-256 digest computed over a skill's file payload:
+ *
+ *   • `skillMdSha256` — SHA-256 over the SKILL.md content as UTF-8 bytes.
+ *     The server intentionally returns an empty string for SKILL.md's
+ *     `sha256` field (see `src/lib/api/skill-response.ts:224`), so
+ *     clients must compute it locally. Used to detect user edits to
+ *     the SKILL.md frontmatter or body between syncs.
+ *
+ *   • `filesSha256` — SHA-256 over a deterministic projection of every
+ *     file's path and content hash. The projection is:
+ *
+ *         <path-1>|<sha-1>\n<path-2>|<sha-2>\n...<path-n>|<sha-n>
+ *
+ *     where entries are sorted by `path` using byte-order comparison
+ *     (NOT locale-aware), joined by `\n`, with NO trailing newline.
+ *     Implementations that re-derive this projection MUST match this
+ *     format byte-for-byte — a trailing newline would change the
+ *     resulting digest and break every drift comparison. Used to
+ *     detect edits to ANY file in the skill — references/, scripts/,
+ *     assets/, plus SKILL.md — in a single constant-size value.
+ *
+ * Why two SHAs instead of one
+ * ---------------------------
+ * `filesSha256` is the "anything changed?" rollup. `skillMdSha256`
+ * isolates SKILL.md edits, which are by far the most common kind of
+ * user modification (the spec encourages keeping SKILL.md under 500
+ * lines and pushing detail into references/, so SKILL.md is the
+ * working face of a skill). Surfacing "edited" specifically against
+ * SKILL.md gives clearer messages and lets `list` and a future
+ * `status` distinguish "user tweaked the body" from "support file
+ * changed."
+ *
+ * Path-format requirements
+ * ------------------------
+ * Callers MUST pass paths in canonical POSIX form (`/` separators,
+ * relative to the skill root, no leading `./`). The CLI's sync path
+ * uses server-provided paths directly, which already meet this
+ * requirement. A future on-disk reader (#1555) is responsible for
+ * normalizing platform-native separators back to `/` before calling
+ * these helpers — otherwise the same skill would produce different
+ * `filesSha256` values on Windows vs. POSIX and every disk read would
+ * spuriously report `edited`.
+ *
+ * Byte-content requirements
+ * -------------------------
+ * `content` is hashed as UTF-8 bytes. The CLI does not support
+ * binary file payloads today (see `validateSkill` in `file-write.mjs`),
+ * so `content` is always a JS string and `Buffer.from(content, "utf8")`
+ * produces the same bytes written to disk by `writeFileSync(path,
+ * content, "utf-8")`. If binary support is added, this helper needs
+ * an `encoding` discriminant per file.
+ */
+
+import { createHash } from "node:crypto";
+
+/**
+ * @typedef {Object} SkillFileLike
+ * @property {string} path     - Canonical POSIX path relative to skill root.
+ * @property {string} content  - UTF-8 string content as written to disk.
+ */
+
+/**
+ * @typedef {Object} SkillShas
+ * @property {string | null} skillMdSha256
+ *   Hex-encoded SHA-256 of SKILL.md's content. `null` when no SKILL.md
+ *   is present in `files` — that's a malformed skill, and callers
+ *   should not persist a result with `skillMdSha256: null` to
+ *   `.last-sync`. The helper still returns it (rather than throwing)
+ *   so callers can branch — throwing here would couple this pure
+ *   function to a policy decision that belongs at the call site.
+ * @property {string} filesSha256
+ *   Hex-encoded SHA-256 over the sorted `path|sha` projection of
+ *   every file. Never `null`: an empty `files` array hashes to the
+ *   SHA-256 of the empty string, which is a well-defined value.
+ */
+
+/**
+ * Compute both digests for a skill's file payload.
+ *
+ * Pure function — no I/O, no filesystem access, no clock reads. The
+ * same input always produces the same output, which is what lets the
+ * sync path and the (future) disk-walk path compare results
+ * meaningfully.
+ *
+ * SKILL.md identification: case-sensitive, root-level only. A file at
+ * `path: "skill.md"` (lowercase) or `path: "docs/SKILL.md"` (nested)
+ * is NOT treated as the canonical SKILL.md. The spec at agentskills.io
+ * mandates the exact filename `SKILL.md` at the skill root; matching
+ * the server's behavior here keeps `filesSha256` consistent with
+ * server-side hashing rules.
+ *
+ * @param {ReadonlyArray<SkillFileLike>} files
+ * @returns {SkillShas}
+ */
+export function computeSkillShas(files) {
+  if (!Array.isArray(files)) {
+    throw new TypeError("computeSkillShas: files must be an array");
+  }
+
+  /** @type {{ path: string, sha: string }[]} */
+  const perFile = [];
+  /** @type {string | null} */
+  let skillMdSha256 = null;
+
+  for (const file of files) {
+    if (!file || typeof file.path !== "string" || typeof file.content !== "string") {
+      throw new TypeError(
+        "computeSkillShas: each file must have string `path` and string `content`",
+      );
+    }
+    const sha = createHash("sha256").update(file.content, "utf8").digest("hex");
+    perFile.push({ path: file.path, sha });
+    if (file.path === "SKILL.md") {
+      skillMdSha256 = sha;
+    }
+  }
+
+  // Byte-order sort (not locale-aware). The `localeCompare` API is
+  // explicitly avoided here — two callers in different locales would
+  // otherwise hash to different values for the same skill, defeating
+  // the whole point of the digest.
+  perFile.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+
+  const projection = perFile.map((entry) => `${entry.path}|${entry.sha}`).join("\n");
+  const filesSha256 = createHash("sha256").update(projection, "utf8").digest("hex");
+
+  return { skillMdSha256, filesSha256 };
+}