skillrepo 2.0.0 → 3.0.0

package/src/lib/cli-config.mjs

@@ -0,0 +1,230 @@
+/**
+ * Shared credential + flag resolution for command modules.
+ *
+ * Every command needs to:
+ *   1. Resolve `--key`/`--url`/`--ide`/`--global`/`--json` flags
+ *   2. Fall back to ~/.claude/skillrepo/config.json
+ *   3. Fall back to SKILLREPO_ACCESS_KEY / SKILLREPO_URL env vars
+ *   4. Hard-error with an actionable hint pointing at `init` if no
+ *      key is configured
+ *
+ * Centralizing this here keeps the four command modules thin and
+ * means a future change to credential resolution (e.g., adding a
+ * keychain backend) is a single edit instead of four.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+
+import { globalConfigPath } from "./paths.mjs";
+import { authError, validationError } from "./errors.mjs";
+
+const VALID_VENDORS = new Set(["claudeCode", "cursor", "windsurf", "vscode"]);
+const VENDOR_ALIASES = { claude: "claudeCode" };
+
+/**
+ * @typedef {Object} ResolvedFlags
+ * @property {string} serverUrl
+ * @property {string} apiKey
+ * @property {boolean} global
+ * @property {string[]|null} vendors  - null = use the default
+ * @property {boolean} json
+ */
+
+/**
+ * Parse common flags from an argv slice. Returns a typed object with
+ * `serverUrl` and `apiKey` resolved per the priority order documented
+ * at the top of this file.
+ *
+ * Throws `validationError` for unknown flags (caller can intercept
+ * extra positional args before calling this).
+ *
+ * @param {string[]} argv - The argv slice the dispatcher passed to the command
+ * @param {object} [opts]
+ * @param {boolean} [opts.requireAuth=true] - If false, skip the no-key error
+ *        (used by commands that may run without credentials, but PR2 has none)
+ * @param {boolean} [opts.skipConfig=false] - If true, DO NOT read from
+ *        ~/.claude/skillrepo/config.json as a fallback. Only flag values
+ *        and env vars are considered. Used by `init` so that its own
+ *        --force / stale-key flow can decide whether to consume cached
+ *        credentials — without this, resolveFlags would silently inject
+ *        the cached key before init's decision logic runs, making
+ *        --force a no-op.
+ * @param {(arg: string, i: number, argv: string[]) => boolean | number} [opts.acceptPositional]
+ *        Optional callback to consume positional args. Return:
+ *          - `false` (or any falsy non-zero) → arg rejected as unknown
+ *          - a positive integer N → consume N args (the current arg
+ *            plus the next N-1 if any)
+ *          - 0 is INVALID and treated the same as `false` — a
+ *            callback that "handles but consumes nothing" is a
+ *            contract violation and would loop forever
+ *          - any non-finite or negative number → invalid, treated as `false`
+ * @returns {ResolvedFlags}
+ */
+export function resolveFlags(argv, opts = {}) {
+  const flagState = {
+    global: false,
+    vendors: null,
+    json: false,
+    key: null,
+    serverUrl: null,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (arg === "--global") {
+      flagState.global = true;
+    } else if (arg === "--ide" && argv[i + 1] !== undefined) {
+      flagState.vendors = parseVendorList(argv[++i]);
+    } else if (arg === "--json") {
+      flagState.json = true;
+    } else if ((arg === "--key" || arg === "-k") && argv[i + 1] !== undefined) {
+      flagState.key = argv[++i];
+    } else if ((arg === "--url" || arg === "-u") && argv[i + 1] !== undefined) {
+      flagState.serverUrl = argv[++i];
+    } else if (arg === "--help" || arg === "-h") {
+      // Dispatcher should have intercepted this. Defensive no-op.
+      continue;
+    } else {
+      // Allow the caller to consume a positional arg before we treat
+      // it as unknown. This is how `get @owner/name` and
+      // `search <query>` slot in their main argument.
+      //
+      // Contract: callback returns a positive integer N (consume N
+      // args), `false`, or any falsy/zero/negative/non-integer value
+      // (reject the arg). Returning 0 is INVALID — it would mean
+      // "handled but consumed nothing", which would infinite-loop on
+      // the same arg. We reject zero defensively rather than trust
+      // every caller to read the JSDoc.
+      const consumed = opts.acceptPositional?.(arg, i, argv);
+      if (
+        typeof consumed === "number" &&
+        Number.isInteger(consumed) &&
+        consumed > 0
+      ) {
+        i += consumed - 1; // -1 because the for loop also increments
+      } else {
+        throw validationError(`Unknown argument: ${arg}`, {
+          hint: "Run the command with --help for valid options.",
+        });
+      }
+    }
+  }
+
+  // Resolve credentials in priority order
+  let serverUrl = flagState.serverUrl;
+  let apiKey = flagState.key;
+
+  // `skipConfig` suppresses the config-file fallback AND the eager
+  // default for serverUrl. `init` needs this because it owns the
+  // credential lifecycle: it reads the config file itself so
+  // `--force` and the stale-key re-prompt path can decide whether
+  // to use the cached credentials, and it needs to see `null`
+  // serverUrl (not the baked-in production URL) so its own
+  // "existingConfig.serverUrl → env → DEFAULT_URL" fallback chain
+  // takes effect. Without this, `init`'s `!serverUrl` branch was
+  // dead because resolveFlags would already have set it to
+  // https://skillrepo.dev.
+  if (opts.skipConfig) {
+    // Env var still applies — it's explicit config, not a cached
+    // credential. But the production URL default does NOT apply;
+    // the caller is expected to provide its own default.
+    if (!serverUrl) serverUrl = process.env.SKILLREPO_URL || null;
+    if (!apiKey) apiKey = process.env.SKILLREPO_ACCESS_KEY || null;
+  } else {
+    if (!serverUrl || !apiKey) {
+      const config = readGlobalConfig();
+      if (config) {
+        serverUrl = serverUrl || config.serverUrl;
+        apiKey = apiKey || config.apiKey;
+      }
+    }
+    if (!serverUrl) serverUrl = process.env.SKILLREPO_URL || "https://skillrepo.dev";
+    if (!apiKey) apiKey = process.env.SKILLREPO_ACCESS_KEY || null;
+  }
+
+  if (!apiKey && opts.requireAuth !== false) {
+    throw authError("No access key configured.", {
+      hint: "Run `skillrepo init` first, or pass --key sk_live_...",
+    });
+  }
+
+  return {
+    serverUrl,
+    apiKey,
+    global: flagState.global,
+    vendors: flagState.vendors,
+    json: flagState.json,
+  };
+}
+
+/**
+ * Compute the vendor list to pass to file-write / sync. Defaults to
+ * `["claudeCode"]` when neither `--ide` nor `--global` is provided —
+ * the v3.0.0 CLI deliberately does NOT silently fall back to
+ * `[claudeCode, cursor]` like v2.0.0 did. The user opts in.
+ */
+export function effectiveVendors(flags) {
+  if (flags.global) return undefined; // global mode ignores vendors
+  if (flags.vendors) return flags.vendors;
+  return ["claudeCode"];
+}
+
+// ── Internals ──────────────────────────────────────────────────────────
+
+function parseVendorList(raw) {
+  if (typeof raw !== "string") {
+    throw validationError(`--ide expects a comma-separated list, got: ${raw}`);
+  }
+
+  // First pass: collect tokens, normalize aliases, detect `all`.
+  const pieces = raw.split(",").map((p) => p.trim()).filter(Boolean);
+  const normalized = pieces.map((v) => VENDOR_ALIASES[v] ?? v);
+  const hasAll = normalized.includes("all");
+  const otherVendors = normalized.filter((v) => v !== "all");
+
+  // Defense against confusing input: `--ide cursor,all` is ambiguous
+  // — the user might think it means "cursor first, then everything"
+  // or "all minus duplicates". Both interpretations are wrong because
+  // `all` is the full set. Reject the combination so the user is
+  // forced to pick one.
+  if (hasAll && otherVendors.length > 0) {
+    throw validationError(
+      `--ide cannot mix "all" with other vendors: "${raw}"`,
+      { hint: "Use --ide all OR --ide claude,cursor,... — not both." },
+    );
+  }
+
+  if (hasAll) {
+    return ["claudeCode", "cursor", "windsurf", "vscode"];
+  }
+
+  if (normalized.length === 0) {
+    throw validationError("--ide list is empty.");
+  }
+
+  // Validate each vendor token
+  for (const resolved of normalized) {
+    if (!VALID_VENDORS.has(resolved)) {
+      // Find the original (un-aliased) form for the error message
+      const original = pieces[normalized.indexOf(resolved)];
+      throw validationError(`Unknown --ide vendor: "${original}"`, {
+        hint: "Use claudeCode (or 'claude'), cursor, windsurf, vscode, or 'all'.",
+      });
+    }
+  }
+
+  return normalized;
+}
+
+function readGlobalConfig() {
+  const path = globalConfigPath();
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    if (parsed && typeof parsed === "object") return parsed;
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/lib/config.mjs

@@ -0,0 +1,238 @@
+/**
+ * Global skillrepo config reader/writer — ~/.claude/skillrepo/config.json
+ *
+ * Built for PR3b's `init` rewrite (#673). The config file is the
+ * single source of truth for credentials that every command resolves
+ * from when `--key`/`--url` are not provided. The existing
+ * `cli-config.mjs` helper already READS this file (via the
+ * `readGlobalConfig` helper inside `resolveFlags`); this module adds
+ * the WRITE side so `init` can persist credentials after a
+ * successful validation.
+ *
+ * Schema:
+ *
+ *   {
+ *     "schemaVersion": 1,
+ *     "apiKey": "sk_live_...",
+ *     "serverUrl": "https://skillrepo.dev",
+ *     "accountSlug": "alice",
+ *     "accountId": "acc_...",
+ *     "userId": "user_...",
+ *     "writtenAt": "2026-04-15T00:00:00Z"
+ *   }
+ *
+ * Only `apiKey` and `serverUrl` are structurally required by the
+ * command layer (everything else is metadata for diagnostics). A
+ * missing field is treated as a corrupt-but-recoverable state — the
+ * reader returns null and the command layer falls back to env vars
+ * or prompts.
+ *
+ * File permissions: the config file contains a live access key.
+ * chmod 0600 on POSIX (owner read/write only). Skipped on Windows
+ * (where 0600 is a no-op anyway and chmod doesn't prevent
+ * Administrator reads).
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  chmodSync,
+  renameSync,
+  unlinkSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import { platform } from "node:os";
+
+import { globalConfigPath } from "./paths.mjs";
+import { diskError, validationError } from "./errors.mjs";
+
+/**
+ * Current schema version. Bump this on any structural change.
+ * Readers treat unknown future versions as "ignore this file,
+ * do a full re-init" rather than crashing.
+ */
+export const CONFIG_SCHEMA_VERSION = 1;
+
+/**
+ * @typedef {Object} GlobalConfig
+ * @property {number} schemaVersion
+ * @property {string} apiKey
+ * @property {string} serverUrl
+ * @property {string} [accountSlug]
+ * @property {string} [accountId]
+ * @property {string} [userId]
+ * @property {string} [writtenAt]
+ */
+
+/**
+ * Read the global config file. Returns null if the file does not
+ * exist, is corrupt, or has an unrecognized schema version.
+ *
+ * Corrupt cases return null rather than throwing because the command
+ * layer has a well-defined fallback (env vars, interactive prompt)
+ * and we don't want a garbled config file to crash the CLI.
+ *
+ * @returns {GlobalConfig | null}
+ */
+export function readConfig() {
+  const path = globalConfigPath();
+  if (!existsSync(path)) return null;
+
+  let raw;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  if (!parsed || typeof parsed !== "object") return null;
+
+  // Reject unknown future schema versions. A null return here
+  // triggers the caller's prompt-for-new-config path — acceptable
+  // degradation for an old CLI reading a new-format file.
+  if (parsed.schemaVersion !== undefined && parsed.schemaVersion !== CONFIG_SCHEMA_VERSION) {
+    return null;
+  }
+
+  // Legacy fallback: the v2.0.0 CLI wrote config files WITHOUT a
+  // schemaVersion field. Accept those as schemaVersion 1 so the new
+  // CLI can transparently upgrade. The next writeConfig() call will
+  // add the explicit version field.
+  if (parsed.schemaVersion === undefined) {
+    parsed.schemaVersion = CONFIG_SCHEMA_VERSION;
+  }
+
+  // Required fields
+  if (typeof parsed.apiKey !== "string" || !parsed.apiKey) return null;
+  if (typeof parsed.serverUrl !== "string" || !parsed.serverUrl) return null;
+
+  return parsed;
+}
+
+/**
+ * Write the global config file atomically. Creates the parent
+ * directory if missing. Chmods the file to 0600 on POSIX.
+ *
+ * Throws `diskError` on any filesystem failure so the init command
+ * can surface a clean error with exit code 3.
+ *
+ * @param {Partial<GlobalConfig>} config - Caller-provided fields.
+ *        Required: apiKey, serverUrl. Optional: everything else.
+ * @returns {"created" | "updated"} Whether the file existed before.
+ */
+export function writeConfig(config) {
+  if (!config || typeof config !== "object") {
+    throw validationError("writeConfig: config object is required");
+  }
+  if (typeof config.apiKey !== "string" || !config.apiKey) {
+    throw validationError("writeConfig: apiKey is required");
+  }
+  if (typeof config.serverUrl !== "string" || !config.serverUrl) {
+    throw validationError("writeConfig: serverUrl is required");
+  }
+
+  const path = globalConfigPath();
+  const existed = existsSync(path);
+  const dir = dirname(path);
+
+  // Ensure the parent dir exists — the dir itself holds other
+  // CLI state (.last-sync, maybe more in the future), so creating
+  // it is expected.
+  try {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  } catch (err) {
+    throw diskError(`Cannot create ${dir}: ${err.message}`, { cause: err });
+  }
+
+  // Build the persisted shape. Preserve unknown fields from the
+  // existing file if any — a future CLI version might add fields
+  // that this writer doesn't know about.
+  let existing = {};
+  if (existed) {
+    const current = readConfig();
+    if (current) existing = current;
+  }
+  const merged = {
+    ...existing,
+    schemaVersion: CONFIG_SCHEMA_VERSION,
+    apiKey: config.apiKey,
+    serverUrl: config.serverUrl,
+    writtenAt: new Date().toISOString(),
+  };
+  // Copy optional fields if provided
+  for (const key of ["accountSlug", "accountId", "userId"]) {
+    if (config[key] !== undefined) merged[key] = config[key];
+  }
+
+  // Atomic write via temp-file + rename. Matches the file-write.mjs
+  // pattern: the config file is never in a half-written state, so
+  // a crash mid-write can't leave it corrupted.
+  const tmpPath = `${path}.tmp`;
+  try {
+    writeFileSync(tmpPath, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+  } catch (err) {
+    throw diskError(`Cannot write ${tmpPath}: ${err.message}`, { cause: err });
+  }
+
+  // chmod the temp file before renaming so the destination never
+  // exists with world-readable perms (which would be a brief
+  // credential leak window on a shared system).
+  if (platform() !== "win32") {
+    try {
+      chmodSync(tmpPath, 0o600);
+    } catch {
+      // Non-fatal — chmod failure doesn't corrupt the file, it just
+      // means permissions are looser than we'd like. We intentionally
+      // DON'T emit a warning here: the round-1 review caught that
+      // the warning used the tmp path (which doesn't exist after
+      // rename), and mixing stream output into a pure I/O helper
+      // leaks concerns across layers. Callers that care about
+      // permissions can stat the file themselves after the write.
+    }
+  }
+
+  try {
+    // renameSync on POSIX is atomic on the same filesystem
+    renameSync(tmpPath, path);
+  } catch (err) {
+    // Round-1 review fix: clean up the stale .tmp file on rename
+    // failure so a live access key isn't left behind on disk. The
+    // unlink is best-effort — if IT also fails, the original
+    // rename error is still the one we surface to the caller.
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+      /* best-effort */
+    }
+    throw diskError(`Cannot install ${path}: ${err.message}`, { cause: err });
+  }
+
+  return existed ? "updated" : "created";
+}
+
+/**
+ * Delete the global config file. Returns true if the file existed
+ * and was removed, false if it wasn't there. Used by tests and
+ * future `skillrepo logout` (not yet implemented).
+ */
+export function clearConfig() {
+  const path = globalConfigPath();
+  if (!existsSync(path)) return false;
+  try {
+    unlinkSync(path);
+    return true;
+  } catch (err) {
+    throw diskError(`Cannot delete ${path}: ${err.message}`, { cause: err });
+  }
+}

package/src/lib/detect-ides.mjs

@@ -42,22 +42,3 @@ export function formatDetectedIdes(detected) {
     { 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;
-}