skillrepo 2.0.0 → 3.1.0

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

@@ -0,0 +1,279 @@
+/**
+ * Integration tests for src/lib/file-write.mjs (PR1 of #646).
+ *
+ * Differs from the unit tests in that we compose the public API against
+ * a real temp filesystem and assert on multi-step behaviors:
+ *   - End-to-end skill round-trip (write → read back → verify)
+ *   - Update path leaves NO orphan state on success
+ *   - Sequential rewrites are atomic from the reader's perspective
+ *   - Recovery from injected partial state (simulated mid-write crash)
+ *   - Multi-target writes produce identical content
+ *
+ * These tests touch the real filesystem in a temp directory. They do
+ * not require network or a running server.
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  rmSync,
+  mkdirSync,
+  writeFileSync,
+  existsSync,
+  readFileSync,
+  readdirSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  writeSkillDir,
+  removeSkillDir,
+  cleanupOrphans,
+  resolvePlacementDir,
+} from "../../lib/file-write.mjs";
+
+let sandbox;
+let originalCwd;
+let originalHome;
+
+function setupSandbox() {
+  sandbox = mkdtempSync(join(tmpdir(), "cli-fw-int-"));
+  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 });
+}
+
+function multiFileSkill(name = "pdf-helper") {
+  return {
+    owner: "alice",
+    name,
+    files: [
+      {
+        path: "SKILL.md",
+        content: `---\nname: ${name}\ndescription: Multi-file integration test skill.\n---\n\nMain body.\n`,
+      },
+      { path: "scripts/extract.py", content: "import sys\nprint(sys.argv)\n" },
+      { path: "scripts/format.sh", content: "#!/bin/bash\necho ok\n" },
+      { path: "references/REFERENCE.md", content: "# Reference\n\nDetails.\n" },
+      { path: "assets/template.json", content: '{"version": 1}\n' },
+      // Path-preserving non-spec dir — proves Defect A fix end-to-end
+      { path: "lib/helper.py", content: "def helper():\n    return 42\n" },
+    ],
+  };
+}
+
+describe("file-write.mjs integration — round-trip", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("writes a 6-file skill and reads back identical bytes", () => {
+    const skill = multiFileSkill();
+    const result = writeSkillDir(skill, { vendors: ["claudeCode"] });
+    assert.equal(result.written.length, 1);
+    const dir = result.written[0];
+
+    for (const file of skill.files) {
+      const onDisk = readFileSync(join(dir, file.path), "utf-8");
+      assert.equal(onDisk, file.content, `Mismatch for ${file.path}`);
+    }
+  });
+
+  it("writes the same skill identically to multiple targets", () => {
+    const skill = multiFileSkill();
+    const result = writeSkillDir(skill, { vendors: ["claudeCode", "cursor"] });
+    assert.equal(result.written.length, 2);
+
+    const [firstDir, secondDir] = result.written;
+    for (const file of skill.files) {
+      const a = readFileSync(join(firstDir, file.path), "utf-8");
+      const b = readFileSync(join(secondDir, file.path), "utf-8");
+      assert.equal(a, b, `Targets diverged for ${file.path}`);
+    }
+  });
+
+  it("writes to global dir under HOME with --global", () => {
+    const skill = multiFileSkill();
+    const result = writeSkillDir(skill, { global: true });
+    assert.equal(result.written.length, 1);
+    const dir = result.written[0];
+    assert.ok(dir.startsWith(process.env.HOME), "should write under HOME");
+    for (const file of skill.files) {
+      assert.ok(existsSync(join(dir, file.path)));
+    }
+  });
+});
+
+describe("file-write.mjs integration — update path", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("leaves no .tmp/ or .old/ directories after a successful write", () => {
+    writeSkillDir(multiFileSkill(), { vendors: ["claudeCode"] });
+    const root = join(process.cwd(), ".claude", "skills");
+    const entries = readdirSync(root);
+    for (const entry of entries) {
+      assert.ok(!entry.endsWith(".tmp"), `Unexpected .tmp leftover: ${entry}`);
+      assert.ok(!entry.endsWith(".old"), `Unexpected .old leftover: ${entry}`);
+    }
+  });
+
+  it("removes deleted files when overwriting", () => {
+    // First write
+    writeSkillDir(multiFileSkill(), { vendors: ["claudeCode"] });
+
+    // Second write removes the lib/ and references/ dirs
+    const trimmed = {
+      owner: "alice",
+      name: "pdf-helper",
+      files: [
+        { path: "SKILL.md", content: "---\nname: pdf-helper\n---\nTrimmed.\n" },
+        { path: "scripts/extract.py", content: "print('only this remains')\n" },
+      ],
+    };
+    const result = writeSkillDir(trimmed, { vendors: ["claudeCode"] });
+    const dir = result.written[0];
+
+    assert.ok(existsSync(join(dir, "SKILL.md")));
+    assert.ok(existsSync(join(dir, "scripts/extract.py")));
+    assert.ok(!existsSync(join(dir, "lib/helper.py")), "lib/ should be gone");
+    assert.ok(!existsSync(join(dir, "references/REFERENCE.md")), "references/ should be gone");
+    assert.ok(!existsSync(join(dir, "assets/template.json")), "assets/ should be gone");
+  });
+
+  it("multiple sequential updates each end in a clean state", () => {
+    for (let i = 0; i < 5; i++) {
+      const skill = {
+        owner: "alice",
+        name: "pdf-helper",
+        files: [
+          { path: "SKILL.md", content: `---\nname: pdf-helper\n---\nIteration ${i}.\n` },
+          { path: "scripts/iter.py", content: `# iteration ${i}\n` },
+        ],
+      };
+      writeSkillDir(skill, { vendors: ["claudeCode"] });
+
+      const dir = resolvePlacementDir("claudeProject", "pdf-helper");
+      const skillMd = readFileSync(join(dir, "SKILL.md"), "utf-8");
+      assert.match(skillMd, new RegExp(`Iteration ${i}`));
+
+      // No leftovers
+      const root = join(process.cwd(), ".claude", "skills");
+      const entries = readdirSync(root);
+      for (const entry of entries) {
+        assert.ok(!entry.endsWith(".tmp"));
+        assert.ok(!entry.endsWith(".old"));
+      }
+    }
+  });
+});
+
+describe("file-write.mjs integration — orphan recovery", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("cleanupOrphans removes injected .tmp/ (with live siblings) and .old/ across all roots", () => {
+    // Inject orphans in claudeProject root, claudeGlobal root, and
+    // projectFallback root. .tmp/ entries need a live sibling so the
+    // safety invariant doesn't preserve them as recoverable.
+    const claudeProjectRoot = join(process.cwd(), ".claude", "skills");
+    const fallbackRoot = join(process.cwd(), "skills");
+    const globalRoot = join(process.env.HOME, ".claude", "skills");
+    mkdirSync(claudeProjectRoot, { recursive: true });
+    mkdirSync(fallbackRoot, { recursive: true });
+    mkdirSync(globalRoot, { recursive: true });
+
+    // ghost-1: live sibling + .tmp + .old (.tmp gets cleaned because live exists)
+    mkdirSync(join(claudeProjectRoot, "ghost-1"));
+    mkdirSync(join(claudeProjectRoot, "ghost-1.tmp"));
+    mkdirSync(join(claudeProjectRoot, "ghost-1.old"));
+    writeFileSync(join(claudeProjectRoot, "ghost-1.tmp", "garbage.txt"), "leftover");
+
+    // ghost-2: just a .old/ in the fallback root (.old has no invariant)
+    mkdirSync(join(fallbackRoot, "ghost-2.old"));
+
+    // ghost-3: live sibling + .tmp in the global root
+    mkdirSync(join(globalRoot, "ghost-3"));
+    mkdirSync(join(globalRoot, "ghost-3.tmp"));
+
+    const result = cleanupOrphans({});
+    assert.equal(result.cleaned.length, 4);
+
+    assert.ok(!existsSync(join(claudeProjectRoot, "ghost-1.tmp")));
+    assert.ok(!existsSync(join(claudeProjectRoot, "ghost-1.old")));
+    assert.ok(!existsSync(join(fallbackRoot, "ghost-2.old")));
+    assert.ok(!existsSync(join(globalRoot, "ghost-3.tmp")));
+    // Live siblings preserved
+    assert.ok(existsSync(join(claudeProjectRoot, "ghost-1")));
+    assert.ok(existsSync(join(globalRoot, "ghost-3")));
+  });
+
+  it("cleanupOrphans preserves a .tmp/ whose live target is missing (Windows recovery)", () => {
+    // This is the safety invariant proof — a .tmp/ with no live
+    // sibling is the user's only copy of a skill that crashed
+    // mid-rename on Windows, and must not be deleted.
+    const root = join(process.cwd(), ".claude", "skills");
+    mkdirSync(join(root, "recoverable.tmp"), { recursive: true });
+    writeFileSync(join(root, "recoverable.tmp", "SKILL.md"), "---\nname: recoverable\n---\nUser's only copy.\n");
+
+    const result = cleanupOrphans({});
+    assert.equal(result.cleaned.length, 0, "no orphans should be cleaned");
+    assert.ok(existsSync(join(root, "recoverable.tmp", "SKILL.md")), "recoverable .tmp must survive");
+  });
+
+  it("write recovers when a stale .tmp/ from a crashed run is present", () => {
+    const skill = multiFileSkill();
+    // Pre-populate stale .tmp/ with garbage that would conflict
+    const targetDir = resolvePlacementDir("claudeProject", "pdf-helper");
+    mkdirSync(`${targetDir}.tmp`, { recursive: true });
+    writeFileSync(`${targetDir}.tmp/old-garbage.txt`, "x");
+
+    const result = writeSkillDir(skill, { vendors: ["claudeCode"] });
+    const dir = result.written[0];
+
+    // Old garbage should be gone; new files should be present
+    assert.ok(!existsSync(join(dir, "old-garbage.txt")));
+    for (const file of skill.files) {
+      assert.ok(existsSync(join(dir, file.path)));
+    }
+    // No .tmp/ leftover
+    assert.ok(!existsSync(`${targetDir}.tmp`));
+  });
+});
+
+describe("file-write.mjs integration — remove + .gitignore", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("write then remove leaves the skills root empty", () => {
+    writeSkillDir(multiFileSkill(), { vendors: ["claudeCode"] });
+    const result = removeSkillDir("pdf-helper", { vendors: ["claudeCode"] });
+    assert.equal(result.removed.length, 1);
+    const root = join(process.cwd(), ".claude", "skills");
+    if (existsSync(root)) {
+      const entries = readdirSync(root);
+      assert.equal(entries.length, 0, "skills root should be empty after remove");
+    }
+  });
+
+  it("write to fallback creates .gitignore entry; remove does not delete it", () => {
+    writeSkillDir(multiFileSkill(), { vendors: ["cursor"] });
+    const giBefore = readFileSync(join(process.cwd(), ".gitignore"), "utf-8");
+    assert.match(giBefore, /\/skills\//);
+
+    removeSkillDir("pdf-helper", { vendors: ["cursor"] });
+    const giAfter = readFileSync(join(process.cwd(), ".gitignore"), "utf-8");
+    // remove should not touch .gitignore
+    assert.equal(giAfter, giBefore);
+  });
+});

package/src/test/lib/artifact-registry.test.mjs

@@ -0,0 +1,268 @@
+/**
+ * CI enforcement test for the artifact registry (#885).
+ *
+ * Architect tightening #1: the artifact-registry test must be
+ * BIDIRECTIONAL. It's not enough to iterate registry entries and
+ * assert each has a matching remover — that catches "descriptor
+ * without implementation" but misses the more dangerous direction,
+ * "new merger writes a file we never catalogued."
+ *
+ * The checks below:
+ *
+ *   1. Filesystem → registry:
+ *      - Every file in `src/lib/mergers/*.mjs` (installer modules)
+ *        must be declared in MERGER_EXPECTED, which maps installer
+ *        names to the registry ids they produce. A new merger file
+ *        without an expected-set entry FAILS this test.
+ *      - Every file in `src/lib/removers/*.mjs` (uninstaller
+ *        modules) must be declared in REMOVER_EXPECTED, which
+ *        maps remover names to the registry ids they delete. A new
+ *        remover file without an expected-set entry FAILS.
+ *
+ *   2. Registry → filesystem:
+ *      - Every descriptor id in ARTIFACT_REGISTRY must appear in
+ *        REMOVER_EXPECTED or DIRECTORY_ARTIFACT_IDS (the inline-
+ *        handled directory removals in uninstall.mjs). A new
+ *        descriptor without a remover mapping FAILS.
+ *
+ *   3. Mutual consistency:
+ *      - Every registry id in MERGER_EXPECTED also appears in
+ *        REMOVER_EXPECTED or DIRECTORY_ARTIFACT_IDS. A merger that
+ *        writes an artifact with no remover path FAILS.
+ *
+ * When this test fails, the fix is always either (a) update the
+ * expected-set in this test because the change was intentional
+ * (adding a new merger/remover pair), or (b) update the registry
+ * because the implementation drifted. NEVER silence the test — that
+ * defeats the entire drift-protection mechanism.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { ARTIFACT_REGISTRY } from "../../lib/artifact-registry.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const LIB_DIR = join(__dirname, "..", "..", "lib");
+const MERGERS_DIR = join(LIB_DIR, "mergers");
+const REMOVERS_DIR = join(LIB_DIR, "removers");
+
+/**
+ * Maps each installer merger file (by basename without `.mjs`) to
+ * the registry descriptor ids it produces. The init flow writes
+ * through these mergers; every installed artifact must correspond
+ * to a catalogued descriptor so the uninstaller can find it.
+ *
+ * UPDATE this table in the same PR that adds a new merger. The
+ * "filesystem → registry" assertion below reads the directory and
+ * requires every file to appear here. A missing entry fails with:
+ *
+ *   "merger X.mjs has no entry in MERGER_EXPECTED"
+ *
+ * which points directly at this file.
+ */
+const MERGER_EXPECTED = Object.freeze({
+  "claude-mcp": ["claude-mcp-entry"],
+  "cursor-mcp": ["cursor-mcp-entry"],
+  "vscode-mcp": ["vscode-mcp-entry", "vscode-mcp-input"],
+  "windsurf-mcp": ["windsurf-mcp-entry"],
+  "env-local": ["env-local-key"],
+  gitignore: ["gitignore-entries"],
+  // Session-sync installer added by #884. Writes the hook entry that
+  // the `settings` remover (src/lib/removers/settings.mjs) identifies
+  // via SESSION_HOOK_FINGERPRINT. One installer module, two target
+  // paths: project-local (`.claude/settings.local.json`) when called
+  // without --global, user-wide (`~/.claude/settings.local.json`)
+  // with --global. Each path has its own registry descriptor so
+  // `skillrepo uninstall` and `skillrepo uninstall --global` both
+  // know to look in the right place. Round-trip contracts are
+  // verified in src/test/mergers/session-hook.test.mjs.
+  "session-hook": ["settings-session-hook", "settings-session-hook-global"],
+});
+
+/**
+ * Maps each remover file (by basename without `.mjs`) to the
+ * registry descriptor ids it tears down. Symmetric to
+ * MERGER_EXPECTED — every file in src/lib/removers/ must appear
+ * here.
+ */
+const REMOVER_EXPECTED = Object.freeze({
+  "claude-mcp": ["claude-mcp-entry"],
+  "cursor-mcp": ["cursor-mcp-entry"],
+  "vscode-mcp": ["vscode-mcp-entry", "vscode-mcp-input"],
+  "windsurf-mcp": ["windsurf-mcp-entry"],
+  "env-local": ["env-local-key"],
+  gitignore: ["gitignore-entries"],
+  // One remover file (settings.mjs), two descriptor ids — project-
+  // local and global variants go through the same walk with the
+  // settings remover's `{ global }` option.
+  settings: ["settings-session-hook", "settings-session-hook-global"],
+});
+
+/**
+ * Registry ids handled inline by uninstall.mjs's
+ * `removeDirectoryArtifact` (not by a dedicated remover module).
+ * These are the `kind: "directory"` descriptors in the registry.
+ */
+const DIRECTORY_ARTIFACT_IDS = Object.freeze([
+  "skills-dir-project",
+  "skills-dir-global",
+  "global-config-dir",
+]);
+
+/**
+ * Read an mjs directory and return an array of basenames without
+ * extension, excluding any hidden files or subdirectories.
+ */
+function listMjsBasenames(dir) {
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isFile() && d.name.endsWith(".mjs"))
+    .map((d) => d.name.replace(/\.mjs$/, ""));
+}
+
+describe("artifact-registry: drift enforcement", () => {
+  it("every file in src/lib/mergers/ is declared in MERGER_EXPECTED", () => {
+    // Filesystem-first direction: a new merger with no expected-set
+    // entry fails here. This is the load-bearing check — it catches
+    // "engineer added a new write path without updating the catalog."
+    const found = listMjsBasenames(MERGERS_DIR);
+    for (const name of found) {
+      assert.ok(
+        MERGER_EXPECTED[name],
+        `merger ${name}.mjs has no entry in MERGER_EXPECTED. ` +
+          `Add it to src/test/lib/artifact-registry.test.mjs AND add ` +
+          `a matching remover + registry descriptor.`,
+      );
+    }
+  });
+
+  it("every entry in MERGER_EXPECTED has a corresponding mjs file", () => {
+    // Inverse: catches a typo or stale entry in MERGER_EXPECTED
+    // (e.g., someone removed a merger file but forgot to trim this
+    // table). Low-severity drift but still worth catching.
+    const found = new Set(listMjsBasenames(MERGERS_DIR));
+    for (const name of Object.keys(MERGER_EXPECTED)) {
+      assert.ok(
+        found.has(name),
+        `MERGER_EXPECTED names ${name}.mjs but the file does not exist at ${MERGERS_DIR}.`,
+      );
+    }
+  });
+
+  it("every file in src/lib/removers/ is declared in REMOVER_EXPECTED", () => {
+    const found = listMjsBasenames(REMOVERS_DIR);
+    for (const name of found) {
+      assert.ok(
+        REMOVER_EXPECTED[name],
+        `remover ${name}.mjs has no entry in REMOVER_EXPECTED. ` +
+          `Add it to src/test/lib/artifact-registry.test.mjs AND confirm ` +
+          `its target ids are in ARTIFACT_REGISTRY.`,
+      );
+    }
+  });
+
+  it("every entry in REMOVER_EXPECTED has a corresponding mjs file", () => {
+    const found = new Set(listMjsBasenames(REMOVERS_DIR));
+    for (const name of Object.keys(REMOVER_EXPECTED)) {
+      assert.ok(
+        found.has(name),
+        `REMOVER_EXPECTED names ${name}.mjs but the file does not exist at ${REMOVERS_DIR}.`,
+      );
+    }
+  });
+
+  it("every registry descriptor id has a remover or is an inline directory removal", () => {
+    // Registry-first direction: catches "descriptor added but no
+    // one implemented the removal."
+    const allImplementedIds = new Set([
+      ...Object.values(REMOVER_EXPECTED).flat(),
+      ...DIRECTORY_ARTIFACT_IDS,
+    ]);
+    for (const d of ARTIFACT_REGISTRY) {
+      assert.ok(
+        allImplementedIds.has(d.id),
+        `ARTIFACT_REGISTRY id "${d.id}" has no remover. Either add ` +
+          `it to REMOVER_EXPECTED (with a matching src/lib/removers/ ` +
+          `file) or to DIRECTORY_ARTIFACT_IDS if it's a whole-directory ` +
+          `removal handled inline by uninstall.mjs.`,
+      );
+    }
+  });
+
+  it("every REMOVER_EXPECTED id exists in ARTIFACT_REGISTRY", () => {
+    // Catches a typo in the expected-set that doesn't match a real
+    // descriptor.
+    const registryIds = new Set(ARTIFACT_REGISTRY.map((d) => d.id));
+    for (const [removerName, ids] of Object.entries(REMOVER_EXPECTED)) {
+      for (const id of ids) {
+        assert.ok(
+          registryIds.has(id),
+          `REMOVER_EXPECTED["${removerName}"] references id "${id}" ` +
+            `but ARTIFACT_REGISTRY has no descriptor with that id.`,
+        );
+      }
+    }
+  });
+
+  it("every MERGER_EXPECTED id has a matching descriptor AND a remover path", () => {
+    // Mutual consistency: a merger that installs an artifact must
+    // have both a registry descriptor AND a teardown path (direct
+    // remover or inline directory removal). Otherwise we're
+    // writing state the user can never clean up.
+    const registryIds = new Set(ARTIFACT_REGISTRY.map((d) => d.id));
+    const allImplementedIds = new Set([
+      ...Object.values(REMOVER_EXPECTED).flat(),
+      ...DIRECTORY_ARTIFACT_IDS,
+    ]);
+    for (const [mergerName, ids] of Object.entries(MERGER_EXPECTED)) {
+      for (const id of ids) {
+        assert.ok(
+          registryIds.has(id),
+          `MERGER_EXPECTED["${mergerName}"] references id "${id}" ` +
+            `but ARTIFACT_REGISTRY has no descriptor with that id.`,
+        );
+        assert.ok(
+          allImplementedIds.has(id),
+          `MERGER_EXPECTED["${mergerName}"] installs id "${id}" but ` +
+            `no remover is bound to it. A write with no teardown is ` +
+            `exactly the drift #885 exists to prevent.`,
+        );
+      }
+    }
+  });
+
+  it("every DIRECTORY_ARTIFACT_ID is a directory-kind descriptor in the registry", () => {
+    for (const id of DIRECTORY_ARTIFACT_IDS) {
+      const d = ARTIFACT_REGISTRY.find((x) => x.id === id);
+      assert.ok(d, `DIRECTORY_ARTIFACT_IDS references unknown id ${id}`);
+      assert.equal(
+        d.kind,
+        "directory",
+        `DIRECTORY_ARTIFACT_IDS contains non-directory descriptor ${id} (kind=${d.kind})`,
+      );
+    }
+  });
+
+  it("descriptor kind enum is limited to the known set", () => {
+    // Catches a descriptor that uses a `kind` the dispatch table
+    // doesn't understand — would produce a runtime "no remover
+    // bound" error at uninstall time rather than a clean test failure.
+    const VALID_KINDS = new Set([
+      "json-key",
+      "json-input",
+      "line",
+      "section",
+      "directory",
+    ]);
+    for (const d of ARTIFACT_REGISTRY) {
+      assert.ok(
+        VALID_KINDS.has(d.kind),
+        `descriptor ${d.id} has unknown kind "${d.kind}". Allowed: ` +
+          `${[...VALID_KINDS].join(", ")}`,
+      );
+    }
+  });
+});