skillrepo 2.0.0 → 3.0.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/cli-config.test.mjs

@@ -0,0 +1,407 @@
+/**
+ * Unit tests for src/lib/cli-config.mjs (PR2 of #646).
+ *
+ * Covers:
+ *   • resolveFlags — every flag, the priority order (CLI flag > config
+ *     file > env var > default), error paths
+ *   • effectiveVendors — defaults, --global override, explicit list
+ *   • parseVendorList edge cases (alias, all, empty, unknown)
+ *
+ * The cli-config helper is shared by all four PR2 commands and PR3a's
+ * write commands, so coverage here is load-bearing.
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { resolveFlags, effectiveVendors } from "../../lib/cli-config.mjs";
+import { CliError, EXIT_AUTH, EXIT_VALIDATION } from "../../lib/errors.mjs";
+
+let sandbox;
+let originalHome;
+let originalEnv;
+
+function setupSandbox() {
+  sandbox = mkdtempSync(join(tmpdir(), "cli-config-"));
+  mkdirSync(join(sandbox, "home", ".claude", "skillrepo"), { recursive: true });
+  originalHome = process.env.HOME;
+  // Snapshot the env vars we mutate so tests don't bleed into each other
+  originalEnv = {
+    SKILLREPO_ACCESS_KEY: process.env.SKILLREPO_ACCESS_KEY,
+    SKILLREPO_URL: process.env.SKILLREPO_URL,
+  };
+  process.env.HOME = join(sandbox, "home");
+  delete process.env.SKILLREPO_ACCESS_KEY;
+  delete process.env.SKILLREPO_URL;
+}
+
+function teardownSandbox() {
+  process.env.HOME = originalHome;
+  if (originalEnv.SKILLREPO_ACCESS_KEY === undefined) {
+    delete process.env.SKILLREPO_ACCESS_KEY;
+  } else {
+    process.env.SKILLREPO_ACCESS_KEY = originalEnv.SKILLREPO_ACCESS_KEY;
+  }
+  if (originalEnv.SKILLREPO_URL === undefined) {
+    delete process.env.SKILLREPO_URL;
+  } else {
+    process.env.SKILLREPO_URL = originalEnv.SKILLREPO_URL;
+  }
+  if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+}
+
+function writeConfig(obj) {
+  writeFileSync(
+    join(sandbox, "home", ".claude", "skillrepo", "config.json"),
+    JSON.stringify(obj),
+  );
+}
+
+// ── resolveFlags — priority order ──────────────────────────────────────
+
+describe("resolveFlags — credential priority", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("uses --key and --url when provided (highest priority)", () => {
+    writeConfig({ apiKey: "config_key", serverUrl: "https://config.example" });
+    process.env.SKILLREPO_ACCESS_KEY = "env_key";
+    process.env.SKILLREPO_URL = "https://env.example";
+
+    const flags = resolveFlags(["--key", "flag_key", "--url", "https://flag.example"]);
+    assert.equal(flags.apiKey, "flag_key");
+    assert.equal(flags.serverUrl, "https://flag.example");
+  });
+
+  it("falls back to config file when CLI flags absent", () => {
+    writeConfig({ apiKey: "config_key", serverUrl: "https://config.example" });
+    process.env.SKILLREPO_ACCESS_KEY = "env_key";
+    process.env.SKILLREPO_URL = "https://env.example";
+
+    const flags = resolveFlags([]);
+    assert.equal(flags.apiKey, "config_key");
+    assert.equal(flags.serverUrl, "https://config.example");
+  });
+
+  it("falls back to env vars when no config file", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "env_key";
+    process.env.SKILLREPO_URL = "https://env.example";
+
+    const flags = resolveFlags([]);
+    assert.equal(flags.apiKey, "env_key");
+    assert.equal(flags.serverUrl, "https://env.example");
+  });
+
+  it("falls back to DEFAULT_URL when nothing provides a URL", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "env_key";
+    const flags = resolveFlags([]);
+    assert.equal(flags.serverUrl, "https://skillrepo.dev");
+  });
+
+  it("throws authError when no key is configured anywhere", () => {
+    assert.throws(
+      () => resolveFlags([]),
+      (err) => err instanceof CliError && err.exitCode === EXIT_AUTH && /No access key/.test(err.message),
+    );
+  });
+
+  it("requireAuth: false skips the no-key error", () => {
+    const flags = resolveFlags([], { requireAuth: false });
+    assert.equal(flags.apiKey, null);
+  });
+
+  it("ignores corrupt config file gracefully", () => {
+    writeFileSync(
+      join(sandbox, "home", ".claude", "skillrepo", "config.json"),
+      "this is not json {{{",
+    );
+    process.env.SKILLREPO_ACCESS_KEY = "env_key";
+    const flags = resolveFlags([]);
+    assert.equal(flags.apiKey, "env_key");
+  });
+
+  it("merges flag override with config-file fallback (mixed)", () => {
+    writeConfig({ apiKey: "config_key", serverUrl: "https://config.example" });
+    // Override only the URL via flag; key still comes from config
+    const flags = resolveFlags(["--url", "https://flag.example"]);
+    assert.equal(flags.apiKey, "config_key");
+    assert.equal(flags.serverUrl, "https://flag.example");
+  });
+});
+
+// ── resolveFlags — skipConfig (round-1 review fix) ────────────────────
+
+describe("resolveFlags — skipConfig", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  // This option was introduced in the round-1 PR3b fix because `init`
+  // needs to own its credential lifecycle end-to-end. Before this
+  // option, `resolveFlags` would silently inject the cached config key
+  // AND eagerly default `serverUrl` to the production URL — making
+  // init's `--force` and stale-key branches dead code. These tests
+  // lock the skipConfig contract: (1) config file is ignored,
+  // (2) production-URL default does NOT apply (caller must supply its
+  // own), (3) env vars still apply because they're explicit runtime
+  // state, not a cached credential.
+
+  it("skipConfig: true ignores the config file entirely", () => {
+    writeConfig({ apiKey: "config_key", serverUrl: "https://config.example" });
+    const flags = resolveFlags([], { requireAuth: false, skipConfig: true });
+    assert.equal(
+      flags.apiKey,
+      null,
+      "config-file key must NOT leak through when skipConfig is set",
+    );
+    assert.equal(
+      flags.serverUrl,
+      null,
+      "config-file URL must NOT leak through when skipConfig is set",
+    );
+  });
+
+  it("skipConfig: true does NOT apply the https://skillrepo.dev default", () => {
+    // Without skipConfig, an empty argv would return the production
+    // URL. With skipConfig, serverUrl stays null so the caller can
+    // decide what to do. This is the specific bug that made init's
+    // `!serverUrl && existingConfig` branch dead code in round 0.
+    const flags = resolveFlags([], { requireAuth: false, skipConfig: true });
+    assert.equal(flags.serverUrl, null);
+    assert.notEqual(flags.serverUrl, "https://skillrepo.dev");
+  });
+
+  it("skipConfig: true still consumes SKILLREPO_URL / SKILLREPO_ACCESS_KEY env vars", () => {
+    // Env vars are explicit runtime state, not cached credentials —
+    // they should still resolve under skipConfig. This matches the
+    // init.mjs flow: `init` reads the env directly in its own
+    // credential collection step too, so the behavior is consistent
+    // whether init is called via `resolveFlags` or not.
+    process.env.SKILLREPO_ACCESS_KEY = "env_key";
+    process.env.SKILLREPO_URL = "https://env.example";
+    const flags = resolveFlags([], { requireAuth: false, skipConfig: true });
+    assert.equal(flags.apiKey, "env_key");
+    assert.equal(flags.serverUrl, "https://env.example");
+  });
+
+  it("skipConfig: true still honors --key and --url flags (highest priority)", () => {
+    writeConfig({ apiKey: "config_key", serverUrl: "https://config.example" });
+    process.env.SKILLREPO_ACCESS_KEY = "env_key";
+    const flags = resolveFlags(
+      ["--key", "flag_key", "--url", "https://flag.example"],
+      { requireAuth: false, skipConfig: true },
+    );
+    // Flags still win — the option only suppresses the config-file
+    // fallback, it doesn't disable flag parsing.
+    assert.equal(flags.apiKey, "flag_key");
+    assert.equal(flags.serverUrl, "https://flag.example");
+  });
+});
+
+// ── resolveFlags — flag parsing ────────────────────────────────────────
+
+describe("resolveFlags — flag parsing", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("parses --global", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    const flags = resolveFlags(["--global"]);
+    assert.equal(flags.global, true);
+  });
+
+  it("parses --json", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    const flags = resolveFlags(["--json"]);
+    assert.equal(flags.json, true);
+  });
+
+  it("parses -k as alias for --key", () => {
+    const flags = resolveFlags(["-k", "k1"]);
+    assert.equal(flags.apiKey, "k1");
+  });
+
+  it("parses -u as alias for --url", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    const flags = resolveFlags(["-u", "https://x"]);
+    assert.equal(flags.serverUrl, "https://x");
+  });
+
+  it("parses --ide claudeCode", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    const flags = resolveFlags(["--ide", "claudeCode"]);
+    assert.deepEqual(flags.vendors, ["claudeCode"]);
+  });
+
+  it("parses --ide alias 'claude' as claudeCode", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    const flags = resolveFlags(["--ide", "claude"]);
+    assert.deepEqual(flags.vendors, ["claudeCode"]);
+  });
+
+  it("parses --ide multi-vendor", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    const flags = resolveFlags(["--ide", "claude,cursor,windsurf"]);
+    assert.deepEqual(flags.vendors, ["claudeCode", "cursor", "windsurf"]);
+  });
+
+  it("parses --ide all as the full vendor list", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    const flags = resolveFlags(["--ide", "all"]);
+    assert.deepEqual(flags.vendors, ["claudeCode", "cursor", "windsurf", "vscode"]);
+  });
+
+  it("rejects --ide cursor,all (mixing all with explicit vendors is ambiguous)", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    assert.throws(
+      () => resolveFlags(["--ide", "cursor,all"]),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION && /cannot mix/.test(err.message),
+    );
+  });
+
+  it("rejects --ide all,cursor in the other order too", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    assert.throws(
+      () => resolveFlags(["--ide", "all,cursor"]),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("accepts --ide all,all (degenerate case dedupes to the full set)", () => {
+    // The `all` token is hard-coded to mean the full vendor list. A
+    // user passing it twice is a degenerate input but unambiguous —
+    // both `all`s expand to the same set, so we accept it. This test
+    // locks the behavior so a future tightening of parseVendorList
+    // doesn't accidentally start rejecting it.
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    const flags = resolveFlags(["--ide", "all,all"]);
+    assert.deepEqual(flags.vendors, ["claudeCode", "cursor", "windsurf", "vscode"]);
+  });
+
+  it("rejects unknown --ide vendor", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    assert.throws(
+      () => resolveFlags(["--ide", "jetbrains"]),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("rejects empty --ide list", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    assert.throws(
+      () => resolveFlags(["--ide", ","]),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("rejects unknown flag without acceptPositional", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    assert.throws(
+      () => resolveFlags(["--bogus"]),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+});
+
+// ── resolveFlags — positional handling ─────────────────────────────────
+
+describe("resolveFlags — positional callback", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("invokes acceptPositional for non-flag args", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    const captured = [];
+    resolveFlags(["@alice/skill"], {
+      acceptPositional(arg) {
+        captured.push(arg);
+        return 1;
+      },
+    });
+    assert.deepEqual(captured, ["@alice/skill"]);
+  });
+
+  it("respects the consume count from acceptPositional", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    const captured = [];
+    resolveFlags(["--limit", "50", "@alice/skill"], {
+      acceptPositional(arg, i, all) {
+        if (arg === "--limit") {
+          captured.push(["limit", all[i + 1]]);
+          return 2;
+        }
+        captured.push(["query", arg]);
+        return 1;
+      },
+    });
+    assert.deepEqual(captured, [["limit", "50"], ["query", "@alice/skill"]]);
+  });
+
+  it("treats positional as unknown when acceptPositional returns false", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    assert.throws(
+      () => resolveFlags(["random"], { acceptPositional: () => false }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("rejects positional when acceptPositional returns 0 (would loop forever)", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    assert.throws(
+      () => resolveFlags(["random"], { acceptPositional: () => 0 }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("rejects positional when acceptPositional returns a negative number", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    assert.throws(
+      () => resolveFlags(["random"], { acceptPositional: () => -1 }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("rejects positional when acceptPositional returns a non-integer", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    assert.throws(
+      () => resolveFlags(["random"], { acceptPositional: () => 1.5 }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("treats positional as unknown when no callback provided", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "k";
+    assert.throws(
+      () => resolveFlags(["random"]),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+});
+
+// ── effectiveVendors ───────────────────────────────────────────────────
+
+describe("effectiveVendors", () => {
+  it("returns ['claudeCode'] by default", () => {
+    assert.deepEqual(effectiveVendors({ vendors: null, global: false }), ["claudeCode"]);
+  });
+
+  it("returns undefined for global mode", () => {
+    assert.equal(effectiveVendors({ vendors: null, global: true }), undefined);
+  });
+
+  it("global overrides explicit vendors", () => {
+    assert.equal(
+      effectiveVendors({ vendors: ["cursor"], global: true }),
+      undefined,
+    );
+  });
+
+  it("returns explicit vendors when set", () => {
+    assert.deepEqual(
+      effectiveVendors({ vendors: ["claudeCode", "cursor"], global: false }),
+      ["claudeCode", "cursor"],
+    );
+  });
+});