skillrepo 2.0.0 → 3.1.0

package/src/commands/init.mjs

@@ -1,190 +1,636 @@
 /**
- * `skillrepo init` — main command orchestrator.
+ * `skillrepo init` (#673) — PR3b rewrite, v3.1.0 session-sync (#884).
  *
- * Flow:
- * 1. Detect IDEs
- * 2. Prompt for access key
- * 3. Validate key + fetch skill count
- * 4. Write configs (global config, MCP, .gitignore)
- * 5. Print summary
+ * First-run command. Replaces the v2.0.0 init that consumed the
+ * deprecated `/api/v1/setup` endpoint and wrote hook-delivery
+ * artifacts. The new flow:
+ *
+ *   1. Collect credentials (--key | env var | interactive prompt)
+ *   2. Validate the key via POST /api/v1/auth/validate
+ *   3. Write ~/.claude/skillrepo/config.json via config.mjs
+ *   4. Detect installed IDEs (.claude/, .cursor/, .vscode/, ~/.codeium/windsurf/)
+ *   5. Run MCP auto-merge for detected IDEs (user-confirmed unless --yes)
+ *   6. Install Claude Code SessionStart hook (v3.1.0 #884)
+ *   7. Run the first library sync via sync.mjs
+ *   8. Print summary
+ *
+ * Key differences from v2.0.0:
+ *
+ *   - Uses /api/v1/auth/validate (not /api/v1/setup)
+ *   - Writes config.mjs format with schemaVersion
+ *   - MCP merge is interactive with per-vendor prompts
+ *   - NO rules-delivery files (.claude/rules/, .claude/skillrepo*.md) —
+ *     those died with the hooks in #835
+ *   - NO silent vendor fallback — if nothing is detected, refuse with
+ *     a clear --ide hint
+ *   - Idempotent: re-running with a valid existing config re-runs
+ *     detection + MCP merge prompts + sync, but does NOT re-prompt
+ *     for a key. A stale (401) key triggers automatic re-prompt.
+ *   - --force re-prompts unconditionally for a new key
+ *
+ * Exit codes: inherited from errors.mjs via the underlying calls.
+ *
+ * Flags:
+ *   --key/-k <key>   Access key (overrides config + env)
+ *   --url/-u <url>   SkillRepo server URL (overrides config + env)
+ *   --yes/-y         Non-interactive: skip all prompts (MCP merge + IDE confirm)
+ *   --force          Re-prompt for a new key even if config exists and is valid
+ *   --global         Run first sync in global mode (~/.claude/skills/)
+ *   --ide <list>     Override detected IDEs (comma-separated)
+ *   --json           JSON summary output
  */
 
-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 { validateAccessKey } from "../lib/http.mjs";
+import { detectIdes, formatDetectedIdes } from "../lib/detect-ides.mjs";
+import { readConfig, writeConfig } from "../lib/config.mjs";
+import { resolveFlags, effectiveVendors } from "../lib/cli-config.mjs";
+import { mergeMcpForVendors, printManualMcpInstructions } from "../lib/mcp-merge.mjs";
+import { runSync } from "../lib/sync.mjs";
+import { mergeEnvLocal } from "../lib/mergers/env-local.mjs";
+import { mergeGitignore } from "../lib/mergers/gitignore.mjs";
+import { mergeSessionHook } from "../lib/mergers/session-hook.mjs";
+import { resolveKeyFromEnvFiles } from "../lib/resolve-key.mjs";
 import {
-  printHeader,
-  printStep,
-  printSuccess,
-  printWarning,
-  printError,
-  printResult,
-  printBlank,
   promptSecret,
   confirm,
 } from "../lib/prompt.mjs";
