skillrepo 2.0.0 → 3.1.0

package/src/lib/file-write.mjs

@@ -0,0 +1,705 @@
+/**
+ * Spec-compliant skill file-write pipeline (#681).
+ *
+ * Writes skill directories from server-returned skill payloads to per-vendor
+ * placement targets on disk. Path-preserving (Option B in the #646 plan):
+ * the file paths the server returns are written verbatim, so any references
+ * inside SKILL.md to supporting files continue to resolve. Layout
+ * conformance is the registry's concern (tracked in follow-up #874), not
+ * the CLI's.
+ *
+ * ── Design ─────────────────────────────────────────────────────────────
+ *
+ *   • Atomic update path on POSIX uses the .tmp / .old rename dance:
+ *
+ *       1. Populate <skill>.tmp/ with all files
+ *       2. If <skill>/ already exists, rename it to <skill>.old/
+ *       3. Rename <skill>.tmp/ to <skill>/
+ *       4. rm -rf <skill>.old/
+ *
+ *     A crash between any two steps leaves a recoverable state. The
+ *     `cleanupOrphans()` function called at the start of every write
+ *     command removes leftover .tmp/ and .old/ siblings.
+ *
+ *   • Windows is best-effort: fs.rename fails on existing destinations
+ *     and locked files. We fall back to direct-write semantics. A crash
+ *     mid-update on Windows can leave a partially-updated skill — the
+ *     next `update` run fully overwrites it.
+ *
+ *   • Safety checks (NOT layout enforcement):
+ *       - Path traversal (..) — rejected
+ *       - Absolute paths — rejected
+ *       - Depth > 5 — rejected (matches server MAX_PATH_DEPTH)
+ *       - Blocked extensions — rejected (matches server BLOCKED_EXTENSIONS)
+ *       - Skill name vs frontmatter `name` — must match
+ *
+ *   • Vendor placement: Claude Code uses .claude/skills/<name>/ (project)
+ *     or ~/.claude/skills/<name>/ (--global) per Anthropic's documented
+ *     convention. Other detected vendors without their own convention
+ *     fall back to <cwd>/skills/<name>/, with /skills/ added to .gitignore
+ *     on first creation. See follow-up #876.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  writeFileSync,
+  renameSync,
+  rmSync,
+  readdirSync,
+  statSync,
+} from "node:fs";
+import { dirname, join, isAbsolute, relative } from "node:path";
+import { platform } from "node:os";
+
+import { readFileSafe, writeFileSafe } from "./fs-utils.mjs";
+import {
+  claudeSkillsProject,
+  claudeSkillsGlobal,
+  projectSkillsFallback,
+  projectSkillsFallbackRoot,
+  claudeSkillsProjectRoot,
+  claudeSkillsGlobalRoot,
+  gitignorePath,
+} from "./paths.mjs";
+import { CliError, validationError, diskError } from "./errors.mjs";
+
+// ── Constants (mirror the server-side validators in src/lib/skills/) ────
+
+/** Max nesting depth for file paths — must stay in sync with src/lib/skills/constants.ts MAX_PATH_DEPTH. */
+export const MAX_PATH_DEPTH = 5;
+
+/**
+ * Blocked file extensions — must stay in sync with
+ * src/lib/skills/constants.ts BLOCKED_EXTENSIONS. Duplicated here
+ * because the CLI is a separate package that cannot import server-
+ * side TypeScript modules.
+ */
+export const BLOCKED_EXTENSIONS = new Set([
+  ".exe", ".dll", ".so", ".dylib", ".bin",
+  ".bat", ".cmd", ".com", ".msi", ".scr",
+  ".app", ".dmg", ".pkg", ".deb", ".rpm",
+  ".jar", ".war", ".class",
+  ".wasm",
+]);
+
+const GITIGNORE_SKILLS_LINE = "/skills/";
+const GITIGNORE_SKILLS_HEADER = "# SkillRepo (CLI-managed library skills)";
+
+// ── Types (JSDoc only — this is plain JS) ───────────────────────────────
+
+/**
+ * @typedef {Object} SkillFile
+ * @property {string} path - Relative path within the skill directory (e.g., "SKILL.md", "scripts/extract.py").
+ * @property {string} content - File content as a UTF-8 string (the CLI fetches via JSON; binary blobs out of scope for v3.0.0).
+ */
+
+/**
+ * @typedef {Object} Skill
+ * @property {string} owner - Account slug owning the skill.
+ * @property {string} name - Skill name (must match the directory name and SKILL.md frontmatter).
+ * @property {SkillFile[]} files - All files in the skill, including SKILL.md at index 0 (or anywhere — finder is by path).
+ */
+
+/**
+ * @typedef {"claudeProject" | "claudeGlobal" | "projectFallback"} PlacementTarget
+ */
+
+// ── Public API ──────────────────────────────────────────────────────────
+
+/**
+ * Validate a single file path inside a skill directory.
+ *
+ * Safety-only checks. Returns null for valid, or an error message string.
+ * Mirrors the server-side `validateFilePath` in `src/lib/skills/file-validation.ts`
+ * except we do NOT enforce a directory whitelist — the CLI is path-preserving.
+ *
+ * @param {string} rawPath
+ * @returns {string | null}
+ */
+export function validateFilePath(rawPath) {
+  // Decode URL-encoded characters before validation
+  let path;
+  try {
+    path = decodeURIComponent(rawPath);
+  } catch {
+    return `Invalid URL encoding in path "${rawPath}".`;
+  }
+
+  // Path traversal
+  if (path.includes("..")) {
+    return `Blocked path traversal in "${rawPath}".`;
+  }
+
+  // Absolute paths (POSIX or Windows drive letter)
+  if (path.startsWith("/") || /^[a-zA-Z]:/.test(path)) {
+    return `Blocked absolute path "${rawPath}".`;
+  }
+
+  // Depth check
+  if (path.split("/").length > MAX_PATH_DEPTH) {
+    return `Path "${rawPath}" exceeds maximum nesting depth of ${MAX_PATH_DEPTH}.`;
+  }
+
+  // Blocked extensions
+  const dotIdx = path.lastIndexOf(".");
+  const ext = dotIdx >= 0 ? path.substring(dotIdx).toLowerCase() : "";
+  if (BLOCKED_EXTENSIONS.has(ext)) {
+    return `Blocked file type "${ext}" in "${rawPath}".`;
+  }
+
+  return null;
+}
+
+/**
+ * Resolve the absolute filesystem directory for a skill at a given
+ * placement target. The directory does not need to exist yet.
+ *
+ * @param {PlacementTarget} target
+ * @param {string} skillName
+ * @returns {string}
+ */
+export function resolvePlacementDir(target, skillName) {
+  switch (target) {
+    case "claudeProject":
+      return claudeSkillsProject(skillName);
+    case "claudeGlobal":
+      return claudeSkillsGlobal(skillName);
+    case "projectFallback":
+      return projectSkillsFallback(skillName);
+    default: {
+      throw validationError(`Unknown placement target: ${target}`);
+    }
+  }
+}
+
+/**
+ * Compute the placement targets for a write based on detected/requested
+ * vendors and the --global flag.
+ *
+ * Rules:
+ *   - --global → only ["claudeGlobal"] (other vendors don't have a
+ *     documented global convention; we don't synthesize one)
+ *   - claudeCode in vendors → "claudeProject"
+ *   - any non-claudeCode vendor in vendors (cursor, windsurf, vscode)
+ *     → "projectFallback" (single fallback, deduped — multiple
+ *     non-claude vendors share the same fallback)
+ *
+ * @param {object} options
+ * @param {string[]} options.vendors - List of vendor keys (claudeCode, cursor, windsurf, vscode).
+ * @param {boolean} [options.global] - If true, write to personal/global Claude Code dir only.
+ * @returns {PlacementTarget[]}
+ */
+export function placementTargetsFor({ vendors, global = false }) {
+  if (global) {
+    return ["claudeGlobal"];
+  }
+
+  if (!Array.isArray(vendors) || vendors.length === 0) {
+    throw validationError(
+      "No vendors specified. Pass --ide claude (or another vendor) explicitly.",
+    );
+  }
+
+  const targets = [];
+  let needsFallback = false;
+  for (const vendor of vendors) {
+    if (vendor === "claudeCode") {
+      targets.push("claudeProject");
+    } else if (vendor === "cursor" || vendor === "windsurf" || vendor === "vscode") {
+      needsFallback = true;
+    } else {
+      throw validationError(`Unknown vendor: ${vendor}`);
+    }
+  }
+  if (needsFallback) {
+    targets.push("projectFallback");
+  }
+  return targets;
+}
+
+/**
+ * Find the SKILL.md file inside a skill's files array and return its
+ * frontmatter `name` value, or null if none could be parsed.
+ *
+ * Lightweight YAML frontmatter parser — looks for `---` fences and a
+ * `name:` line inside them. Sufficient for the spec-required `name`
+ * field; we don't attempt to parse arbitrary YAML.
+ *
+ * @param {SkillFile[]} files
+ * @returns {string | null}
+ */
+export function readFrontmatterName(files) {
+  const skillMd = files.find((f) => f.path === "SKILL.md");
+  if (!skillMd || typeof skillMd.content !== "string") return null;
+  const lines = skillMd.content.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") return null;
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === "---") return null; // end of frontmatter, no name
+    const m = line.match(/^name:\s*(.+?)\s*$/);
+    if (m) {
+      // Strip optional surrounding quotes
+      return m[1].replace(/^['"]|['"]$/g, "");
+    }
+  }
+  return null;
+}
+
+/**
+ * Write a single skill to all configured placement targets.
+ *
+ * Atomic on POSIX via the .tmp/.old rename dance. Best-effort on Windows.
+ *
+ * @param {Skill} skill
+ * @param {object} options
+ * @param {string[]} [options.vendors] - Vendor keys; required unless `global`.
+ * @param {boolean} [options.global] - If true, write to global Claude Code dir.
+ * @returns {{ written: string[] }} Per-target absolute directory paths.
+ *
+ * Note: `writeSkillDir` does NOT short-circuit when an existing skill on
+ * disk already matches the incoming payload. PR2's `sync.mjs` performs
+ * the change-detection (via SHAs from the server) and only invokes
+ * `writeSkillDir` for skills that genuinely changed. A future
+ * skip-if-unchanged enhancement at this layer would duplicate that work
+ * and require re-reading every file from disk.
+ *
+ * Pre-flight: `.gitignore` setup for the projectFallback target runs
+ * BEFORE any per-target write. This is intentional — running it inline
+ * inside the loop would let a read-only `.gitignore` failure abort the
+ * loop AFTER an earlier vendor (e.g., claudeCode) had already
+ * succeeded, leaving the user with partial state and a thrown error
+ * that lies about what was written. Failing the pre-flight aborts
+ * cleanly with NO disk writes performed.
+ */
+export function writeSkillDir(skill, options = {}) {
+  validateSkill(skill);
+
+  const targets = placementTargetsFor(options);
+
+  // Pre-flight: if any target requires the project /skills/ fallback,
+  // 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("projectFallback")) {
+    ensureFallbackGitignore();
+  }
+
+  const written = [];
+
+  for (const target of targets) {
+    const targetDir = resolvePlacementDir(target, skill.name);
+
+    try {
+      writeSkillToDir(skill, targetDir);
+      written.push(targetDir);
+    } catch (err) {
+      if (err instanceof CliError) throw err;
+      throw diskError(`Failed to write ${targetDir}: ${err.message}`, { cause: err });
+    }
+  }
+
+  return { written };
+}
+
+/**
+ * Remove a skill directory from all configured placement targets.
+ *
+ * Used by `remove` (direct local delete after a successful DELETE call)
+ * and by `update` when processing tombstones from the sync response.
+ *
+ * @param {string} skillName
+ * @param {object} options
+ * @param {string[]} [options.vendors]
+ * @param {boolean} [options.global]
+ * @returns {{ removed: string[], notFound: string[] }}
+ */
+export function removeSkillDir(skillName, options = {}) {
+  if (!isValidSkillName(skillName)) {
+    throw validationError(`Invalid skill name: "${skillName}"`);
+  }
+
+  const targets = placementTargetsFor(options);
+  const removed = [];
+  const notFound = [];
+
+  for (const target of targets) {
+    const targetDir = resolvePlacementDir(target, skillName);
+    if (!existsSync(targetDir)) {
+      notFound.push(targetDir);
+      continue;
+    }
+    try {
+      rmSync(targetDir, { recursive: true, force: true });
+      removed.push(targetDir);
+    } catch (err) {
+      throw diskError(`Failed to remove ${targetDir}: ${err.message}`, { cause: err });
+    }
+  }
+
+  return { removed, notFound };
+}
+
+/**
+ * Scan all configured placement roots and remove orphan .tmp/ and .old/
+ * directories left over from a crashed write. Called at the start of
+ * every write-flavored command (update, get, add, init).
+ *
+ * Safety invariants:
+ *
+ *   1. Only directories whose names end in `.tmp` or `.old` are
+ *      considered. Spec-valid skill names cannot end with these
+ *      suffixes because `isValidSkillName` rejects any name containing
+ *      `.`, so a legitimate skill never collides with the orphan
+ *      pattern. This is invisible at the call site, so it's
+ *      load-bearing for safety: if the spec ever relaxed the name
+ *      regex, this function would need a stricter check.
+ *
+ *   2. A `.tmp/` whose corresponding live target does NOT exist is
+ *      preserved, NOT deleted. This protects the Windows recovery
+ *      path: when `rmSync(targetDir)` succeeded but `renameSync(tmpDir,
+ *      targetDir)` failed, the user's only copy of the skill is in
+ *      `<name>.tmp/`. Deleting it here would compound the data loss.
+ *      The user has to manually rename it (the disk error from
+ *      writeSkillToDir tells them how).
+ *
+ *   3. `.old/` directories are always cleanable — they only exist as
+ *      transient state during a successful or failed rename dance, and
+ *      the live target is the authoritative source.
+ *
+ * Idempotent: safe to call when no orphans exist.
+ *
+ * @param {object} options
+ * @param {string[]} [options.vendors]
+ * @param {boolean} [options.global]
+ * @returns {{ cleaned: string[] }}
+ */
+export function cleanupOrphans(options = {}) {
+  const roots = [];
+  if (options.global) {
+    roots.push(claudeSkillsGlobalRoot());
+  } else {
+    if (Array.isArray(options.vendors) && options.vendors.length > 0) {
+      if (options.vendors.includes("claudeCode")) {
+        roots.push(claudeSkillsProjectRoot());
+      }
+      if (
+        options.vendors.includes("cursor") ||
+        options.vendors.includes("windsurf") ||
+        options.vendors.includes("vscode")
+      ) {
+        roots.push(projectSkillsFallbackRoot());
+      }
+    } else {
+      // No vendors specified — clean everything we know about.
+      roots.push(claudeSkillsProjectRoot());
+      roots.push(projectSkillsFallbackRoot());
+      roots.push(claudeSkillsGlobalRoot());
+    }
+  }
+
+  const cleaned = [];
+  for (const root of roots) {
+    if (!existsSync(root)) continue;
+    let entries;
+    try {
+      entries = readdirSync(root);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!(entry.endsWith(".tmp") || entry.endsWith(".old"))) continue;
+
+      const orphanPath = join(root, entry);
+      let st;
+      try {
+        st = statSync(orphanPath);
+      } catch {
+        continue; // Orphan vanished mid-iteration
+      }
+      if (!st.isDirectory()) continue;
+
+      // Invariant #2: preserve a .tmp/ whose live target is missing —
+      // it is the user's only copy of a skill that crashed mid-rename.
+      if (entry.endsWith(".tmp")) {
+        const liveTarget = join(root, entry.slice(0, -".tmp".length));
+        if (!existsSync(liveTarget)) {
+          // Recoverable orphan — leave it alone so the user can rename
+          // it manually per the diskError hint from writeSkillToDir.
+          continue;
+        }
+      }
+
+      try {
+        rmSync(orphanPath, { recursive: true, force: true });
+        cleaned.push(orphanPath);
+      } catch {
+        // Best-effort — a locked file or permission error here is not
+        // fatal. The next run will retry.
+      }
+    }
+  }
+  return { cleaned };
+}
+
+// ── Internals ───────────────────────────────────────────────────────────
+
+/**
+ * Validate that a skill name is well-formed per the agentskills.io spec.
+ * Lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens, 1-64 chars.
+ */
+export function isValidSkillName(name) {
+  if (typeof name !== "string" || name.length === 0 || name.length > 64) return false;
+  if (!/^[a-z0-9-]+$/.test(name)) return false;
+  if (name.startsWith("-") || name.endsWith("-")) return false;
+  if (name.includes("--")) return false;
+  return true;
+}
+
+/**
+ * Validate the entire skill payload before any disk work. Throws CliError
+ * on first violation so the caller can map to an exit code.
+ */
+function validateSkill(skill) {
+  if (!skill || typeof skill !== "object") {
+    throw validationError("Skill payload is missing or not an object");
+  }
+  if (!isValidSkillName(skill.name)) {
+    throw validationError(`Invalid skill name: "${skill.name}"`);
+  }
+  if (typeof skill.owner !== "string" || skill.owner.length === 0) {
+    throw validationError(`Skill "${skill.name}" is missing an owner`);
+  }
+  if (!Array.isArray(skill.files) || skill.files.length === 0) {
+    throw validationError(`Skill "${skill.owner}/${skill.name}" has no files`);
+  }
+
+  // Spec compliance: SKILL.md must exist at the root
+  const hasSkillMd = skill.files.some((f) => f.path === "SKILL.md");
+  if (!hasSkillMd) {
+    throw validationError(
+      `Skill "${skill.owner}/${skill.name}" is missing a SKILL.md at the root (agentskills.io spec)`,
+    );
+  }
+
+  // Spec compliance: frontmatter `name` must match the skill's name
+  const frontmatterName = readFrontmatterName(skill.files);
+  if (frontmatterName !== null && frontmatterName !== skill.name) {
+    throw validationError(
+      `Skill "${skill.owner}/${skill.name}" has a SKILL.md frontmatter ` +
+        `name "${frontmatterName}" that does not match the parent directory name. ` +
+        `This violates the agentskills.io spec.`,
+    );
+  }
+
+  // Per-file safety checks
+  const seenPaths = new Set();
+  for (const file of skill.files) {
+    if (!file || typeof file.path !== "string") {
+      throw validationError(`Skill "${skill.owner}/${skill.name}" has a file with no path`);
+    }
+    const err = validateFilePath(file.path);
+    if (err) {
+      throw validationError(`Skill "${skill.owner}/${skill.name}": ${err}`);
+    }
+    if (seenPaths.has(file.path)) {
+      throw validationError(
+        `Skill "${skill.owner}/${skill.name}" has duplicate file path "${file.path}"`,
+      );
+    }
+    seenPaths.add(file.path);
+    if (typeof file.content !== "string") {
+      throw validationError(
+        `Skill "${skill.owner}/${skill.name}" file "${file.path}" has non-string content (binary blobs are not supported in v3.0.0)`,
+      );
+    }
+  }
+}
+
+/**
+ * Write a skill to a single target directory using the atomic dance.
+ *
+ * Throws CliError (specifically diskError) on every failure path so the
+ * caller can rely on the exit code without re-wrapping. Callers MAY
+ * still wrap to enrich the message with the per-target context, but the
+ * exit code is correct from this function alone.
+ */
+function writeSkillToDir(skill, targetDir) {
+  const tmpDir = `${targetDir}.tmp`;
+  const oldDir = `${targetDir}.old`;
+
+  // Pre-flight: clean any stale .tmp from a previous crash
+  if (existsSync(tmpDir)) {
+    try {
+      rmSync(tmpDir, { recursive: true, force: true });
+    } catch (err) {
+      throw diskError(`Cannot remove stale ${tmpDir}: ${err.message}`, { cause: err });
+    }
+  }
+
+  // 1. Populate <name>.tmp/
+  try {
+    mkdirSync(tmpDir, { recursive: true });
+  } catch (err) {
+    throw diskError(`Cannot create ${tmpDir}: ${err.message}`, { cause: err });
+  }
+  for (const file of skill.files) {
+    const filePath = join(tmpDir, file.path);
+    // Defense in depth: confirm the resolved path is still inside tmpDir.
+    // validateFilePath already rejected `..` and absolute paths, but a
+    // race or symlink could in principle defeat that check.
+    const rel = relative(tmpDir, filePath);
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+      throw diskError(`Refusing to write outside skill directory: ${file.path}`);
+    }
+    try {
+      mkdirSync(dirname(filePath), { recursive: true });
+      writeFileSync(filePath, file.content, "utf-8");
+    } catch (err) {
+      throw diskError(`Cannot write ${filePath}: ${err.message}`, { cause: err });
+    }
+  }
+
+  // 2 + 3 + 4: rename dance (POSIX atomic on same filesystem; best-effort on Windows)
+  if (platform() === "win32") {
+    // Windows: rename fails on existing destinations and locked files,
+    // so we fall back to remove-then-rename. There is a window where
+    // the live target is gone but the rename has not yet completed.
+    // If the rename fails (e.g., file lock from an IDE indexer scan),
+    // we surface a SPECIFIC disk error pointing the user at the .tmp/
+    // directory so they can recover manually. The cleanup-orphans
+    // function will NOT delete a `.tmp/` whose live target is missing
+    // — it only deletes `.tmp/` siblings whose live target also exists,
+    // so the user's data is preserved on disk.
+    if (existsSync(targetDir)) {
+      try {
+        rmSync(targetDir, { recursive: true, force: true });
+      } catch (err) {
+        // Live target still exists — .tmp/ is fine to clean later
+        try { rmSync(tmpDir, { recursive: true, force: true }); } catch { /* best-effort */ }
+        throw diskError(
+          `Cannot replace existing ${targetDir} on Windows: ${err.message}`,
+          { cause: err, hint: "A file in that directory may be locked by another process." },
+        );
+      }
+    }
+    try {
+      renameSync(tmpDir, targetDir);
+    } catch (err) {
+      throw diskError(
+        `Skill files were prepared at ${tmpDir} but the final rename to ${targetDir} failed: ${err.message}`,
+        {
+          cause: err,
+          hint:
+            `The skill files are recoverable at ${tmpDir} — rename it to ${targetDir} manually. ` +
+            `cleanupOrphans() will NOT delete this directory while the live target is missing.`,
+        },
+      );
+    }
+    return;
+  }
+
+  // POSIX path
+  if (existsSync(targetDir)) {
+    // Step 2: move existing target out of the way
+    if (existsSync(oldDir)) {
+      // Stale .old from a previous crash — clean it first
+      try {
+        rmSync(oldDir, { recursive: true, force: true });
+      } catch (err) {
+        throw diskError(`Cannot remove stale ${oldDir}: ${err.message}`, { cause: err });
+      }
+    }
+    try {
+      renameSync(targetDir, oldDir);
+    } catch (err) {
+      throw diskError(`Cannot stage existing ${targetDir} for replacement: ${err.message}`, { cause: err });
+    }
+  }
+
+  // Step 3: rename tmp into place (atomic)
+  try {
+    renameSync(tmpDir, targetDir);
+  } catch (err) {
+    // Rollback: restore the old directory if we can. Either way, throw
+    // a typed diskError with the specifics so the caller never sees a
+    // raw OS error escape this function.
+    let rollbackOk = false;
+    if (existsSync(oldDir)) {
+      try {
+        renameSync(oldDir, targetDir);
+        rollbackOk = true;
+      } catch {
+        // Both rename attempts failed — fall through to throw below
+      }
+    }
+    throw diskError(
+      `Failed to install ${targetDir}: ${err.message}` +
+        (rollbackOk
+          ? ` (previous version restored from ${oldDir})`
+          : ` and rollback from ${oldDir} also failed — manual recovery required`),
+      { cause: err },
+    );
+  }
+
+  // Step 4: clean up the old directory
+  if (existsSync(oldDir)) {
+    try {
+      rmSync(oldDir, { recursive: true, force: true });
+    } catch (err) {
+      // Non-fatal: the new skill is in place; the .old dir is stale
+      // state that cleanupOrphans() will sweep on the next run. We log
+      // this via process.stderr so a user who cares can see it.
+      process.stderr.write(
+        `  warning: leftover ${oldDir} could not be removed (${err.message}). ` +
+          `Will be cleaned on the next run.\n`,
+      );
+    }
+  }
+}
+
+/**
+ * Ensure the project /skills/ directory is gitignored. Idempotent —
+ * skips if the entry is already present. Creates .gitignore if missing.
+ *
+ * Throws diskError on any write failure so a read-only or symlinked
+ * .gitignore surfaces as a user-visible error instead of silent data
+ * loss. This is the explicit fix for the architect's PR1 review item:
+ * `writeFileSafe` was previously called without a try/catch and a
+ * failing write would leave the user with skills on disk but no
+ * .gitignore protection — the next `git add` would commit them.
+ */
+function ensureFallbackGitignore() {
+  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 /skills/ before re-running.",
+    });
+  }
+
+  if (existing !== null && existing.includes(GITIGNORE_SKILLS_LINE)) {
+    return; // Already present — no-op
+  }
+
+  const newContent =
+    existing === null
+      ? `${GITIGNORE_SKILLS_HEADER}\n${GITIGNORE_SKILLS_LINE}\n`
+      : `${existing}${existing.endsWith("\n") ? "" : "\n"}\n${GITIGNORE_SKILLS_HEADER}\n${GITIGNORE_SKILLS_LINE}\n`;
+
+  try {
+    writeFileSafe(filePath, newContent);
+  } catch (err) {
+    throw diskError(`Cannot update ${filePath}: ${err.message}`, {
+      cause: err,
+      hint:
+        "The CLI needs to add /skills/ to .gitignore so library skills don't get committed. " +
+        "Update .gitignore manually and re-run, or remove the read-only/symlinked constraint.",
+    });
+  }
+}