skillrepo 4.4.0 → 4.5.0

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 };
+}

package/src/lib/drift.mjs

@@ -0,0 +1,175 @@
+/**
+ * Per-skill drift classification (#1555 — `list` local-awareness).
+ *
+ * Pure functions for deciding "is this skill current, stale, missing,
+ * or edited?" given the three input axes:
+ *
+ *   1. **Library state** — version from `GET /api/v1/library`.
+ *   2. **Last-sync baseline** — version + content SHAs persisted by
+ *      `runSync` to `~/.claude/skillrepo/.last-sync` (v2 schema).
+ *   3. **On-disk presence** — { present, skillMdSha256, filesSha256 }
+ *      from walking the vendor's placement directory.
+ *
+ * No I/O, no clock, no env reads. Same input → same output. This is
+ * the layer that gets exhaustive unit tests; the file-system walker
+ * and the `list` renderer compose this with their own concerns.
+ */
+
+import semver from "semver";
+
+/**
+ * Per-vendor placement state. The four values cover the
+ * "where is this skill, and is it the right version" question. A
+ * fifth state, `extra` (on disk but not in the library), lives in
+ * the renderer because it depends on the library shape, not just
+ * the per-skill comparison here.
+ */
+export const SKILL_STATE = Object.freeze({
+  CURRENT: "current",
+  STALE: "stale",
+  MISSING: "missing",
+  EDITED: "edited",
+});
+
+/**
+ * Compute the placement-level state for a single (skill, vendor) pair.
+ *
+ * Decision order — first match wins:
+ *
+ *   1. **No on-disk presence** → `missing`. The vendor's placement
+ *      directory does not contain this skill.
+ *   2. **No last-sync baseline** → `missing`. We can't verify
+ *      anything without the SHA from the prior sync. Even if the
+ *      directory exists, treating it as `current` would lie about
+ *      drift we cannot detect. The user's resolution is the same as
+ *      true `missing`: run `skillrepo update` to establish a
+ *      baseline. This matches the spec's "fresh install → missing
+ *      everywhere" behavior.
+ *   3. **Library version newer than synced version** → `stale`. The
+ *      registry has moved on; the user is behind.
+ *   4. **Either SHA differs from baseline** → `edited`. Same
+ *      version, content drifted. The user (or an agent) touched the
+ *      files on disk after the last sync.
+ *   5. **Otherwise** → `current`.
+ *
+ * Semver comparison falls back to strict string equality when either
+ * value is not a valid semver. The fallback's effect: any non-semver
+ * mismatch is treated as `stale` (the user is "behind" some
+ * unparseable label). Pre-existing test fixtures (`"1.0.0"`,
+ * `"2.0.1"`) all parse; this branch exists for forward-compat with
+ * versioning schemes the registry may adopt later.
+ *
+ * @param {Object} input
+ * @param {string | null} input.libraryVersion
+ *   The current version per the library response, or null if the
+ *   library entry has no version yet (shouldn't happen in production
+ *   but the type allows it).
+ * @param {{ version: string, skillMdSha256: string, filesSha256: string } | null} input.lastSyncEntry
+ *   Persisted state from the last successful sync, or null if no
+ *   baseline exists for this skill.
+ * @param {{ present: boolean, skillMdSha256: string | null, filesSha256: string | null } | null} input.localPlacement
+ *   Disk presence at one vendor's placement target. `present: false`
+ *   means the directory is absent; non-null SHAs imply `present:
+ *   true`.
+ * @returns {"current" | "stale" | "missing" | "edited"}
+ */
+export function computeSkillState({ libraryVersion, lastSyncEntry, localPlacement }) {
+  if (!localPlacement || !localPlacement.present) {
+    return SKILL_STATE.MISSING;
+  }
+  if (!lastSyncEntry) {
+    // On-disk but no baseline → cannot verify. Spec choice: report
+    // missing rather than fabricating a "current" verdict. See the
+    // docstring's decision-order comment.
+    return SKILL_STATE.MISSING;
+  }
+
+  if (libraryVersionIsNewer(libraryVersion, lastSyncEntry.version)) {
+    return SKILL_STATE.STALE;
+  }
+
+  const skillMdMatches =
+    localPlacement.skillMdSha256 !== null &&
+    localPlacement.skillMdSha256 === lastSyncEntry.skillMdSha256;
+  const filesMatch =
+    localPlacement.filesSha256 !== null &&
+    localPlacement.filesSha256 === lastSyncEntry.filesSha256;
+
+  if (skillMdMatches && filesMatch) return SKILL_STATE.CURRENT;
+  return SKILL_STATE.EDITED;
+}
+
+/**
+ * Reduce per-vendor states for a single skill to a single
+ * worst-state-wins value for the `Local` column in `list`'s table
+ * and the top-level `state` in `--json`.
+ *
+ * Precedence (high → low severity):
+ *   missing > edited > stale > current
+ *
+ * Reasoning: the user's action depends on the worst state.
+ *   - `missing` requires `skillrepo update` to populate the placement.
+ *   - `edited` requires user judgement (keep edits? overwrite?).
+ *   - `stale` requires `skillrepo update` to fetch the new version.
+ *   - `current` requires nothing.
+ *
+ * Edited ranks above stale because the user is more likely to lose
+ * work on `edited` (overwrite by sync). Missing ranks above edited
+ * because the missing placement is the most immediately broken.
+ *
+ * An empty input array returns `missing` — there are no detected
+ * vendors to check against, so we can't claim anything is current.
+ * Callers that have a true "no vendors detected" case usually
+ * short-circuit before getting here, but the safe fallback is the
+ * conservative one.
+ *
+ * @param {ReadonlyArray<"current" | "stale" | "missing" | "edited">} perVendorStates
+ * @returns {"current" | "stale" | "missing" | "edited"}
+ */
+export function rollupState(perVendorStates) {
+  if (!Array.isArray(perVendorStates) || perVendorStates.length === 0) {
+    return SKILL_STATE.MISSING;
+  }
+  const order = [
+    SKILL_STATE.MISSING,
+    SKILL_STATE.EDITED,
+    SKILL_STATE.STALE,
+    SKILL_STATE.CURRENT,
+  ];
+  for (const s of order) {
+    if (perVendorStates.includes(s)) return s;
+  }
+  // Defensive fallback for an array containing an unknown enum value.
+  // Treating it as the worst case (missing) is the conservative
+  // choice — it tells the user "something's off, run update" rather
+  // than silently rendering as current.
+  return SKILL_STATE.MISSING;
+}
+
+/**
+ * Strict semver `>` with a string-fallback escape hatch.
+ *
+ * `semver.gt` throws on invalid versions; we wrap with `semver.valid`
+ * to avoid the throw. When EITHER side is not valid semver, fall
+ * back to a plain string inequality — any difference is treated as
+ * the library being "ahead," which classifies the skill as `stale`.
+ * This is the right safety direction: false-stale tells the user to
+ * run `update`, which is harmless; false-current would mask drift.
+ *
+ * @param {string | null} libraryVersion
+ * @param {string | null} syncedVersion
+ * @returns {boolean}
+ */
+function libraryVersionIsNewer(libraryVersion, syncedVersion) {
+  if (typeof libraryVersion !== "string" || libraryVersion === "") return false;
+  if (typeof syncedVersion !== "string" || syncedVersion === "") {
+    // No baseline version → we can't decide ordering. Caller treats
+    // this as "version comparison inconclusive" and continues to
+    // the SHA check.
+    return false;
+  }
+  if (semver.valid(libraryVersion) && semver.valid(syncedVersion)) {
+    return semver.gt(libraryVersion, syncedVersion);
+  }
+  return libraryVersion !== syncedVersion;
+}

package/src/lib/file-write.mjs

@@ -227,10 +227,25 @@ export function describePlacementTarget(target) {
   }
 }
 
+/**
+ * Resolve the parent directory for a `PlacementTarget` — the dir
+ * that contains all skill subdirectories for this target. Exposed so
+ * read-side consumers (`placement-walk.mjs` for `list`'s drift
+ * detection in #1555) can enumerate skill placements without
+ * duplicating the target→root mapping that already lives here.
+ *
+ * @param {PlacementTarget} target
+ * @returns {string}
+ */
+export function resolvePlacementRoot(target) {
+  return placementRootFn(target)();
+}
+
 /**
  * Map a `PlacementTarget` to its parent root resolver. Used by
  * `cleanupOrphans` to know which directories to scan for `.tmp`/`.old`
- * siblings.
+ * siblings, and by `resolvePlacementRoot` above for read-side
+ * consumers.
  *
  * @param {PlacementTarget} target
  * @returns {() => string}