-
-import { resolveKeyFromEnvFiles } from "../lib/resolve-key.mjs";
-
-const DEFAULT_URL = "https://skillrepo.dev";
+import {
+  CliError,
+  authError,
+  validationError,
+  EXIT_AUTH,
+} from "../lib/errors.mjs";
+
+// Local print helpers that use the INJECTED stdout/stderr streams.
+// The prompt.mjs `print*` helpers write to process.stdout directly,
+// which collides with the stream-injection pattern used by every
+// other command. The init command is the only one that needs the
+// step-progress UI, so these helpers live here rather than being
+// added to prompt.mjs.
+//
+// In --json mode, every human-readable helper is a no-op — stdout
+// is reserved for the final JSON blob so the output is pipe-friendly.
+
+const GREEN = (s) => `\x1b[32m${s}\x1b[0m`;
+const YELLOW = (s) => `\x1b[33m${s}\x1b[0m`;
+const RED = (s) => `\x1b[31m${s}\x1b[0m`;
+const DIM = (s) => `\x1b[2m${s}\x1b[0m`;
+const BOLD = (s) => `\x1b[1m${s}\x1b[0m`;
 
 /**
- * Parse CLI flags from argv.
- * @param {string[]} argv
+ * Build a set of print helpers tied to a specific output stream.
+ * When `silent` is true, every helper is a no-op except for
+ * `write()` which still writes to stdout (used for the final JSON).
  */
