skillrepo 3.2.0 → 4.1.0

package/src/test/lib/detect-agents.test.mjs

@@ -0,0 +1,336 @@
+/**
+ * Unit tests for src/lib/detect-agents.mjs (#1236, Phase 3 of #876).
+ *
+ * Coverage:
+ *   - Per-signal-type probes (env / home / project)
+ *   - OR semantics: any signal fires → detected
+ *   - Priority order: env > home > project (first-fire wins for the
+ *     human-readable `reason`)
+ *   - All seven registry agents produce a result (registry-driven)
+ *   - Cross-platform path resolution via sandbox-home
+ *   - Truthy-vs-empty env handling (empty string is NOT truthy)
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { detectAgents } from "../../lib/detect-agents.mjs";
+import { AGENT_REGISTRY } from "../../lib/agent-registry.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+} from "../helpers/sandbox-home.mjs";
+
+let sandbox;
+let originalCwd;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
+/** @type {Record<string, string | undefined>} */
+let originalEnvVars;
+
+// Every env var the registry references as a detection signal. Each
+// test snapshots and restores these so a stray env var on the host
+// machine cannot leak into the assertions.
+const ENV_VAR_NAMES = Array.from(
+  new Set(
+    AGENT_REGISTRY.flatMap((entry) =>
+      entry.detectionSignals
+        .filter((s) => s.type === "env")
+        .map((s) => s.value),
+    ),
+  ),
+);
+
+function setup() {
+  sandbox = mkdtempSync(join(tmpdir(), "cli-detect-agents-"));
+  mkdirSync(join(sandbox, "home"), { recursive: true });
+  mkdirSync(join(sandbox, "project"), { recursive: true });
+  originalCwd = process.cwd();
+  originalHomeEnv = captureHome();
+  // Snapshot every detection-relevant env var. Delete each so the
+  // baseline is "no signals firing" — individual tests opt-in to the
+  // env vars they want to set.
+  originalEnvVars = {};
+  for (const name of ENV_VAR_NAMES) {
+    originalEnvVars[name] = process.env[name];
+    delete process.env[name];
+  }
+  process.chdir(join(sandbox, "project"));
+  setSandboxHome(join(sandbox, "home"));
+}
+
+function teardown() {
+  process.chdir(originalCwd);
+  restoreHome(originalHomeEnv);
+  for (const name of ENV_VAR_NAMES) {
+    if (originalEnvVars[name] === undefined) delete process.env[name];
+    else process.env[name] = originalEnvVars[name];
+  }
+  if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+}
+
+function findResult(detections, key) {
+  return detections.find((d) => d.key === key);
+}
+
+// ── Baseline ────────────────────────────────────────────────────────
+
+describe("detectAgents — baseline", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("returns one result per registry entry, in registry order", () => {
+    const result = detectAgents();
+    assert.equal(result.length, AGENT_REGISTRY.length);
+    for (let i = 0; i < AGENT_REGISTRY.length; i++) {
+      assert.equal(result[i].key, AGENT_REGISTRY[i].key);
+      assert.equal(result[i].displayName, AGENT_REGISTRY[i].displayName);
+    }
+  });
+
+  it("returns detected=false and reason=null for every agent in a clean sandbox", () => {
+    const result = detectAgents();
+    for (const detection of result) {
+      assert.equal(
+        detection.detected,
+        false,
+        `${detection.key} should not be detected in a clean sandbox`,
+      );
+      assert.equal(detection.reason, null);
+    }
+  });
+});
+
+// ── Per-signal-type probes ──────────────────────────────────────────
+
+describe("detectAgents — env signal", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("detects Claude Code via CLAUDECODE env var", () => {
+    process.env.CLAUDECODE = "1";
+    const result = findResult(detectAgents(), "claudeCode");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "CLAUDECODE=1");
+  });
+
+  it("detects Cursor via CURSOR_AGENT env var", () => {
+    process.env.CURSOR_AGENT = "1";
+    const result = findResult(detectAgents(), "cursor");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "CURSOR_AGENT=1");
+  });
+
+  it("detects Cursor via CURSOR_CLI env var (fallback signal)", () => {
+    process.env.CURSOR_CLI = "1";
+    const result = findResult(detectAgents(), "cursor");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "CURSOR_CLI=1");
+  });
+
+  it("detects Gemini via GEMINI_CLI env var", () => {
+    process.env.GEMINI_CLI = "1";
+    const result = findResult(detectAgents(), "gemini");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "GEMINI_CLI=1");
+  });
+
+  it("detects Cline via CLINE_ACTIVE='true'", () => {
+    process.env.CLINE_ACTIVE = "true";
+    const result = findResult(detectAgents(), "cline");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "CLINE_ACTIVE=true");
+  });
+
+  it("does NOT fire on empty-string env var (e.g., CLAUDECODE='')", () => {
+    process.env.CLAUDECODE = "";
+    const result = findResult(detectAgents(), "claudeCode");
+    assert.equal(result.detected, false);
+    assert.equal(result.reason, null);
+  });
+
+  it("does NOT detect Codex via env var (Codex has no documented active-session env)", () => {
+    // Defensive lock: a future maintainer who adds CODEX_HOME as an
+    // env signal would silently produce false positives because
+    // CODEX_HOME is a config var Codex *reads*, not one it sets in
+    // spawned shells. This test holds the line.
+    process.env.CODEX_HOME = "/some/path";
+    const result = findResult(detectAgents(), "codex");
+    assert.equal(result.detected, false);
+  });
+});
+
+describe("detectAgents — home signal", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("detects Claude Code via ~/.claude/ directory", () => {
+    mkdirSync(join(process.env.HOME, ".claude"), { recursive: true });
+    const result = findResult(detectAgents(), "claudeCode");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "~/.claude/");
+  });
+
+  it("detects Cursor via ~/.cursor/ directory", () => {
+    mkdirSync(join(process.env.HOME, ".cursor"), { recursive: true });
+    const result = findResult(detectAgents(), "cursor");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "~/.cursor/");
+  });
+
+  it("detects Windsurf via ~/.codeium/windsurf/ directory (Codeium prefix)", () => {
+    mkdirSync(join(process.env.HOME, ".codeium", "windsurf"), {
+      recursive: true,
+    });
+    const result = findResult(detectAgents(), "windsurf");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "~/.codeium/windsurf/");
+  });
+
+  it("detects Codex via ~/.codex/ directory (HOME-only — no env signal)", () => {
+    mkdirSync(join(process.env.HOME, ".codex"), { recursive: true });
+    const result = findResult(detectAgents(), "codex");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "~/.codex/");
+  });
+
+  it("detects Copilot via ~/.copilot/ directory", () => {
+    mkdirSync(join(process.env.HOME, ".copilot"), { recursive: true });
+    const result = findResult(detectAgents(), "copilot");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "~/.copilot/");
+  });
+});
+
+describe("detectAgents — project signal", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("detects Claude Code via project .claude/ directory", () => {
+    mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+    const result = findResult(detectAgents(), "claudeCode");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, ".claude/");
+  });
+
+  it("detects Cursor via project .cursor/ directory", () => {
+    mkdirSync(join(process.cwd(), ".cursor"), { recursive: true });
+    const result = findResult(detectAgents(), "cursor");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, ".cursor/");
+  });
+
+  it("detects Windsurf via project .windsurf/ directory", () => {
+    mkdirSync(join(process.cwd(), ".windsurf"), { recursive: true });
+    const result = findResult(detectAgents(), "windsurf");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, ".windsurf/");
+  });
+
+  it("detects Gemini via project .gemini/ directory", () => {
+    mkdirSync(join(process.cwd(), ".gemini"), { recursive: true });
+    const result = findResult(detectAgents(), "gemini");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, ".gemini/");
+  });
+
+  it("detects Codex via project .codex/ directory", () => {
+    mkdirSync(join(process.cwd(), ".codex"), { recursive: true });
+    const result = findResult(detectAgents(), "codex");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, ".codex/");
+  });
+
+  it("detects Cline via project .cline/ directory", () => {
+    mkdirSync(join(process.cwd(), ".cline"), { recursive: true });
+    const result = findResult(detectAgents(), "cline");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, ".cline/");
+  });
+
+  it("detects Copilot via .github/skills/ directory", () => {
+    mkdirSync(join(process.cwd(), ".github", "skills"), { recursive: true });
+    const result = findResult(detectAgents(), "copilot");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, ".github/skills/");
+  });
+});
+
+// ── OR semantics + priority order ───────────────────────────────────
+
+describe("detectAgents — OR semantics + priority", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("fires when only one of multiple signals is present", () => {
+    // Cursor has env + home + project; only project is set here.
+    mkdirSync(join(process.cwd(), ".cursor"), { recursive: true });
+    const result = findResult(detectAgents(), "cursor");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, ".cursor/");
+  });
+
+  it("env signal wins over home signal when both fire", () => {
+    process.env.CLAUDECODE = "1";
+    mkdirSync(join(process.env.HOME, ".claude"), { recursive: true });
+    const result = findResult(detectAgents(), "claudeCode");
+    assert.equal(result.detected, true);
+    // env first by registry signal order — the formatted reason
+    // confirms the env signal won.
+    assert.equal(result.reason, "CLAUDECODE=1");
+  });
+
+  it("env signal wins over project signal when both fire", () => {
+    process.env.CLAUDECODE = "1";
+    mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+    const result = findResult(detectAgents(), "claudeCode");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "CLAUDECODE=1");
+  });
+
+  it("home signal wins over project signal when env is absent", () => {
+    mkdirSync(join(process.env.HOME, ".claude"), { recursive: true });
+    mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+    const result = findResult(detectAgents(), "claudeCode");
+    assert.equal(result.detected, true);
+    assert.equal(result.reason, "~/.claude/");
+  });
+
+  it("primary env signal wins over fallback env signal (Cursor: CURSOR_AGENT > CURSOR_CLI)", () => {
+    process.env.CURSOR_AGENT = "1";
+    process.env.CURSOR_CLI = "1";
+    const result = findResult(detectAgents(), "cursor");
+    assert.equal(result.reason, "CURSOR_AGENT=1");
+  });
+});
+
+// ── Registry-driven coverage (the real durability win) ─────────────
+
+describe("detectAgents — registry-driven coverage", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("every agent has at least one detection signal declared", () => {
+    // Locks the registry contract: a future entry that forgets
+    // detectionSignals would silently never fire.
+    for (const entry of AGENT_REGISTRY) {
+      assert.ok(
+        Array.isArray(entry.detectionSignals) &&
+          entry.detectionSignals.length > 0,
+        `${entry.key} must have at least one detection signal`,
+      );
+    }
+  });
+
+  it("every agent's first signal is reachable (probe doesn't throw)", () => {
+    // Smoke test: detectAgents() must succeed regardless of which
+    // signal types the registry uses. A typo'd signal type would
+    // silently return null forever; this test catches that by
+    // proving a clean run completes.
+    assert.doesNotThrow(() => detectAgents());
+  });
+});

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

