skillrepo 4.8.0 → 4.8.2

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

@@ -37,6 +37,7 @@ import {
   isValidSkillName,
   readFrontmatterName,
   resolvePlacementDir,
+  describePlacementTarget,
   placementTargetsFor,
   writeSkillDir,
   removeSkillDir,
@@ -267,6 +268,42 @@ describe("readFrontmatterName", () => {
     const files = [{ path: "SKILL.md", content: "---\ndescription: foo\n---\nBody" }];
     assert.equal(readFrontmatterName(files), null);
   });
+
+  it("returns null when the frontmatter block closes before any name line (closing --- branch)", () => {
+    // Frontmatter opens and immediately closes with `---` on the very
+    // next line — the loop hits the closing-fence branch and returns
+    // null without ever seeing a `name:` line.
+    const files = [{ path: "SKILL.md", content: "---\n---\nBody only, no fields" }];
+    assert.equal(readFrontmatterName(files), null);
+  });
+
+  it("returns null when SKILL.md content is not a string", () => {
+    // A SKILL.md entry whose content isn't a string (defensive guard).
+    const files = [{ path: "SKILL.md", content: Buffer.from("---\nname: x\n---") }];
+    assert.equal(readFrontmatterName(files), null);
+  });
+});
+
+// ── describePlacementTarget ─────────────────────────────────────────────
+
+describe("describePlacementTarget", () => {
+  it("maps every known target to its human-readable path label", () => {
+    assert.equal(describePlacementTarget("claudeProject"), ".claude/skills/");
+    assert.equal(describePlacementTarget("claudeGlobal"), "~/.claude/skills/");
+    assert.equal(describePlacementTarget("agentsProject"), ".agents/skills/");
+    assert.equal(describePlacementTarget("agentsGlobal"), "~/.agents/skills/");
+    assert.equal(
+      describePlacementTarget("windsurfGlobal"),
+      "~/.codeium/windsurf/skills/",
+    );
+  });
+
+  it("falls back to echoing an unknown target (default branch)", () => {
+    // Defensive default arm: an unrecognized target string is echoed
+    // verbatim rather than throwing, so a future target that forgets a
+    // label still renders something.
+    assert.equal(describePlacementTarget("someFutureTarget"), "someFutureTarget");
+  });
 });
 
 // ── resolvePlacementDir + placementTargetsFor ───────────────────────────
@@ -446,6 +483,39 @@ describe("writeSkillDir — validation", () => {
       (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
     );
   });