-function parseFlags(argv) {
-  const flags = {
-    key: resolveKeyFromEnvFiles(),
-    url: process.env.SKILLREPO_URL || DEFAULT_URL,
-    yes: false,
+function makePrinter(stdout, stderr, silent) {
+  const useColor = !silent && !process.env.NO_COLOR && stdout.isTTY;
+  const paint = (color) => (s) => (useColor ? color(s) : s);
+  const green = paint(GREEN);
+  const yellow = paint(YELLOW);
+  const red = paint(RED);
+  const dim = paint(DIM);
+  const bold = paint(BOLD);
+
+  const noop = () => {};
+
+  return {
+    header: silent ? noop : (title) => {
+      stdout.write(`\n  ${bold(title)}\n\n`);
+    },
+    step: silent ? noop : (n, total, msg) => {
+      stdout.write(`  ${dim(`Step ${n}/${total}:`)} ${msg}\n`);
+    },
+    success: silent ? noop : (msg) => {
+      stdout.write(`  ${green("✓")} ${msg}\n`);
+    },
+    warning: silent ? noop : (msg) => {
+      stdout.write(`  ${yellow("⚠")} ${msg}\n`);
+    },
+    error: silent ? noop : (msg) => {
+      stderr.write(`  ${red("✗")} ${msg}\n`);
+    },
+    blank: silent ? noop : () => {
+      stdout.write("\n");
+    },
+    /** Always writes regardless of silent mode — used for the final JSON. */
+    write: (text) => stdout.write(text),
   };
-
-  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;
 }
 
+const DEFAULT_URL = "https://skillrepo.dev";
+
 /**
- * Run the setup command.
- * @param {string[]} argv - CLI arguments after the "setup" subcommand
+ * A minimal no-op writable-stream shape. Used in --json mode to
+ * suppress sub-module writes that would otherwise pollute the
+ * captured stdout with non-JSON text. Any command/helper that
+ * follows the `{ stdout, stderr }` injection pattern can be
+ * silenced by passing this as `stdout`.
  */
-export async function runInit(argv) {
-  const flags = parseFlags(argv);
-
-  printHeader("SkillRepo Setup");
+const BLACK_HOLE_STREAM = {
+  write: () => true,
+  isTTY: false,
+};
 
-  // ── 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}`);
-    }
+/**
+ * Run `init`. Throws CliError on failure.
+ *
+ * @param {string[]} argv
+ * @param {object} [io]
+ * @param {NodeJS.WritableStream} [io.stdout=process.stdout]
+ * @param {NodeJS.WritableStream} [io.stderr=process.stderr]
+ */
+export async function runInit(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+
+  const { flags, yes, force, noSessionSync } = parseInitFlags(argv);
+
+  // In --json mode, suppress all step-progress output so stdout
+  // carries only the final JSON blob.
+  const p = makePrinter(stdout, stderr, flags.json);
+
+  p.header("SkillRepo Init");
+
+  // ── Step 1: Collect credentials ───────────────────────────────
+  p.step(1, 7, "Credentials");
+
+  // Try sources in priority: --key flag > --url flag > global
+  // config > env vars > interactive prompt.
+  const existingConfig = readConfig();
+  let apiKey = flags.apiKey;
+  let serverUrl = flags.serverUrl;
+
+  // `--force` re-prompts for a new key AND clears the stored
+  // serverUrl so a user pointing at a different SkillRepo instance
+  // (e.g., switching orgs) starts fresh. Without the URL clear,
+  // --force was surprising: the key was re-prompted but the URL
+  // silently inherited from the old config.
+  if (!apiKey && !force && existingConfig) {
+    apiKey = existingConfig.apiKey;
   }
-
-  if (detectedKeys.length === 0 || !Object.values(detected).some(Boolean)) {
-    printWarning("No IDEs detected — defaulting to Claude Code + Cursor");
+  if (!serverUrl && !force && existingConfig) {
+    serverUrl = existingConfig.serverUrl;
   }
-
-  // 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);
+  if (!serverUrl) {
+    serverUrl = process.env.SKILLREPO_URL || DEFAULT_URL;
+  }
+  if (!apiKey && !force) {
+    apiKey = resolveKeyFromEnvFiles();
+  }
+  // Interactive prompt if still missing (and not non-interactive)
+  if (!apiKey) {
+    if (yes) {
+      throw authError("No access key provided.", {
+        hint: "Pass --key sk_live_... or set SKILLREPO_ACCESS_KEY.",
+      });
     }
+    apiKey = await promptSecret("Enter your access key (sk_live_...)");
   }
 
-  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_...)");
+  // Trim whitespace from the key before validating. Pasting an API
+  // key from a browser or email client frequently adds a leading or
+  // trailing space or newline, which the server-side check would
+  // reject as invalid with no context. Trim early so the user gets
+  // a clean "works" or "wrong format" result.
+  if (typeof apiKey === "string") {
+    apiKey = apiKey.trim();
   }
 
-  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);
+  // Basic shape check (the full check is server-side via validate)
+  if (!apiKey || typeof apiKey !== "string" || !apiKey.startsWith("sk_live_")) {
+    throw validationError("Invalid access key format (must start with sk_live_).");
   }
 
-  printBlank();
+  p.blank();
 
-  // ── Step 3: Validate + Fetch ──────────────────────────────────────────
-  printStep(3, 4, "Validating key...");
+  // ── Step 2: Validate against the server ──────────────────────
+  p.step(2, 7, "Validating key");
+  let accountCtx;
+  try {
+    accountCtx = await validateAccessKey(serverUrl, apiKey);
+  } catch (err) {
+    // If the existing config had a stale/revoked key, fall back to
+    // prompt (unless --yes, which is meant to be non-interactive).
+    // Use the EXIT_AUTH constant rather than a magic number so a
+    // future refactor of errors.mjs can't silently break this branch.
+    if (
+      err instanceof CliError &&
+      err.exitCode === EXIT_AUTH &&
+      existingConfig &&
+      !force &&
+      !yes
+    ) {
+      p.warning("Existing config has an invalid key. Re-prompting for a new one.");
+      apiKey = (await promptSecret("Enter your access key (sk_live_...)")).trim();
+      if (!apiKey || !apiKey.startsWith("sk_live_")) {
+        throw validationError("Invalid access key format.");
+      }
+      accountCtx = await validateAccessKey(serverUrl, apiKey);
+    } else {
+      throw err;
+    }
+  }
+  p.success(`Valid. Account: ${accountCtx.accountSlug} (${accountCtx.tier})`);
+  p.blank();
+
+  // ── Step 3: Write global config ──────────────────────────────
+  p.step(3, 7, "Writing config");
+  const configAction = writeConfig({
+    apiKey,
+    serverUrl,
+    accountSlug: accountCtx.accountSlug,
+    accountId: accountCtx.accountId,
+    userId: accountCtx.userId,
+  });
+  p.success(`~/.claude/skillrepo/config.json ${configAction}`);
+
+  // Also write to .env.local so agents that read the env var
+  // continue to work. The mergeEnvLocal helper is unchanged from
+  // v2.0.0 and writes SKILLREPO_ACCESS_KEY=... in the project root.
+  try {
+    mergeEnvLocal(apiKey);
+  } catch (err) {
+    // Defensive: `err?.message ?? String(err)` handles the edge
+    // case where a non-Error value is thrown (plain string, number,
+    // etc.) and `err.message` would be undefined, producing a
+    // garbled warning.
+    p.warning(
+      `Could not write .env.local: ${err?.message ?? String(err)}. ` +
+        `Config is still saved at ~/.claude/skillrepo/config.json.`,
+    );
+  }
 
-  let payload;
+  // Ensure .env.local, .claude/skills/, and
+  // .claude/settings.local.json are in .gitignore. The access key
+  // in .env.local is the security-critical entry — without this
+  // step a user running `init` in a fresh project could commit
+  // their key with the next `git add .`. PR4 round-3 review caught
+  // that this gitignore management was documented but never
+  // implemented; this call closes that gap.
+  //
+  // Failure is non-fatal: if .gitignore is read-only or the user
+  // isn't in a git repo, we print a warning pointing them at the
+  // three entries they should add manually. The config is already
+  // saved at this point, so we don't abort init.
   try {
-    payload = await fetchSetupPayload(apiKey, flags.url);
+    const gitignoreResult = mergeGitignore();
+    if (gitignoreResult.action === "created") {
+      p.success(`.gitignore created with ${gitignoreResult.added.length} SkillRepo entries`);
+    } else if (gitignoreResult.action === "updated") {
+      p.success(
+        `.gitignore updated (added: ${gitignoreResult.added.join(", ")})`,
+      );
+    }
+    // "skipped" → all entries already present, no output needed
   } catch (err) {
-    if (err instanceof AuthError) {
-      printError(`Invalid access key. Get your key at ${flags.url}/app/integrations`);
-      process.exit(1);
+    p.warning(
+      `Could not update .gitignore: ${err?.message ?? String(err)}. ` +
+        `Add these entries manually: .env.local, .claude/skills/, ` +
+        `.claude/settings.local.json`,
+    );
+  }
+  p.blank();
+
+  // ── Step 4: Detect IDEs ──────────────────────────────────────
+  p.step(4, 7, "Detecting IDEs");
+
+  // The v2.0.0 CLI had a silent fallback to [claudeCode, cursor]
+  // when nothing was detected. The v3.0.0 CLI removes that — the
+  // user must opt in via --ide. This catches headless CI scenarios
+  // early rather than silently installing configs the user didn't
+  // ask for.
+  let vendors;
+  if (flags.vendors) {
+    vendors = flags.vendors;
+    p.success(`Using explicit --ide list: ${vendors.join(", ")}`);
+  } else {
+    const detected = detectIdes();
+    const detectedKeys = Object.entries(detected)
+      .filter(([, v]) => v)
+      .map(([k]) => k);
+    const ideList = formatDetectedIdes(detected);
+    for (const ide of ideList) {
+      if (ide.detected) p.success(ide.name);
     }
-    if (err instanceof SuspendedError) {
-      printError(`Account suspended: ${err.reason || "Contact your admin"}`);
-      process.exit(1);
+    if (detectedKeys.length === 0) {
+      // Print a copy-pasteable MCP config blob so users whose IDEs
+      // aren't supported for auto-detection can still wire up MCP
+      // manually. Then refuse so headless CI scenarios fail loudly
+      // unless the user opts in with --ide. This call makes
+      // printManualMcpInstructions live code — it was exported
+      // but unused after the initial PR3b draft.
+      const mcpUrl = `${serverUrl}/api/mcp`;
+      printManualMcpInstructions(mcpUrl, { stdout });
+
+      throw validationError("No IDEs detected in this directory.", {
+        hint:
+          "The JSON above is a copy-pasteable MCP config for any IDE. " +
+          "Or run init from inside a project with .claude/, .cursor/, .vscode/, " +
+          "or with --ide <vendor> (claude, cursor, windsurf, vscode).",
+      });
     }
-    if (err instanceof NetworkError) {
-      printError(`Cannot reach ${flags.url}. Check your network and the --url flag.`);
-      process.exit(1);
+    // Confirm the detected list unless --yes
+    if (!yes) {
+      const names = ideList
+        .filter((i) => i.detected)
+        .map((i) => i.name)
+        .join(", ");
+      const ok = await confirm(`Configure for: ${names}?`, true);
+      if (!ok) {
+        throw validationError("Cancelled. Pass --ide <vendor> to target specific IDEs.");
+      }
     }
-    throw err;
+    vendors = detectedKeys;
   }
-
-  printSuccess(`Valid. ${payload.skillCount} skills in your library.`);
-
-  if (payload.skillCount === 0) {
-    printWarning("No skills in your library yet. Config will be written — skills will activate when you add them.");
+  p.blank();
+
+  // ── Step 5: MCP auto-merge ───────────────────────────────────
+  p.step(5, 7, "Configuring MCP");
+  const mcpUrl = `${serverUrl}/api/mcp`;
+  // In --json mode, pass a black-hole stdout to mergeMcpForVendors
+  // so its per-vendor preview lines don't pollute the JSON output.
+  // Preserve stderr for warnings (which go to the user regardless).
+  const mergeIo = flags.json
+    ? { stdout: BLACK_HOLE_STREAM, stderr: stderr }
+    : io;
+  const mcpResults = await mergeMcpForVendors({
+    vendors,
+    mcpUrl,
+    yes,
+    io: mergeIo,
+  });
+  // Summarize
+  const merged = mcpResults.filter((r) => r.outcome === "merged");
+  const skipped = mcpResults.filter((r) => r.outcome === "skipped");
+  const failed = mcpResults.filter((r) => r.outcome === "failed");
+  if (merged.length > 0) {
+    p.success(`MCP configured for ${merged.length} vendor${merged.length === 1 ? "" : "s"}`);
   }
+  if (skipped.length > 0) {
+    p.warning(`MCP skipped for ${skipped.length} vendor${skipped.length === 1 ? "" : "s"}`);
+  }
+  if (failed.length > 0) {
+    p.warning(`MCP failed for ${failed.length} vendor${failed.length === 1 ? "" : "s"}`);
+    for (const r of failed) {
+      p.error(`  ${r.path}: ${r.reason}`);
+    }
+  }
+  p.blank();
+
+  // ── Step 6: Session sync (#884) ──────────────────────────────
+  //
+  // Install the Claude Code SessionStart hook so the user's library
+  // auto-syncs on every session start. Per the architect design in
+  // issue #884:
+  //   - Opt-in by default. Interactive mode prompts before installing.
+  //     `--yes` skips the prompt and installs. `--no-session-sync`
+  //     is the explicit opt-out for BOTH modes — CI bootstraps
+  //     without session sync by passing it.
+  //   - If `which skillrepo` fails (e.g. npx user without a global
+  //     install), we SKIP with a warning. Init continues — do not
+  //     abort for this.
+  //   - A failure writing the settings file is non-fatal: the
+  //     config, MCP, and first sync still run. Users can re-run
+  //     `skillrepo session-sync enable` later.
+  //   - **Skip entirely when Claude Code is not the target.** The
+  //     SessionStart hook is Claude Code-specific: it lives at
+  //     `.claude/settings.local.json` and is only read by Claude
+  //     Code's session-start machinery. A Cursor-only or
+  //     Windsurf-only user doesn't benefit from it and shouldn't
+  //     get a prompt for it. Cross-PR review (v3.1.0) flagged this
+  //     as a silent-useless-state bug: without the guard, the hook
+  //     file was written even for non-Claude projects. The only
+  //     "Claude Code is the target" signals are:
+  //       • `vendors` includes "claudeCode" (either explicit
+  //         `--ide claude` or detected `.claude/` directory), OR
+  //       • `--global` is passed (writes to
+  //         `~/.claude/settings.local.json`, which is explicitly
+  //         Claude Code's user-wide path).
+  //     Everything else → skip with a clear message.
+  //
+  // This step is INSERTED between MCP merge (step 5) and the first
+  // sync (step 7). Order matters — we need the config written
+  // (step 3) so the hook's `skillrepo update` calls find creds.
+  p.step(6, 7, "Session sync");
+  let sessionSyncAction = "skipped";
+  let sessionSyncPath = null;
+  const claudeTargeted =
+    Boolean(flags.global) ||
+    (Array.isArray(vendors) && vendors.includes("claudeCode"));
+  if (noSessionSync) {
+    p.warning("Session sync skipped (--no-session-sync).");
+    sessionSyncAction = "opted-out";
+  } else if (!claudeTargeted) {
+    // Non-Claude-Code target (e.g. `--ide cursor`) — the hook would
+    // never fire, so skip the prompt AND the install. This is the
+    // v3.1.0 cross-PR review fix.
+    p.warning(
+      "Session sync skipped: the SessionStart hook is Claude Code-specific " +
+        "and no Claude Code target was configured.",
+    );
+    sessionSyncAction = "not-applicable";
+  } else {
+    let proceed = true;
+    if (!yes) {
+      proceed = await confirm(
+        "Install Claude Code SessionStart hook so your library auto-syncs on every session start?",
+        true,
+      );
+    }
+    if (!proceed) {
+      p.warning(
+        "Session sync skipped. Run `skillrepo session-sync enable` to install it later.",
+      );
+      sessionSyncAction = "declined";
+    } else {
+      try {
+        const result = mergeSessionHook({ global: flags.global });
+        sessionSyncAction = result.action;
+        sessionSyncPath = result.path;
+        if (result.action === "installed") {
+          p.success(`SessionStart hook installed (${result.path})`);
+        } else if (result.action === "updated") {
+          p.success(`SessionStart hook updated (${result.path})`);
+        } else if (result.action === "unchanged") {
+          p.success(`SessionStart hook already installed (${result.path})`);
+        } else if (result.action === "skipped") {
+          // Binary not resolvable — the installer returned a reason.
+          p.warning(result.reason ?? "Session sync skipped.");
+        }
+      } catch (err) {
+        // Disk error (corrupt settings file, permissions). The
+        // other init steps already ran, so the config and MCP are
+        // still in place. Surface the error and continue to the
+        // first sync step — do NOT abort.
+        p.warning(
+          `Session sync failed: ${err?.message ?? String(err)}. ` +
+            `Run \`skillrepo session-sync enable\` after fixing the issue.`,
+        );
+        sessionSyncAction = "failed";
+      }
+    }
+  }
+  p.blank();
 
-  printBlank();
-
-  // ── Step 4: Write configs ─────────────────────────────────────────────
-  printStep(4, 4, "Writing configuration...");
-  printBlank();
-
-  const mcpUrl = `${flags.url}/api/mcp`;
-
-  let results;
+  // ── Step 7: First sync ───────────────────────────────────────
+  p.step(7, 7, "Pulling library");
+  let syncSummary;
+  let syncFailedReason = null;
   try {
-    results = writeAllConfigs({
-      ides: detectedKeys,
-      mcpUrl,
+    // In --json mode, suppress runSync's warning prints to stdout
+    // by passing a black-hole stream. (Its warnings go to stderr
+    // by default, which stays visible.)
+    const syncIo = flags.json
+      ? { stdout: BLACK_HOLE_STREAM, stderr: stderr }
+      : io;
+    syncSummary = await runSync({
+      serverUrl,
       apiKey,
-      serverUrl: flags.url,
-      userId: payload.userId,
+      vendors: effectiveVendors({ vendors, global: flags.global }),
+      global: flags.global,
+      io: syncIo,
     });
   } catch (err) {
-    printError(err.message);
-    process.exit(2);
+    // A sync failure after the rest of init succeeded is a
+    // partial-state concern: config IS saved, MCP IS configured,
+    // and the access key IS validated — only the skill files
+    // haven't been fetched yet. The right recovery is `skillrepo
+    // update`, not a re-init. Surface the warning and exit 0 so
+    // the user sees the "run update later" message as actionable
+    // guidance rather than as a failed-command contradiction.
+    //
+    // Round-2 review caught the prior behavior (warn + unconditional
+    // rethrow) as an inconsistent contract: the warning told users
+    // to retry with `update`, but the non-zero exit code made it
+    // look like the whole init had failed.
+    p.warning(
+      `Config saved but first sync failed: ${err.message}. ` +
+        `Run \`skillrepo update\` later to retry.`,
+    );
+    syncFailedReason = err.message;
+    // Synthesize a zero-delta summary matching the SyncSummary
+    // typedef in sync.mjs (added, updated, removed, notModified,
+    // syncedAt). No `unchanged` or `failed` field — those were
+    // phantom fields the cross-review flagged; failure is signaled
+    // via `syncFailedReason` locally and via `sync.failureReason`
+    // in the --json output below.
+    syncSummary = {
+      added: 0,
+      updated: 0,
+      removed: 0,
+      notModified: false,
+      syncedAt: new Date().toISOString(),
+    };
   }
 
-  for (const r of results) {
-    printResult(r.path, r.action);
+  if (syncFailedReason) {
+    // The warning already printed; the step-summary success line
+    // would be misleading, so we skip it. Any helpful "next steps"
+    // is in the final `SkillRepo is ready` block.
+  } else if (syncSummary.notModified || syncSummary.added + syncSummary.updated + syncSummary.removed === 0) {
+    p.success("No skills in library yet (add some with `skillrepo add @owner/name`)");
+  } else {
+    p.success(
+      `${syncSummary.added} added, ${syncSummary.updated} updated, ${syncSummary.removed} removed`,
+    );
   }
-
-  printBlank();
-
-  // ── 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 init");
-  console.log("  • SKILLREPO_ACCESS_KEY is in .env.local (gitignored)");
-
-  if (detectedKeys.includes("claudeCode")) {
-    printBlank();
-    console.log("  Claude Code: Skills are delivered via .claude/rules/ files.");
-    console.log("  They refresh automatically on each session start.");
+  p.blank();
+
+  // ── Summary ──────────────────────────────────────────────────
+  if (flags.json) {
+    stdout.write(
+      JSON.stringify(
+        {
+          action: "initialized",
+          account: {
+            slug: accountCtx.accountSlug,
+            id: accountCtx.accountId,
+            tier: accountCtx.tier,
+          },
+          config: { action: configAction },
+          vendors,
+          mcp: {
+            merged: merged.map((r) => r.path),
+            skipped: skipped.map((r) => r.path),
+            failed: failed.map((r) => ({ path: r.path, reason: r.reason })),
+          },
+          // Session-sync block — action values:
+          //   "installed" | "updated" | "unchanged" (success states)
+          //   "opted-out" (--no-session-sync)
+          //   "declined" (user said no at the prompt)
+          //   "not-applicable" (no Claude Code target — e.g. `--ide cursor`)
+          //   "skipped" (binary not resolvable — reason in non-json path)
+          //   "failed" (disk error during install)
+          sessionSync: {
+            action: sessionSyncAction,
+            path: sessionSyncPath,
+          },
+          // Sync block always shows the counts (zeroed on failure)
+          // and adds `failureReason` when the first sync blew up —
+          // downstream scripts can `.failureReason != null` to
+          // detect a recoverable partial init.
+          sync: syncFailedReason
+            ? { ...syncSummary, failureReason: syncFailedReason }
+            : syncSummary,
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    return;
   }
 
-  if (detectedKeys.includes("vscode")) {
-    printBlank();
-    console.log("  Note: VS Code will prompt for your access key on first use.");
-  }
+  stdout.write("\n  ✓ SkillRepo is ready.\n\n");
+  stdout.write("  Next steps:\n");
+  stdout.write("    • skillrepo list    — see what's in your library\n");
+  stdout.write("    • skillrepo search <query>  — find skills\n");
+  stdout.write("    • skillrepo add @owner/name — add a skill\n\n");
+}
 
-  printBlank();
+/**
+ * Parse init-specific flags. Uses resolveFlags for the common ones
+ * (--key/--url/--global/--ide/--json) and pulls out --yes/-y + --force.
+ */
+function parseInitFlags(argv) {
+  // resolveFlags handles --key/--url/--global/--ide/--json and
+  // rejects unknown flags via its acceptPositional callback. We
+  // intercept --yes, --force, and --no-session-sync as "positional-
+  // shaped" flags via the callback so we don't need to pre-filter
+  // argv.
+  let yes = false;
+  let force = false;
+  let noSessionSync = false;
+
+  const flags = resolveFlags(argv, {
+    requireAuth: false, // init MAY prompt for a key, so don't hard-fail
+    // Don't let resolveFlags read from the global config file. init
+    // owns the credential lifecycle — it reads the config itself
+    // (via readConfig) so --force and the stale-key re-prompt path
+    // can decide whether to consume the cached credentials. If we
+    // let resolveFlags inject them silently, --force becomes a
+    // no-op: flags.apiKey would already be the cached key by the
+    // time init's --force branch runs.
+    skipConfig: true,
+    acceptPositional(arg) {
+      if (arg === "--yes" || arg === "-y") {
+        yes = true;
+        return 1;
+      }
+      if (arg === "--force") {
+        force = true;
+        return 1;
+      }
+      if (arg === "--no-session-sync") {
+        // #884: explicit opt-out for BOTH interactive and --yes
+        // modes. CI scripts that bootstrap a project without ever
+        // starting a Claude Code session pass this to skip the hook
+        // installation entirely.
+        noSessionSync = true;
+        return 1;
+      }
+      return false; // anything else is unknown
+    },
+  });
+
+  return { flags, yes, force, noSessionSync };
 }