skillrepo 4.14.0 → 4.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "4.14.0",
+  "version": "4.14.1",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {

package/src/commands/update.mjs

@@ -65,6 +65,8 @@ import {
  *
  *   - 304 Not Modified → exit 0, NO output.
  *   - 200 with changes → exit 0, ONE line: `[SkillRepo] Library synced: N added, N updated, N removed.`
+ *     ("Skillset" replaces "Library" when a declared repo ran a scoped
+ *     skillset sync — #2679.)
  *   - Any failure → exit 0, ONE line: `[SkillRepo] Sync failed: <reason>.`
  *   - Global-boundary disclosure (#2495): when the sync's summary
  *     reports global skills that will also load in this session
@@ -172,6 +174,7 @@ export async function runUpdate(argv, io = {}) {
       const skipped = summary.skipped ?? 0;
       const total =
         summary.added + summary.updated + summary.removed + skipped;
+      const subject = syncSubject(summary);
       // Global-boundary disclosure (#2495), computed BEFORE the silent
       // branch below: the quiet 304/zero-delta/throttled session is
       // the COMMON session, and it must still disclose — the line
@@ -232,7 +235,7 @@ export async function runUpdate(argv, io = {}) {
         return;
       }
       stdout.write(
-        `[SkillRepo] Library synced: ${summary.added} added, ${summary.updated} updated, ${summary.removed} removed` +
+        `[SkillRepo] ${subject} synced: ${summary.added} added, ${summary.updated} updated, ${summary.removed} removed` +
           (skipped > 0 ? `, ${skipped} SKIPPED (could not be written)` : "") +
           `.\n`,
       );
@@ -338,17 +341,28 @@ export async function runUpdate(argv, io = {}) {
   printSummary(summary, stdout);
 }
 
+// The noun for the scope a sync operated on (#2679). A declared repo's
+// scoped sync carries a top-level `skillsetRef` (stamped by the runSync
+// dispatcher on EVERY scoped return, including the grace/fail-closed path);
+// a whole-library sync does not. Keying off THIS — not the #2665
+// `compliance` object, whose presence excludes the non-fresh-scan paths —
+// is what keeps a scoped grace sync from mislabeling itself "Library".
+function syncSubject(summary) {
+  return summary.skillsetRef ? "Skillset" : "Library";
+}
+
 function printSummary(s, out) {
   // `skipped` counts here: a run that dropped a skill is NOT "up to date",
   // and saying so was a false statement to the user (#2413 adversarial
   // review — the counter was incremented and never read).
   const skipped = s.skipped ?? 0;
   const total = s.added + s.updated + s.removed + skipped;
+  const subject = syncSubject(s);
   if (s.notModified || total === 0) {
-    out.write("  ✓ Library is up to date.\n");
+    out.write(`  ✓ ${subject} is up to date.\n`);
     return;
   }
-  out.write("\n  Library sync complete:\n");
+  out.write(`\n  ${subject} sync complete:\n`);
   if (s.added > 0)   out.write(`    + ${s.added} added\n`);
   if (s.updated > 0) out.write(`    ↻ ${s.updated} updated\n`);
   if (s.removed > 0) out.write(`    − ${s.removed} removed\n`);

package/src/lib/sync.mjs

@@ -163,6 +163,24 @@
  *                                   the throttled early-exit, and the
  *                                   grace/fail-closed paths (no fresh
  *                                   scans there to state a fact from).
+ * @property {string} [skillsetRef] - The skillset this run was scoped to
+ *                                   (`declaration.use`), stamped by the
+ *                                   `runSync` dispatcher on EVERY return of
+ *                                   `runSkillsetScopedSync` — 200, 304,
+ *                                   grace/fail-closed, and that body's own
+ *                                   per-repo throttle exit. Unlike
+ *                                   `compliance.skillsetRef` (a narrower
+ *                                   subset), presence means "this run
+ *                                   dispatched to the skillset-scoped body".
+ *                                   ABSENT on whole-library syncs AND on the
+ *                                   machine-global throttled early-exit in
+ *                                   `runSync`'s own preamble — that path
+ *                                   returns BEFORE the declaration is
+ *                                   resolved, so a declared repo never
+ *                                   reaches dispatch there (same exclusion
+ *                                   `compliance` carries). Sound discriminator
+ *                                   for scope-aware copy on any path that
+ *                                   actually prints it (#2679).
  * @property {string} syncedAt    - ISO timestamp of the sync: the server
  *                                   response `syncedAt` on a 200, or the
  *                                   previously-cached sync timestamp on a
@@ -947,7 +965,7 @@ export async function runSync(options) {
   // extracted verbatim; the golden wire-identity tests arbitrate that
   // its behavior is character-for-character unchanged.
   if (declarationResolution?.status === "declared") {
-    return runSkillsetScopedSync({
+    const scopedSummary = await runSkillsetScopedSync({
       serverUrl,
       apiKey,
       vendors,
@@ -956,6 +974,18 @@ export async function runSync(options) {
       minSyncIntervalMs: intervalMs,
       resolution: declarationResolution,
     });
+    // Reliable top-level scope marker (#2679). EVERY scoped return is a
+    // skillset sync — including the grace/fail-closed path
+    // (`serveLastVerified`) and the defensive 304-no-prior branch, where the
+    // #2665 `compliance` object is intentionally ABSENT. Presentation
+    // (`printSummary`, the session-hook line) keys the "Skillset" vs
+    // "Library" noun off THIS field, never off `compliance.skillsetRef`
+    // (whose presence rules exclude the non-fresh-scan paths, so keying off
+    // it mislabels a scoped grace sync as "Library").
+    return {
+      ...scopedSummary,
+      skillsetRef: declarationResolution.declaration.use,
+    };
   }
 
   return runWholeLibrarySync({

package/src/test/commands/update.test.mjs

@@ -988,6 +988,113 @@ describe("runUpdate — skillset-declaration gate (#2362)", () => {
   });
 });
 
+// ── Scoped skillset sync says "Skillset", not "Library" (#2679) ────────
+//
+// In a declared repo, `update` runs a scoped skillset sync (sync.mjs
+// dispatch) and the summary carries a top-level `skillsetRef` (stamped
+// at the dispatcher on every scoped return), so the printer names that
+// scope. An undeclared repo (whole library) stays byte-identical
+// ("Library"). Sibling to #2672 (`list` vocabulary).
+
+describe("runUpdate — scoped skillset sync vocabulary (#2679)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  function declareRepo() {
+    // .git bounds the declaration walk inside the sandbox project dir.
+    mkdirSync(join(sandbox, "project", ".git"), { recursive: true });
+    writeFileSync(
+      join(sandbox, "project", "skillrepo.json"),
+      JSON.stringify({
+        skillset: { version: 1, name: "checkout", use: "acme/backend-core" },
+      }),
+    );
+  }
+
+  function scopedResponse(skills) {
+    return {
+      skills,
+      removals: [],
+      syncedAt: "2026-08-20T00:00:00.000Z",
+      skillset: {
+        name: "backend-core",
+        updatedAt: "2026-08-20T00:00:00.000Z",
+        skippedExtras: [],
+      },
+    };
+  }
+
+  it("no-op scoped sync prints 'Skillset is up to date', never 'Library'", async () => {
+    declareRepo();
+    server.setSkillsetResponse(scopedResponse([]));
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const out = stdout.text();
+    assert.match(out, /Skillset is up to date/);
+    assert.doesNotMatch(out, /Library is up to date/);
+  });
+
+  it("scoped sync that writes a skill prints 'Skillset sync complete'", async () => {
+    declareRepo();
+    server.setSkillsetResponse(scopedResponse([makeSkill("checkout-flow")]));
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const out = stdout.text();
+    assert.match(out, /Skillset sync complete/);
+    assert.match(out, /added/);
+    assert.doesNotMatch(out, /Library sync complete/);
+  });
+
+  it("--session-hook scoped sync reports 'Skillset synced', not 'Library synced'", async () => {
+    declareRepo();
+    server.setSkillsetResponse(scopedResponse([makeSkill("checkout-flow")]));
+    await runUpdate(
+      ["--session-hook", "--key", VALID_KEY, "--url", serverUrl],
+      { stdout },
+    );
+    const out = stdout.text();
+    assert.match(out, /\[SkillRepo\] Skillset synced: \d+ added/);
+    assert.doesNotMatch(out, /Library synced/);
+  });
+
+  it("an UNDECLARED repo keeps the 'Library' vocabulary (whole-library scope)", async () => {
+    // Guards against over-broadening: no declaration → no skillsetRef →
+    // the subject must remain "Library".
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const out = stdout.text();
+    assert.match(out, /Library is up to date/);
+    assert.doesNotMatch(out, /Skillset/);
+  });
+
+  it("declared repo during a registry outage (grace path) still says 'Skillset'", async () => {
+    // Regression for the review finding: the scoped grace path
+    // (serveLastVerified) returns NO `compliance` object, so a discriminator
+    // keyed off compliance.skillsetRef mislabeled it "Library". The reliable
+    // top-level skillsetRef (sync.mjs dispatcher) fixes it. First a
+    // successful scoped sync writes the per-repo verified state (which
+    // requires a server ETag — see the `result.etag` gate in sync.mjs)...
+    declareRepo();
+    server.setSkillsetEtag('W/"ss-' + "a".repeat(64) + '"');
+    server.setSkillsetResponse(scopedResponse([makeSkill("checkout-flow")]));
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // ...then the registry goes unreachable; the interactive sync (never
+    // throttled) serves last-verified and must keep the "Skillset" noun.
+    server.setSkillsetError({
+      status: 503,
+      body: { error: "upstream flake" },
+      headers: { "Retry-After": "30" },
+    });
+    const graceStdout = createCaptureStream();
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl],
+      { stdout: graceStdout },
+    );
+    const graceOut = graceStdout.text();
+    assert.match(graceOut, /Skillset is up to date/);
+    assert.doesNotMatch(graceOut, /Library is up to date/);
+  });
+});
+
 // ── Throttle window + declaration interplay through the hook flags ─────
 // (#2362 prod-readiness QA): a throttled hook sync returns BEFORE the
 // gate by documented design (#2174 zero-work contract). A repo that

package/src/test/lib/sync-skillset.test.mjs

@@ -1549,7 +1549,9 @@ describe("repo compliance state line (#2665) — always on while non-compliant",
       { stdout },
     );
     const out = stdout.text();
-    assert.match(out, /\[SkillRepo\] Library synced: 1 added/);
+    // Declared repo → scoped sync → the noun is "Skillset", not "Library"
+    // (#2679; a top-level `skillsetRef` is stamped on the scoped path).
+    assert.match(out, /\[SkillRepo\] Skillset synced: 1 added/);
     assert.match(
       out,
       /\[SkillRepo\] This repo does not match its skillset acme\/backend-core \(1 extra skill in the project\) — it is reported as not compliant\./,