skillrepo 3.2.0 → 4.1.0

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

@@ -148,6 +148,61 @@ describe("validateFilePath", () => {
     const err = validateFilePath("%E0%A4%A");
     assert.match(err, /URL encoding/);
   });
+
+  // QA cross-PR review (#1252): lock the current behavior of the
+  // safety pre-check against backslash + Unicode-encoded traversal
+  // patterns. validateFilePath uses an ASCII `..` substring check —
+  // backslash variants reduce to ASCII-`..` after decode and ARE
+  // caught; the full-width-period U+FF0E variant is NOT caught.
+  // Both behaviors are intentional:
+  //   • Catching the backslash forms is correct and we lock it so a
+  //     future regex tightening doesn't accidentally drop them.
+  //   • NOT catching the full-width form is a documented limitation
+  //     of the path-preserving CLI — the registry-side validator at
+  //     `src/lib/skills/file-validation.ts` is the authoritative
+  //     security boundary. Locking the gap with this test forces a
+  //     future author who tries to "fix" this without the depth
+  //     check or registry validator backing them up to confront the
+  //     actual invariant.
+  it("rejects backslash-style path traversal (..\\\\etc\\\\passwd)", () => {
+    // Backslash-style traversal still contains the literal `..`
+    // substring, so the existing ASCII check catches it.
+    const err = validateFilePath("..\\etc\\passwd");
+    assert.match(err, /traversal/);
+  });
+
+  it("rejects URL-encoded backslash path traversal (..%5Cetc%5Cpasswd)", () => {
+    // After decodeURIComponent, this becomes `..\etc\passwd`. The
+    // ASCII `..` substring check still fires — locking that this
+    // wrapping doesn't bypass the check.
+    const err = validateFilePath("..%5Cetc%5Cpasswd");
+    assert.match(err, /traversal/);
+  });
+
+  it("does NOT catch full-width period Unicode traversal (．．/etc/passwd) — known gap", () => {
+    // U+FF0E (FULLWIDTH FULL STOP) is visually identical to the
+    // ASCII period but is a different codepoint. The ASCII `..`
+    // substring check does NOT match this sequence. The CLI's
+    // validateFilePath returns null (accepts the path) because:
+    //   • The substring check fires only on ASCII `..`.
+    //   • There is no traversal at the resolved-path level — `．．`
+    //     is just a normal directory name on disk.
+    //   • Depth here is 2 segments, well under MAX_PATH_DEPTH=5.
+    //
+    // The registry-side validator at
+    // `src/lib/skills/file-validation.ts` MUST also reject paths with
+    // homoglyph-style traversal attempts. The CLI is path-preserving
+    // and is NOT the security boundary; the registry is. This test
+    // pins the current behavior and exists as a forcing function:
+    // any future contributor who reads it and assumes the CLI is the
+    // authority should be redirected to the server-side validator.
+    const result = validateFilePath("．．/etc/passwd");
+    assert.equal(
+      result,
+      null,
+      "Locking known limitation: the CLI's ASCII substring check does not catch full-width-period traversal. The server-side validator is the authoritative security boundary. See file-validation.ts.",
+    );
+  });
 });
 
 // ── isValidSkillName ────────────────────────────────────────────────────
