skillrepo 4.15.0 → 4.17.0

package/README.md

@@ -167,9 +167,10 @@ skillrepo update [--global] [--agent <list>] [--json] [--silent]
 
 Pulls the latest state of your library from the server using a delta
 sync. Writes new and updated skills, removes skills that were removed
-from the library, and skips skills that are unchanged. Uses ETag
-caching so repeat runs return `304 Not Modified` when nothing has
-changed.
+from the library, and skips skills that are unchanged. In a repo that
+declares a skillset, `update` instead reconciles that declared set (a
+full-set resolve, not a delta). Uses ETag caching so repeat runs return
+`304 Not Modified` when nothing has changed.
 
 `--silent` suppresses normal output and writes a single `{}` line to
 stdout on success. Designed for SessionStart hooks that pipe stdout
@@ -246,48 +247,80 @@ One-shot fetch. Does NOT mutate your library or the server — just reads
 `GET /api/v1/skills/{owner}/{name}` and writes the skill to disk. Use
 this to preview or pin a specific skill without adding it to your library.
 
-### `list` — show what's in your library and what needs syncing
+### `list` — show what's on disk and how it compares to the server
 
 ```sh
 skillrepo list [--json]
 ```
 
-Renders your library as a table with a per-row `Local` column showing
-on-disk drift state for each detected vendor:
+`list` is disk-first: it walks the skills actually on disk, then
+annotates each against your last sync (local integrity) and the server
+(governance + freshness). This means an on-disk skill is never hidden —
+a hand-authored directory, a skill the server has withdrawn, or one you
+deleted all show up, alongside the ones that are healthy.
 
-- `OK` — local copy matches the last sync.
-- `STALE` — library has a newer version than what's on disk.
-- `MISS` — library has the skill but no on-disk placement (or no sync
-  history yet — run `skillrepo update` to establish a baseline).
-- `EDIT` — local files have been modified since the last sync (different
-  SHA than what was persisted).
+The `State` column shows one worst-wins signal per row, staying quiet
+when a row is healthy:
 
-When multiple vendors are detected, the column shows a worst-state-wins
-rollup (`missing > edited > stale > current`). The `--json` output
-includes a `placements[]` array per item with per-vendor states for
-scripts that want the full breakdown.
-
-A footer reports library-level sync state:
-
-- `library in sync — local skills up to date` — everything is current.
-- `library in sync — but N skills show local drift` — library hasn't
-  changed but some local placements need attention.
-- `library has changed since last sync` — registry has new content; run
+- `OK` — on disk, matches your last sync, and the server hasn't moved on.
+- `EDITED` — local files were modified since the last sync; `update`
+  would overwrite them.
+- `BEHIND` — the server has a newer version than what you synced; run
   `skillrepo update`.
