skillrepo 4.9.2 → 4.11.0

package/README.md

@@ -169,6 +169,32 @@ code and the error message goes to stderr (distinct from
 `--session-hook`, which is Claude-Code-specific and exits 0 on every
 error so a sync failure can't block a session start).
 
+Every sync also inventories the skill folders it manages. A directory
+the CLI did not write — a hand-authored or copied-in skill — gets a
+one-line warning naming the path, why it matters (agents load skills
+from disk whether or not they came from your library), and what to do
+about it (`skillrepo push <path>` to bring it into your library, or
+remove the directory). Each finding is reported once: the warning
+repeats only when something changes, and only interactive runs print
+it (session auto-sync hooks stay quiet). Warnings are local only
+(skill names never leave your machine), and nothing is ever deleted or
+modified. `--json` output includes the total count as `unmanaged`.
+Sync also warns — once per repo, same rules — when a `skillrepo.json`
+at the repo root is gitignored: the skillset declaration only works as
+a committed file, so remove it from `.gitignore` and commit it.
+
+A repository can declare a skillset in a root `skillrepo.json`:
+`{"skillset": {"version": 1, "name": "<repo-identity>", "use":
+"owner/skillset-name"}}` (optional `extra: ["owner/skill"]`). The CLI
+finds the file from any subdirectory (it walks up to the repository
+root) and validates it before syncing. Skillset delivery is not yet
+available: a repository with a declaration fails its sync closed
+(exit code `6`) rather than receiving the whole library — a declared
+repo only ever receives its declared skillset. Keep the declaration
+while your team prepares for skillsets, or remove the `skillset`
+block to sync your whole library. A `skillrepo.json` without a
+`skillset` key is plain configuration and does not change sync.
+
 ### `get` — fetch a single skill
 
 ```sh
@@ -543,9 +569,9 @@ Skills land at one of two project paths, depending on the agent:
 | Cursor / Windsurf / Gemini CLI / Codex CLI / Cline / GitHub Copilot | `.agents/skills/<name>/` | `~/.agents/skills/<name>/` |
 | Windsurf (personal-scope override) | — | `~/.codeium/windsurf/skills/<name>/` |
 
-The CLI auto-adds `.claude/skills/` and `.agents/skills/` to your project
-`.gitignore` on first write — skills are a per-developer cache, not
-committed content. The `--agent` flag overrides detection (e.g.
+The CLI keeps `.claude/skills/` and `.agents/skills/` listed in the
+SkillRepo section of your project `.gitignore`, re-checked on every
+sync — skills are a per-developer cache, not committed content. The `--agent` flag overrides detection (e.g.
 `--agent claude,agents` writes both paths). See
 [`docs/vendor-paths.md`](docs/vendor-paths.md) for primary-source
 citations on each agent's read paths.
@@ -560,6 +586,7 @@ citations on each agent's read paths.
 | 3 | Disk error (cannot read or write a file/directory) |
 | 4 | Scope error (key lacks the required `registry:write` scope) |
 | 5 | Validation error (bad flag, malformed identifier, unknown vendor) |
+| 6 | Unresolvable skillset declaration — the repo's root `skillrepo.json` declares a skillset that cannot be honored (invalid or nested declaration, reserved `@` version syntax, or skillset delivery not yet available). Fail-closed: nothing was written or removed. |
 
 Pass `--verbose` to any command to print stack traces and retry
 attempts on failure.

package/package.json

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

package/src/commands/init.mjs

@@ -94,6 +94,7 @@ import {
   authError,
   validationError,
   EXIT_AUTH,
+  EXIT_UNRESOLVABLE,
 } from "../lib/errors.mjs";
 import { cliAuthUrl } from "../lib/constants.mjs";
 import {
@@ -658,10 +659,23 @@ export async function runInit(argv, io = {}, deps = {}) {
       // rethrow) as an inconsistent contract: the warning told users
       // to retry with `update`, but the non-zero exit code made it
       // look like the whole init had failed.
-      p.warning(
-        `Config saved but first sync failed: ${err.message}. ` +
-          `Run \`skillrepo update\` later to retry.`,
-      );
+      // Declaration-gated repos (#2362) get tailored copy: "run
+      // update later to retry" is wrong advice when the sync failed
+      // closed on the repo's skillset declaration — retrying changes
+      // nothing until the declaration is fixed/removed (or, for the
+      // not-yet-available case, until skillset delivery ships). The
+      // error message + hint already carry why and what to do.
+      if (err instanceof CliError && err.exitCode === EXIT_UNRESOLVABLE) {
+        p.warning(
+          `Config saved, but this repository's library sync is blocked: ${err.message}` +
+            (err.hint ? ` ${err.hint}` : ""),
+        );
+      } else {
+        p.warning(
+          `Config saved but first sync failed: ${err.message}. ` +
+            `Run \`skillrepo update\` later to retry.`,
+        );
+      }
       syncFailedReason = err.message;
       // Synthesize a zero-delta summary matching the SyncSummary
       // typedef in sync.mjs (added, updated, removed, notModified,

