skillrepo 4.9.2 → 4.10.0

package/src/lib/mergers/gitignore.mjs

@@ -1,8 +1,8 @@
 /**
- * Merger for .gitignore — adds the paths `skillrepo init` writes that
- * must not be committed.
+ * Merger for .gitignore — the init-facing entry point over the CLI's
+ * single marked section (core writer: `../gitignore-section.mjs`).
  *
- * Always added:
+ * Always added by `skillrepo init`:
  *   - `.env.local` — contains SKILLREPO_ACCESS_KEY, a live credential
  *   - `.claude/settings.local.json` — Claude Code per-user settings
  *
@@ -10,16 +10,20 @@
  *   - `.claude/skills/` — when any vendor maps to `claudeProject`
  *   - `.agents/skills/` — when any vendor maps to `agentsProject`
  *
- * Idempotent: entries already present are skipped. A single call
- * either adds all missing entries in one grouped section or exits
- * without writing if they're all already present.
+ * The sync-time pre-flight (`file-write.mjs`) manages the managed-root
+ * entries through the same core, so every CLI-authored gitignore line
+ * lives in the one marked section the uninstall remover strips (#2361).
+ *
+ * Idempotent: entries already present are skipped; a legacy sync-time
+ * section is healed into the marked section as a side effect.
  */
 
-import { readFileSafe, writeFileSafe } from "../fs-utils.mjs";
-import { gitignorePath } from "../paths.mjs";
 import { placementTargetsFor } from "../file-write.mjs";
+import {
+  ensureGitignoreEntries,
+  MANAGED_ROOT_ENTRIES,
+} from "../gitignore-section.mjs";
 
