skillrepo 4.3.0 → 4.5.0

package/src/test/lib/placement-walk.test.mjs

@@ -0,0 +1,453 @@
+/**
+ * Unit tests for `src/lib/placement-walk.mjs` (#1555).
+ *
+ * Sandboxed filesystem tests. Uses `sandbox-home.mjs` (sets BOTH
+ * HOME and USERPROFILE) so the walker's `~/.codeium/windsurf/skills/`
+ * lookups don't escape the sandbox on Windows.
+ *
+ * Each test scenario seeds a fake placement directory under the
+ * sandbox CWD (for project-scope targets) or sandbox HOME (for
+ * global-scope targets), runs the walker, and asserts on the
+ * resulting SHAs and structure.
+ *
+ * The SHAs are NOT pinned to specific hex values — that's
+ * `crypto-shas.test.mjs`'s job. Here we assert SHA stability
+ * properties (changing content changes the SHA) and structural
+ * properties (one entry per skill, multi-vendor cohort expansion).
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdirSync,
+  writeFileSync,
+  rmSync,
+  mkdtempSync,
+  existsSync,
+  chmodSync,
+  symlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { walkDetectedPlacements, walkPlacementTarget } from "../../lib/placement-walk.mjs";
+import { computeSkillShas } from "../../lib/crypto-shas.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+} from "../helpers/sandbox-home.mjs";
+
+let sandbox;
+let originalCwd;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
+
+function setup() {
+  sandbox = mkdtempSync(join(tmpdir(), "placement-walk-"));
+  mkdirSync(join(sandbox, "project"), { recursive: true });
+  mkdirSync(join(sandbox, "home"), { recursive: true });
+  originalCwd = process.cwd();
+  originalHomeEnv = captureHome();
+  process.chdir(join(sandbox, "project"));
+  setSandboxHome(join(sandbox, "home"));
+}
+
+function teardown() {
+  process.chdir(originalCwd);
+  restoreHome(originalHomeEnv);
+  if (sandbox && existsSync(sandbox)) {
+    rmSync(sandbox, { recursive: true, force: true });
+  }
+}
+
+/** Seed a skill directory at the given target's parent. */
+function seedSkill(targetParent, skillName, files) {
+  const dir = join(targetParent, skillName);
+  mkdirSync(dir, { recursive: true });
+  for (const file of files) {
+    const filePath = join(dir, ...file.path.split("/"));
+    mkdirSync(join(filePath, ".."), { recursive: true });
+    writeFileSync(filePath, file.content, "utf8");
+  }
+}
+
+/** Make a standard SKILL.md content with the canonical frontmatter. */
+function skillMd(name, body = `# ${name}\n`) {
+  return `---\nname: ${name}\ndescription: ${name} skill\n---\n\n${body}`;
+}
+
+// ── walkPlacementTarget ────────────────────────────────────────────────
+
+describe("walkPlacementTarget", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("returns empty array when the parent dir does not exist", () => {
+    // No `.claude/skills/` created — walker must not throw.
+    assert.deepEqual(walkPlacementTarget("claudeProject"), []);
+  });
+
+  it("returns empty array for an unknown target (defensive)", () => {
+    assert.deepEqual(walkPlacementTarget("notARealTarget"), []);
+  });
+
+  it("returns one entry per skill subdirectory at the target", () => {
+    const parent = join(process.cwd(), ".claude", "skills");
+    seedSkill(parent, "pdf-helper", [
+      { path: "SKILL.md", content: skillMd("pdf-helper") },
+    ]);
+    seedSkill(parent, "code-review", [
+      { path: "SKILL.md", content: skillMd("code-review") },
+    ]);
+    const result = walkPlacementTarget("claudeProject");
+    assert.equal(result.length, 2);
+    const names = result.map((r) => r.skillName).sort();
+    assert.deepEqual(names, ["code-review", "pdf-helper"]);
+  });
+
+  it("computes SHAs that match crypto-shas on the same content", () => {
+    // Cross-check that the disk walker produces the same digests as
+    // the in-memory helper that runSync uses. Without this property,
+    // a fresh sync would immediately report `edited` on every skill
+    // because the persisted SHA would never match the read-back SHA.
+    const parent = join(process.cwd(), ".claude", "skills");
+    const content = skillMd("matching-skill");
+    seedSkill(parent, "matching-skill", [{ path: "SKILL.md", content }]);
+
+    const result = walkPlacementTarget("claudeProject");
+    assert.equal(result.length, 1);
+
+    const expected = computeSkillShas([{ path: "SKILL.md", content }]);
+    assert.equal(result[0].skillMdSha256, expected.skillMdSha256);
+    assert.equal(result[0].filesSha256, expected.filesSha256);
+  });
+
+  it("handles multi-file skills (SKILL.md + references/ + scripts/)", () => {
+    const parent = join(process.cwd(), ".claude", "skills");
+    const files = [
+      { path: "SKILL.md", content: skillMd("multi") },
+      { path: "references/notes.md", content: "# Notes\n" },
+      { path: "scripts/run.sh", content: "#!/bin/sh\necho hi\n" },
+    ];
+    seedSkill(parent, "multi", files);
+
+    const result = walkPlacementTarget("claudeProject");
+    assert.equal(result.length, 1);
+
+    const expected = computeSkillShas(files);
+    assert.equal(result[0].skillMdSha256, expected.skillMdSha256);
+    assert.equal(result[0].filesSha256, expected.filesSha256);
+  });
+
+  it("skips .tmp/ and .old/ orphan directories", () => {
+    const parent = join(process.cwd(), ".claude", "skills");
+    seedSkill(parent, "live-skill", [
+      { path: "SKILL.md", content: skillMd("live-skill") },
+    ]);
+    seedSkill(parent, "crashed.tmp", [
+      { path: "SKILL.md", content: skillMd("crashed") },
+    ]);
+    seedSkill(parent, "rollback.old", [
+      { path: "SKILL.md", content: skillMd("rollback") },
+    ]);
+
+    const result = walkPlacementTarget("claudeProject");
+    assert.equal(result.length, 1);
+    assert.equal(result[0].skillName, "live-skill");
+  });
+
+  it("returns null SHAs (not throw) when a skill dir contains an unreadable file", () => {
+    // Permission-denied simulation: write a file, then chmod 000.
+    // Skipped on Windows (chmod is a no-op there) and on root (root
+    // bypasses permission checks).
+    if (process.platform === "win32" || process.getuid?.() === 0) return;
+
+    const parent = join(process.cwd(), ".claude", "skills");
+    const skillDir = join(parent, "unreadable");
+    mkdirSync(skillDir, { recursive: true });
+    const filePath = join(skillDir, "SKILL.md");
+    writeFileSync(filePath, skillMd("unreadable"), "utf8");
+    chmodSync(filePath, 0o000);
+
+    try {
+      const result = walkPlacementTarget("claudeProject");
+      assert.equal(result.length, 1);
+      assert.equal(result[0].skillName, "unreadable");
+      assert.equal(result[0].skillMdSha256, null);
+      assert.equal(result[0].filesSha256, null);
+    } finally {
+      chmodSync(filePath, 0o644);
+    }
+  });
+
+  it("continues past an unreadable sibling and still produces null SHAs (deterministic)", () => {
+    // Multi-file regression for the return→continue fix in
+    // walkSkillDirRecursive. A skill with one unreadable file +
+    // multiple readable siblings used to bail on the unreadable
+    // entry and silently drop the remaining files from the hash
+    // input. Outcome was still "null SHAs → edited" (correct), but
+    // the ordering of readdirSync could affect intermediate state.
+    //
+    // After the fix: we continue past the unreadable file, the
+    // readError flag is set, and the caller's gate at
+    // computeShasFromDir discards the partial accum → null SHAs.
+    // Behavior is deterministic regardless of readdirSync ordering.
+    if (process.platform === "win32" || process.getuid?.() === 0) return;
+
+    const parent = join(process.cwd(), ".claude", "skills");
+    const skillDir = join(parent, "partial");
+    mkdirSync(join(skillDir, "references"), { recursive: true });
+    const skillMdPath = join(skillDir, "SKILL.md");
+    const refPath = join(skillDir, "references", "notes.md");
+    const lockedPath = join(skillDir, "locked.md");
+
+    writeFileSync(skillMdPath, skillMd("partial"), "utf8");
+    writeFileSync(refPath, "# notes\n", "utf8");
+    writeFileSync(lockedPath, "blocked\n", "utf8");
+    chmodSync(lockedPath, 0o000);
+
+    try {
+      const result = walkPlacementTarget("claudeProject");
+      assert.equal(result.length, 1);
+      const partial = result[0];
+      assert.equal(partial.skillName, "partial");
+      // Null SHAs — the partial-accum gate fired.
+      assert.equal(partial.skillMdSha256, null);
+      assert.equal(partial.filesSha256, null);
+    } finally {
+      chmodSync(lockedPath, 0o644);
+    }
+  });
+
+  it("skips non-directory entries at the parent root", () => {
+    const parent = join(process.cwd(), ".claude", "skills");
+    mkdirSync(parent, { recursive: true });
+    // Stray file at the root of the skills/ dir
+    writeFileSync(join(parent, "README.txt"), "junk", "utf8");
+    seedSkill(parent, "real-skill", [
+      { path: "SKILL.md", content: skillMd("real-skill") },
+    ]);
+
+    const result = walkPlacementTarget("claudeProject");
+    assert.equal(result.length, 1);
+    assert.equal(result[0].skillName, "real-skill");
+  });
+
+  it("returns null SHAs for an empty skill directory", () => {
+    const parent = join(process.cwd(), ".claude", "skills");
+    mkdirSync(join(parent, "empty"), { recursive: true });
+
+    const result = walkPlacementTarget("claudeProject");
+    assert.equal(result.length, 1);
+    assert.equal(result[0].skillName, "empty");
+    // No files read → null SHAs → drift classifier treats as `edited`.
+    assert.equal(result[0].skillMdSha256, null);
+    assert.equal(result[0].filesSha256, null);
+  });
+
+  it("does NOT crash on a circular symlink inside a skill directory", () => {
+    // Stack-overflow regression guard. Previously the walker used
+    // statSync (which follows symlinks), so a `references/loop -> .`
+    // symlink caused infinite recursion. lstatSync + isSymbolicLink
+    // skip avoids the crash. Documented as the spec choice: symlinks
+    // are not valid skill content per agentskills.io.
+    if (process.platform === "win32") return; // symlink creation requires admin on Windows
+
+    const parent = join(process.cwd(), ".claude", "skills");
+    const skillDir = join(parent, "with-loop");
+    mkdirSync(join(skillDir, "references"), { recursive: true });
+    writeFileSync(
+      join(skillDir, "SKILL.md"),
+      skillMd("with-loop"),
+      "utf8",
+    );
+    writeFileSync(
+      join(skillDir, "references", "real.md"),
+      "# real\n",
+      "utf8",
+    );
+    // Circular symlink: references/loop points back to the skill root.
+    // Pre-fix this would infinite-recurse.
+    symlinkSync(skillDir, join(skillDir, "references", "loop"));
+
+    // Must complete without throwing or hanging.
+    const result = walkPlacementTarget("claudeProject");
+    assert.equal(result.length, 1);
+    assert.equal(result[0].skillName, "with-loop");
+    // SHAs are valid (the symlink was skipped, the real files were hashed).
+    assert.equal(typeof result[0].skillMdSha256, "string");
+    assert.equal(result[0].skillMdSha256.length, 64);
+  });
+
+  it("skips a symlink-to-directory at the placements root (no recursion into target)", () => {
+    if (process.platform === "win32") return;
+
+    const parent = join(process.cwd(), ".claude", "skills");
+    mkdirSync(parent, { recursive: true });
+    // A skill placed elsewhere (outside .claude/skills/).
+    const outsideDir = join(process.cwd(), "outside");
+    mkdirSync(outsideDir, { recursive: true });
+    writeFileSync(join(outsideDir, "SKILL.md"), skillMd("outside"), "utf8");
+    // Symlink at the placement root pointing OUT of the skills dir.
+    // The walker must not treat this as a valid skill.
+    symlinkSync(outsideDir, join(parent, "symlinked-skill"));
+    // Also seed a real skill so we can verify the walker still
+    // enumerates the legitimate one.
+    seedSkill(parent, "real-skill", [
+      { path: "SKILL.md", content: skillMd("real-skill") },
+    ]);
+
+    const result = walkPlacementTarget("claudeProject");
+    assert.equal(result.length, 1);
+    assert.equal(result[0].skillName, "real-skill");
+    // Belt-and-suspenders: explicitly assert the symlinked entry is
+    // absent from the result. The length-and-first-name checks above
+    // would catch a regression where the symlink was enumerated as
+    // a second result, but they don't document the intent as
+    // clearly as a direct absence check.
+    const names = result.map((r) => r.skillName);
+    assert.ok(
+      !names.includes("symlinked-skill"),
+      "symlinked-skill entry must be absent from the result",
+    );
+  });
+
+  it("skips a symlink-to-file inside a skill directory (no content read from outside)", () => {
+    if (process.platform === "win32") return;
+
+    const parent = join(process.cwd(), ".claude", "skills");
+    const skillDir = join(parent, "linkholder");
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(join(skillDir, "SKILL.md"), skillMd("linkholder"), "utf8");
+
+    // Target file lives outside the skill dir.
+    const outsideFile = join(process.cwd(), "outside.txt");
+    writeFileSync(outsideFile, "secrets\n", "utf8");
+    symlinkSync(outsideFile, join(skillDir, "link.md"));
+
+    const result = walkPlacementTarget("claudeProject");
+    assert.equal(result.length, 1);
+
+    // The expected hash is computed from SKILL.md alone — the
+    // symlink and its target are NOT included in the projection.
+    const expected = computeSkillShas([
+      { path: "SKILL.md", content: skillMd("linkholder") },
+    ]);
+    assert.equal(result[0].skillMdSha256, expected.skillMdSha256);
+    assert.equal(result[0].filesSha256, expected.filesSha256);
+  });
+
+  it("walks the agentsProject cohort root", () => {
+    const parent = join(process.cwd(), ".agents", "skills");
+    seedSkill(parent, "cohort-skill", [
+      { path: "SKILL.md", content: skillMd("cohort-skill") },
+    ]);
+
+    const result = walkPlacementTarget("agentsProject");
+    assert.equal(result.length, 1);
+    assert.equal(result[0].skillName, "cohort-skill");
+  });
+});
+
+// ── walkDetectedPlacements ──────────────────────────────────────────────
+
+describe("walkDetectedPlacements", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("returns an empty map when no vendors detected", () => {
+    assert.equal(walkDetectedPlacements([]).size, 0);
+  });
+
+  it("returns an empty map for unknown vendor keys", () => {
+    assert.equal(walkDetectedPlacements(["not-a-real-vendor"]).size, 0);
+  });
+
+  it("returns one entry per (vendor, skill) for a Claude Code skill", () => {
+    const parent = join(process.cwd(), ".claude", "skills");
+    seedSkill(parent, "claude-only", [
+      { path: "SKILL.md", content: skillMd("claude-only") },
+    ]);
+
+    const placements = walkDetectedPlacements(["claudeCode"]);
+    assert.equal(placements.size, 1);
+    assert.ok(placements.has("claudeCode::project::claude-only"));
+    const entry = placements.get("claudeCode::project::claude-only");
+    assert.equal(entry.vendorKey, "claudeCode");
+    assert.equal(entry.scope, "project");
+    assert.equal(entry.target, "claudeProject");
+    assert.equal(entry.present, true);
+    assert.equal(typeof entry.skillMdSha256, "string");
+  });
+
+  it("expands the same .agents/skills/ skill across all detected cohort vendors", () => {
+    // Cohort vendors (cursor, windsurf, gemini, codex, cline, copilot)
+    // all share `agentsProject`. Walking once produces one disk read;
+    // expansion emits one entry per detected vendor so list.mjs can
+    // render the per-vendor placement breakdown without re-reading.
+    const parent = join(process.cwd(), ".agents", "skills");
+    seedSkill(parent, "shared-cohort", [
+      { path: "SKILL.md", content: skillMd("shared-cohort") },
+    ]);
+
+    const placements = walkDetectedPlacements(["cursor", "windsurf"]);
+    assert.equal(placements.size, 2);
+    const cursor = placements.get("cursor::project::shared-cohort");
+    const windsurf = placements.get("windsurf::project::shared-cohort");
+    assert.ok(cursor);
+    assert.ok(windsurf);
+    // Identical SHAs — both see the same physical file.
+    assert.equal(cursor.skillMdSha256, windsurf.skillMdSha256);
+    assert.equal(cursor.filesSha256, windsurf.filesSha256);
+    // Different vendor keys, same target.
+    assert.equal(cursor.vendorKey, "cursor");
+    assert.equal(windsurf.vendorKey, "windsurf");
+    assert.equal(cursor.target, "agentsProject");
+    assert.equal(windsurf.target, "agentsProject");
+  });
+
+  it("walks each unique target only once (cohort vendors do not multiply reads)", () => {
+    // Indirect verification: if the walk read files multiple times,
+    // we'd see correct behavior anyway because the operation is
+    // idempotent. So we verify a STRUCTURAL property — every cohort
+    // vendor in the input that maps to the same target emits one
+    // entry per skill, regardless of cohort size.
+    const parent = join(process.cwd(), ".agents", "skills");
+    seedSkill(parent, "one", [{ path: "SKILL.md", content: skillMd("one") }]);
+    seedSkill(parent, "two", [{ path: "SKILL.md", content: skillMd("two") }]);
+
+    const placements = walkDetectedPlacements(["cursor", "gemini", "codex"]);
+    // 3 vendors × 2 skills = 6 entries.
+    assert.equal(placements.size, 6);
+  });
+
+  it("walks both Claude Code AND cohort targets when both detected", () => {
+    const claudeParent = join(process.cwd(), ".claude", "skills");
+    const cohortParent = join(process.cwd(), ".agents", "skills");
+    seedSkill(claudeParent, "for-claude", [
+      { path: "SKILL.md", content: skillMd("for-claude") },
+    ]);
+    seedSkill(cohortParent, "for-cohort", [
+      { path: "SKILL.md", content: skillMd("for-cohort") },
+    ]);
+
+    const placements = walkDetectedPlacements(["claudeCode", "cursor"]);
+    assert.equal(placements.size, 2);
+    assert.ok(placements.has("claudeCode::project::for-claude"));
+    assert.ok(placements.has("cursor::project::for-cohort"));
+    // Critically, claudeCode does NOT see for-cohort and cursor
+    // does NOT see for-claude — placement targets are distinct.
+    assert.equal(placements.has("claudeCode::project::for-cohort"), false);
+    assert.equal(placements.has("cursor::project::for-claude"), false);
+  });
+
+  it("ignores vendors with null projectTarget (e.g. future scope changes)", () => {
+    // Defense in depth: every current registry entry has a non-null
+    // projectTarget. If a future entry ever has null (e.g. a personal-
+    // scope-only vendor), this guard ensures we don't blow up.
+    // We can't easily fixture this without registry surgery, but
+    // we cover the code path by passing an empty array.
+    assert.equal(walkDetectedPlacements([]).size, 0);
+  });
+});