package/src/lib/artifact-registry.mjs

@@ -58,22 +58,39 @@ import { AGENT_REGISTRY } from "./agent-registry.mjs";
  * and are removed by the gitignore remover. User-authored lines outside
  * the section are never touched — this is the attribution mechanism.
  *
- * MUST stay in lockstep with `src/lib/mergers/gitignore.mjs`
- * SECTION_HEADER. The artifact-registry CI test asserts both modules
- * resolve the same header text.
+ * The section writer (`src/lib/gitignore-section.mjs`) imports this
+ * constant directly (#2361 consolidated the previously duplicated
+ * header definitions), so merger, sync pre-flight, and remover are in
+ * lockstep at the language level.
  */
 export const GITIGNORE_SECTION_HEADER =
   "# SkillRepo CLI (added by `skillrepo init`)";
 
 /**
- * Entries written under the gitignore section by init. The remover
- * does not match individual entries — it removes every line between the
- * header and the next blank line — but the expected set is exported so
- * tests can verify the two lists stay in sync.
+ * Header of the RETIRED sync-time gitignore section (#2361). Before
+ * 4.10.0 the sync pre-flight wrote `.agents/skills/` under this
+ * separate header, outside the marked section above — so the uninstall
+ * remover never cleaned it. The merger's heal migrates the shape into
+ * the marked section on every sync, and the remover strips a leftover
+ * legacy section on uninstall. Nothing writes this header anymore;
+ * the constant exists so heal and remover stay in lockstep on the
+ * exact historical text.
+ */
+export const LEGACY_GITIGNORE_SECTION_HEADER =
+  "# SkillRepo (CLI-managed library skills)";
+
+/**
+ * Entries the CLI may write under the gitignore section. Init writes
+ * all of them (subject to vendor targets); the sync-time pre-flight
+ * (`ensureManagedRootIgnores`) writes only the managed-root entries.
+ * The remover does not match individual entries — it removes every
+ * line between the header and the next blank line — but the expected
+ * set is exported so tests can verify the lists stay in sync.
  */
 export const GITIGNORE_REQUIRED_ENTRIES = Object.freeze([
   ".env.local",
   ".claude/skills/",
+  ".agents/skills/",
   ".claude/settings.local.json",
 ]);
 
@@ -346,9 +363,10 @@ export const ARTIFACT_REGISTRY = Object.freeze([
     id: "global-config-dir",
     scope: "global",
     kind: "directory",
-    // `~/.claude/skillrepo/` — the parent dir of both config.json and
-    // .last-sync. Whole-directory removal is correct because both
-    // children are CLI-owned and there's no room for user content.
+    // `~/.claude/skillrepo/` — the parent dir of config.json,
+    // .last-sync, .npm-version-check, and .governance-seen (#2361).
+    // Whole-directory removal is correct because every child is
+    // CLI-owned and there's no room for user content.
     pathFn: () => join(homedir(), ".claude", "skillrepo"),
     displayPath: "~/.claude/skillrepo/",
   }),

package/src/lib/constants.mjs

@@ -37,6 +37,17 @@
  * and authorized regardless. Spoofing the params just affects UX
  * immediacy, not authorization.
  */
+/**
+ * Repo-root skillset declaration file (#2361, design doc D6 amendment
+ * 2026-08-07). The committed, human-owned governance contract: the
+ * declaration lives at the repo root in `skillrepo.json`, nested under
+ * a `skillset` key. H4 ships only the gitignored-declaration warning
+ * (`foreign-content.mjs`); reading and resolving the declaration is
+ * H5 (#2362), which consumes the sub-schema recorded in the design
+ * doc's D6 note.
+ */
+export const SKILLSET_DECLARATION_FILE = "skillrepo.json";
+
 const DEFAULT_CLI_AUTH_HOST = "https://skillrepo.dev";
 const CLI_AUTH_PATH = "/cli/auth";
 const CLI_AUTH_QUERY = "?source=cli&new=1";