-- `No sync history on this machine` — fresh install or
-  baseline-less state; run `skillrepo update`.
-
-Glyphs (`✓` / `⚠`) are used in TTY contexts; ASCII fallbacks (`OK` /
-`[!]` / `STALE` / `MISS` / `EDIT`) appear when stdout is not a TTY or
-`NO_COLOR` is set, so piped output stays clean.
-
-`--json` is a bare array of skill objects with the additional fields
-`state` (rollup) and `placements[]`. Existing scripts that consume
-the pre-#1555 `--json` shape keep working — the additions are purely
-per-item, no top-level wrapper.
-
-Uses the same cached ETag as `update` for the library-level footer
-state.
+- `SERVING` — the server rolled a recalled version back to an earlier
+  one; you're being served the fallback.
+- `WITHDRAWN` — on disk and once served to you, but the server no longer
+  serves it. The CLI can't tell a recall from an unpublish or a skillset
+  re-scope, so it doesn't guess — it flags that it's no longer served
+  (remove it, or investigate).
+- `MISSING` — expected (in your library, or your repo's skillset) but not
+  on disk.
+- `FOREIGN` — on disk in a managed directory, but not from your library.
+- `NOT DELIVERED` — a skillset member the CLI declined to write (edited
+  locally, replaced, incomplete, or invalid), with the reason.
+- `NOT CHECKED` — the server couldn't be reached, so freshness is
+  unknown. `list` never reports a stale copy as current.
+
+`list` speaks the dashboard's `LATEST` / `SERVING` vocabulary (green is
+used only for a served head version), so healthy and recall-fallback
+states read identically on the CLI and the web. Where the CLI can't verify
+a governance cause — a skill that's simply no longer served — it says
+`WITHDRAWN` rather than asserting `RECALLED`; `recalled` appears only in a
+`SERVING` row's reason, where the server names the recalled version. Each attention row also carries a
+plain-English reason — what changed, why, and what to do — listed in an
+attention block beneath the table. Both `list` views render the same way
+(see "Same view everywhere" below).
+
+When multiple vendors are detected, the local integrity axis is a
+worst-wins rollup (`missing > edited > present`).
+
+**Same view everywhere.** A repo that declares a skillset shows its
+delivered set in the identical table — same columns, same colours, same
+attention block as the whole-library view — plus a compliance line for
+the declared set. `list` issues a non-recording freshness probe for the
+declared set (a full read that resolves and records nothing) so a
+recalled-then-restored skill reads `BEHIND` even inside the sync throttle
+window, and a recall fallback reads `SERVING` rather than a false green.
+
+**Offline-capable.** `list` works with no network: the local axes are
+computed from disk, and the server axis degrades to `NOT CHECKED` rather
+than failing.
+
+**Read-only.** `list` never records a delivery, writes sync state, or
+consumes a warning `update` owes you.
+
+The `State` chip is coloured to match the dashboard — green for the one
+healthy state (`OK` / `LATEST`), amber for `SERVING`, red for `WITHDRAWN`
+and `MISSING`. Glyphs and colour are used in TTY contexts; plain ASCII
+tokens (`OK` / `EDITED` / `BEHIND` / …) with no colour appear when stdout
+is not a TTY or `NO_COLOR` is set, so piped output stays clean.
+
+`--json` is a bare array of skill objects (a top-level object with a
+`skillset` block in a declared repo). Each row carries the full model —
+`classification`, `local`, `governance`, `freshness`, the collapsed
+`signal`, and a per-vendor `placements[]` array. The pre-#2806 `state`
+(worst-wins drift rollup) field is kept for backward compatibility, so
+existing scripts keep working.
 
 ### `search` — explore the registry
 
@@ -460,7 +493,7 @@ Auto-refresh hooks for Windsurf and Cline are not yet supported — those agents
 
 **On 304 (nothing changed) the hook is silent.** You only see output when your library actually syncs or a failure happens. No "Syncing…" noise on every session.
 
-**Throttled to skip redundant syncs (v4.9.0+).** Because the hook fires on *every* editor session, the hook-triggered `update` (`--session-hook` / `--silent`) syncs at most once per ~15 minutes: within that window it exits immediately with **no network call**. This bounds redundant per-session load. The tradeoff is that a brand-new session started shortly after a recent sync may be up to ~15 minutes behind a just-published change — and the same bound applies to local repair: if you delete or corrupt a synced skill's folder on disk, the hook restores it on its next non-throttled run, up to ~15 minutes later. A bare `skillrepo update` **you** run yourself is never throttled — it always syncs immediately (repairing any local damage) and resets the window. `skillrepo list` is likewise never throttled (it always queries the server live), though it doesn't reset the window.
+**Throttled to skip redundant syncs (v4.9.0+).** Because the hook fires on *every* editor session, the hook-triggered `update` (`--session-hook` / `--silent`) syncs at most once per ~15 minutes: within that window it exits immediately with **no network call**. This bounds redundant per-session load. The tradeoff is that a brand-new session started shortly after a recent sync may be up to ~15 minutes behind a just-published change — and the same bound applies to local repair: if you delete or corrupt a synced skill's folder on disk, the hook restores it on its next non-throttled run, up to ~15 minutes later. A bare `skillrepo update` **you** run yourself is never throttled — it always syncs immediately (repairing any local damage) and resets the window. `skillrepo list` is likewise never throttled: it reads the server live (a non-recording request) when reachable and degrades to local-only when it isn't, and it never resets the window. A repo that declares a skillset throttles on its **own** per-repo clock, so an unrelated repo's bulk sync elsewhere on the machine can no longer starve its refresh (v4.16.0+).
 
 Flags:
 

package/bin/skillrepo.mjs

