skillrepo 1.0.0

package/bin/skillrepo.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+/**
+ * SkillRepo CLI — Set up SkillRepo in any IDE, one command.
+ *
+ * Usage:
+ *   npx skillrepo init [--key <key>] [--url <url>] [--yes]
+ */
+
+import { runInit } from "../src/commands/init.mjs";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (!command || command === "init") {
+  runInit(args.slice(command === "init" ? 1 : 0)).catch((err) => {
+    console.error(`\n  Error: ${err.message}\n`);
+    process.exit(1);
+  });
+} else if (command === "--help" || command === "-h") {
+  console.log(`
+  SkillRepo CLI
+
+  Usage:
+    npx skillrepo init [options]
+
+  Options:
+    --key, -k <key>    Access key (or set SKILLREPO_API_KEY env var)
+    --url, -u <url>    SkillRepo URL (default: https://skillrepo.dev)
+    --yes, -y          Non-interactive mode
+
+  Examples:
+    npx skillrepo init
+    npx skillrepo init --key sk_live_abc123
+    npx skillrepo init --url https://my-skillrepo.com --yes
+`);
+} else if (command === "--version" || command === "-v") {
+  // Read version from package.json
+  import("../package.json", { with: { type: "json" } })
+    .then((pkg) => console.log(pkg.default.version))
+    .catch(() => console.log("1.0.0"));
+} else {
+  console.error(`  Unknown command: ${command}`);
+  console.error(`  Run "npx skillrepo --help" for usage.`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "skillrepo",
+  "version": "1.0.0",
+  "description": "Set up SkillRepo in any IDE — one command",
+  "type": "module",
+  "bin": {
+    "skillrepo": "./bin/skillrepo.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "skills",
+    "ai",
+    "ide",
+    "cursor",
+    "claude",
+    "vscode",
+    "windsurf",
+    "setup"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/atxpace/skill-repo.git",
+    "directory": "packages/cli"
+  },
+  "license": "AGPL-3.0",
+  "scripts": {
+    "test": "find src/test -name '*.test.mjs' | xargs node --test"
+  }
+}

package/src/commands/init.mjs

@@ -0,0 +1,184 @@
+/**
+ * `skillrepo init` — main command orchestrator.
+ *
+ * Flow:
+ * 1. Detect IDEs
+ * 2. Prompt for access key
+ * 3. Validate key + fetch skill mappings
+ * 4. Write all configs
+ * 5. Print summary
+ */
+
+import { detectIdes, formatDetectedIdes, getDetectedIdeKeys } from "../lib/detect-ides.mjs";
+import { fetchSetupPayload, AuthError, SuspendedError, NetworkError } from "../lib/http.mjs";
+import { writeAllConfigs } from "../lib/write-configs.mjs";
+import {
+  printHeader,
+  printStep,
+  printSuccess,
+  printWarning,
+  printError,
+  printResult,
+  printBlank,
+  promptSecret,
+  confirm,
+} from "../lib/prompt.mjs";
+
+const DEFAULT_URL = "https://skillrepo.dev";
+
+/**
+ * Parse CLI flags from argv.
+ * @param {string[]} argv
+ */
+function parseFlags(argv) {
+  const flags = {
+    key: process.env.SKILLREPO_API_KEY || null,
+    url: process.env.SKILLREPO_URL || DEFAULT_URL,
+    yes: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if ((arg === "--key" || arg === "-k") && argv[i + 1]) {
+      flags.key = argv[++i];
+    } else if ((arg === "--url" || arg === "-u") && argv[i + 1]) {
+      flags.url = argv[++i];
+    } else if (arg === "--yes" || arg === "-y") {
+      flags.yes = true;
+    }
+  }
+
+  // Normalize URL
+  flags.url = flags.url.replace(/\/+$/, "");
+
+  return flags;
+}
+
+/**
+ * Run the setup command.
+ * @param {string[]} argv - CLI arguments after the "setup" subcommand
+ */
+export async function runInit(argv) {
+  const flags = parseFlags(argv);
+
+  printHeader("SkillRepo Setup");
+
+  // ── Step 1: Detect IDEs ───────────────────────────────────────────────
+  printStep(1, 4, "Detecting IDEs...");
+
+  const detected = detectIdes();
+  const ideList = formatDetectedIdes(detected);
+  const detectedKeys = getDetectedIdeKeys(detected);
+
+  for (const ide of ideList) {
+    if (ide.detected) {
+      printSuccess(`${ide.name}`);
+    }
+  }
+
+  if (detectedKeys.length === 0 || !Object.values(detected).some(Boolean)) {
+    printWarning("No IDEs detected — defaulting to Claude Code + Cursor");
+  }
+
+  // Confirm IDE selection
+  if (!flags.yes) {
+    const names = detectedKeys.map((k) => ideList.find((i) => i.key === k)?.name).filter(Boolean);
+    const ok = await confirm(`Configure for: ${names.join(", ")}?`);
+    if (!ok) {
+      console.log("  Setup cancelled.");
+      process.exit(0);
+    }
+  }
+
+  printBlank();
+
+  // ── Step 2: Access Key ────────────────────────────────────────────────
+  printStep(2, 4, "Access Key");
+
+  let apiKey = flags.key;
+  if (!apiKey) {
+    apiKey = await promptSecret("Enter your SkillRepo access key (sk_live_...)");
+  }
+
+  if (!apiKey || !apiKey.startsWith("sk_live_")) {
+    printError("Invalid key format. Keys start with sk_live_");
+    printError(`Get your key at ${flags.url}/app/integrations`);
+    process.exit(1);
+  }
+
+  printBlank();
+
+  // ── Step 3: Validate + Fetch ──────────────────────────────────────────
+  printStep(3, 4, "Validating key...");
+
+  let payload;
+  try {
+    payload = await fetchSetupPayload(apiKey, flags.url);
+  } catch (err) {
+    if (err instanceof AuthError) {
+      printError(`Invalid access key. Get your key at ${flags.url}/app/integrations`);
+      process.exit(1);
+    }
+    if (err instanceof SuspendedError) {
+      printError(`Account suspended: ${err.reason || "Contact your admin"}`);
+      process.exit(1);
+    }
+    if (err instanceof NetworkError) {
+      printError(`Cannot reach ${flags.url}. Check your network and the --url flag.`);
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  printSuccess(`Valid. ${payload.skillCount} skills in your library.`);
+
+  if (payload.skillCount === 0) {
+    printWarning("No skills in your library yet. MCP config will be written — skills will activate when you add them.");
+  }
+
+  printBlank();
+
+  // ── Step 4: Write configs ─────────────────────────────────────────────
+  printStep(4, 4, "Writing configuration...");
+  printBlank();
+
+  const mcpUrl = `${flags.url}/api/mcp`;
+
+  let results;
+  try {
+    results = writeAllConfigs({
+      ides: detectedKeys,
+      mcpUrl,
+      apiKey,
+      payload,
+    });
+  } catch (err) {
+    printError(err.message);
+    process.exit(2);
+  }
+
+  for (const r of results) {
+    printResult(r.path, r.action);
+  }
+
+  // ── Summary ───────────────────────────────────────────────────────────
+  printBlank();
+  printSuccess("SkillRepo is ready.");
+  printBlank();
+  console.log("  Next steps:");
+  console.log("  • Commit the generated config files to git");
+  console.log("  • Each team member runs: npx skillrepo setup");
+  console.log("  • SKILLREPO_API_KEY is in .env.local (gitignored)");
+
+  if (detectedKeys.includes("vscode")) {
+    printBlank();
+    console.log("  Note: VS Code will prompt for your access key on first use.");
+  }
+
+  if (detectedKeys.includes("claudeCode")) {
+    printBlank();
+    console.log("  Claude Code: Skills refresh automatically on each session start.");
+  }
+
+  printBlank();
+}

package/src/lib/detect-ides.mjs

@@ -0,0 +1,63 @@
+/**
+ * IDE auto-detection.
+ * Checks for IDE-specific directories/files in the project and home dir.
+ */
+
+import { pathExists } from "./fs-utils.mjs";
+import * as paths from "./paths.mjs";
+
+/**
+ * @typedef {Object} DetectedIdes
+ * @property {boolean} claudeCode
+ * @property {boolean} cursor
+ * @property {boolean} windsurf
+ * @property {boolean} vscode
+ */
+
+/**
+ * Detect which IDEs are configured in the current project.
+ * @returns {DetectedIdes}
+ */
+export function detectIdes() {
+  return {
+    claudeCode:
+      pathExists(paths.claudeMcpJson()) ||
+      pathExists(paths.claudeDir()),
+    cursor: pathExists(paths.cursorDir()),
+    windsurf: pathExists(paths.windsurfDir()),
+    vscode: pathExists(paths.vscodeDir()),
+  };
+}
+
+/**
+ * Format detected IDEs as a human-readable list.
+ * @param {DetectedIdes} detected
+ * @returns {{ name: string; detected: boolean }[]}
+ */
+export function formatDetectedIdes(detected) {
+  return [
+    { name: "Claude Code", key: "claudeCode", detected: detected.claudeCode },
+    { name: "Cursor", key: "cursor", detected: detected.cursor },
+    { name: "Windsurf", key: "windsurf", detected: detected.windsurf },
+    { name: "VS Code + Copilot", key: "vscode", detected: detected.vscode },
+  ];
+}
+
+/**
+ * Get the list of IDE keys that were detected.
+ * If none detected, defaults to Claude Code + Cursor (most common pair).
+ * @param {DetectedIdes} detected
+ * @returns {string[]}
+ */
+export function getDetectedIdeKeys(detected) {
+  const keys = Object.entries(detected)
+    .filter(([, v]) => v)
+    .map(([k]) => k);
+
+  // Default to Claude Code + Cursor if nothing detected
+  if (keys.length === 0) {
+    return ["claudeCode", "cursor"];
+  }
+
+  return keys;
+}

package/src/lib/fs-utils.mjs

@@ -0,0 +1,43 @@
+/**
+ * Safe filesystem utilities.
+ * Creates directories as needed, handles errors cleanly.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+
+/**
+ * Read a file as UTF-8, returning null if it doesn't exist.
+ * Throws on other errors (permission denied, etc.)
+ */
+export function readFileSafe(filePath) {
+  try {
+    return readFileSync(filePath, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+/**
+ * Write a file, creating parent directories as needed.
+ * Throws on permission errors.
+ */
+export function writeFileSafe(filePath, content) {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  // Guard against writing to a directory
+  if (existsSync(filePath) && statSync(filePath).isDirectory()) {
+    throw new Error(`${filePath} is a directory, expected a file`);
+  }
+  writeFileSync(filePath, content, "utf-8");
+}
+
+/**
+ * Check if a path exists (file or directory).
+ */
+export function pathExists(p) {
+  return existsSync(p);
+}

package/src/lib/http.mjs

@@ -0,0 +1,66 @@
+/**
+ * HTTP client for the SkillRepo API.
+ * Uses Node 18+ built-in fetch. Zero dependencies.
+ */
+
+const VERSION = "1.0.0";
+const DEFAULT_URL = "https://skillrepo.dev";
+
+/**
+ * Fetch the setup payload from the SkillRepo API.
+ * @param {string} apiKey - Access key (sk_live_...)
+ * @param {string} [baseUrl] - SkillRepo base URL (defaults to https://skillrepo.dev)
+ * @returns {Promise<object>} The setup payload
+ */
+export async function fetchSetupPayload(apiKey, baseUrl) {
+  const url = `${(baseUrl || DEFAULT_URL).replace(/\/+$/, "")}/api/v1/setup`;
+
+  const res = await fetch(url, {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      Accept: "application/json",
+      "User-Agent": `skillrepo-cli/${VERSION}`,
+    },
+  });
+
+  if (res.status === 401) {
+    const body = await res.json().catch(() => ({}));
+    throw new AuthError(body.error || "Invalid access key");
+  }
+
+  if (res.status === 403) {
+    const body = await res.json().catch(() => ({}));
+    throw new SuspendedError(body.error || "Account suspended", body.reason);
+  }
+
+  if (!res.ok) {
+    throw new NetworkError(`Server returned ${res.status}: ${res.statusText}`);
+  }
+
+  return res.json();
+}
+
+// ── Error types ─────────────────────────────────────────────────────────
+
+export class AuthError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AuthError";
+  }
+}
+
+export class SuspendedError extends Error {
+  constructor(message, reason) {
+    super(message);
+    this.name = "SuspendedError";
+    this.reason = reason;
+  }
+}
+
+export class NetworkError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NetworkError";
+  }
+}

package/src/lib/mergers/claude-mcp.mjs

@@ -0,0 +1,47 @@
+/**
+ * Merger for Claude Code .mcp.json
+ * Format: { mcpServers: { skillrepo: { type: "http", url, headers } } }
+ * Env vars: ${VAR} syntax
+ */
+
+import { readFileSafe, writeFileSafe } from "../fs-utils.mjs";
+import { claudeMcpJson } from "../paths.mjs";
+
+/**
+ * @param {string} mcpUrl
+ * @returns {{ path: string; action: string }}
+ */
+export function mergeClaudeMcpConfig(mcpUrl) {
+  const filePath = claudeMcpJson();
+  const serverEntry = {
+    type: "http",
+    url: mcpUrl,
+    headers: {
+      Authorization: "Bearer ${SKILLREPO_API_KEY}",
+    },
+  };
+
+  const existing = readFileSafe(filePath);
+
+  if (existing === null) {
+    writeFileSafe(filePath, JSON.stringify({ mcpServers: { skillrepo: serverEntry } }, null, 2) + "\n");
+    return { path: ".mcp.json", action: "created" };
+  }
+
+  let config;
+  try {
+    config = JSON.parse(existing);
+  } catch {
+    throw new Error(`Cannot parse .mcp.json — invalid JSON. Fix or delete it, then run setup again.`);
+  }
+
+  if (!config.mcpServers || typeof config.mcpServers !== "object") {
+    config.mcpServers = {};
+  }
+
+  const action = config.mcpServers.skillrepo ? "merged" : "created";
+  config.mcpServers.skillrepo = serverEntry;
+
+  writeFileSafe(filePath, JSON.stringify(config, null, 2) + "\n");
+  return { path: ".mcp.json", action };
+}

package/src/lib/mergers/cursor-mcp.mjs

@@ -0,0 +1,46 @@
+/**
+ * Merger for Cursor .cursor/mcp.json
+ * Format: { mcpServers: { skillrepo: { url, headers } } }
+ * Env vars: ${env:VAR} syntax (different from Claude Code)
+ */
+
+import { readFileSafe, writeFileSafe } from "../fs-utils.mjs";
+import { cursorMcpJson } from "../paths.mjs";
+
+/**
+ * @param {string} mcpUrl
+ * @returns {{ path: string; action: string }}
+ */
+export function mergeCursorMcpConfig(mcpUrl) {
+  const filePath = cursorMcpJson();
+  const serverEntry = {
+    url: mcpUrl,
+    headers: {
+      Authorization: "Bearer ${env:SKILLREPO_API_KEY}",
+    },
+  };
+
+  const existing = readFileSafe(filePath);
+
+  if (existing === null) {
+    writeFileSafe(filePath, JSON.stringify({ mcpServers: { skillrepo: serverEntry } }, null, 2) + "\n");
+    return { path: ".cursor/mcp.json", action: "created" };
+  }
+
+  let config;
+  try {
+    config = JSON.parse(existing);
+  } catch {
+    throw new Error(`Cannot parse .cursor/mcp.json — invalid JSON. Fix or delete it, then run setup again.`);
+  }
+
+  if (!config.mcpServers || typeof config.mcpServers !== "object") {
+    config.mcpServers = {};
+  }
+
+  const action = config.mcpServers.skillrepo ? "merged" : "created";
+  config.mcpServers.skillrepo = serverEntry;
+
+  writeFileSafe(filePath, JSON.stringify(config, null, 2) + "\n");
+  return { path: ".cursor/mcp.json", action };
+}

package/src/lib/mergers/env-local.mjs

@@ -0,0 +1,48 @@
+/**
+ * Merge SKILLREPO_API_KEY into .env.local
+ * Append-only — never overwrite existing keys unless the value differs.
+ */
+
+import { readFileSafe, writeFileSafe } from "../fs-utils.mjs";
+import { envLocal } from "../paths.mjs";
+
+const KEY_NAME = "SKILLREPO_API_KEY";
+
+/**
+ * @param {string} apiKey
+ * @returns {{ path: string; action: string }}
+ */
+export function mergeEnvLocal(apiKey) {
+  const filePath = envLocal();
+  const prefix = `${KEY_NAME}=`;
+  const existing = readFileSafe(filePath);
+
+  if (existing === null) {
+    writeFileSafe(filePath, `${prefix}${apiKey}\n`);
+    return { path: ".env.local", action: "created" };
+  }
+
+  const lines = existing.split(/\r?\n/);
+  const lineEnding = existing.includes("\r\n") ? "\r\n" : "\n";
+  const idx = lines.findIndex((l) => l.startsWith(prefix));
+
+  if (idx >= 0) {
+    const currentValue = lines[idx].slice(prefix.length);
+    if (currentValue === apiKey) {
+      return { path: ".env.local", action: "skipped" };
+    }
+    // Different value — update in place
+    lines[idx] = `${prefix}${apiKey}`;
+    writeFileSafe(filePath, lines.join(lineEnding));
+    return { path: ".env.local", action: "updated" };
+  }
+
+  // Key not found — append
+  let content = existing;
+  if (content && !content.endsWith("\n") && !content.endsWith("\r\n")) {
+    content += lineEnding;
+  }
+  content += `${prefix}${apiKey}${lineEnding}`;
+  writeFileSafe(filePath, content);
+  return { path: ".env.local", action: "added" };
+}

package/src/lib/mergers/hooks-json.mjs

@@ -0,0 +1,69 @@
+/**
+ * Merger for Claude Code .claude/hooks/hooks.json
+ * Also writes the skillrepo-sync.mjs hook script.
+ *
+ * Merge strategy: add a SessionStart entry without destroying existing hooks.
+ * Idempotent — if the hook is already installed, skip.
+ */
+
+import { readFileSafe, writeFileSafe } from "../fs-utils.mjs";
+import { claudeHooksJson, claudeSyncHook } from "../paths.mjs";
+
+const TARGET_COMMAND = "node .claude/hooks/skillrepo-sync.mjs";
+
+/**
+ * Merge the SkillRepo SessionStart hook into hooks.json.
+ * @param {string} hooksJsonContent - The canonical hooks.json content from the API
+ * @param {string} syncHookContent - The sync hook script content from the API
+ * @returns {{ results: { path: string; action: string }[] }}
+ */
+export function mergeHooksConfig(hooksJsonContent, syncHookContent) {
+  const results = [];
+
+  // Always write the sync hook script (latest version from server)
+  const hookExisted = readFileSafe(claudeSyncHook()) !== null;
+  writeFileSafe(claudeSyncHook(), syncHookContent);
+  results.push({ path: ".claude/hooks/skillrepo-sync.mjs", action: hookExisted ? "updated" : "created" });
+
+  // Merge hooks.json
+  const filePath = claudeHooksJson();
+  const existing = readFileSafe(filePath);
+
+  if (existing === null) {
+    writeFileSafe(filePath, hooksJsonContent);
+    results.push({ path: ".claude/hooks/hooks.json", action: "created" });
+    return { results };
+  }
+
+  let config;
+  try {
+    config = JSON.parse(existing);
+  } catch {
+    throw new Error(`Cannot parse .claude/hooks/hooks.json — invalid JSON. Fix or delete it, then run setup again.`);
+  }
+
+  // Navigate to hooks.SessionStart
+  if (!config.hooks) config.hooks = {};
+  if (!Array.isArray(config.hooks.SessionStart)) config.hooks.SessionStart = [];
+
+  // Check if already installed
+  const found = config.hooks.SessionStart.some((group) =>
+    Array.isArray(group.hooks) &&
+    group.hooks.some((h) => h.command === TARGET_COMMAND)
+  );
+
+  if (found) {
+    results.push({ path: ".claude/hooks/hooks.json", action: "skipped" });
+    return { results };
+  }
+
+  // Append new entry
+  config.hooks.SessionStart.push({
+    matcher: "startup|resume",
+    hooks: [{ type: "command", command: TARGET_COMMAND }],
+  });
+
+  writeFileSafe(filePath, JSON.stringify(config, null, 2) + "\n");
+  results.push({ path: ".claude/hooks/hooks.json", action: "merged" });
+  return { results };
+}

package/src/lib/mergers/vscode-mcp.mjs

@@ -0,0 +1,69 @@
+/**
+ * Merger for VS Code + Copilot .vscode/mcp.json
+ * Format: { inputs: [...], servers: { skillrepo: { type: "http", url, headers } } }
+ * Note: uses "servers" not "mcpServers", and "${input:id}" for access key
+ * VS Code does NOT support env var interpolation in mcp.json
+ */
+
+import { readFileSafe, writeFileSafe } from "../fs-utils.mjs";
+import { vscodeMcpJson } from "../paths.mjs";
+
+const INPUT_ENTRY = {
+  id: "skillrepo-api-key",
+  type: "promptString",
+  description: "SkillRepo access key (sk_live_...)",
+  password: true,
+};
+
+/**
+ * @param {string} mcpUrl
+ * @returns {{ path: string; action: string }}
+ */
+export function mergeVscodeMcpConfig(mcpUrl) {
+  const filePath = vscodeMcpJson();
+  const serverEntry = {
+    type: "http",
+    url: mcpUrl,
+    headers: {
+      Authorization: "Bearer ${input:skillrepo-api-key}",
+    },
+  };
+
+  const existing = readFileSafe(filePath);
+
+  if (existing === null) {
+    const config = {
+      inputs: [INPUT_ENTRY],
+      servers: { skillrepo: serverEntry },
+    };
+    writeFileSafe(filePath, JSON.stringify(config, null, 2) + "\n");
+    return { path: ".vscode/mcp.json", action: "created" };
+  }
+
+  let config;
+  try {
+    config = JSON.parse(existing);
+  } catch {
+    throw new Error(`Cannot parse .vscode/mcp.json — invalid JSON. Fix or delete it, then run setup again.`);
+  }
+
+  // Ensure inputs array exists and has our entry
+  if (!Array.isArray(config.inputs)) {
+    config.inputs = [];
+  }
+  const hasInput = config.inputs.some((i) => i.id === INPUT_ENTRY.id);
+  if (!hasInput) {
+    config.inputs.push(INPUT_ENTRY);
+  }
+
+  // Ensure servers object exists
+  if (!config.servers || typeof config.servers !== "object") {
+    config.servers = {};
+  }
+
+  const action = config.servers.skillrepo ? "merged" : "created";
+  config.servers.skillrepo = serverEntry;
+
+  writeFileSafe(filePath, JSON.stringify(config, null, 2) + "\n");
+  return { path: ".vscode/mcp.json", action };
+}

package/src/lib/mergers/windsurf-mcp.mjs

@@ -0,0 +1,47 @@
+/**
+ * Merger for Windsurf mcp_config.json (GLOBAL — always at ~/.codeium/windsurf/)
+ * Format: { mcpServers: { skillrepo: { serverUrl, headers } } }
+ * Note: uses "serverUrl" not "url"
+ * Env vars: ${env:VAR} syntax
+ */
+
+import { readFileSafe, writeFileSafe } from "../fs-utils.mjs";
+import { windsurfMcpJson } from "../paths.mjs";
+
+/**
+ * @param {string} mcpUrl
+ * @returns {{ path: string; action: string }}
+ */
+export function mergeWindsurfMcpConfig(mcpUrl) {
+  const filePath = windsurfMcpJson();
+  const serverEntry = {
+    serverUrl: mcpUrl,
+    headers: {
+      Authorization: "Bearer ${env:SKILLREPO_API_KEY}",
+    },
+  };
+
+  const existing = readFileSafe(filePath);
+
+  if (existing === null) {
+    writeFileSafe(filePath, JSON.stringify({ mcpServers: { skillrepo: serverEntry } }, null, 2) + "\n");
+    return { path: "~/.codeium/windsurf/mcp_config.json", action: "created" };
+  }
+
+  let config;
+  try {
+    config = JSON.parse(existing);
+  } catch {
+    throw new Error(`Cannot parse ~/.codeium/windsurf/mcp_config.json — invalid JSON. Fix or delete it, then run setup again.`);
+  }
+
+  if (!config.mcpServers || typeof config.mcpServers !== "object") {
+    config.mcpServers = {};
+  }
+
+  const action = config.mcpServers.skillrepo ? "merged" : "created";
+  config.mcpServers.skillrepo = serverEntry;
+
+  writeFileSafe(filePath, JSON.stringify(config, null, 2) + "\n");
+  return { path: "~/.codeium/windsurf/mcp_config.json", action };
+}

package/src/lib/paths.mjs

@@ -0,0 +1,35 @@
+/**
+ * Cross-platform path resolution for all config files the CLI writes.
+ * Uses Node built-ins only — no dependencies.
+ */
+
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+
+const cwd = () => process.cwd();
+
+// Claude Code
+export const claudeMcpJson = () => join(cwd(), ".mcp.json");
+export const claudeDir = () => join(cwd(), ".claude");
+export const claudeHooksDir = () => join(cwd(), ".claude", "hooks");
+export const claudeHooksJson = () => join(cwd(), ".claude", "hooks", "hooks.json");
+export const claudeSyncHook = () => join(cwd(), ".claude", "hooks", "skillrepo-sync.mjs");
+export const claudeSkillrepoMd = () => join(cwd(), ".claude", "skillrepo.md");
+
+// Cursor
+export const cursorDir = () => join(cwd(), ".cursor");
+export const cursorMcpJson = () => join(cwd(), ".cursor", "mcp.json");
+export const cursorRulesDir = () => join(cwd(), ".cursor", "rules");
+export const cursorSkillrepoMdc = () => join(cwd(), ".cursor", "rules", "skillrepo.mdc");
+
+// Windsurf (always global — no project-level config)
+export const windsurfDir = () => join(homedir(), ".codeium", "windsurf");
+export const windsurfMcpJson = () => join(homedir(), ".codeium", "windsurf", "mcp_config.json");
+
+// VS Code + Copilot
+export const vscodeDir = () => join(cwd(), ".vscode");
+export const vscodeMcpJson = () => join(cwd(), ".vscode", "mcp.json");
+
+// Shared
+export const envLocal = () => join(cwd(), ".env.local");
+export const projectRoot = () => resolve(cwd());

package/src/lib/prompt.mjs

@@ -0,0 +1,139 @@
+/**
+ * Interactive prompts using Node's built-in readline.
+ * Zero dependencies. Supports TTY detection and NO_COLOR.
+ */
+
+import { createInterface } from "node:readline";
+
+const isTTY = process.stdout.isTTY && !process.env.NO_COLOR;
+
+// ── Colors ──────────────────────────────────────────────────────────────
+
+const green = (s) => (isTTY ? `\x1b[32m${s}\x1b[0m` : s);
+const yellow = (s) => (isTTY ? `\x1b[33m${s}\x1b[0m` : s);
+const red = (s) => (isTTY ? `\x1b[31m${s}\x1b[0m` : s);
+const dim = (s) => (isTTY ? `\x1b[2m${s}\x1b[0m` : s);
+const bold = (s) => (isTTY ? `\x1b[1m${s}\x1b[0m` : s);
+
+// ── Output helpers ──────────────────────────────────────────────────────
+
+export function printHeader(title) {
+  console.log("");
+  console.log(`  ${bold(title)}`);
+  console.log("");
+}
+
+export function printStep(n, total, message) {
+  console.log(`  ${dim(`Step ${n}/${total}:`)} ${message}`);
+}
+
+export function printSuccess(message) {
+  console.log(`  ${green("✓")} ${message}`);
+}
+
+export function printWarning(message) {
+  console.log(`  ${yellow("⚠")} ${message}`);
+}
+
+export function printError(message) {
+  console.error(`  ${red("✗")} ${message}`);
+}
+
+export function printResult(path, action) {
+  const label =
+    action === "created" ? green("created") :
+    action === "merged" ? yellow("merged") :
+    action === "updated" ? yellow("updated") :
+    dim("skipped");
+  console.log(`  ${path.padEnd(45)} ${label}`);
+}
+
+export function printBlank() {
+  console.log("");
+}
+
+// ── Prompts ─────────────────────────────────────────────────────────────
+
+function createRl() {
+  return createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+/**
+ * Prompt for text input.
+ */
+export function promptText(question, defaultValue) {
+  return new Promise((resolve) => {
+    const rl = createRl();
+    const suffix = defaultValue ? ` ${dim(`(${defaultValue})`)} ` : " ";
+    rl.question(`  ${question}${suffix}> `, (answer) => {
+      rl.close();
+      resolve(answer.trim() || defaultValue || "");
+    });
+  });
+}
+
+/**
+ * Prompt for a secret (access key). Disables echo.
+ */
+export function promptSecret(question) {
+  return new Promise((resolve) => {
+    const rl = createRl();
+    // Disable echo for the key input
+    if (process.stdin.isTTY) {
+      process.stdout.write(`  ${question} > `);
+      process.stdin.setRawMode(true);
+      let input = "";
+      const onData = (ch) => {
+        const c = ch.toString();
+        if (c === "\n" || c === "\r") {
+          process.stdin.setRawMode(false);
+          process.stdin.removeListener("data", onData);
+          process.stdout.write("\n");
+          rl.close();
+          resolve(input.trim());
+        } else if (c === "\x03") {
+          // Ctrl-C
+          process.stdin.setRawMode(false);
+          process.stdout.write("\n");
+          rl.close();
+          process.exit(0);
+        } else if (c === "\x7f" || c === "\b") {
+          // Backspace
+          if (input.length > 0) {
+            input = input.slice(0, -1);
+            process.stdout.write("\b \b");
+          }
+        } else {
+          input += c;
+          process.stdout.write("*");
+        }
+      };
+      process.stdin.on("data", onData);
+    } else {
+      // Non-TTY: just read normally
+      rl.question(`  ${question} > `, (answer) => {
+        rl.close();
+        resolve(answer.trim());
+      });
+    }
+  });
+}
+
+/**
+ * y/n confirmation.
+ */
+export function confirm(question, defaultYes = true) {
+  return new Promise((resolve) => {
+    const rl = createRl();
+    const hint = defaultYes ? "Y/n" : "y/N";
+    rl.question(`  ${question} (${hint}) `, (answer) => {
+      rl.close();
+      const a = answer.trim().toLowerCase();
+      if (a === "") resolve(defaultYes);
+      else resolve(a === "y" || a === "yes");
+    });
+  });
+}

package/src/lib/write-configs.mjs

@@ -0,0 +1,68 @@
+/**
+ * Orchestrates writing all config files based on detected IDEs.
+ * Calls individual mergers and collects results.
+ */
+
+import { readFileSafe, writeFileSafe } from "./fs-utils.mjs";
+import { claudeSkillrepoMd, cursorSkillrepoMdc } from "./paths.mjs";
+import { mergeClaudeMcpConfig } from "./mergers/claude-mcp.mjs";
+import { mergeCursorMcpConfig } from "./mergers/cursor-mcp.mjs";
+import { mergeWindsurfMcpConfig } from "./mergers/windsurf-mcp.mjs";
+import { mergeVscodeMcpConfig } from "./mergers/vscode-mcp.mjs";
+import { mergeHooksConfig } from "./mergers/hooks-json.mjs";
+import { mergeEnvLocal } from "./mergers/env-local.mjs";
+
+/**
+ * Write all configuration files.
+ * @param {object} options
+ * @param {string[]} options.ides - IDE keys to configure (claudeCode, cursor, windsurf, vscode)
+ * @param {string} options.mcpUrl - The MCP endpoint URL
+ * @param {string} options.apiKey - The access key
+ * @param {object} options.payload - The setup payload from the API
+ * @returns {{ path: string; action: string }[]}
+ */
+export function writeAllConfigs({ ides, mcpUrl, apiKey, payload }) {
+  const results = [];
+
+  // Claude Code
+  if (ides.includes("claudeCode")) {
+    results.push(mergeClaudeMcpConfig(mcpUrl));
+
+    // Skill mapping file (always refresh with latest)
+    const claudeMdExisted = readFileSafe(claudeSkillrepoMd()) !== null;
+    writeFileSafe(claudeSkillrepoMd(), payload.claudeCode.skillrepoMd.content);
+    results.push({ path: ".claude/skillrepo.md", action: claudeMdExisted ? "updated" : "created" });
+
+    // SessionStart hook
+    const hookResults = mergeHooksConfig(
+      payload.claudeCode.hooksJson.content,
+      payload.claudeCode.syncHook.content
+    );
+    results.push(...hookResults.results);
+  }
+
+  // Cursor
+  if (ides.includes("cursor")) {
+    results.push(mergeCursorMcpConfig(mcpUrl));
+
+    // Skill mapping file (always refresh with latest)
+    const cursorMdcExisted = readFileSafe(cursorSkillrepoMdc()) !== null;
+    writeFileSafe(cursorSkillrepoMdc(), payload.cursor.skillrepoMdc.content);
+    results.push({ path: ".cursor/rules/skillrepo.mdc", action: cursorMdcExisted ? "updated" : "created" });
+  }
+
+  // Windsurf
+  if (ides.includes("windsurf")) {
+    results.push(mergeWindsurfMcpConfig(mcpUrl));
+  }
+
+  // VS Code + Copilot
+  if (ides.includes("vscode")) {
+    results.push(mergeVscodeMcpConfig(mcpUrl));
+  }
+
+  // .env.local (always — every IDE needs the key)
+  results.push(mergeEnvLocal(apiKey));
+
+  return results;
+}

package/src/test/detect-ides.test.mjs

@@ -0,0 +1,70 @@
+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";
+
+let originalCwd;
+let tempDir;
+
+beforeEach(() => {
+  originalCwd = process.cwd;
+  tempDir = mkdtempSync(join(tmpdir(), "cli-test-"));
+  process.cwd = () => tempDir;
+});
+
+afterEach(() => {
+  process.cwd = originalCwd;
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("IDE detection", () => {
+  it("detects Claude Code from .claude/ directory", async () => {
+    const { detectIdes } = await import("../lib/detect-ides.mjs");
+    mkdirSync(join(tempDir, ".claude"));
+
+    const result = detectIdes();
+    assert.equal(result.claudeCode, true);
+  });
+
+  it("detects Cursor from .cursor/ directory", async () => {
+    const { detectIdes } = await import("../lib/detect-ides.mjs");
+    mkdirSync(join(tempDir, ".cursor"));
+
+    const result = detectIdes();
+    assert.equal(result.cursor, true);
+  });
+
+  it("detects VS Code from .vscode/ directory", async () => {
+    const { detectIdes } = await import("../lib/detect-ides.mjs");
+    mkdirSync(join(tempDir, ".vscode"));
+
+    const result = detectIdes();
+    assert.equal(result.vscode, true);
+  });
+
+  it("returns all false when no IDE directories exist", async () => {
+    const { detectIdes } = await import("../lib/detect-ides.mjs");
+
+    const result = detectIdes();
+    assert.equal(result.claudeCode, false);
+    assert.equal(result.cursor, false);
+    assert.equal(result.vscode, false);
+    // windsurf depends on home dir, skip assertion
+  });
+
+  it("defaults to claudeCode + cursor when nothing detected", async () => {
+    const { getDetectedIdeKeys, detectIdes } = await import("../lib/detect-ides.mjs");
+
+    // Override windsurf detection too
+    const keys = getDetectedIdeKeys({ claudeCode: false, cursor: false, windsurf: false, vscode: false });
+    assert.deepEqual(keys, ["claudeCode", "cursor"]);
+  });
+
+  it("returns only detected IDEs", async () => {
+    const { getDetectedIdeKeys } = await import("../lib/detect-ides.mjs");
+
+    const keys = getDetectedIdeKeys({ claudeCode: true, cursor: false, windsurf: false, vscode: true });
+    assert.deepEqual(keys, ["claudeCode", "vscode"]);
+  });
+});

package/src/test/env-local.test.mjs

@@ -0,0 +1,71 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+let originalCwd;
+let tempDir;
+
+beforeEach(() => {
+  originalCwd = process.cwd;
+  tempDir = mkdtempSync(join(tmpdir(), "cli-test-"));
+  process.cwd = () => tempDir;
+});
+
+afterEach(() => {
+  process.cwd = originalCwd;
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe(".env.local merger", () => {
+  it("creates .env.local when file does not exist", async () => {
+    const { mergeEnvLocal } = await import("../lib/mergers/env-local.mjs");
+    const result = mergeEnvLocal("sk_live_test123");
+
+    assert.equal(result.action, "created");
+    const content = readFileSync(join(tempDir, ".env.local"), "utf-8");
+    assert.equal(content, "SKILLREPO_API_KEY=sk_live_test123\n");
+  });
+
+  it("skips when key already exists with same value", async () => {
+    const { mergeEnvLocal } = await import("../lib/mergers/env-local.mjs");
+    writeFileSync(join(tempDir, ".env.local"), "SKILLREPO_API_KEY=sk_live_test123\n");
+
+    const result = mergeEnvLocal("sk_live_test123");
+    assert.equal(result.action, "skipped");
+  });
+
+  it("updates when key exists with different value", async () => {
+    const { mergeEnvLocal } = await import("../lib/mergers/env-local.mjs");
+    writeFileSync(join(tempDir, ".env.local"), "SKILLREPO_API_KEY=sk_live_old\n");
+
+    const result = mergeEnvLocal("sk_live_new");
+    assert.equal(result.action, "updated");
+
+    const content = readFileSync(join(tempDir, ".env.local"), "utf-8");
+    assert.ok(content.includes("SKILLREPO_API_KEY=sk_live_new"));
+    assert.ok(!content.includes("sk_live_old"));
+  });
+
+  it("appends when key does not exist in file", async () => {
+    const { mergeEnvLocal } = await import("../lib/mergers/env-local.mjs");
+    writeFileSync(join(tempDir, ".env.local"), "OTHER_VAR=value\n");
+
+    const result = mergeEnvLocal("sk_live_test123");
+    assert.equal(result.action, "added");
+
+    const content = readFileSync(join(tempDir, ".env.local"), "utf-8");
+    assert.ok(content.includes("OTHER_VAR=value"));
+    assert.ok(content.includes("SKILLREPO_API_KEY=sk_live_test123"));
+  });
+
+  it("preserves CRLF line endings", async () => {
+    const { mergeEnvLocal } = await import("../lib/mergers/env-local.mjs");
+    writeFileSync(join(tempDir, ".env.local"), "OTHER=val\r\n");
+
+    mergeEnvLocal("sk_live_test123");
+    const content = readFileSync(join(tempDir, ".env.local"), "utf-8");
+    assert.ok(content.includes("\r\n"));
+  });
+});

package/src/test/mergers/claude-mcp.test.mjs

@@ -0,0 +1,78 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+// We need to override the cwd for testing
+let originalCwd;
+let tempDir;
+
+beforeEach(() => {
+  originalCwd = process.cwd;
+  tempDir = mkdtempSync(join(tmpdir(), "cli-test-"));
+  process.cwd = () => tempDir;
+});
+
+afterEach(() => {
+  process.cwd = originalCwd;
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe("Claude Code MCP config merger", () => {
+  it("creates .mcp.json when file does not exist", async () => {
+    const { mergeClaudeMcpConfig } = await import("../../lib/mergers/claude-mcp.mjs");
+    const result = mergeClaudeMcpConfig("https://skillrepo.dev/api/mcp");
+
+    assert.equal(result.action, "created");
+    assert.equal(result.path, ".mcp.json");
+
+    const content = JSON.parse(readFileSync(join(tempDir, ".mcp.json"), "utf-8"));
+    assert.equal(content.mcpServers.skillrepo.type, "http");
+    assert.equal(content.mcpServers.skillrepo.url, "https://skillrepo.dev/api/mcp");
+    assert.equal(content.mcpServers.skillrepo.headers.Authorization, "Bearer ${SKILLREPO_API_KEY}");
+  });
+
+  it("merges into existing config without destroying other servers", async () => {
+    const { mergeClaudeMcpConfig } = await import("../../lib/mergers/claude-mcp.mjs");
+
+    // Pre-existing config with another server
+    const existing = {
+      mcpServers: {
+        other: { type: "stdio", command: "some-server" },
+      },
+    };
+    writeFileSync(join(tempDir, ".mcp.json"), JSON.stringify(existing));
+
+    const result = mergeClaudeMcpConfig("https://skillrepo.dev/api/mcp");
+
+    assert.equal(result.action, "created"); // new entry, not merge
+    const content = JSON.parse(readFileSync(join(tempDir, ".mcp.json"), "utf-8"));
+    assert.ok(content.mcpServers.other, "other server preserved");
+    assert.ok(content.mcpServers.skillrepo, "skillrepo added");
+  });
+
+  it("updates existing skillrepo entry (merged)", async () => {
+    const { mergeClaudeMcpConfig } = await import("../../lib/mergers/claude-mcp.mjs");
+
+    const existing = {
+      mcpServers: {
+        skillrepo: { type: "http", url: "https://old-url.com/api/mcp", headers: {} },
+      },
+    };
+    writeFileSync(join(tempDir, ".mcp.json"), JSON.stringify(existing));
+
+    const result = mergeClaudeMcpConfig("https://new-url.com/api/mcp");
+
+    assert.equal(result.action, "merged");
+    const content = JSON.parse(readFileSync(join(tempDir, ".mcp.json"), "utf-8"));
+    assert.equal(content.mcpServers.skillrepo.url, "https://new-url.com/api/mcp");
+  });
+
+  it("throws on invalid JSON", async () => {
+    const { mergeClaudeMcpConfig } = await import("../../lib/mergers/claude-mcp.mjs");
+    writeFileSync(join(tempDir, ".mcp.json"), "not json");
+
+    assert.throws(() => mergeClaudeMcpConfig("https://skillrepo.dev/api/mcp"), /invalid JSON/);
+  });
+});