+
+  it("rejects a null/non-object skill payload", () => {
+    // The `!skill || typeof skill !== "object"` guard at the top of
+    // validateSkill — exercised via the public writeSkillDir entry.
+    assert.throws(
+      () => writeSkillDir(null, { vendors: ["claudeCode"] }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /missing or not an object/.test(err.message),
+    );
+    assert.throws(
+      () => writeSkillDir("not-an-object", { vendors: ["claudeCode"] }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("rejects a skill whose file entry has no string path", () => {
+    // The per-file `!file || typeof file.path !== "string"` guard.
+    const skill = minimalSkill({
+      files: [
+        ...minimalSkill().files,
+        { content: "no path here" },
+      ],
+    });
+    assert.throws(
+      () => writeSkillDir(skill, { vendors: ["claudeCode"] }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /has a file with no path/.test(err.message),
+    );
+  });
 });
 
 // ── writeSkillDir happy path + path preservation (Defect A fix) ─────────
@@ -556,6 +626,23 @@ describe("writeSkillDir — happy path", () => {
     assert.match(gi, /\.env/);
     assert.match(gi, /\.agents\/skills\//);
   });
+
+  it("inserts a newline when the existing .gitignore has no trailing newline", () => {
+    // The `existing.endsWith("\n") ? "" : "\n"` ternary: when the file
+    // does NOT end in a newline, the appended block must be preceded by
+    // one so the existing last line and the SkillRepo header don't
+    // collapse onto a single line.
+    writeFileSync(join(process.cwd(), ".gitignore"), "node_modules"); // no trailing \n
+    writeSkillDir(minimalSkill(), { vendors: ["cursor"] });
+    const gi = readFileSync(join(process.cwd(), ".gitignore"), "utf-8");
+    // The original entry stays on its own line — not "node_modules# SkillRepo…".
+    assert.match(gi, /node_modules\n/);
+    assert.ok(
+      !/node_modules#/.test(gi),
+      "the no-trailing-newline branch must insert a separator newline",
+    );
+    assert.match(gi, /\.agents\/skills\//);
+  });
 });
 
 // ── writeSkillDir update path (atomic) ──────────────────────────────────
@@ -649,6 +736,53 @@ describe("writeSkillDir — update path", () => {
     assert.ok(!existsSync(oldDir));
   });
 
+  it(
+    "throws diskError when the .tmp/ directory cannot be created (read-only skills root)",
+    { skip: process.platform === "win32" || process.getuid?.() === 0 },
+    () => {
+      // Covers the `catch` around mkdirSync(tmpDir): the skills root
+      // exists but is read-only, so creating <skill>.tmp/ inside it
+      // fails with EACCES. writeSkillToDir must surface a typed
+      // diskError (EXIT_DISK = 3), wrapped by writeSkillDir's per-target
+      // catch into a "Failed to write" diskError (still exit code 3).
+      const root = join(process.cwd(), ".claude", "skills");
+      mkdirSync(root, { recursive: true });
+      chmodSync(root, 0o555); // read + execute, no write
+      try {
+        assert.throws(
+          () => writeSkillDir(minimalSkill(), { vendors: ["claudeCode"] }),
+          (err) => err instanceof CliError && err.exitCode === 3,
+        );
+      } finally {
+        chmodSync(root, 0o755);
+      }
+    },
+  );
+
+  it(
+    "throws diskError when a stale .tmp/ cannot be removed (read-only skills root)",
+    { skip: process.platform === "win32" || process.getuid?.() === 0 },
+    () => {
+      // Covers the `catch` around rmSync of a pre-existing stale .tmp/:
+      // a leftover <skill>.tmp/ exists from a prior crash, but the
+      // skills root is read-only so the cleanup rmSync is denied. The
+      // function surfaces a "Cannot remove stale" diskError.
+      const root = join(process.cwd(), ".claude", "skills");
+      const targetDir = resolvePlacementDir("claudeProject", "pdf-helper");
+      mkdirSync(`${targetDir}.tmp`, { recursive: true });
+      writeFileSync(`${targetDir}.tmp/leftover.txt`, "garbage");
+      chmodSync(root, 0o555);
+      try {
+        assert.throws(
+          () => writeSkillDir(minimalSkill(), { vendors: ["claudeCode"] }),
+          (err) => err instanceof CliError && err.exitCode === 3,
+        );
+      } finally {
+        chmodSync(root, 0o755);
+      }
+    },
+  );
+
   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");
@@ -786,6 +920,22 @@ describe("ensureFallbackGitignore — error surfacing", () => {
     }
   });
 
+  it("throws diskError when .gitignore cannot be READ (it is a directory → EISDIR)", () => {
+    // The read-error branch in ensureAgentsGitignore: 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
+    // attempted. Cross-platform (no chmod needed).
+    mkdirSync(join(process.cwd(), ".gitignore"), { recursive: true });
+    assert.throws(
+      () => writeSkillDir(minimalSkill(), { vendors: ["cursor"] }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === 3 &&
+        /Cannot read/.test(err.message),
+    );
+  });
+
   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
@@ -877,6 +1027,27 @@ describe("removeSkillDir", () => {
       (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
     );
   });
+
+  it(
+    "throws diskError when the skill directory cannot be removed (rmSync fails)",
+    { skip: process.platform === "win32" || process.getuid?.() === 0 },
+    () => {
+      // Write a skill, then make its PARENT (the skills root) read-only
+      // so rmSync of the skill dir fails with EACCES. removeSkillDir must
+      // surface a typed diskError (EXIT_DISK = 3), not a raw OS error.
+      writeSkillDir(minimalSkill(), { vendors: ["claudeCode"] });
+      const root = join(process.cwd(), ".claude", "skills");
+      chmodSync(root, 0o555); // read + execute, no write → unlink denied
+      try {
+        assert.throws(
+          () => removeSkillDir("pdf-helper", { vendors: ["claudeCode"] }),
+          (err) => err instanceof CliError && err.exitCode === 3,
+        );
+      } finally {
+        chmodSync(root, 0o755);
+      }
+    },
+  );
 });
 
 // ── cleanupOrphans ──────────────────────────────────────────────────────
@@ -947,6 +1118,79 @@ describe("cleanupOrphans", () => {
     assert.deepEqual(result.cleaned, []);
   });
 
+  it("sweeps every global root under --global with no vendors (global-only branch)", () => {
+    // The `else if (options.global)` arm: bare --global with no vendors
+    // sweeps the known GLOBAL roots. Seed a cleanable .old/ in the
+    // claudeGlobal root and confirm it's swept.
+    const globalRoot = join(process.env.HOME, ".claude", "skills");
+    mkdirSync(globalRoot, { recursive: true });
+    mkdirSync(join(globalRoot, "ghost.old"));
+
+    const result = cleanupOrphans({ global: true });
+    assert.equal(result.cleaned.length, 1);
+    assert.ok(!existsSync(join(globalRoot, "ghost.old")));
+  });
+
+  it("ignores a .tmp/.old name that is a regular FILE, not a directory", () => {
+    // The `if (!st.isDirectory()) continue` guard: a plain file whose
+    // name happens to end in .old must NOT be removed — only orphan
+    // DIRECTORIES are cleanable.
+    const root = join(process.cwd(), ".claude", "skills");
+    mkdirSync(root, { recursive: true });
+    writeFileSync(join(root, "decoy.old"), "i am a file, not a dir");
+
+    const result = cleanupOrphans({ vendors: ["claudeCode"] });
+    assert.deepEqual(result.cleaned, []);
+    assert.ok(existsSync(join(root, "decoy.old")), "the file must be left alone");
+  });
+
+  it(
+    "skips an unreadable root without throwing (readdir EACCES is swallowed)",
+    { skip: process.platform === "win32" || process.getuid?.() === 0 },
+    () => {
+      // The `catch { continue; }` around readdirSync(root): a root dir
+      // that exists but can't be listed is skipped rather than crashing
+      // the cleanup sweep.
+      const root = join(process.cwd(), ".claude", "skills");
+      mkdirSync(root, { recursive: true });
+      mkdirSync(join(root, "ghost.old"));
+      chmodSync(root, 0o000);
+      try {
+        const result = cleanupOrphans({ vendors: ["claudeCode"] });
+        // Could not enumerate the root → nothing cleaned, no throw.
+        assert.deepEqual(result.cleaned, []);
+      } finally {
+        chmodSync(root, 0o755);
+      }
+    },
+  );
+
+  it(
+    "best-effort swallows an rmSync failure on an orphan (no throw, not counted)",
+    { skip: process.platform === "win32" || process.getuid?.() === 0 },
+    () => {
+      // The `catch { /* best-effort */ }` around rmSync(orphanPath):
+      // the root is readable+searchable (so readdir + statSync succeed
+      // and the orphan is identified as cleanable) but NOT writable, so
+      // the actual rmSync(orphanPath) is denied. cleanupOrphans must
+      // swallow that, report nothing cleaned, and not throw.
+      const root = join(process.cwd(), ".claude", "skills");
+      mkdirSync(root, { recursive: true });
+      // .old/ has no preservation invariant → it IS selected for removal.
+      mkdirSync(join(root, "ghost.old"));
+      // 0o555 = read + execute (readdir + statSync work), no write
+      // (removing the child entry is denied with EACCES).
+      chmodSync(root, 0o555);
+      try {
+        const result = cleanupOrphans({ vendors: ["claudeCode"] });
+        assert.deepEqual(result.cleaned, [], "rmSync failure must not be counted as cleaned");
+        assert.ok(existsSync(join(root, "ghost.old")), "the orphan survives the failed rmSync");
+      } finally {
+        chmodSync(root, 0o755);
+      }
+    },
+  );
+
   // QA cross-PR review (#1252): the permutation where BOTH .tmp/ and
   // .old/ exist but the live target is MISSING was uncovered. This
   // tests the divergence between the two recovery invariants:

package/src/test/lib/fs-utils.test.mjs

@@ -0,0 +1,259 @@
+/**
+ * Unit tests for src/lib/fs-utils.mjs.
+ *
+ * Covers the three exported helpers:
+ *   - readFileSafe   — UTF-8 read, null on ENOENT, re-throw otherwise
+ *   - writeFileSafe  — write + recursive parent mkdir + dir-as-file guard
+ *   - pathExists     — thin existsSync wrapper
+ *   - writeFileAtomic — temp-file + rename dance, optional chmod, dir guard,
+ *                       and the cleanup-on-rename-failure path
+ *
+ * Every test runs in a `mkdtempSync` sandbox so nothing touches the
+ * developer's real filesystem. chmod- and permission-dependent tests are
+ * guarded with `process.platform === "win32"` (Windows ACLs don't map to
+ * POSIX mode bits) and `process.getuid?.() === 0` (root bypasses 0o555
+ * permission denials), matching the convention in config.test.mjs.
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+  readFileSync,
+  statSync,
+  chmodSync,
+  readdirSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  readFileSafe,
+  writeFileSafe,
+  pathExists,
+  writeFileAtomic,
+} from "../../lib/fs-utils.mjs";
+
+let sandbox;
+
+function setupSandbox() {
+  sandbox = mkdtempSync(join(tmpdir(), "cli-fs-utils-"));
+}
+
+function teardownSandbox() {
+  if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+}
+
+// ── readFileSafe ─────────────────────────────────────────────────────────
+
+describe("readFileSafe", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("returns the file content as UTF-8", () => {
+    const p = join(sandbox, "file.txt");
+    writeFileSync(p, "hello world", "utf-8");
+    assert.equal(readFileSafe(p), "hello world");
+  });
+
+  it("returns null when the file does not exist (ENOENT)", () => {
+    assert.equal(readFileSafe(join(sandbox, "missing.txt")), null);
+  });
+
+  it("re-throws non-ENOENT errors (EISDIR when path is a directory)", () => {
+    // Reading a directory throws EISDIR, not ENOENT — must propagate.
+    assert.throws(
+      () => readFileSafe(sandbox),
+      (err) => err.code !== "ENOENT",
+    );
+  });
+
+  it(
+    "re-throws permission errors (EACCES)",
+    { skip: process.platform === "win32" || process.getuid?.() === 0 },
+    () => {
+      const p = join(sandbox, "locked.txt");
+      writeFileSync(p, "secret", "utf-8");
+      chmodSync(p, 0o000);
+      try {
+        assert.throws(
+          () => readFileSafe(p),
+          (err) => err.code === "EACCES",
+        );
+      } finally {
+        chmodSync(p, 0o644);
+      }
+    },
+  );
+});
+
+// ── writeFileSafe ──────────────────────────────────────────────────────────
+
+describe("writeFileSafe", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("writes content to a file in an existing directory", () => {
+    const p = join(sandbox, "out.txt");
+    writeFileSafe(p, "content");
+    assert.equal(readFileSync(p, "utf-8"), "content");
+  });
+
+  it("creates missing parent directories recursively", () => {
+    const p = join(sandbox, "a", "b", "c", "deep.txt");
+    writeFileSafe(p, "nested");
+    assert.equal(readFileSync(p, "utf-8"), "nested");
+  });
+
+  it("overwrites an existing file", () => {
+    const p = join(sandbox, "over.txt");
+    writeFileSafe(p, "v1");
+    writeFileSafe(p, "v2");
+    assert.equal(readFileSync(p, "utf-8"), "v2");
+  });
+
+  it("throws when the target path is an existing directory", () => {
+    const dirPath = join(sandbox, "iAmADir");
+    mkdirSync(dirPath);
+    assert.throws(
+      () => writeFileSafe(dirPath, "content"),
+      /is a directory, expected a file/,
+    );
+  });
+});
+
+// ── pathExists ─────────────────────────────────────────────────────────────
+
+describe("pathExists", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("returns true for an existing file", () => {
+    const p = join(sandbox, "exists.txt");
+    writeFileSync(p, "x");
+    assert.equal(pathExists(p), true);
+  });
+
+  it("returns true for an existing directory", () => {
+    assert.equal(pathExists(sandbox), true);
+  });
+
+  it("returns false for a missing path", () => {
+    assert.equal(pathExists(join(sandbox, "nope")), false);
+  });
+});
+
+// ── writeFileAtomic ────────────────────────────────────────────────────────
+
+describe("writeFileAtomic", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("writes content atomically and leaves no .tmp residue", () => {
+    const p = join(sandbox, "atomic.txt");
+    writeFileAtomic(p, "atomic content");
+    assert.equal(readFileSync(p, "utf-8"), "atomic content");
+    // No leftover *.tmp siblings.
+    const siblings = readdirSync(sandbox);
+    assert.ok(
+      !siblings.some((f) => f.endsWith(".tmp")),
+      `expected no .tmp residue, found: ${siblings.join(", ")}`,
+    );
+  });
+
+  it("creates missing parent directories recursively", () => {
+    const p = join(sandbox, "x", "y", "z", "atomic.txt");
+    writeFileAtomic(p, "deep atomic");
+    assert.equal(readFileSync(p, "utf-8"), "deep atomic");
+  });
+
+  it("overwrites an existing destination file", () => {
+    const p = join(sandbox, "replace.txt");
+    writeFileSync(p, "old");
+    writeFileAtomic(p, "new");
+    assert.equal(readFileSync(p, "utf-8"), "new");
+  });
+
+  it("throws when the destination path is an existing directory", () => {
+    const dirPath = join(sandbox, "destDir");
+    mkdirSync(dirPath);
+    assert.throws(
+      () => writeFileAtomic(dirPath, "content"),
+      /is a directory, expected a file/,
+    );
+  });
+
+  it(
+    "applies the requested mode to the final file on POSIX",
+    { skip: process.platform === "win32" || process.getuid?.() === 0 },
+    () => {
+      const p = join(sandbox, "perms.txt");
+      writeFileAtomic(p, "secret", { mode: 0o600 });
+      const mode = statSync(p).mode & 0o777;
+      assert.equal(mode, 0o600, `expected 0o600, got ${mode.toString(8)}`);
+    },
+  );
+
+  it("ignores mode when undefined (no chmod attempted, write still succeeds)", () => {
+    const p = join(sandbox, "nomode.txt");
+    // mode omitted → the chmod branch is skipped entirely.
+    writeFileAtomic(p, "no mode");
+    assert.equal(readFileSync(p, "utf-8"), "no mode");
+  });
+
+  it(
+    "succeeds even when chmod on the temp file fails (chmod failure is non-fatal)",
+    { skip: process.platform === "win32" || process.getuid?.() === 0 },
+    () => {
+      // An immutable-mode value can't be forced portably, but we CAN
+      // exercise the non-fatal chmod path with a normal mode and assert
+      // the write still completes. The chmod-failure swallow is defensive
+      // (see fs-utils.mjs) — the contract we lock here is that a mode
+      // request never aborts the write.
+      const p = join(sandbox, "chmod-ok.txt");
+      writeFileAtomic(p, "data", { mode: 0o640 });
+      assert.equal(readFileSync(p, "utf-8"), "data");
+    },
+  );
+
+  it(
+    "wraps a temp-file write failure with a 'Cannot write' message and preserves the cause",
+    { skip: process.platform === "win32" || process.getuid?.() === 0 },
+    () => {
+      // Make the parent directory non-writable so writeFileSync on the
+      // temp path fails. The dir must already exist (so the mkdir branch
+      // is skipped) and be read-only.
+      const dir = join(sandbox, "ro-parent");
+      mkdirSync(dir);
+      chmodSync(dir, 0o555);
+      const p = join(dir, "target.txt");
+      try {
+        assert.throws(
+          () => writeFileAtomic(p, "content"),
+          (err) =>
+            err instanceof Error &&
+            /Cannot write .*\.tmp:/.test(err.message) &&
+            err.cause !== undefined,
+        );
+      } finally {
+        chmodSync(dir, 0o755);
+      }
+    },
+  );
+
+  // NOTE: the rename-failure cleanup branch in writeFileAtomic (the
+  // `catch` around `renameSync(tmpPath, filePath)` that unlinks the temp
+  // file and throws "Cannot install …") is NOT covered here. The temp
+  // file and the destination share the same parent directory
+  // (`dirname(filePath)`), so any state that makes the rename fail also
+  // makes the preceding temp-file write fail — there is no portable,
+  // deterministic way to fail ONLY the rename without mocking
+  // `node:fs.renameSync`. The CI harness runs the suite with a plain
+  // `node --test` (no `--experimental-test-module-mocks`), so module
+  // mocking is off the table. Reaching this branch would require a DI
+  // seam for the rename call, which is out of scope for a tests-only
+  // change.
+});