@@ -54,7 +54,7 @@ const COMMANDS = {
     run: async (argv) => runInit(argv),
   },
   update: {
-    description: "Sync your library against the registry (delta + tombstones)",
+    description: "Sync your library, or this repo's declared skillset, from the registry",
     usage: "skillrepo update [--global] [--agent <list>] [--json]",
     run: async (argv) => runUpdate(argv),
   },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "skillrepo",
-  "version": "4.15.0",
-  "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
+  "version": "4.17.0",
+  "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library, synced across your dev environment",
   "type": "module",
   "bin": {
     "skillrepo": "./bin/skillrepo.mjs"

package/src/commands/list-providers.mjs

@@ -0,0 +1,285 @@
+/**
+ * `skillrepo list` — data-gathering providers (#2806).
+ *
+ * Everything that turns the environment (detected vendors, the server,
+ * the last-sync baseline, the per-repo state) into the normalized inputs
+ * the disk-first engine (`lib/list-engine.mjs`) classifies. The command
+ * orchestrators in `list.mjs` compose these with the walk + the engine +
+ * the renderers (`list-render.mjs`).
+ *
+ * READ-ONLY to the letter: the library manifest peek (#1832) and the
+ * skillset freshness probe (`manifest=1&skillset=…`) both record NO
+ * delivery, and neither writes local state. The one server-touching
+ * failure mode that MUST NOT crash a status command — an unreachable /
+ * transient server — degrades the server axis to NOT CHECKED here, never
+ * a false "up to date".
+ */
+
+import { getLibrary } from "../lib/http.mjs";
+import { readLastSync } from "../lib/sync.mjs";
+import { detectAgents } from "../lib/detect-agents.mjs";
+import { getAgentByKey } from "../lib/agent-registry.mjs";
+import { EXIT_NETWORK } from "../lib/errors.mjs";
+import {
+  scanGlobalBoundary,
+  managedGlobalNamesFrom,
+  GLOBAL_SHADOWED_CATEGORY,
+  GLOBAL_LIBRARY_CATEGORY,
+  GLOBAL_FOREIGN_CATEGORY,
+} from "../lib/global-boundary.mjs";
+import {
+  scanForeignContent,
+  buildRepoCompliance,
+} from "../lib/foreign-content.mjs";
+
+// ── detection + baseline shaping ────────────────────────────────────────
+
+/**
+ * Detect the vendors with footprint on this machine/project and
+ * pre-resolve the ones that contribute a project-scope placement. Shared
+ * by both views. Returns the detected entries (for the "Detected:" line)
+ * and the flat key list (for the walk + engine).
+ *
+ * @returns {{ detected: object[], detectedKeys: string[] }}
+ */
+export function resolveDetected() {
+  const detected = detectAgents().filter((d) => d.detected);
+  const detectedVendorEntries = detected
+    .map((d) => getAgentByKey(d.key))
+    .filter((entry) => entry !== null && entry.projectTarget !== null);
+  return { detected, detectedKeys: detectedVendorEntries.map((e) => e.key) };
+}
+
+/**
+ * Build the baseline map keyed `"owner/name"` from a `.last-sync`-style
+ * skills map, dropping entries that fail the required-string shape
+ * check (a tampered or half-written entry). The whole-library baseline.
+ *
+ * @param {Record<string, unknown>} skillsMap
+ * @returns {Map<string, {version: string, skillMdSha256: string, filesSha256: string}>}
+ */
+export function buildBaselineByKey(skillsMap) {
+  const out = new Map();
+  if (!skillsMap || typeof skillsMap !== "object") return out;
+  for (const [key, raw] of Object.entries(skillsMap)) {
+    const entry = validateBaselineShape(raw);
+    if (entry) out.set(key, entry);
+  }
+  return out;
+}
+
+/**
+ * Shape a skillset repo's `resolved` manifest into the engine's expected
+ * set + baseline. Every resolved member is expected (delivered or not);
+ * only `written: true` members with a valid SHA pair contribute a
+ * baseline (a served-but-unwritten member has no on-disk content of ours
+ * to diff against).
+ *
+ * @param {import("../lib/repo-sync-state.mjs").RepoResolvedEntry[]} resolved
+ * @returns {{ expected: object[], baselineByKey: Map<string, object> }}
+ */
+export function buildSkillsetInputs(resolved) {
+  const expected = resolved.map((e) => ({
+    owner: e.owner,
+    name: e.name,
+    version: e.version ?? null,
+    written: e.written === true,
+    unwrittenReason: typeof e.unwrittenReason === "string" ? e.unwrittenReason : null,
+  }));
+  const baselineByKey = new Map();
+  for (const e of resolved) {
+    if (e && e.written === true) {
+      const b = validateBaselineShape({
+        version: e.version,
+        skillMdSha256: e.skillMdSha256,
+        filesSha256: e.filesSha256,
+      });
+      if (b) baselineByKey.set(`${e.owner}/${e.name}`, b);
+    }
+  }
+  return { expected, baselineByKey };
+}
+
+/**
+ * Reject a baseline entry missing required string fields — a tampered
+ * or partially-written entry returns null, treated as "no baseline".
+ */
+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 entry;
+}
+
+// ── whole-library server truth ──────────────────────────────────────────
+
+/**
+ * Fetch the non-recording whole-library manifest (#1832) and shape it
+ * into the engine's expected set + server truth + display metadata.
+ * Governance rides on every skill since #2793. No `If-None-Match` is
+ * sent — the undeclared request stays byte-identical to the pre-#2672
+ * CLI (D2 wire identity).
+ *
+ * Offline-capable: a network/unreachable/transient failure (EXIT_NETWORK
+ * covers a fetch throw, a timeout, a 5xx, and an exhausted 429) degrades
+ * to a disk-first offline view — server axis NOT CHECKED, expected set
+ * falling back to what we last synced. A bad key / bad URL (auth /
+ * validation / scope) is a real problem the user must fix, so those
+ * still throw.
+ *
+ * @param {object} args
+ * @param {ReturnType<typeof import("../lib/cli-config.mjs").resolveFlags>} args.flags
+ * @param {Map<string, object>} args.baselineByKey - The offline fallback expected set.
+ * @returns {Promise<{ expected: object[], serverTruth: object, metaByKey: Map<string, object>, offline: boolean }>}
+ */
+export async function fetchLibraryData({ flags, baselineByKey }) {
+  const metaByKey = new Map();
+  try {
+    const libraryResponse = await getLibrary(flags.serverUrl, flags.apiKey, {
+      manifest: true,
+    });
+    const skills = Array.isArray(libraryResponse.skills) ? libraryResponse.skills : [];
+    const expected = skills.map((s) => ({ owner: s.owner, name: s.name, version: s.version ?? null }));
+    const byKey = new Map();
+    for (const s of skills) {
+      byKey.set(`${s.owner}/${s.name}`, {
+        servedVersion: s.version ?? null,
+        governance: s.governance ?? null,
+      });
+      metaByKey.set(`${s.owner}/${s.name}`, {
+        description: s.description ?? "",
+        updatedAt: s.updatedAt ?? null,
+        filesIncomplete: s.filesIncomplete ?? false,
+      });
+    }
+    return { expected, serverTruth: { checked: true, byKey }, metaByKey, offline: false };
+  } catch (err) {
+    if (!(err && err.exitCode === EXIT_NETWORK)) throw err;
+    const expected = [...baselineByKey.entries()].map(([key, b]) => {
+      const slash = key.indexOf("/");
+      return { owner: key.slice(0, slash), name: key.slice(slash + 1), version: b.version ?? null };
+    });
+    return {
+      expected,
+      serverTruth: { checked: false, byKey: null },
+      metaByKey,
+      offline: true,
+    };
+  }
+}
+
+// ── skillset server truth + governance ──────────────────────────────────
+
+/**
+ * Fire the non-recording skillset freshness probe (an UNCONDITIONAL 200
+ * manifest read) and shape the result into the engine's `ServerTruth` plus
+ * the display metadata for the Updated / Description columns. NEVER throws
+ * — the probe is a best-effort annotation, so every failure mode collapses
+ * to `checked: false` (NOT CHECKED).
+ *
+ * Unconditional by design (#2807, resolving the Phase-1 boundary): the
+ * whole-library variant already issues a full 200 every time
+ * (`fetchLibraryData` sends no `If-None-Match`), and the two `list` views
+ * must read identically. A conditional `If-None-Match` → 304 would return
+ * no body, so a steady-state recall fallback would render a quiet green OK
+ * instead of `serving` (green for a non-latest served version — the exact
+ * invariant this epic exists to hold). #1847's 304-path DB-load concern is
+ * about the SessionStart sync THROTTLE (a hot, per-session path), not this
+ * cold, explicit `list` probe, so the conditional saved nothing that
+ * mattered and cost the governance signal. The read remains non-recording
+ * (records no delivery / heartbeat / sync-state) and `list` never persists
+ * its etag. See `docs/SKILL-STATE-MODEL.md` §7.
+ *
+ * @param {object} args
+ * @param {ReturnType<typeof import("../lib/cli-config.mjs").resolveFlags>} args.flags
+ * @param {string} args.skillsetRef
+ * @param {string} args.repoName
+ * @param {string[]} args.extra
+ * @returns {Promise<{ serverTruth: import("../lib/list-engine.mjs").ServerTruth, metaByKey: Map<string, object> }>}
+ */
+export async function probeSkillsetFreshness({ flags, skillsetRef, repoName, extra }) {
+  const metaByKey = new Map();
+  try {
+    const resp = await getLibrary(flags.serverUrl, flags.apiKey, {
+      manifest: true,
+      skillset: skillsetRef,
+      repo: repoName,
+      extra,
+    });
+    const skills = Array.isArray(resp.skills) ? resp.skills : [];
+    const byKey = new Map();
+    for (const s of skills) {
+      byKey.set(`${s.owner}/${s.name}`, {
+        servedVersion: s.version ?? null,
+        governance: s.governance ?? null,
+      });
+      metaByKey.set(`${s.owner}/${s.name}`, {
+        description: s.description ?? "",
+        updatedAt: s.updatedAt ?? null,
+        filesIncomplete: s.filesIncomplete ?? false,
+      });
+    }
+    return { serverTruth: { checked: true, byKey }, metaByKey };
+  } catch {
+    // Best-effort to the letter: an offline machine, a bad key, an
+    // unresolvable skillset, or a server hiccup all leave the freshness
+    // axis NOT CHECKED (and Updated / Description blank) rather than
+    // failing a read-only status command.
+    return { serverTruth: { checked: false, byKey: null }, metaByKey };
+  }
+}
+
+/**
+ * Run the read-only governance scans for the skillset view ONCE and
+ * return both the #2665 compliance object and the raw global-boundary
+ * scan. Unchanged from pre-#2806: compliance replays the delivery-reason
+ * counts from `resolved` and re-scans foreign + global content fresh
+ * from disk (read-only, never committing seen-state).
+ *
+ * @param {object} args
+ * @param {string} args.skillsetRef
+ * @param {import("../lib/repo-sync-state.mjs").RepoResolvedEntry[]} args.resolved
+ * @param {string[]} args.detectedKeys
+ * @param {string} args.rootDir
+ */
+export function evaluateSkillsetGovernance({ skillsetRef, resolved, detectedKeys, rootDir }) {
+  const managedSkills = {};
+  for (const e of resolved) {
+    if (e && e.owner && e.name) managedSkills[`${e.owner}/${e.name}`] = { version: e.version };
+  }
+
+  let foreignCount = 0;
+  let gbScan = null;
+  try {
+    foreignCount = scanForeignContent({
+      vendors: detectedKeys,
+      global: false,
+      managedSkills,
+      baseDir: rootDir,
+    }).foreignCount;
+    gbScan = scanGlobalBoundary({
+      vendors: detectedKeys,
+      memberNames: new Set(resolved.map((e) => e.name)),
+      managedGlobalNames: managedGlobalNamesFrom(readLastSync()?.skills),
+      baseDir: rootDir,
+    });
+  } catch {
+    // Best-effort: a scan failure must never crash the delivered-set view.
+  }
+
+  const compliance = buildRepoCompliance({
+    skillsetRef,
+    foreignCount,
+    shadowedCount: gbScan?.counts?.[GLOBAL_SHADOWED_CATEGORY] ?? 0,
+    globalBeyondCount:
+      (gbScan?.counts?.[GLOBAL_LIBRARY_CATEGORY] ?? 0) +
+      (gbScan?.counts?.[GLOBAL_FOREIGN_CATEGORY] ?? 0),
+    resolved,
+  });
+  return { compliance, gbScan };
+}