@@ -0,0 +1,264 @@
+/**
+ * Per-agent placement-target tests for file-write.mjs (#1234).
+ *
+ * The cohort-dedupe assertion is the central piece: every vendor
+ * except claudeCode resolves to `agentsProject`, and the result of
+ * `placementTargetsFor` for a multi-vendor cohort must be one entry,
+ * not six. This is what makes `--agent cursor,windsurf,gemini,codex,
+ * cline,copilot` produce a single write instead of duplicating the
+ * skill across paths nobody reads.
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir, homedir } from "node:os";
+
+import {
+  placementTargetsFor,
+  resolvePlacementDir,
+} from "../../lib/file-write.mjs";
+import { CliError, EXIT_VALIDATION } from "../../lib/errors.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+} from "../helpers/sandbox-home.mjs";
+
+let sandbox;
+let originalCwd;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
+
+function setupSandbox() {
+  sandbox = mkdtempSync(join(tmpdir(), "cli-fw-place-"));
+  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 teardownSandbox() {
+  process.chdir(originalCwd);
+  restoreHome(originalHomeEnv);
+  if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+}
+
+describe("placementTargetsFor — project scope", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("claudeCode → [claudeProject]", () => {
+    assert.deepEqual(
+      placementTargetsFor({ vendors: ["claudeCode"] }),
+      ["claudeProject"],
+    );
+  });
+
+  it("cursor → [agentsProject]", () => {
+    assert.deepEqual(
+      placementTargetsFor({ vendors: ["cursor"] }),
+      ["agentsProject"],
+    );
+  });
+
+  it("windsurf → [agentsProject]", () => {
+    assert.deepEqual(
+      placementTargetsFor({ vendors: ["windsurf"] }),
+      ["agentsProject"],
+    );
+  });
+
+  it("gemini → [agentsProject]", () => {
+    assert.deepEqual(
+      placementTargetsFor({ vendors: ["gemini"] }),
+      ["agentsProject"],
+    );
+  });
+
+  it("codex → [agentsProject]", () => {
+    assert.deepEqual(
+      placementTargetsFor({ vendors: ["codex"] }),
+      ["agentsProject"],
+    );
+  });
+
+  it("cline → [agentsProject]", () => {
+    assert.deepEqual(
+      placementTargetsFor({ vendors: ["cline"] }),
+      ["agentsProject"],
+    );
+  });
+
+  it("copilot → [agentsProject]", () => {
+    assert.deepEqual(
+      placementTargetsFor({ vendors: ["copilot"] }),
+      ["agentsProject"],
+    );
+  });
+
+  it("claudeCode + cursor → [claudeProject, agentsProject]", () => {
+    assert.deepEqual(
+      placementTargetsFor({ vendors: ["claudeCode", "cursor"] }),
+      ["claudeProject", "agentsProject"],
+    );
+  });
+
+  it("cohort dedupe: cursor + windsurf + gemini + codex + cline + copilot → [agentsProject]", () => {
+    const targets = placementTargetsFor({
+      vendors: ["cursor", "windsurf", "gemini", "codex", "cline", "copilot"],
+    });
+    assert.deepEqual(
+      targets,
+      ["agentsProject"],
+      "six cohort vendors must collapse to ONE write",
+    );
+  });
+
+  it("preserves order: first-seen-target wins", () => {
+    const targets = placementTargetsFor({
+      vendors: ["cursor", "claudeCode", "windsurf"],
+    });
+    // cursor pushes agentsProject first, claudeCode pushes claudeProject
+    // second, windsurf is a dedupe of agentsProject.
+    assert.deepEqual(targets, ["agentsProject", "claudeProject"]);
+  });
+});
+
+describe("placementTargetsFor — global scope", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("--global claudeCode → [claudeGlobal]", () => {
+    assert.deepEqual(
+      placementTargetsFor({ global: true, vendors: ["claudeCode"] }),
+      ["claudeGlobal"],
+    );
+  });
+
+  it("--global cursor → [agentsGlobal]", () => {
+    assert.deepEqual(
+      placementTargetsFor({ global: true, vendors: ["cursor"] }),
+      ["agentsGlobal"],
+    );
+  });
+
+  it("--global windsurf → [windsurfGlobal] (vendor-specific personal path)", () => {
+    assert.deepEqual(
+      placementTargetsFor({ global: true, vendors: ["windsurf"] }),
+      ["windsurfGlobal"],
+    );
+  });
+
+  it("--global gemini → [agentsGlobal]", () => {
+    assert.deepEqual(
+      placementTargetsFor({ global: true, vendors: ["gemini"] }),
+      ["agentsGlobal"],
+    );
+  });
+
+  it("--global codex → [agentsGlobal]", () => {
+    assert.deepEqual(
+      placementTargetsFor({ global: true, vendors: ["codex"] }),
+      ["agentsGlobal"],
+    );
+  });
+
+  it("--global cline → [agentsGlobal]", () => {
+    assert.deepEqual(
+      placementTargetsFor({ global: true, vendors: ["cline"] }),
+      ["agentsGlobal"],
+    );
+  });
+
+  it("--global copilot → throws validationError (no personal scope)", () => {
+    assert.throws(
+      () => placementTargetsFor({ global: true, vendors: ["copilot"] }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /has no documented personal scope/.test(err.message),
+    );
+  });
+
+  it("--global cohort dedupes the agents cohort to [agentsGlobal, windsurfGlobal]", () => {
+    const targets = placementTargetsFor({
+      global: true,
+      vendors: ["cursor", "windsurf", "gemini", "codex", "cline"],
+    });
+    // cursor/gemini/codex/cline → agentsGlobal; windsurf → windsurfGlobal.
+    // Order is first-seen.
+    assert.deepEqual(targets, ["agentsGlobal", "windsurfGlobal"]);
+  });
+});
+
+describe("placementTargetsFor — error paths", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("rejects an empty vendors list when not --global", () => {
+    assert.throws(
+      () => placementTargetsFor({ vendors: [] }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("rejects an unknown vendor", () => {
+    assert.throws(
+      () => placementTargetsFor({ vendors: ["jetbrains"] }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("rejects the deleted projectFallback target", () => {
+    assert.throws(
+      () => resolvePlacementDir("projectFallback", "pdf-helper"),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("rejects bare --global with no vendors", () => {
+    // Every caller (init, add, get, update, remove) routes through
+    // `effectiveVendors`, which guarantees a non-empty vendor list
+    // before placementTargetsFor sees it. An empty-vendors call here
+    // is a programming error in a future caller, not a user input —
+    // surface it loudly rather than silently routing to claudeGlobal.
+    assert.throws(
+      () => placementTargetsFor({ global: true, vendors: [] }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+    assert.throws(
+      () => placementTargetsFor({ global: true }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+});
+
+describe("resolvePlacementDir — cross-platform paths", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("agentsProject resolves under cwd/.agents/skills/<name>", () => {
+    assert.equal(
+      resolvePlacementDir("agentsProject", "pdf-helper"),
+      join(process.cwd(), ".agents", "skills", "pdf-helper"),
+    );
+  });
+
+  it("agentsGlobal resolves under HOME/.agents/skills/<name>", () => {
+    assert.equal(
+      resolvePlacementDir("agentsGlobal", "pdf-helper"),
+      join(homedir(), ".agents", "skills", "pdf-helper"),
+    );
+  });
+
+  it("windsurfGlobal resolves under HOME/.codeium/windsurf/skills/<name>", () => {
+    assert.equal(
+      resolvePlacementDir("windsurfGlobal", "pdf-helper"),
+      join(homedir(), ".codeium", "windsurf", "skills", "pdf-helper"),
+    );
+  });
+});