-const SECTION_HEADER = "# SkillRepo CLI (added by `skillrepo init`)";
 const ALWAYS_ENTRIES = Object.freeze([
   ".env.local",
   ".claude/settings.local.json",
@@ -38,7 +42,7 @@ const ALWAYS_ENTRIES = Object.freeze([
 function entriesFor(options) {
   const entries = [...ALWAYS_ENTRIES];
   if (!Array.isArray(options.vendors) || options.vendors.length === 0) {
-    entries.push(".claude/skills/");
+    entries.push(MANAGED_ROOT_ENTRIES.claudeProject);
     return entries;
   }
   let targets;
@@ -50,72 +54,25 @@ function entriesFor(options) {
   } catch {
     // Caller passed an unknown vendor; fall back to the always-set
     // entries plus `.claude/skills/` so we never under-protect.
-    entries.push(".claude/skills/");
+    entries.push(MANAGED_ROOT_ENTRIES.claudeProject);
     return entries;
   }
-  if (targets.includes("claudeProject")) entries.push(".claude/skills/");
-  if (targets.includes("agentsProject")) entries.push(".agents/skills/");
+  for (const [target, entry] of Object.entries(MANAGED_ROOT_ENTRIES)) {
+    if (targets.includes(target)) entries.push(entry);
+  }
   return entries;
 }
 
 /**
  * Ensure the init-required paths are in .gitignore. Creates the file
  * if it doesn't exist. Idempotent — returns `"skipped"` if every
- * required entry is already present, `"created"` if the file didn't
- * exist, `"updated"` if it did and at least one entry was missing.
+ * required entry is already present and no legacy section needed
+ * healing, `"created"` if the file didn't exist, `"updated"` if it did
+ * and at least one entry was missing (or a legacy section was healed).
  *
  * @param {{ vendors?: string[], global?: boolean }} [options]
  * @returns {{ path: string; action: "created" | "updated" | "skipped"; added: string[] }}
  */
 export function mergeGitignore(options = {}) {
-  const requiredEntries = entriesFor(options);
-  const filePath = gitignorePath();
-  const existing = readFileSafe(filePath);
-
-  if (existing === null) {
-    // Fresh .gitignore — write all required entries as one section.
-    const content = renderSection(requiredEntries);
-    writeFileSafe(filePath, content);
-    return {
-      path: ".gitignore",
-      action: "created",
-      added: [...requiredEntries],
-    };
-  }
-
-  // Line-exact match check. `.env.local` as a line is distinct from
-  // `.env.local.backup` or a comment `# .env.local` — split on
-  // newlines and trim so we match the entry literally.
-  const lines = existing.split(/\r?\n/).map((l) => l.trim());
-  const missing = requiredEntries.filter((entry) => !lines.includes(entry));
-
-  if (missing.length === 0) {
-    return {
-      path: ".gitignore",
-      action: "skipped",
-      added: [],
-    };
-  }
-
-  // Append only the missing entries as a new section. Preserve the
-  // original line-ending style.
-  const lineEnding = existing.includes("\r\n") ? "\r\n" : "\n";
-  const separator = existing.endsWith("\n") ? "" : lineEnding;
-  const block = renderSection(missing, lineEnding);
-  writeFileSafe(filePath, existing + separator + lineEnding + block);
-
-  return {
-    path: ".gitignore",
-    action: "updated",
-    added: missing,
-  };
-}
-
-/**
- * Render the SkillRepo section with the given entries. The leading
- * blank line separates the section from whatever precedes it when
- * appending, and the trailing newline keeps the file POSIX-clean.
- */
-function renderSection(entries, lineEnding = "\n") {
-  return SECTION_HEADER + lineEnding + entries.join(lineEnding) + lineEnding;
+  return ensureGitignoreEntries(entriesFor(options));
 }

package/src/lib/paths.mjs

@@ -38,6 +38,17 @@ export const globalLastSyncPath = () => join(homedir(), ".claude", "skillrepo",
 export const globalNpmVersionCheckPath = () =>
   join(homedir(), ".claude", "skillrepo", ".npm-version-check");
 
+/**
+ * Governance warn-on-new state (#2361 owner directive): which unmanaged
+ * dirs (per placement root) and gitignored declarations (per repo) the
+ * CLI has already warned about. Separate file from `.last-sync` —
+ * different concern (what the USER was told vs. library content state)
+ * and a schema bump in one must not gate the other. Same parent dir so
+ * uninstall's whole-directory removal covers it.
+ */
+export const globalGovernanceSeenPath = () =>
+  join(homedir(), ".claude", "skillrepo", ".governance-seen");
+
 // ── Skill placement targets ────────────────────────────────────────────
 //
 // Per-vendor placement decisions live in `agent-registry.mjs`. This

package/src/lib/removers/gitignore.mjs

@@ -22,7 +22,10 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { writeFileAtomic } from "../fs-utils.mjs";
-import { GITIGNORE_SECTION_HEADER } from "../artifact-registry.mjs";
+import {
+  GITIGNORE_SECTION_HEADER,
+  LEGACY_GITIGNORE_SECTION_HEADER,
+} from "../artifact-registry.mjs";
 import { gitignorePath } from "../paths.mjs";
 
 /**
@@ -50,10 +53,41 @@ export function removeGitignore({ dryRun = false } = {}) {
   // stays CRLF. `split(/\r?\n/)` discards the line-ending bytes, so
   // we detect them explicitly and rebuild on that basis.
   const lineEnding = original.includes("\r\n") ? "\r\n" : "\n";
-  const lines = original.split(/\r?\n/);
+  let lines = original.split(/\r?\n/);
+
+  // Legacy sync-time section (#2361): pre-4.10.0 syncs wrote
+  // `.agents/skills/` under its own header, outside the marked
+  // section. If the merger's heal never ran (user uninstalls without
+  // syncing on 4.10.0+), strip the attributable shape here: the
+  // header line plus a directly-following `.agents/skills/` line.
+  // Any other line under the legacy header is user content and
+  // survives.
+  let legacyRemoved = 0;
+  const legacyIdx = lines.findIndex(
+    (l) => l === LEGACY_GITIGNORE_SECTION_HEADER,
+  );
+  if (legacyIdx !== -1) {
+    let legacyEnd = legacyIdx + 1;
+    if (legacyEnd < lines.length && lines[legacyEnd] === ".agents/skills/") {
+      legacyEnd += 1;
+    }
+    legacyRemoved = legacyEnd - legacyIdx;
+    lines = [...lines.slice(0, legacyIdx), ...lines.slice(legacyEnd)];
+  }
 
   const headerIdx = lines.findIndex((l) => l === GITIGNORE_SECTION_HEADER);
   if (headerIdx === -1) {
+    if (legacyRemoved > 0) {
+      if (dryRun) {
+        return {
+          path: ".gitignore",
+          action: "would-remove",
+          removed: legacyRemoved,
+        };
+      }
+      writeFileAtomic(filePath, lines.join(lineEnding));
+      return { path: ".gitignore", action: "removed", removed: legacyRemoved };
+    }
     return { path: ".gitignore", action: "skipped", removed: 0 };
   }
 
@@ -89,7 +123,8 @@ export function removeGitignore({ dryRun = false } = {}) {
   // ? 1 : 0)` gives the SkillRepo-line count.
   const consumedTrailingBlank =
     end > headerIdx + 1 && lines[end - 1] === "";
-  const reportedRemoved = removedLines - (consumedTrailingBlank ? 1 : 0);
+  const reportedRemoved =
+    removedLines - (consumedTrailingBlank ? 1 : 0) + legacyRemoved;
 
   if (dryRun) {
     return {

package/src/lib/sync.mjs

@@ -99,6 +99,18 @@
  *                                   Consumers must distinguish these to
  *                                   render accurate user messages (see
  *                                   init.mjs step 7).
+ * @property {number} [unmanaged] - Unmanaged (non-CLI-managed) skill dirs
+ *                                   detected in the managed placement roots
+ *                                   this sync writes to (#2361). "unmanaged"
+ *                                   is the one wire word for this concept —
+ *                                   same as the receipts category and the
+ *                                   warning copy; the design doc's internal
+ *                                   term is "foreign content". Warn-only
+ *                                   observability — NOT part of the change
+ *                                   totals the hook printers gate on, so a
+ *                                   304 with unmanaged content stays silent
+ *                                   in hook modes. Absent on a throttled
+ *                                   skip (detection doesn't run there).
  * @property {string} syncedAt    - ISO timestamp of the sync: the server
  *                                   response `syncedAt` on a 200, or the
  *                                   previously-cached sync timestamp on a
@@ -152,6 +164,16 @@ import {
   EXIT_VALIDATION,
 } from "./errors.mjs";
 import { computeSkillShas } from "./crypto-shas.mjs";
+import {
+  scanForeignContent,
+  formatForeignWarnings,
+  checkDeclarationGitignored,
+  formatDeclarationIgnoredWarning,
+  readGovernanceSeen,
+  commitGovernanceSeen,
+  selectNewFindings,
+  normalizeStateKey,
+} from "./foreign-content.mjs";
 
 /**
  * Current schema version of the .last-sync file. Bump on any
@@ -913,12 +935,26 @@ export async function runSync(options) {
           `Next sync will not be throttled.\n`,
       );
     }
+    // Foreign-content detection runs on the 304 path too (#2361): the
+    // library being unchanged says nothing about what else sits in the
+    // managed roots, and a deliberately-stable library would otherwise
+    // never surface violations. The on-disk managed set on a 304 is
+    // exactly the prior `.last-sync` skills map.
+    const unmanaged = emitGovernanceWarnings({
+      vendors,
+      global,
+      managedSkills: lastSync?.skills,
+      stderr,
+      hookMode: throttle === true,
+    });
+
     return {
       added: 0,
       updated: 0,
       removed: 0,
       notModified: true,
       fullSync,
+      unmanaged,
       syncedAt: lastSync?.syncedAt ?? new Date().toISOString(),
     };
   }
@@ -1130,6 +1166,17 @@ export async function runSync(options) {
     }
   }
 
+  // Foreign-content detection (#2361): after writes and tombstones, so
+  // skills delivered THIS round are already in `skillsMap` and never
+  // misclassified as unmanaged. Warn-only; never affects the sync result.
+  summary.unmanaged = emitGovernanceWarnings({
+    vendors,
+    global,
+    managedSkills: skillsMap,
+    stderr,
+    hookMode: throttle === true,
+  });
+
   // Re-assert the full on-disk state via a sync receipt (#1832). This
   // confirmed-write signal — not the fetch itself — is what sets team
   // sync state. We post the COMPLETE post-sync on-disk set (`skillsMap`:
@@ -1157,6 +1204,76 @@ export async function runSync(options) {
 
 // ── Internals ──────────────────────────────────────────────────────────
 
+/**
+ * Run the sync-time governance checks and write their warnings to the
+ * caller's stderr (#2361): foreign-content detection over the managed
+ * roots this sync writes to, plus the gitignored-declaration probe.
+ * Returns the unmanaged-dir count for the summary.
+ *
+ * Warn-only by construction — never throws, never changes sync
+ * behavior. Foreign dir NAMES appear only in these local warning
+ * lines; anything that leaves the machine goes through
+ * `receiptViolationSummary` (counts/category only — the H7 #2364
+ * seam; see foreign-content.mjs for the privacy contract).
+ *
+ * WARN-ON-NEW (owner directive, 2026-08-07): a warning that repeats
+ * unchanged findings on every sync trains users to ignore it. The
+ * already-warned set persists in `.governance-seen`; only NEW findings
+ * print, and a removed-then-reappearing dir re-warns. The returned
+ * count is always the TOTAL currently on disk (state observability),
+ * not just the new ones.
+ *
+ * HOOK SYNCS (`hookMode: true` — the --session-hook / --silent
+ * branches) neither print warnings nor mark findings as seen: the
+ * user isn't looking at those streams, and recording seen there would
+ * permanently swallow the warning before an interactive sync ever
+ * showed it. Governance warnings are an interactive-surface feature;
+ * hook syncs still contribute the count. The throttled early-exit
+ * returns before this runs at all (zero-work contract).
+ *
+ * @param {object} options
+ * @param {string[]} [options.vendors]
+ * @param {boolean} [options.global]
+ * @param {Record<string, unknown> | null | undefined} options.managedSkills
+ * @param {NodeJS.WritableStream} options.stderr
+ * @param {boolean} [options.hookMode] - True for hook-triggered syncs.
+ * @returns {number} Unmanaged-dir count across scanned roots (the
+ *          summary's `unmanaged` field — total, not just new).
+ */
+function emitGovernanceWarnings({ vendors, global, managedSkills, stderr, hookMode }) {
+  let unmanagedCount = 0;
+  try {
+    const scan = scanForeignContent({ vendors, global, managedSkills });
+    unmanagedCount = scan.foreignCount;
+    if (hookMode) return unmanagedCount;
+
+    const seen = readGovernanceSeen();
+    const newScan = selectNewFindings(scan, seen);
+    for (const line of formatForeignWarnings(newScan)) {
+      stderr.write(`${line}\n`);
+    }
+
+    // Gitignored-declaration warning, gated the same way: once per
+    // repo while the state holds; leaving the gitignored state re-arms
+    // it. Keyed by the NORMALIZED repo path (realpath + win32
+    // case-fold) so two spellings of one checkout share a flag.
+    const repoKey = normalizeStateKey(process.cwd());
+    const decl = checkDeclarationGitignored();
+    const declarationIgnored = decl.present && decl.ignored;
+    if (declarationIgnored && !seen.declarations[repoKey]) {
+      stderr.write(`${formatDeclarationIgnoredWarning()}\n`);
+    }
+
+    // Narrow-merge commit: re-reads the file and rewrites ONLY this
+    // sync's scanned roots + this repo's declaration flag, so a
+    // concurrent sync in another repo keeps its update.
+    commitGovernanceSeen({ scan, repoKey, declarationIgnored });
+  } catch {
+    // Detection is best-effort; a probe failure must never fail a sync.
+  }
+  return unmanagedCount;
+}
+
 /**
  * Build sync-receipt entries from a `.last-sync` skills map (#1832).
  *

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

@@ -261,6 +261,25 @@ describe("runUpdate — --session-hook contract", () => {
     );
   });
 
+  it("stays silent on a zero-change sync even when foreign content is present (#2361)", async () => {
+    // Foreign dirs are observability, not changes: the hook-mode
+    // output gate keys on added+updated+removed+skipped, and the
+    // foreign count must never trip it. Both streams are black-holed
+    // in this mode, so the warning lines vanish too — session start
+    // stays clean.
+    const { mkdirSync, writeFileSync } = await import("node:fs");
+    const { join } = await import("node:path");
+    const dir = join(process.cwd(), ".claude", "skills", "hand-rolled");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "SKILL.md"), "---\nname: hand-rolled\n---\n");
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+      { stdout },
+    );
+    assert.equal(stdout.text(), "", "foreign content must not break hook silence");
+  });
+
   it("is silent on 304 / up-to-date (no 'Syncing' output every session)", async () => {
     // INTENT: 304 means nothing changed. Printing "Syncing..." on
     // every session start with no value to show would clutter the
@@ -473,6 +492,38 @@ describe("runUpdate — --silent contract", () => {
     assert.equal(stdout.text(), "{}\n");
   });
 
+  it("emits no governance warning under --silent, and does not consume it (#2361)", async () => {
+    // Governance warnings are an interactive-surface feature: hook
+    // syncs print nothing (the user is not looking at vendor hook
+    // logs) and must NOT mark the finding as seen — the next
+    // interactive `update` is the first to warn. Stdout stays pure
+    // JSON either way (Gemini contract).
+    const { mkdirSync, writeFileSync } = await import("node:fs");
+    const { join } = await import("node:path");
+    const { createCaptureStream } = await import("../helpers/capture-stream.mjs");
+    const dir = join(process.cwd(), ".claude", "skills", "hand-rolled");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "SKILL.md"), "---\nname: hand-rolled\n---\n");
+    const stderr = createCaptureStream();
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--silent"],
+      { stdout, stderr },
+    );
+    assert.equal(stdout.text(), "{}\n", "stdout must stay pure JSON");
+    assert.ok(!stderr.text().includes("not from your library"), "hook sync must not warn");
+
+    // Interactive update afterwards: the warning is still available.
+    const stdout2 = createCaptureStream();
+    const stderr2 = createCaptureStream();
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl],
+      { stdout: stdout2, stderr: stderr2 },
+    );
+    assert.match(stderr2.text(), /hand-rolled/);
+    assert.match(stderr2.text(), /skillrepo push/);
+  });
+
   it("emits `{}\\n` even when the sync produced changes (no progress lines on stdout)", async () => {
     server.setLibraryResponse({
       skills: [makeSkill("silent-test")],

package/src/test/e2e/cli-commands.test.mjs

@@ -122,6 +122,69 @@ describe("CLI E2E — read commands", () => {
     assert.match(r.stdout, /up to date/);
   });
 
+  it("update warns about a foreign skill dir on stderr and exits 0 (#2361)", async () => {
+    const { writeFileSync } = await import("node:fs");
+    // Hand-authored dir the CLI never wrote — a governance violation,
+    // surfaced but never touched.
+    mkdirSync(join(tempDir, ".claude", "skills", "hand-rolled"), { recursive: true });
+    writeFileSync(
+      join(tempDir, ".claude", "skills", "hand-rolled", "SKILL.md"),
+      "---\nname: hand-rolled\n---\n",
+    );
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "pdf-helper")],
+      removals: [],
+      syncedAt: "x",
+    });
+    const r = await runCli([
+      "update",
+      "--key", VALID_KEY,
+      "--url", `http://127.0.0.1:${port}`,
+    ]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.match(r.stderr, /is not from your library/);
+    assert.match(r.stderr, /skillrepo push/);
+    assert.match(r.stderr, /\.claude\/skills\/hand-rolled\//);
+    // The foreign dir is surfaced, never destroyed.
+    assert.ok(existsSync(join(tempDir, ".claude", "skills", "hand-rolled", "SKILL.md")));
+    // The synced skill is managed — not warned about.
+    assert.ok(!r.stderr.includes("pdf-helper"));
+
+    // Warn-on-new: an identical second run repeats nothing.
+    const r2 = await runCli([
+      "update",
+      "--key", VALID_KEY,
+      "--url", `http://127.0.0.1:${port}`,
+    ]);
+    assert.equal(r2.status, 0, `stderr: ${r2.stderr}`);
+    assert.ok(
+      !r2.stderr.includes("hand-rolled"),
+      "unchanged finding must not re-warn on the next run",
+    );
+  });
+
+  it("update --json carries the unmanaged count (#2361)", async () => {
+    const { writeFileSync } = await import("node:fs");
+    mkdirSync(join(tempDir, ".claude", "skills", "rogue"), { recursive: true });
+    writeFileSync(
+      join(tempDir, ".claude", "skills", "rogue", "SKILL.md"),
+      "---\nname: rogue\n---\n",
+    );
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "pdf-helper")],
+      removals: [],
+      syncedAt: "x",
+    });
+    const r = await runCli([
+      "update", "--json",
+      "--key", VALID_KEY,
+      "--url", `http://127.0.0.1:${port}`,
+    ]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    const json = JSON.parse(r.stdout);
+    assert.equal(json.unmanaged, 1);
+  });
+
   it("update writes a single skill and prints the summary", async () => {
     server.setLibraryResponse({
       skills: [makeSkill("alice", "pdf-helper")],

package/src/test/lib/file-write.test.mjs

@@ -956,7 +956,7 @@ describe("ensureFallbackGitignore — error surfacing", () => {
   });
 
   it("throws diskError when .gitignore cannot be READ (it is a directory → EISDIR)", () => {
-    // The read-error branch in ensureAgentsGitignore: readFileSafe
+    // The read-error branch in the gitignore-section core: readFileSafe
     // re-throws any non-ENOENT error. Making `.gitignore` a DIRECTORY
     // causes readFileSync to throw EISDIR, which surfaces as a typed
     // diskError with a "Cannot read" message before any write is