skillrepo 4.4.0 → 4.5.1

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/commands/remove.mjs

@@ -43,6 +43,7 @@ import {
   effectiveVendors,
   requireVendorTargets,
 } from "../lib/cli-config.mjs";
+import { deleteLastSyncEntry } from "../lib/sync.mjs";
 import { parseIdentifier, formatIdentifier } from "../lib/identifier.mjs";
 import { validationError } from "../lib/errors.mjs";
 
@@ -111,6 +112,18 @@ export async function runRemove(argv, io = {}) {
   // owner-namespacing caveat.
   const localResult = removeSkillDir(name, { vendors, global: flags.global });
 
+  // Step 2.5: purge the `.last-sync` entry for this skill so a future
+  // re-add of the same identifier doesn't compare against a stale
+  // baseline. Idempotent: no-op if the entry isn't there. Non-fatal
+  // on write failure — the user's primary intent (skill gone from
+  // library + disk) was honored; a stale baseline is recoverable
+  // via the next `update`.
+  try {
+    deleteLastSyncEntry(owner, name);
+  } catch {
+    // Same warn-and-proceed semantics as runSync's last-sync writes.
+  }
+
   if (flags.json) {
     stdout.write(
       JSON.stringify(

package/src/lib/agent-registry.mjs

@@ -140,7 +140,21 @@ export const AGENT_REGISTRY = Object.freeze([
     agentHook: null,
     detectionSignals: Object.freeze([
       Object.freeze({ type: "env", value: "CLAUDECODE" }),
-      Object.freeze({ type: "home", value: ".claude" }),
+      // Home signal MUST be a file Claude Code creates that SkillRepo
+      // itself never writes. The earlier `.claude` (bare dir) signal
+      // false-positive-detected on any user who'd ever run a SkillRepo
+      // command — because `init` writes config to
+      // `~/.claude/skillrepo/config.json` and every `runSync` writes
+      // `.last-sync` to the same parent, both of which create the
+      // `~/.claude/` directory as a side effect. Cursor-only users
+      // (or any non-Claude-Code user) were then incorrectly detected
+      // as Claude Code users on every subsequent `list` invocation,
+      // producing MISS for every skill at the claudeProject placement
+      // that was never populated. Probing `settings.json` — created by
+      // Claude Code on first run and never touched by SkillRepo — is
+      // the load-bearing distinction. See PR #1574 production-
+      // readiness audit for the full chain.
+      Object.freeze({ type: "home", value: ".claude/settings.json" }),
       Object.freeze({ type: "project", value: ".claude" }),
     ]),
   }),

package/src/lib/cli-config.mjs

@@ -25,6 +25,7 @@ import {
   AGENTS_COHORT_KEYS,
   getAgentByAlias,
 } from "./agent-registry.mjs";
+import { detectAgents } from "./detect-agents.mjs";
 import { authError, validationError } from "./errors.mjs";
 
 const ALL_VENDOR_KEYS = AGENT_REGISTRY.map((entry) => entry.key);
@@ -204,22 +205,48 @@ export function resolveFlags(argv, opts = {}) {
  *      always wins. Both flags propagate together, so `--global
  *      --agent windsurf` correctly resolves to `["windsurf"]` and
  *      placementTargetsFor maps that to `windsurfGlobal`.
- *   2. No `--agent` defaults to `["claudeCode"]`, regardless of
- *      `--global`. The v3.0.0 CLI deliberately does NOT silently
- *      fall back to `[claudeCode, cursor]` like v2.0.0 did.
+ *   2. No `--agent` defaults to ALL DETECTED vendors (4.5.1+) — every
+ *      agent whose detection signal fires in the current cwd / HOME /
+ *      env. This matches `init`'s picker behavior and `list`'s drift
+ *      detection model: the CLI assumes you want to keep every
+ *      agent on your machine in sync.
+ *   3. Fallback to `["claudeCode"]` when nothing is detected (fresh
+ *      machine with no agent installed yet — extremely rare, but
+ *      preserves the historical default so `skillrepo init` from
+ *      scratch still has a meaningful behavior).
+ *
+ * History: 4.4.0 and earlier defaulted to `["claudeCode"]` only,
+ * which created a mismatch with `list`'s drift detection in 4.5.0:
+ * `list` reported drift against all detected vendors while
+ * `update`/`add`/`remove`/`get` only wrote to Claude Code's
+ * placement. Multi-agent users saw every skill as `MISS` even after
+ * a full sync because the cohort `.agents/skills/` directory was
+ * never written to. See #1573 follow-up.
  *
  * The empty-array `--agent none` sentinel is returned verbatim —
  * callers detect "no placement" via `vendors.length === 0`. The
  * default-fallback branch uses an explicit null/undefined check so
  * the empty array survives.
  */
-export function effectiveVendors(flags) {
+export function effectiveVendors(flags, { detect = defaultDetectVendors } = {}) {
   if (flags.vendors === null || flags.vendors === undefined) {
-    return ["claudeCode"];
+    const detected = detect();
+    return detected.length > 0 ? detected : ["claudeCode"];
   }
   return flags.vendors;
 }
 
+/**
+ * Default detection callable for `effectiveVendors`. Exposed for tests
+ * that want to inject a deterministic vendor list via the second-arg
+ * `{ detect }` option — production callers should not pass anything.
+ */
+function defaultDetectVendors() {
+  return detectAgents()
+    .filter((d) => d.detected)
+    .map((d) => d.key);
+}
+
 /**
  * Reject `--agent none` for commands that have no meaningful behavior
  * without a placement target. `init` and `update` accept `--agent none`