skillrepo 2.0.0 → 3.0.0

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

@@ -0,0 +1,784 @@
+/**
+ * Unit tests for src/lib/file-write.mjs (PR1 of #646).
+ *
+ * Covers:
+ *  - Path validation (safety only — no layout enforcement)
+ *  - Skill name validation
+ *  - Frontmatter name parsing
+ *  - Placement target resolution
+ *  - placementTargetsFor() decision logic
+ *  - validateSkill rejection paths via writeSkillDir
+ *  - writeSkillDir + readback (path-preserving via lib/helper.py)
+ *  - Update path (atomic POSIX dance)
+ *  - removeSkillDir
+ *  - cleanupOrphans
+ *  - .gitignore management for the project /skills/ fallback
+ *
+ * Each test uses a temp cwd and HOME so vendor placement targets resolve
+ * to throwaway directories.
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  rmSync,
+  mkdirSync,
+  writeFileSync,
+  existsSync,
+  readFileSync,
+  chmodSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  validateFilePath,
+  isValidSkillName,
+  readFrontmatterName,
+  resolvePlacementDir,
+  placementTargetsFor,
+  writeSkillDir,
+  removeSkillDir,
+  cleanupOrphans,
+  MAX_PATH_DEPTH,
+  BLOCKED_EXTENSIONS,
+} from "../../lib/file-write.mjs";
+import { CliError, EXIT_VALIDATION } from "../../lib/errors.mjs";
+
+// ── Test sandbox helpers ────────────────────────────────────────────────
+
+let sandbox;
+let originalCwd;
+let originalHome;
+
+function setupSandbox() {
+  sandbox = mkdtempSync(join(tmpdir(), "cli-fw-"));
+  mkdirSync(join(sandbox, "project"), { recursive: true });
+  mkdirSync(join(sandbox, "home"), { recursive: true });
+  originalCwd = process.cwd();
+  originalHome = process.env.HOME;
+  process.chdir(join(sandbox, "project"));
+  process.env.HOME = join(sandbox, "home");
+}
+
+function teardownSandbox() {
+  process.chdir(originalCwd);
+  process.env.HOME = originalHome;
+  if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+}
+
+// A minimal valid skill payload for happy-path tests
+function minimalSkill(overrides = {}) {
+  return {
+    owner: "alice",
+    name: "pdf-helper",
+    files: [
+      {
+        path: "SKILL.md",
+        content: "---\nname: pdf-helper\ndescription: Test skill.\n---\n\nBody.\n",
+      },
+    ],
+    ...overrides,
+  };
+}
+
+// ── validateFilePath ────────────────────────────────────────────────────
+
+describe("validateFilePath", () => {
+  it("accepts a plain SKILL.md", () => {
+    assert.equal(validateFilePath("SKILL.md"), null);
+  });
+
+  it("accepts a script under scripts/", () => {
+    assert.equal(validateFilePath("scripts/extract.py"), null);
+  });
+
+  it("accepts a non-spec top-level dir (Option B path-preserving)", () => {
+    // This is the central proof of Defect A's fix — the CLI does NOT
+    // enforce the spec layout. lib/helper.py is path-preserving and OK.
+    assert.equal(validateFilePath("lib/helper.py"), null);
+    assert.equal(validateFilePath("utils/format.js"), null);
+    assert.equal(validateFilePath("data/lookup.json"), null);
+  });
+
+  it("rejects path traversal", () => {
+    assert.match(validateFilePath("../etc/passwd"), /traversal/);
+    assert.match(validateFilePath("scripts/../../../etc/passwd"), /traversal/);
+  });
+
+  it("rejects URL-encoded path traversal", () => {
+    assert.match(validateFilePath("..%2Fetc%2Fpasswd"), /traversal/);
+  });
+
+  it("rejects absolute paths (POSIX)", () => {
+    assert.match(validateFilePath("/etc/passwd"), /absolute/);
+  });
+
+  it("rejects absolute paths (Windows drive letter)", () => {
+    assert.match(validateFilePath("C:/Windows/System32/cmd.exe"), /absolute/);
+  });
+
+  it("rejects paths exceeding MAX_PATH_DEPTH", () => {
+    const tooDeep = Array(MAX_PATH_DEPTH + 1).fill("a").join("/") + ".py";
+    const err = validateFilePath(tooDeep);
+    assert.match(err, /nesting depth/);
+  });
+
+  it("accepts paths exactly at MAX_PATH_DEPTH", () => {
+    const atLimit = Array(MAX_PATH_DEPTH).fill("a").join("/") + ".py";
+    // depth = 5 segments separated by / — exactly the limit
+    assert.equal(validateFilePath(atLimit), null);
+  });
+
+  it("rejects blocked extensions", () => {
+    for (const ext of BLOCKED_EXTENSIONS) {
+      const err = validateFilePath(`scripts/payload${ext}`);
+      assert.match(err, /Blocked file type/, `Expected ${ext} to be blocked`);
+    }
+  });
+
+  it("rejects malformed URL encoding", () => {
+    const err = validateFilePath("%E0%A4%A");
+    assert.match(err, /URL encoding/);
+  });
+});
+
+// ── isValidSkillName ────────────────────────────────────────────────────
+
+describe("isValidSkillName", () => {
+  it("accepts canonical names", () => {
+    assert.equal(isValidSkillName("pdf-helper"), true);
+    assert.equal(isValidSkillName("a"), true);
+    assert.equal(isValidSkillName("skill123"), true);
+    assert.equal(isValidSkillName("a-very-long-but-valid-name"), true);
+  });
+
+  it("rejects empty and oversize names", () => {
+    assert.equal(isValidSkillName(""), false);
+    assert.equal(isValidSkillName("x".repeat(65)), false);
+  });
+
+  it("rejects uppercase letters", () => {
+    assert.equal(isValidSkillName("PDF-Helper"), false);
+  });
+
+  it("rejects leading or trailing hyphens", () => {
+    assert.equal(isValidSkillName("-pdf"), false);
+    assert.equal(isValidSkillName("pdf-"), false);
+  });
+
+  it("rejects consecutive hyphens", () => {
+    assert.equal(isValidSkillName("pdf--helper"), false);
+  });
+
+  it("rejects non-string input", () => {
+    assert.equal(isValidSkillName(undefined), false);
+    assert.equal(isValidSkillName(null), false);
+    assert.equal(isValidSkillName(42), false);
+  });
+});
+
+// ── readFrontmatterName ─────────────────────────────────────────────────
+
+describe("readFrontmatterName", () => {
+  it("extracts the name field from a SKILL.md", () => {
+    const files = [{ path: "SKILL.md", content: "---\nname: pdf-helper\n---\nBody" }];
+    assert.equal(readFrontmatterName(files), "pdf-helper");
+  });
+
+  it("strips quotes around the name value", () => {
+    const files = [{ path: "SKILL.md", content: '---\nname: "pdf-helper"\n---\nBody' }];
+    assert.equal(readFrontmatterName(files), "pdf-helper");
+  });
+
+  it("returns null when frontmatter is missing", () => {
+    const files = [{ path: "SKILL.md", content: "Plain markdown" }];
+    assert.equal(readFrontmatterName(files), null);
+  });
+
+  it("returns null when SKILL.md is missing", () => {
+    const files = [{ path: "scripts/extract.py", content: "print()" }];
+    assert.equal(readFrontmatterName(files), null);
+  });
+
+  it("returns null when name field is missing inside frontmatter", () => {
+    const files = [{ path: "SKILL.md", content: "---\ndescription: foo\n---\nBody" }];
+    assert.equal(readFrontmatterName(files), null);
+  });
+});
+
+// ── resolvePlacementDir + placementTargetsFor ───────────────────────────
+
+describe("placementTargetsFor", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("returns [claudeGlobal] for --global", () => {
+    assert.deepEqual(placementTargetsFor({ global: true }), ["claudeGlobal"]);
+  });
+
+  it("returns [claudeProject] for vendor=claudeCode only", () => {
+    assert.deepEqual(placementTargetsFor({ vendors: ["claudeCode"] }), ["claudeProject"]);
+  });
+
+  it("returns [projectFallback] for vendor=cursor only", () => {
+    assert.deepEqual(placementTargetsFor({ vendors: ["cursor"] }), ["projectFallback"]);
+  });
+
+  it("returns [claudeProject, projectFallback] for both", () => {
+    assert.deepEqual(
+      placementTargetsFor({ vendors: ["claudeCode", "cursor"] }),
+      ["claudeProject", "projectFallback"],
+    );
+  });
+
+  it("dedupes the fallback when multiple non-claude vendors are present", () => {
+    const targets = placementTargetsFor({
+      vendors: ["cursor", "windsurf", "vscode"],
+    });
+    // Only one projectFallback — not three
+    assert.equal(targets.filter((t) => t === "projectFallback").length, 1);
+  });
+
+  it("throws on empty vendors without --global", () => {
+    assert.throws(
+      () => placementTargetsFor({ vendors: [] }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("throws on unknown vendor", () => {
+    assert.throws(
+      () => placementTargetsFor({ vendors: ["jetbrains"] }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+});
+
+describe("resolvePlacementDir", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("resolves claudeProject under cwd", () => {
+    const dir = resolvePlacementDir("claudeProject", "pdf-helper");
+    assert.ok(dir.endsWith("/.claude/skills/pdf-helper"));
+    assert.ok(dir.startsWith(process.cwd()));
+  });
+
+  it("resolves claudeGlobal under HOME", () => {
+    const dir = resolvePlacementDir("claudeGlobal", "pdf-helper");
+    assert.ok(dir.endsWith("/.claude/skills/pdf-helper"));
+    assert.ok(dir.startsWith(process.env.HOME));
+  });
+
+  it("resolves projectFallback under cwd /skills/", () => {
+    const dir = resolvePlacementDir("projectFallback", "pdf-helper");
+    assert.equal(dir, join(process.cwd(), "skills", "pdf-helper"));
+  });
+
+  it("throws on unknown target", () => {
+    assert.throws(
+      () => resolvePlacementDir("invalid", "pdf-helper"),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+});
+
+// ── writeSkillDir validation rejections ─────────────────────────────────
+
+describe("writeSkillDir — validation", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("rejects skills with no SKILL.md", () => {
+    const skill = minimalSkill({ files: [{ path: "scripts/x.py", content: "print()" }] });
+    assert.throws(
+      () => writeSkillDir(skill, { vendors: ["claudeCode"] }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION && /SKILL\.md/.test(err.message),
+    );
+  });
+
+  it("rejects skills with name/parent mismatch in frontmatter", () => {
+    const skill = minimalSkill({
+      name: "pdf-helper",
+      files: [
+        { path: "SKILL.md", content: "---\nname: not-pdf-helper\n---\nBody" },
+      ],
+    });
+    assert.throws(
+      () => writeSkillDir(skill, { vendors: ["claudeCode"] }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /does not match/.test(err.message),
+    );
+  });
+
+  it("rejects skills with invalid skill name", () => {
+    const skill = minimalSkill({ name: "PDF-Helper" });
+    assert.throws(
+      () => writeSkillDir(skill, { vendors: ["claudeCode"] }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("rejects skills with no owner", () => {
+    const skill = minimalSkill();
+    delete skill.owner;
+    assert.throws(
+      () => writeSkillDir(skill, { vendors: ["claudeCode"] }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("rejects skills with empty files array", () => {
+    const skill = minimalSkill({ files: [] });
+    assert.throws(
+      () => writeSkillDir(skill, { vendors: ["claudeCode"] }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("rejects skills with file containing path traversal", () => {
+    const skill = minimalSkill({
+      files: [
+        ...minimalSkill().files,
+        { path: "../escape.py", content: "x" },
+      ],
+    });
+    assert.throws(
+      () => writeSkillDir(skill, { vendors: ["claudeCode"] }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("rejects skills with duplicate file paths", () => {
+    const skill = minimalSkill({
+      files: [
+        { path: "SKILL.md", content: "---\nname: pdf-helper\n---\n" },
+        { path: "SKILL.md", content: "---\nname: pdf-helper\n---\n duplicate" },
+      ],
+    });
+    assert.throws(
+      () => writeSkillDir(skill, { vendors: ["claudeCode"] }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("rejects skills with non-string file content", () => {
+    const skill = minimalSkill({
+      files: [
+        ...minimalSkill().files,
+        { path: "scripts/binary.dat", content: Buffer.from([0, 1, 2]) },
+      ],
+    });
+    assert.throws(
+      () => writeSkillDir(skill, { vendors: ["claudeCode"] }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+});
+
+// ── writeSkillDir happy path + path preservation (Defect A fix) ─────────
+
+describe("writeSkillDir — happy path", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("writes a skill with SKILL.md only to claudeCode project dir", () => {
+    const skill = minimalSkill();
+    const result = writeSkillDir(skill, { vendors: ["claudeCode"] });
+
+    assert.equal(result.written.length, 1);
+    const dir = result.written[0];
+    const skillMd = readFileSync(join(dir, "SKILL.md"), "utf-8");
+    assert.match(skillMd, /name: pdf-helper/);
+  });
+
+  it("preserves non-spec top-level directories (Defect A fix)", () => {
+    // This is the central proof: the CLI is path-preserving. A file at
+    // lib/helper.py must end up at <skill>/lib/helper.py on disk.
+    const skill = minimalSkill({
+      files: [
+        ...minimalSkill().files,
+        { path: "lib/helper.py", content: "def help(): pass\n" },
+        { path: "utils/format.js", content: "export const fmt = x => x;\n" },
+      ],
+    });
+    const result = writeSkillDir(skill, { vendors: ["claudeCode"] });
+    const dir = result.written[0];
+
+    assert.equal(
+      readFileSync(join(dir, "lib/helper.py"), "utf-8"),
+      "def help(): pass\n",
+    );
+    assert.equal(
+      readFileSync(join(dir, "utils/format.js"), "utf-8"),
+      "export const fmt = x => x;\n",
+    );
+  });
+
+  it("writes spec-compliant subdirs (scripts/, references/, assets/)", () => {
+    const skill = minimalSkill({
+      files: [
+        ...minimalSkill().files,
+        { path: "scripts/extract.py", content: "print('hi')\n" },
+        { path: "references/REFERENCE.md", content: "# Reference\n" },
+        { path: "assets/template.json", content: "{}\n" },
+      ],
+    });
+    const result = writeSkillDir(skill, { vendors: ["claudeCode"] });
+    const dir = result.written[0];
+
+    assert.equal(readFileSync(join(dir, "scripts/extract.py"), "utf-8"), "print('hi')\n");
+    assert.equal(readFileSync(join(dir, "references/REFERENCE.md"), "utf-8"), "# Reference\n");
+    assert.equal(readFileSync(join(dir, "assets/template.json"), "utf-8"), "{}\n");
+  });
+
+  it("writes to multiple targets when claudeCode + cursor detected", () => {
+    const skill = minimalSkill();
+    const result = writeSkillDir(skill, { vendors: ["claudeCode", "cursor"] });
+    assert.equal(result.written.length, 2);
+    for (const dir of result.written) {
+      assert.ok(existsSync(join(dir, "SKILL.md")));
+    }
+  });
+
+  it("writes to global home dir with --global", () => {
+    const skill = minimalSkill();
+    const result = writeSkillDir(skill, { global: true });
+    assert.equal(result.written.length, 1);
+    assert.ok(result.written[0].startsWith(process.env.HOME));
+  });
+
+  it("creates /skills/ fallback when only non-claude vendor is detected", () => {
+    const skill = minimalSkill();
+    const result = writeSkillDir(skill, { vendors: ["cursor"] });
+    assert.equal(result.written.length, 1);
+    assert.ok(result.written[0].includes("/skills/pdf-helper"));
+    // .gitignore should now contain /skills/
+    const gi = readFileSync(join(process.cwd(), ".gitignore"), "utf-8");
+    assert.match(gi, /\/skills\//);
+    assert.match(gi, /SkillRepo/);
+  });
+
+  it("idempotent .gitignore management — does not double-add /skills/", () => {
+    const skill = minimalSkill();
+    writeSkillDir(skill, { vendors: ["cursor"] });
+    writeSkillDir(skill, { vendors: ["cursor"] });
+    const gi = readFileSync(join(process.cwd(), ".gitignore"), "utf-8");
+    const matches = gi.match(/\/skills\//g) || [];
+    assert.equal(matches.length, 1, ".gitignore should have exactly one /skills/ entry");
+  });
+
+  it("appends to an existing .gitignore without clobbering", () => {
+    writeFileSync(join(process.cwd(), ".gitignore"), "node_modules\n.env\n");
+    writeSkillDir(minimalSkill(), { vendors: ["cursor"] });
+    const gi = readFileSync(join(process.cwd(), ".gitignore"), "utf-8");
+    assert.match(gi, /node_modules/);
+    assert.match(gi, /\.env/);
+    assert.match(gi, /\/skills\//);
+  });
+});
+
+// ── writeSkillDir update path (atomic) ──────────────────────────────────
+
+describe("writeSkillDir — update path", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("overwrites an existing skill atomically", () => {
+    // First write
+    writeSkillDir(minimalSkill(), { vendors: ["claudeCode"] });
+
+    // Second write with changed content
+    const updated = minimalSkill({
+      files: [
+        {
+          path: "SKILL.md",
+          content: "---\nname: pdf-helper\ndescription: Updated.\n---\n\nUpdated body.\n",
+        },
+        { path: "scripts/new.py", content: "print('new')\n" },
+      ],
+    });
+    const result = writeSkillDir(updated, { vendors: ["claudeCode"] });
+
+    const dir = result.written[0];
+    const skillMd = readFileSync(join(dir, "SKILL.md"), "utf-8");
+    assert.match(skillMd, /Updated/);
+    assert.equal(readFileSync(join(dir, "scripts/new.py"), "utf-8"), "print('new')\n");
+  });
+
+  it("removes files no longer in the skill (full overwrite semantics)", () => {
+    // First write with two files
+    writeSkillDir(minimalSkill({
+      files: [
+        { path: "SKILL.md", content: "---\nname: pdf-helper\n---\n" },
+        { path: "scripts/old.py", content: "print('old')\n" },
+      ],
+    }), { vendors: ["claudeCode"] });
+
+    // Second write without the old file
+    const result = writeSkillDir(minimalSkill(), { vendors: ["claudeCode"] });
+    const dir = result.written[0];
+    assert.ok(!existsSync(join(dir, "scripts/old.py")), "old file should be gone");
+  });
+
+  it("cleans up stale .tmp/ from a previous crash before populating a new one", () => {
+    const skill = minimalSkill();
+    // Pre-create a stale .tmp/ to simulate a crashed run
+    const targetDir = resolvePlacementDir("claudeProject", "pdf-helper");
+    mkdirSync(`${targetDir}.tmp`, { recursive: true });
+    writeFileSync(`${targetDir}.tmp/leftover.txt`, "garbage");
+
+    // Now run the write — should clean and succeed
+    const result = writeSkillDir(skill, { vendors: ["claudeCode"] });
+    assert.ok(existsSync(join(result.written[0], "SKILL.md")));
+    assert.ok(!existsSync(join(result.written[0], "leftover.txt")));
+  });
+
+  it("successful update overwrites content and leaves no .tmp/.old residue", { skip: process.platform === "win32" }, () => {
+    // KNOWN COVERAGE GAP: this test exercises the happy path of the
+    // atomic .tmp/.old rename dance — write twice, confirm the second
+    // write replaces the first and leaves no orphan state. It does NOT
+    // exercise the rollback branch in writeSkillToDir at the
+    // `renameSync(tmpDir, targetDir)` failure path. Triggering that
+    // branch deterministically requires either root permissions to
+    // chmod a parent directory, a symlink trick, or an injected fault
+    // — none of which are stable across CI runners.
+    //
+    // The rollback branch IS reachable in production (file system
+    // races, EINVAL on unusual filesystems, etc.) and IS implemented
+    // correctly per code review, but it is not covered by an automated
+    // test. The next time someone touches that branch, manual
+    // verification is required — see the comment at the rollback site
+    // in file-write.mjs for the exact branch.
+    writeSkillDir(minimalSkill(), { vendors: ["claudeCode"] });
+
+    const targetDir = resolvePlacementDir("claudeProject", "pdf-helper");
+    const oldDir = `${targetDir}.old`;
+
+    const updated = {
+      owner: "alice",
+      name: "pdf-helper",
+      files: [
+        { path: "SKILL.md", content: "---\nname: pdf-helper\n---\nNew content.\n" },
+      ],
+    };
+    writeSkillDir(updated, { vendors: ["claudeCode"] });
+    const skillMd = readFileSync(join(targetDir, "SKILL.md"), "utf-8");
+    assert.match(skillMd, /New content/);
+    assert.ok(!existsSync(`${targetDir}.tmp`));
+    assert.ok(!existsSync(oldDir));
+  });
+
+  it("throws diskError when the .tmp path is occupied by a regular file", { skip: process.platform === "win32" }, () => {
+    const skill = minimalSkill();
+    const targetDir = resolvePlacementDir("claudeProject", "pdf-helper");
+    // Pre-create the .tmp path as a FILE (not a directory) — the
+    // pre-flight cleanup will rmSync it and re-create as a dir, so
+    // this test verifies the rmSync path works on a file.
+    mkdirSync(join(process.cwd(), ".claude", "skills"), { recursive: true });
+    writeFileSync(`${targetDir}.tmp`, "I am a file, not a dir");
+
+    // Should successfully clean the file and proceed
+    const result = writeSkillDir(skill, { vendors: ["claudeCode"] });
+    assert.ok(existsSync(join(result.written[0], "SKILL.md")));
+    assert.ok(!existsSync(`${targetDir}.tmp`));
+  });
+});
+
+describe("writeSkillDir — return shape", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("returns only `written`, never `skipped` (architect B1 fix)", () => {
+    const skill = minimalSkill();
+    const result = writeSkillDir(skill, { vendors: ["claudeCode"] });
+    assert.deepEqual(Object.keys(result).sort(), ["written"]);
+  });
+});
+
+describe("ensureFallbackGitignore — error surfacing", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("throws diskError when .gitignore is read-only", { skip: process.platform === "win32" || process.getuid?.() === 0 }, () => {
+    // Pre-create a read-only .gitignore
+    const gi = join(process.cwd(), ".gitignore");
+    writeFileSync(gi, "node_modules\n");
+    chmodSync(gi, 0o444);
+
+    try {
+      assert.throws(
+        () => writeSkillDir(minimalSkill(), { vendors: ["cursor"] }),
+        (err) => err instanceof CliError && err.exitCode === 3, // EXIT_DISK
+      );
+    } finally {
+      // Restore writable so afterEach can clean up
+      chmodSync(gi, 0o644);
+    }
+  });
+
+  it("read-only .gitignore aborts ALL writes (no partial state) when both claudeCode + cursor requested", { skip: process.platform === "win32" || process.getuid?.() === 0 }, () => {
+    // Architect re-review found that ensureFallbackGitignore() throwing
+    // mid-loop would leave a successful claudeCode write + a thrown
+    // cursor failure = partial state. The fix moves the .gitignore
+    // pre-flight before the loop. This test locks that fix in.
+    const gi = join(process.cwd(), ".gitignore");
+    writeFileSync(gi, "node_modules\n");
+    chmodSync(gi, 0o444);
+
+    try {
+      assert.throws(
+        () => writeSkillDir(minimalSkill(), { vendors: ["claudeCode", "cursor"] }),
+        (err) => err instanceof CliError && err.exitCode === 3,
+      );
+      // Critical: the claudeCode write must NOT have executed because
+      // the pre-flight failed before any disk work began.
+      const claudeDir = resolvePlacementDir("claudeProject", "pdf-helper");
+      assert.ok(!existsSync(claudeDir), "claudeCode skill must not be partially written");
+    } finally {
+      chmodSync(gi, 0o644);
+    }
+  });
+});
+
+describe("cleanupOrphans — Windows recovery invariant", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("preserves .tmp/ whose live target is missing (recovery from crashed Windows rename)", () => {
+    // Inject a .tmp/ with NO sibling live target — the CLI's only copy
+    // of a recoverable skill from a crashed Windows update.
+    const root = join(process.cwd(), ".claude", "skills");
+    mkdirSync(join(root, "pdf-helper.tmp"), { recursive: true });
+    writeFileSync(join(root, "pdf-helper.tmp", "SKILL.md"), "---\nname: pdf-helper\n---\nRecoverable.\n");
+
+    const result = cleanupOrphans({ vendors: ["claudeCode"] });
+    assert.equal(result.cleaned.length, 0, ".tmp with no live sibling should be preserved");
+    assert.ok(existsSync(join(root, "pdf-helper.tmp", "SKILL.md")), "user's only copy must survive");
+  });
+
+  it("removes .tmp/ when a live sibling exists (post-successful-write cleanup)", () => {
+    // Both live target and .tmp present — .tmp is stale state from a
+    // future-crashed write that the user has since recovered from.
+    const root = join(process.cwd(), ".claude", "skills");
+    writeSkillDir(minimalSkill(), { vendors: ["claudeCode"] });
+    mkdirSync(join(root, "pdf-helper.tmp"));
+    writeFileSync(join(root, "pdf-helper.tmp", "stale.txt"), "x");
+
+    const result = cleanupOrphans({ vendors: ["claudeCode"] });
+    assert.equal(result.cleaned.length, 1, "stale .tmp with live sibling should be cleaned");
+    assert.ok(!existsSync(join(root, "pdf-helper.tmp")));
+    // Live skill untouched
+    assert.ok(existsSync(join(root, "pdf-helper", "SKILL.md")));
+  });
+});
+
+// ── removeSkillDir ──────────────────────────────────────────────────────
+
+describe("removeSkillDir", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("removes an existing skill from claudeCode project dir", () => {
+    writeSkillDir(minimalSkill(), { vendors: ["claudeCode"] });
+    const dir = resolvePlacementDir("claudeProject", "pdf-helper");
+    assert.ok(existsSync(dir));
+
+    const result = removeSkillDir("pdf-helper", { vendors: ["claudeCode"] });
+    assert.equal(result.removed.length, 1);
+    assert.equal(result.notFound.length, 0);
+    assert.ok(!existsSync(dir));
+  });
+
+  it("returns notFound when the skill directory doesn't exist", () => {
+    const result = removeSkillDir("ghost", { vendors: ["claudeCode"] });
+    assert.equal(result.removed.length, 0);
+    assert.equal(result.notFound.length, 1);
+  });
+
+  it("removes from multiple targets", () => {
+    writeSkillDir(minimalSkill(), { vendors: ["claudeCode", "cursor"] });
+    const result = removeSkillDir("pdf-helper", { vendors: ["claudeCode", "cursor"] });
+    assert.equal(result.removed.length, 2);
+  });
+
+  it("rejects invalid skill names", () => {
+    assert.throws(
+      () => removeSkillDir("BAD", { vendors: ["claudeCode"] }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+});
+
+// ── cleanupOrphans ──────────────────────────────────────────────────────
+
+describe("cleanupOrphans", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("removes .tmp/ orphans whose live sibling exists (post-successful-write residue)", () => {
+    // The cleanupOrphans safety invariant preserves a `.tmp/` whose live
+    // target is missing (Windows recovery path). To test that orphan
+    // cleanup actually fires, we need a live sibling so the .tmp is
+    // confirmed safe to delete.
+    const root = join(process.cwd(), ".claude", "skills");
+    mkdirSync(join(root, "ghost"), { recursive: true }); // live sibling
+    mkdirSync(join(root, "ghost.tmp"));
+    writeFileSync(join(root, "ghost.tmp", "x.txt"), "garbage");
+
+    const result = cleanupOrphans({ vendors: ["claudeCode"] });
+    assert.equal(result.cleaned.length, 1);
+    assert.ok(!existsSync(join(root, "ghost.tmp")));
+  });
+
+  it("removes .old/ orphans under claudeProject root", () => {
+    const root = join(process.cwd(), ".claude", "skills");
+    mkdirSync(root, { recursive: true });
+    mkdirSync(join(root, "ghost.old"));
+
+    const result = cleanupOrphans({ vendors: ["claudeCode"] });
+    assert.equal(result.cleaned.length, 1);
+  });
+
+  it("leaves regular skill directories alone", () => {
+    writeSkillDir(minimalSkill(), { vendors: ["claudeCode"] });
+    const result = cleanupOrphans({ vendors: ["claudeCode"] });
+    assert.equal(result.cleaned.length, 0);
+    const dir = resolvePlacementDir("claudeProject", "pdf-helper");
+    assert.ok(existsSync(dir));
+  });
+
+  it("scans all known roots when no vendors specified", () => {
+    // Drop one orphan in each root we know about. .tmp/ entries need
+    // a live sibling so the safety invariant doesn't preserve them.
+    const claudeRoot = join(process.cwd(), ".claude", "skills");
+    const fallbackRoot = join(process.cwd(), "skills");
+    const globalRoot = join(process.env.HOME, ".claude", "skills");
+    mkdirSync(claudeRoot, { recursive: true });
+    mkdirSync(fallbackRoot, { recursive: true });
+    mkdirSync(globalRoot, { recursive: true });
+    mkdirSync(join(claudeRoot, "ghost"));     // live sibling for the .tmp below
+    mkdirSync(join(claudeRoot, "ghost.tmp"));
+    mkdirSync(join(fallbackRoot, "ghost.old")); // .old has no invariant — always cleaned
+    mkdirSync(join(globalRoot, "ghost"));     // live sibling for the .tmp below
+    mkdirSync(join(globalRoot, "ghost.tmp"));
+
+    const result = cleanupOrphans({});
+    assert.equal(result.cleaned.length, 3);
+  });
+
+  it("is idempotent when there are no orphans", () => {
+    const result = cleanupOrphans({ vendors: ["claudeCode"] });
+    assert.deepEqual(result.cleaned, []);
+  });
+
+  it("handles missing roots gracefully", () => {
+    // No roots exist at all
+    const result = cleanupOrphans({ vendors: ["claudeCode"] });
+    assert.deepEqual(result.cleaned, []);
+  });
+});