skillrepo 4.9.2 → 4.10.0

package/README.md

@@ -169,6 +169,20 @@ 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.
+
 ### `get` — fetch a single skill
 
 ```sh
@@ -543,9 +557,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.

package/package.json

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

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/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,10 +145,15 @@ 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")}`,
@@ -417,16 +419,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 +810,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.",
     });
   }
 }