package/src/lib/errors.mjs

@@ -9,6 +9,15 @@
  *   3 — disk error (cannot read or write a file/directory)
  *   4 — scope error (key lacks the required scope for the requested action)
  *   5 — validation error (bad CLI input — invalid flag, malformed identifier, etc.)
+ *   6 — unresolvable skillset declaration (#2362, design doc D9): the
+ *       repo's `skillrepo.json` skillset declaration cannot be honored
+ *       (unparseable file, invalid sub-schema, nested declarations,
+ *       reserved `@` version syntax, or skillset delivery not yet
+ *       available). Fail-closed: nothing was written or removed. This
+ *       one code covers the WHOLE D9 fail-closed class, locally AND —
+ *       once H8 (#2365) wires the server — the server's typed 422
+ *       `harness_unresolvable` response, so CI scripts get one stable
+ *       "declaration cannot be honored" signal.
  *
  * These mirror the documented behavior in #683 and are the contract
  * shell users and CI scripts can rely on.
@@ -40,6 +49,7 @@ export const EXIT_AUTH = 2;
 export const EXIT_DISK = 3;
 export const EXIT_SCOPE = 4;
 export const EXIT_VALIDATION = 5;
+export const EXIT_UNRESOLVABLE = 6;
 
 /**
  * Base error class for typed CLI errors. Carries an exit code and
@@ -89,6 +99,19 @@ export function validationError(message, options) {
   return new CliError(message, EXIT_VALIDATION, options);
 }
 
+/**
+ * Unresolvable skillset declaration (#2362). Distinct from
+ * `validationError` on purpose: exit 5 means "your CLI input is bad",
+ * and one member of this class — skillset delivery not yet being
+ * available — is not the user's fault at all (the declaration file may
+ * be perfectly valid). D9's fail-closed contract holds for every
+ * member: nothing was written or removed, and the sync NEVER falls
+ * back to whole-library delivery.
+ */
+export function unresolvableError(message, options) {
+  return new CliError(message, EXIT_UNRESOLVABLE, options);
+}
+
 // ── Retry helper ───────────────────────────────────────────────────────
 
 /**

package/src/lib/file-write.mjs

@@ -56,7 +56,6 @@ import {
 } from "node:fs";
 import { dirname, join, isAbsolute, relative } from "node:path";
 
-import { readFileSafe, writeFileSafe } from "./fs-utils.mjs";
 import {
   claudeSkillsProject,
   claudeSkillsGlobal,
@@ -71,6 +70,7 @@ import {
   gitignorePath,
 } from "./paths.mjs";
 import { AGENT_REGISTRY, getAgentByKey } from "./agent-registry.mjs";
+import { ensureManagedRootIgnores } from "./gitignore-section.mjs";
 import { CliError, validationError, diskError } from "./errors.mjs";
 import { platformConventions } from "./platform.mjs";
 
@@ -93,9 +93,6 @@ export const BLOCKED_EXTENSIONS = new Set([
   ".wasm",
 ]);
 
-const GITIGNORE_AGENTS_SKILLS_LINE = ".agents/skills/";
-const GITIGNORE_SKILLS_HEADER = "# SkillRepo (CLI-managed library skills)";
-
 // ── Types (JSDoc only — this is plain JS) ───────────────────────────────
 
 /**
@@ -148,16 +145,36 @@ const CONTROL_CHARS_GLOBAL = /[\u0000-\u001f\u007f-\u009f]/g;
  * \uXXXX-escaped, so the error string can never re-inject the characters
  * it rejects into terminal output or sync logs.
  *
+ * Exported (#2361 prod-readiness): the foreign-content warnings print
+ * on-disk directory names — filesystem-sourced, attacker-influenceable
+ * strings — to stderr, the exact injection class this helper exists
+ * for. Single source per the shared-logic rule.
+ *
  * @param {string} value
  * @returns {string}
  */
-function escapeControlChars(value) {
+export function escapeControlChars(value) {
   return value.replace(
     CONTROL_CHARS_GLOBAL,
     (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`,
   );
 }
 
+/**
+ * True when the value contains any control character (C0, DEL, or C1 —
+ * the same class `escapeControlChars` escapes). Exported (#2362) so
+ * validators can REJECT control characters up front with the one
+ * canonical class instead of hand-rolling a second, narrower regex —
+ * the skillset-declaration validator is the first consumer. Single
+ * source per the shared-logic rule.
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function hasControlChars(value) {
+  return CONTROL_CHARS.test(value);
+}
+
 /**
  * Validate a single file path inside a skill directory.
  *
@@ -417,16 +434,17 @@ export function writeSkillDir(skill, options = {}) {
 
   const targets = placementTargetsFor(options);
 
-  // Pre-flight: if any target writes to .agents/skills/, ensure
-  // .gitignore is set up before starting any writes. A failure here
-  // is recoverable (user fixes their .gitignore and re-runs) because
-  // nothing has hit disk yet. A failure here AFTER a successful
-  // claudeProject write would leave the user with a half-applied
-  // state and an error message that doesn't reflect what's actually
-  // on disk.
-  if (targets.includes("agentsProject")) {
-    ensureAgentsGitignore();
-  }
+  // Pre-flight: if any target writes to a project-scope managed root
+  // (.claude/skills/, .agents/skills/), ensure the root's blanket
+  // ignore is present in the CLI's marked .gitignore section before
+  // starting any writes (#2361 — heal on every sync, both roots; the
+  // pre-4.10.0 code covered only .agents/skills/ under a separate
+  // header). A failure here is recoverable (user fixes their
+  // .gitignore and re-runs) because nothing has hit disk yet. A
+  // failure here AFTER a successful write to an earlier target would
+  // leave the user with a half-applied state and an error message
+  // that doesn't reflect what's actually on disk.
+  ensureProjectGitignore(targets);
 
   const written = [];
 
@@ -807,43 +825,25 @@ function writeSkillToDir(skill, targetDir) {
 }
 
 /**
- * Ensure `.agents/skills/` is gitignored. Idempotent — skips if the
- * entry is already present. Creates .gitignore if missing.
+ * Ensure every project-scope managed root in the write set has its
+ * blanket ignore inside the CLI's marked .gitignore section (#2361).
+ * Idempotent; also heals the retired pre-4.10.0 sync-time section.
+ * No-op for global-only write sets.
+ *
+ * `ensureManagedRootIgnores` throws typed diskErrors on read/write
+ * failure so a read-only or symlinked .gitignore surfaces as a
+ * user-visible error instead of silent data loss; the belt-and-
+ * suspenders wrap here only converts a non-CliError escape.
  *
- * Throws diskError on any write failure so a read-only or symlinked
- * .gitignore surfaces as a user-visible error instead of silent data
- * loss.
+ * @param {PlacementTarget[]} targets
  */
-function ensureAgentsGitignore() {
-  const filePath = gitignorePath();
-  let existing = null;
-  try {
-    existing = readFileSafe(filePath);
-  } catch (err) {
-    throw diskError(`Cannot read ${filePath}: ${err.message}`, {
-      cause: err,
-      hint:
-        `Update your .gitignore manually to add ${GITIGNORE_AGENTS_SKILLS_LINE} before re-running.`,
-    });
-  }
-
-  if (existing !== null && existing.includes(GITIGNORE_AGENTS_SKILLS_LINE)) {
-    return; // Already present — no-op
-  }
-
-  const newContent =
-    existing === null
-      ? `${GITIGNORE_SKILLS_HEADER}\n${GITIGNORE_AGENTS_SKILLS_LINE}\n`
-      : `${existing}${existing.endsWith("\n") ? "" : "\n"}\n${GITIGNORE_SKILLS_HEADER}\n${GITIGNORE_AGENTS_SKILLS_LINE}\n`;
-
+function ensureProjectGitignore(targets) {
   try {
-    writeFileSafe(filePath, newContent);
+    ensureManagedRootIgnores(targets);
   } catch (err) {
-    throw diskError(`Cannot update ${filePath}: ${err.message}`, {
+    if (err instanceof CliError) throw err;
+    throw diskError(`Cannot update ${gitignorePath()}: ${err.message}`, {
       cause: err,
-      hint:
-        `The CLI needs to add ${GITIGNORE_AGENTS_SKILLS_LINE} to .gitignore so library skills don't get committed. ` +
-        "Update .gitignore manually and re-run, or remove the read-only/symlinked constraint.",
     });
   }
 }