@@ -220,31 +275,34 @@ describe("placementTargetsFor", () => {
   beforeEach(setupSandbox);
   afterEach(teardownSandbox);
 
-  it("returns [claudeGlobal] for --global", () => {
-    assert.deepEqual(placementTargetsFor({ global: true }), ["claudeGlobal"]);
+  it("returns [claudeGlobal] for --global claudeCode", () => {
+    assert.deepEqual(
+      placementTargetsFor({ global: true, vendors: ["claudeCode"] }),
+      ["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 [agentsProject] for vendor=cursor only", () => {
+    assert.deepEqual(placementTargetsFor({ vendors: ["cursor"] }), ["agentsProject"]);
   });
 
-  it("returns [claudeProject, projectFallback] for both", () => {
+  it("returns [claudeProject, agentsProject] for both", () => {
     assert.deepEqual(
       placementTargetsFor({ vendors: ["claudeCode", "cursor"] }),
-      ["claudeProject", "projectFallback"],
+      ["claudeProject", "agentsProject"],
     );
   });
 
-  it("dedupes the fallback when multiple non-claude vendors are present", () => {
+  it("dedupes the agents target when multiple cohort vendors are present", () => {
     const targets = placementTargetsFor({
-      vendors: ["cursor", "windsurf", "vscode"],
+      vendors: ["cursor", "windsurf", "copilot"],
     });
-    // Only one projectFallback — not three
-    assert.equal(targets.filter((t) => t === "projectFallback").length, 1);
+    // Only one agentsProject — not three
+    assert.equal(targets.filter((t) => t === "agentsProject").length, 1);
   });
 
   it("throws on empty vendors without --global", () => {
@@ -282,9 +340,9 @@ describe("resolvePlacementDir", () => {
     );
   });
 
-  it("resolves projectFallback under cwd /skills/", () => {
-    const dir = resolvePlacementDir("projectFallback", "pdf-helper");
-    assert.equal(dir, join(process.cwd(), "skills", "pdf-helper"));
+  it("resolves agentsProject under cwd/.agents/skills/<name>", () => {
+    const dir = resolvePlacementDir("agentsProject", "pdf-helper");
+    assert.equal(dir, join(process.cwd(), ".agents", "skills", "pdf-helper"));
   });
 
   it("throws on unknown target", () => {
@@ -455,35 +513,39 @@ describe("writeSkillDir — happy path", () => {
     }
   });
 
-  it("writes to global home dir with --global", () => {
+  it("writes to global home dir with --global --agent claudeCode", () => {
     const skill = minimalSkill();
-    const result = writeSkillDir(skill, { global: true });
+    const result = writeSkillDir(skill, {
+      global: true,
+      vendors: ["claudeCode"],
+    });
     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", () => {
+  it("writes to .agents/skills/ when only a cohort vendor is requested", () => {
     const skill = minimalSkill();
     const result = writeSkillDir(skill, { vendors: ["cursor"] });
     assert.equal(result.written.length, 1);
-    // Use join() for the expected fragment so Windows's "\" separator
-    // matches. The forward-slash literal would fail on windows-latest.
-    assert.ok(result.written[0].includes(join("skills", "pdf-helper")));
-    // .gitignore should now contain /skills/ (that literal — it's the
-    // gitignore pattern, not a filesystem path — and gitignore uses
-    // forward slashes even on Windows, per git's own conventions).
+    assert.ok(
+      result.written[0].includes(join(".agents", "skills", "pdf-helper")),
+      `expected dir under .agents/skills/, got ${result.written[0]}`,
+    );
+    // .gitignore should now contain `.agents/skills/` — the gitignore
+    // pattern uses forward slashes on every platform per git's
+    // conventions.
     const gi = readFileSync(join(process.cwd(), ".gitignore"), "utf-8");
-    assert.match(gi, /\/skills\//);
+    assert.match(gi, /\.agents\/skills\//);
     assert.match(gi, /SkillRepo/);
   });
 
-  it("idempotent .gitignore management — does not double-add /skills/", () => {
+  it("idempotent .gitignore management — does not double-add .agents/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");
+    const matches = gi.match(/\.agents\/skills\//g) || [];
+    assert.equal(matches.length, 1, ".gitignore should have exactly one .agents/skills/ entry");
   });
 
   it("appends to an existing .gitignore without clobbering", () => {
@@ -492,7 +554,7 @@ describe("writeSkillDir — happy path", () => {
     const gi = readFileSync(join(process.cwd(), ".gitignore"), "utf-8");
     assert.match(gi, /node_modules/);
     assert.match(gi, /\.env/);
-    assert.match(gi, /\/skills\//);
+    assert.match(gi, /\.agents\/skills\//);
   });
 });
 
@@ -601,6 +663,95 @@ describe("writeSkillDir — update path", () => {
     assert.ok(existsSync(join(result.written[0], "SKILL.md")));
     assert.ok(!existsSync(`${targetDir}.tmp`));
   });
+
+  // QA cross-PR review (#1252): the existing tests cover stale `.tmp/`
+  // recovery (a previous crash before the rename dance completed) and
+  // the `.tmp/`-occupied-by-a-file edge case, but NOT the symmetric
+  // case where `.old/` is left behind by a previous crash. The .old/
+  // dir is created in step 2 of the rename dance and removed in
+  // step 4 — a crash between the two leaves it stranded. The next
+  // writeSkillDir call detects-and-cleans it via the
+  // `if (existsSync(oldDir))` branch in writeSkillToDir.
+  //
+  // Skipping on Windows: the POSIX-only rename dance is the code path
+  // that exposes the stale-`.old/` branch. Windows uses a different
+  // `rmSync(targetDir) → renameSync(tmpDir, targetDir)` flow with no
+  // intermediate `.old/` step at all — there's nothing equivalent to
+  // verify.
+  it("succeeds when a stale .old/ from a prior crash is present", { skip: process.platform === "win32" }, () => {
+    // Pre-create the live target with v1 content.
+    writeSkillDir(minimalSkill(), { vendors: ["claudeCode"] });
+
+    const targetDir = resolvePlacementDir("claudeProject", "pdf-helper");
+    const oldDir = `${targetDir}.old`;
+
+    // Simulate a previous crash: a stale `.old/` survives next to the
+    // live target. The next write must detect-and-clean it before
+    // staging the current target into place. The crash artifact is a
+    // directory with a marker file we'll confirm is gone after the
+    // write; if the cleanup branch were skipped, the stale `.old/`
+    // would block the renameSync(targetDir, oldDir) step (POSIX
+    // rename onto an existing directory fails with ENOTEMPTY).
+    mkdirSync(oldDir, { recursive: true });
+    writeFileSync(join(oldDir, "ghost.txt"), "leftover from a prior crash");
+
+    // The actual write — should clean the stale `.old/` and complete.
+    const updated = minimalSkill({
+      files: [
+        {
+          path: "SKILL.md",
+          content: "---\nname: pdf-helper\ndescription: After recovery.\n---\n\nv2.\n",
+        },
+      ],
+    });
+    const result = writeSkillDir(updated, { vendors: ["claudeCode"] });
+
+    // The new content is at the live target.
+    const skillMd = readFileSync(join(result.written[0], "SKILL.md"), "utf-8");
+    assert.match(skillMd, /v2/);
+
+    // The stale `.old/` is gone — including the ghost file marker.
+    assert.ok(!existsSync(oldDir), "stale .old/ must be cleaned during the next write");
+    // Step 4 of the rename dance also cleans the post-rename .old/,
+    // so the post-state is "no .old/ at all" regardless of which
+    // branch fired. We assert the absence; the marker-file path
+    // proves the cleanup was the pre-flight branch (a no-op cleanup
+    // would have left ghost.txt in place because the live target's
+    // own .old/ is fresh content from THIS write, not the marker).
+  });
+
+  it("succeeds when both stale .tmp/ AND stale .old/ from a prior crash are present", { skip: process.platform === "win32" }, () => {
+    // Compound recovery scenario: a prior write crashed mid-dance,
+    // leaving BOTH a stale .tmp/ (from step 1, populating new files)
+    // AND a stale .old/ (from step 2, after the live target was
+    // moved aside but step 3's rename never landed). The next write
+    // must clean both before proceeding.
+    writeSkillDir(minimalSkill(), { vendors: ["claudeCode"] });
+
+    const targetDir = resolvePlacementDir("claudeProject", "pdf-helper");
+    const tmpDir = `${targetDir}.tmp`;
+    const oldDir = `${targetDir}.old`;
+
+    mkdirSync(tmpDir, { recursive: true });
+    writeFileSync(join(tmpDir, "tmp-leftover.txt"), "from a crashed step 1");
+    mkdirSync(oldDir, { recursive: true });
+    writeFileSync(join(oldDir, "old-leftover.txt"), "from a crashed step 2");
+
+    const updated = minimalSkill({
+      files: [
+        {
+          path: "SKILL.md",
+          content: "---\nname: pdf-helper\ndescription: Recovered.\n---\n\nv3.\n",
+        },
+      ],
+    });
+    const result = writeSkillDir(updated, { vendors: ["claudeCode"] });
+
+    const skillMd = readFileSync(join(result.written[0], "SKILL.md"), "utf-8");
+    assert.match(skillMd, /v3/);
+    assert.ok(!existsSync(tmpDir), "stale .tmp/ must be cleaned");
+    assert.ok(!existsSync(oldDir), "stale .old/ must be cleaned");
+  });
 });
 
 describe("writeSkillDir — return shape", () => {
@@ -770,14 +921,14 @@ describe("cleanupOrphans", () => {
     // 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 agentsRoot = join(process.cwd(), ".agents", "skills");
     const globalRoot = join(process.env.HOME, ".claude", "skills");
     mkdirSync(claudeRoot, { recursive: true });
-    mkdirSync(fallbackRoot, { recursive: true });
+    mkdirSync(agentsRoot, { 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(agentsRoot, "ghost.old")); // .old has no invariant — always cleaned
     mkdirSync(join(globalRoot, "ghost"));     // live sibling for the .tmp below
     mkdirSync(join(globalRoot, "ghost.tmp"));
 
@@ -795,4 +946,54 @@ describe("cleanupOrphans", () => {
     const result = cleanupOrphans({ vendors: ["claudeCode"] });
     assert.deepEqual(result.cleaned, []);
   });
+
+  // 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:
+  //   • .tmp/ — the user's only recovered copy of a crashed-mid-write
+  //     skill when live target is missing → MUST be preserved
+  //     (invariant #2 in the cleanupOrphans header docstring).
+  //   • .old/ — transient state of the rename dance with no recovery
+  //     value when the live target is missing AND a .tmp/ exists
+  //     (the .tmp/ IS the recovery) → must be cleaned.
+  //
+  // If this test fails because cleanupOrphans cleans .tmp/ when
+  // live target is missing, that's a real regression of invariant #2
+  // — DO NOT change the test to match wrong behavior.
+  it("preserves .tmp/ but cleans .old/ when live target is missing", () => {
+    const root = join(process.cwd(), ".claude", "skills");
+    mkdirSync(root, { recursive: true });
+
+    // Stage the permutation: <name>.tmp/ + <name>.old/ + NO live <name>/
+    const tmpDir = join(root, "ghost.tmp");
+    const oldDir = join(root, "ghost.old");
+    mkdirSync(tmpDir);
+    writeFileSync(join(tmpDir, "tmp-content.txt"), "user's only copy of a crashed-mid-write skill");
+    mkdirSync(oldDir);
+    writeFileSync(join(oldDir, "old-content.txt"), "transient state with no recovery value");
+
+    // Live target is intentionally absent
+    assert.ok(!existsSync(join(root, "ghost")), "precondition: no live target");
+
+    const result = cleanupOrphans({ vendors: ["claudeCode"] });
+
+    // .tmp/ is preserved (recovery invariant)
+    assert.ok(
+      existsSync(tmpDir),
+      ".tmp/ must be preserved when live target is missing — it is the user's only copy",
+    );
+    assert.ok(
+      existsSync(join(tmpDir, "tmp-content.txt")),
+      "the .tmp/ contents must survive intact",
+    );
+
+    // .old/ is cleaned (no recovery value because the .tmp/ IS the
+    // recovery; .old/ would be the pre-replacement live target,
+    // which is precisely what's missing here)
+    assert.ok(!existsSync(oldDir), ".old/ must be cleaned regardless of live-target presence");
+
+    // The summary reports exactly the .old/ cleanup
+    assert.equal(result.cleaned.length, 1, "exactly one orphan cleaned (.old/, not .tmp/)");
+    assert.match(result.cleaned[0], /ghost\.old$/);
+  });
 });

package/src/test/lib/mcp-merge.test.mjs

@@ -19,7 +19,7 @@ import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from "nod
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
-import { mergeMcpForVendors, printManualMcpInstructions } from "../../lib/mcp-merge.mjs";
+import { mergeMcpForVendors } from "../../lib/mcp-merge.mjs";
 import { createCaptureStream } from "../helpers/capture-stream.mjs";
 import {
   captureHome,
@@ -302,7 +302,8 @@ describe("mergeMcpForVendors — failure handling", () => {
   });
 
   it("dedupes duplicate vendors (round-1 review fix)", async () => {
-    // --ide claude,claude used to run the merger twice. Now dedupes.
+    // --agent claude,claude used to run the merger twice. Now dedupes
+    // both at parse time and inside mergeMcpForVendors as defense-in-depth.
     const results = await mergeMcpForVendors({
       vendors: ["claudeCode", "claudeCode", "cursor", "cursor"],
       mcpUrl: "https://x.com/mcp",
@@ -313,6 +314,26 @@ describe("mergeMcpForVendors — failure handling", () => {
     assert.equal(results[0].vendor, "claudeCode");
     assert.equal(results[1].vendor, "cursor");
   });
+
+  it("silently skips registry vendors with hasMcp:false (gemini, codex, cline)", async () => {
+    // Cohort vendors without a documented MCP merger must NOT report
+    // 'failed' — they're a deliberate registry classification.
+    const results = await mergeMcpForVendors({
+      vendors: ["claudeCode", "gemini", "codex", "cline", "cursor"],
+      mcpUrl: "https://x.com/mcp",
+      yes: true,
+      io: { stdout, stderr },
+    });
+    const reportedKeys = results.map((r) => r.vendor);
+    assert.deepEqual(
+      reportedKeys,
+      ["claudeCode", "cursor"],
+      "only the two MCP-supported vendors should appear in results",
+    );
+    for (const r of results) {
+      assert.equal(r.outcome, "merged", `${r.vendor} should be merged, got ${r.outcome}`);
+    }
+  });
 });
 
 // ── mergeMcpForVendors — input validation ──────────────────────────────
@@ -336,16 +357,3 @@ describe("mergeMcpForVendors — input validation", () => {
   });
 });
 
-// ── printManualMcpInstructions ─────────────────────────────────────────
-
-describe("printManualMcpInstructions", () => {
-  it("prints a copy-pasteable MCP config blob", () => {
-    const out = createCaptureStream();
-    printManualMcpInstructions("https://skillrepo.dev/api/mcp", { stdout: out });
-    const text = out.text();
-    assert.match(text, /mcpServers/);
-    assert.match(text, /skillrepo/);
-    assert.match(text, /https:\/\/skillrepo\.dev\/api\/mcp/);
-    assert.match(text, /SKILLREPO_ACCESS_KEY/);
-  });
-});

package/src/test/lib/paths.test.mjs

@@ -1,9 +1,9 @@
 /**
- * Unit tests for the new paths.mjs exports added in PR1 of #646.
+ * Unit tests for the skill placement path resolvers in paths.mjs.
  *
  * The pre-existing exports (claudeMcpJson, cursorMcpJson, etc.) are
  * exercised indirectly by the existing mergers tests; this file
- * focuses on the new skill placement + gitignore exports.
+ * focuses on the skill placement + gitignore exports.
  */
 
 import { describe, it, beforeEach, afterEach } from "node:test";
@@ -15,10 +15,14 @@ import { tmpdir, homedir } from "node:os";
 import {
   claudeSkillsProject,
   claudeSkillsGlobal,
-  projectSkillsFallback,
-  projectSkillsFallbackRoot,
   claudeSkillsProjectRoot,
   claudeSkillsGlobalRoot,
+  agentsSkillsProject,
+  agentsSkillsProjectRoot,
+  agentsSkillsGlobal,
+  agentsSkillsGlobalRoot,
+  windsurfSkillsGlobal,
+  windsurfSkillsGlobalRoot,
   gitignorePath,
 } from "../../lib/paths.mjs";
 import {
@@ -59,28 +63,60 @@ describe("paths.mjs — skill placement targets", () => {
 
   it("claudeSkillsGlobal is under HOME/.claude/skills/<name>", () => {
     const dir = claudeSkillsGlobal("pdf-helper");
-    // homedir() reads HOME on POSIX so respects our sandbox
     assert.equal(dir, join(homedir(), ".claude", "skills", "pdf-helper"));
   });
 
-  it("projectSkillsFallback is under cwd/skills/<name>", () => {
-    const dir = projectSkillsFallback("pdf-helper");
-    assert.equal(dir, join(process.cwd(), "skills", "pdf-helper"));
-  });
-
   it("claudeSkillsProjectRoot is the parent of project-local skills", () => {
-    const root = claudeSkillsProjectRoot();
-    assert.equal(root, join(process.cwd(), ".claude", "skills"));
+    assert.equal(
+      claudeSkillsProjectRoot(),
+      join(process.cwd(), ".claude", "skills"),
+    );
   });
 
   it("claudeSkillsGlobalRoot is the parent of personal skills", () => {
-    const root = claudeSkillsGlobalRoot();
-    assert.equal(root, join(homedir(), ".claude", "skills"));
+    assert.equal(claudeSkillsGlobalRoot(), join(homedir(), ".claude", "skills"));
+  });
+
+  it("agentsSkillsProject is under cwd/.agents/skills/<name>", () => {
+    assert.equal(
+      agentsSkillsProject("pdf-helper"),
+      join(process.cwd(), ".agents", "skills", "pdf-helper"),
+    );
+  });
+
+  it("agentsSkillsProjectRoot is the parent of cohort skills", () => {
+    assert.equal(
+      agentsSkillsProjectRoot(),
+      join(process.cwd(), ".agents", "skills"),
+    );
+  });
+
+  it("agentsSkillsGlobal is under HOME/.agents/skills/<name>", () => {
+    assert.equal(
+      agentsSkillsGlobal("pdf-helper"),
+      join(homedir(), ".agents", "skills", "pdf-helper"),
+    );
+  });
+
+  it("agentsSkillsGlobalRoot is the parent of personal cohort skills", () => {
+    assert.equal(
+      agentsSkillsGlobalRoot(),
+      join(homedir(), ".agents", "skills"),
+    );
+  });
+
+  it("windsurfSkillsGlobal is under HOME/.codeium/windsurf/skills/<name>", () => {
+    assert.equal(
+      windsurfSkillsGlobal("pdf-helper"),
+      join(homedir(), ".codeium", "windsurf", "skills", "pdf-helper"),
+    );
   });
 
-  it("projectSkillsFallbackRoot is the parent of fallback skills", () => {
-    const root = projectSkillsFallbackRoot();
-    assert.equal(root, join(process.cwd(), "skills"));
+  it("windsurfSkillsGlobalRoot is the parent of Windsurf personal skills", () => {
+    assert.equal(
+      windsurfSkillsGlobalRoot(),
+      join(homedir(), ".codeium", "windsurf", "skills"),
+    );
   });
 
   it("gitignorePath is at cwd/.gitignore", () => {