@mushi-mushi/cli 0.10.0 → 0.11.1

package/dist/index.js

@@ -263,6 +263,71 @@ export default function App() {
 import { Mushi } from '@mushi-mushi/capacitor'
 
 await Mushi.configure({ projectId: '${projectId}', apiKey: '${apiKey}' })`
+  },
+  express: {
+    id: "express",
+    label: "Express",
+    packageName: "@mushi-mushi/node",
+    needsWebPackage: false,
+    snippet: (apiKey, projectId) => `// src/instrument.ts \u2014 load with: node --import ./dist/instrument.js
+import { MushiNodeClient, attachUnhandledHook } from '@mushi-mushi/node'
+import { mushiExpressErrorHandler } from '@mushi-mushi/node/express'
+import type { Express } from 'express'
+
+export const mushi = new MushiNodeClient({
+  projectId: '${projectId}',
+  apiKey: '${apiKey}',
+  environment: process.env.NODE_ENV ?? 'production',
+})
+attachUnhandledHook({ client: mushi })
+
+export function attachMushi(app: Express) {
+  app.use(mushiExpressErrorHandler({ client: mushi }))
+}`
+  },
+  fastify: {
+    id: "fastify",
+    label: "Fastify",
+    packageName: "@mushi-mushi/node",
+    needsWebPackage: false,
+    snippet: (apiKey, projectId) => `// src/instrument.ts \u2014 load with: node --import ./dist/instrument.js
+import { MushiNodeClient, attachUnhandledHook } from '@mushi-mushi/node'
+import { mushiFastifyPlugin } from '@mushi-mushi/node/fastify'
+import Fastify from 'fastify'
+
+export const mushi = new MushiNodeClient({
+  projectId: '${projectId}',
+  apiKey: '${apiKey}',
+  environment: process.env.NODE_ENV ?? 'production',
+})
+attachUnhandledHook({ client: mushi })
+
+const app = Fastify()
+mushiFastifyPlugin(app, { client: mushi })`
+  },
+  hono: {
+    id: "hono",
+    label: "Hono",
+    packageName: "@mushi-mushi/node",
+    needsWebPackage: false,
+    snippet: (apiKey, projectId) => `// src/instrument.ts \u2014 load with: node --import ./dist/instrument.js
+import { MushiNodeClient, attachUnhandledHook } from '@mushi-mushi/node'
+import { mushiHonoErrorHandler } from '@mushi-mushi/node/hono'
+import { Hono } from 'hono'
+
+export const mushi = new MushiNodeClient({
+  projectId: '${projectId}',
+  apiKey: '${apiKey}',
+  environment: process.env.NODE_ENV ?? 'production',
+})
+attachUnhandledHook({ client: mushi })
+
+const app = new Hono()
+app.onError(
+  mushiHonoErrorHandler({ client: mushi }, (err, c) =>
+    c.text('Internal Server Error', 500),
+  ),
+)`
   },
   vanilla: {
     id: "vanilla",
@@ -296,6 +361,9 @@ function detectFramework(cwd, pkg) {
   if (deps.has("svelte")) return FRAMEWORKS.svelte;
   if (deps.has("vue")) return FRAMEWORKS.vue;
   if (deps.has("react")) return FRAMEWORKS.react;
+  if (deps.has("express")) return FRAMEWORKS.express;
+  if (deps.has("fastify")) return FRAMEWORKS.fastify;
+  if (deps.has("hono") || deps.has("@hono/hono")) return FRAMEWORKS.hono;
   if (existsSync2(join2(cwd, "next.config.js")) || existsSync2(join2(cwd, "next.config.ts"))) {
     return FRAMEWORKS.next;
   }
@@ -321,7 +389,14 @@ function installCommand(pm, packages) {
   const verb = pm === "npm" ? "install" : "add";
   return `${pm} ${verb} ${packages.join(" ")}`;
 }
+var SERVER_FRAMEWORK_IDS = /* @__PURE__ */ new Set(["express", "fastify", "hono"]);
 function envVarsToWrite(apiKey, projectId, framework) {
+  if (SERVER_FRAMEWORK_IDS.has(framework.id)) {
+    return [
+      `MUSHI_PROJECT_ID=${projectId}`,
+      `MUSHI_API_KEY=${apiKey}`
+    ].join("\n");
+  }
   const prefix = framework.id === "next" ? "NEXT_PUBLIC_" : framework.id === "nuxt" ? "NUXT_PUBLIC_" : "VITE_";
   return [
     `${prefix}MUSHI_PROJECT_ID=${projectId}`,
@@ -520,7 +595,7 @@ function getFrameworkFromPkg(pkg) {
 }
 
 // src/version.ts
-var MUSHI_CLI_VERSION = true ? "0.10.0" : "0.0.0-dev";
+var MUSHI_CLI_VERSION = true ? "0.11.1" : "0.0.0-dev";
 
 // src/init.ts
 var ENV_FILES = [".env.local", ".env"];
@@ -569,7 +644,7 @@ function ensureInteractiveOrBailOut(options) {
   );
   if (hasAllFlags) return;
   process.stderr.write(
-    "mushi-mushi: non-interactive terminal detected.\nPass all of --yes (or --framework), --project-id, and --api-key to run unattended.\nExample: npx mushi-mushi --yes --project-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx --api-key mushi_xxx\nYour project ID is the UUID shown in the Projects page of the Mushi admin console.\n"
+    "mushi-mushi: non-interactive terminal detected.\nPass all of --yes (or --framework), --project-id, and --api-key to run unattended.\nExample: npx mushi-mushi --yes --project-id <uuid-from-console> --api-key mushi_xxx\nYour project ID is the UUID shown in the Projects page of the Mushi admin console.\n"
   );
   process.exit(1);
 }
@@ -603,9 +678,9 @@ async function collectCredentials(options) {
   const existing = loadConfig();
   const rawProjectId = options.projectId ?? existing.projectId ?? await promptText({
     message: "Project ID",
-    placeholder: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    placeholder: "e.g. bdafa28d-b153-482f-bd4f-42981f3fd3a4",
     hint: "Where to find it: https://kensaur.us/mushi-mushi/projects \u2192 click your project \u2192 copy the UUID below the project name.",
-    validate: (v) => PROJECT_ID_PATTERN.test(v) ? void 0 : "Expected a UUID (xxxxxxxx-xxxx-...) \u2014 copy it from the Mushi admin console Projects page."
+    validate: (v) => PROJECT_ID_PATTERN.test(v.trim()) ? void 0 : "Expected a UUID (e.g. bdafa28d-b153-482f-bd4f-42981f3fd3a4) \u2014 copy it from the Mushi admin console Projects page."
   });
   const rawApiKey = options.apiKey ?? existing.apiKey ?? await promptText({
     message: "API key",
@@ -617,8 +692,7 @@ async function collectCredentials(options) {
   const apiKey = sanitizeSecret(rawApiKey);
   if (!PROJECT_ID_PATTERN.test(projectId)) {
     throw new Error(
-      `Invalid project ID. Got: ${redact(projectId)}
-Expected a UUID (e.g. 542b34e0-019e-41fe-b900-7b637717bb86) \u2014 copy it from the Projects page in the Mushi console at https://kensaur.us/mushi-mushi/projects`
+      `Invalid project ID. Expected a UUID (e.g. bdafa28d-b153-482f-bd4f-42981f3fd3a4) or the proj_* prefixed form. Got: ${redact(projectId)} \u2014 copy it from the Projects page in the Mushi console at https://kensaur.us/mushi-mushi/projects`
     );
   }
   if (!API_KEY_PATTERN.test(apiKey)) {
@@ -963,7 +1037,7 @@ function depsFromPackageJson(pkg) {
 }
 function runMigrate(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
-  const log3 = opts.log ?? ((s) => console.log(s));
+  const log3 = opts.log ?? ((s) => console.warn(s));
   const pkg = readPackageJson(cwd);
   if (!pkg) {
     log3(
@@ -1232,6 +1306,254 @@ function getAbortSignal(external) {
   return activeController.signal;
 }
 
+// src/nudge.ts
+var PRESETS = {
+  // Alpha: noisy is OK because there are very few users and you need
+  // signal yesterday. Show all triggers, short cooldowns.
+  alpha: {
+    maxProactivePerSession: 3,
+    dismissCooldownHours: 6,
+    suppressAfterDismissals: 5,
+    pageDwellMinutes: 3,
+    firstSessionSeconds: 30,
+    rageClick: true,
+    longTask: true,
+    apiCascade: true,
+    errorBoundary: true,
+    betaMode: true,
+    featureRequestCard: true
+  },
+  // Beta: most apps spend the longest here. Conservative cadence so
+  // we don't poison the well, but every trigger still on.
+  beta: {
+    maxProactivePerSession: 2,
+    dismissCooldownHours: 24,
+    suppressAfterDismissals: 3,
+    pageDwellMinutes: 5,
+    firstSessionSeconds: 45,
+    rageClick: true,
+    longTask: true,
+    apiCascade: true,
+    errorBoundary: true,
+    betaMode: true,
+    featureRequestCard: true
+  },
+  // GA / production: only the technical signals (error boundary, rage
+  // click). No page-dwell, no welcome — those are explicitly beta-only
+  // patterns. Feature-request card still on because it's user-initiated.
+  ga: {
+    maxProactivePerSession: 1,
+    dismissCooldownHours: 168,
+    suppressAfterDismissals: 2,
+    pageDwellMinutes: 0,
+    firstSessionSeconds: 0,
+    rageClick: true,
+    longTask: false,
+    apiCascade: true,
+    errorBoundary: true,
+    betaMode: false,
+    featureRequestCard: true
+  }
+};
+function renderNudgeSnippet(opts) {
+  const p3 = { ...PRESETS[opts.phase], ...opts.overrides };
+  const dwellMs = p3.pageDwellMinutes > 0 ? `${p3.pageDwellMinutes} * 60 * 1000` : null;
+  const firstMs = p3.firstSessionSeconds > 0 ? `${p3.firstSessionSeconds} * 1000` : null;
+  const proactiveLines = [];
+  if (p3.rageClick) proactiveLines.push(`    rageClick: true,`);
+  if (p3.longTask) proactiveLines.push(`    longTask: true,`);
+  if (p3.apiCascade) proactiveLines.push(`    apiCascade: true,`);
+  if (p3.errorBoundary) proactiveLines.push(`    errorBoundary: true,`);
+  if (dwellMs) proactiveLines.push(`    pageDwell: { thresholdMs: ${dwellMs} }, // ${p3.pageDwellMinutes}min on the same route`);
+  if (firstMs) proactiveLines.push(`    firstSession: { delayMs: ${firstMs} }, // welcome new users after ${p3.firstSessionSeconds}s`);
+  proactiveLines.push(`    cooldown: {`);
+  proactiveLines.push(`      maxProactivePerSession: ${p3.maxProactivePerSession},`);
+  proactiveLines.push(`      dismissCooldownHours: ${p3.dismissCooldownHours},`);
+  proactiveLines.push(`      suppressAfterDismissals: ${p3.suppressAfterDismissals},`);
+  proactiveLines.push(`    },`);
+  const widgetLines = [];
+  if (p3.featureRequestCard) widgetLines.push(`    featureRequestCard: true,`);
+  if (p3.betaMode) {
+    widgetLines.push(`    betaMode: {`);
+    widgetLines.push(`      enabled: true,`);
+    widgetLines.push(`      label: 'BETA',`);
+    widgetLines.push(`      // changelogItems: [{ version: 'v0.42', date: '${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}', items: ['\u2026'] }],`);
+    widgetLines.push(`    },`);
+  }
+  return [
+    `// Generated by \`mushi nudge --phase ${opts.phase}\``,
+    `// Phase: ${opts.phase} \u2014 tune via --max, --cooldown, --dwell, --welcome.`,
+    `Mushi.init({`,
+    `  projectId: process.env.MUSHI_PROJECT_ID!,`,
+    `  apiKey: process.env.MUSHI_API_KEY!,`,
+    `  proactive: {`,
+    ...proactiveLines,
+    `  },`,
+    ...widgetLines.length ? [`  widget: {`, ...widgetLines, `  },`] : [],
+    `})`,
+    ``
+  ].join("\n");
+}
+function renderNudgeExplainer(phase) {
+  const p3 = PRESETS[phase];
+  const lines = [];
+  lines.push(``);
+  lines.push(`Nudge preset for "${phase}" phase:`);
+  lines.push(`  - max ${p3.maxProactivePerSession} proactive prompts per session`);
+  lines.push(`  - ${p3.dismissCooldownHours}h cooldown after a dismissal`);
+  lines.push(`  - suppress permanently after ${p3.suppressAfterDismissals} consecutive dismissals`);
+  if (p3.pageDwellMinutes > 0) lines.push(`  - fire page-dwell trigger after ${p3.pageDwellMinutes} continuous minutes on a route`);
+  if (p3.firstSessionSeconds > 0) lines.push(`  - welcome new users with a button pulse ${p3.firstSessionSeconds}s after init`);
+  lines.push(`  - signals enabled: ${[
+    p3.rageClick && "rage-click",
+    p3.longTask && "long-task",
+    p3.apiCascade && "api-cascade",
+    p3.errorBoundary && "error-boundary"
+  ].filter(Boolean).join(", ")}`);
+  lines.push(`  - feature-request card: ${p3.featureRequestCard ? "shown" : "hidden"}`);
+  lines.push(`  - beta-mode UI: ${p3.betaMode ? "on" : "off"}`);
+  lines.push(``);
+  return lines.join("\n");
+}
+
+// src/doctor.ts
+function checkCliConfig(config) {
+  return [
+    {
+      name: "CLI config file",
+      ok: Boolean(config.endpoint),
+      detail: config.endpoint ? `endpoint=${config.endpoint}` : "No endpoint in ~/.mushirc \u2014 run `mushi init` or `mushi config endpoint <url>`"
+    },
+    {
+      name: "API key configured",
+      ok: Boolean(config.apiKey),
+      detail: config.apiKey ? `apiKey=${config.apiKey.slice(0, 8)}\u2026${config.apiKey.slice(-4)}` : "No API key set \u2014 run `mushi login --api-key <key>`"
+    },
+    {
+      name: "Project ID configured",
+      ok: Boolean(config.projectId),
+      detail: config.projectId ? `projectId=${config.projectId}` : "No default project \u2014 set via `mushi config projectId <uuid>`"
+    }
+  ];
+}
+async function checkEndpointReachability(endpoint, doFetch = globalThis.fetch) {
+  try {
+    const res = await doFetch(`${endpoint}/health`, {
+      signal: AbortSignal.timeout(5e3)
+    });
+    return {
+      name: "Endpoint reachable",
+      ok: res.status === 200,
+      detail: `GET ${endpoint}/health \u2192 ${res.status}`
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { name: "Endpoint reachable", ok: false, detail: `Fetch failed: ${msg}` };
+  }
+}
+async function checkSdkInstall(cwd) {
+  try {
+    const { readFile: readFile2, access } = await import("fs/promises");
+    const { join: join6, resolve: resolve2 } = await import("path");
+    const root = resolve2(cwd);
+    const pkgPath = join6(root, "package.json");
+    await access(pkgPath);
+    const pkg = JSON.parse(await readFile2(pkgPath, "utf8"));
+    const deps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
+    const sdks = [
+      "@mushi-mushi/react",
+      "@mushi-mushi/web",
+      "@mushi-mushi/core",
+      "@mushi-mushi/react-native"
+    ];
+    const installed2 = sdks.filter((s) => deps[s]);
+    return {
+      name: "SDK installed in this repo",
+      ok: installed2.length > 0,
+      detail: installed2.length > 0 ? installed2.map((s) => `${s}@${deps[s]}`).join(", ") : "No @mushi-mushi/* package in package.json \u2014 run `mushi init` to install"
+    };
+  } catch {
+    return null;
+  }
+}
+async function checkServerPreflight(config, doFetch = globalThis.fetch) {
+  if (!config.projectId || !config.apiKey || !config.endpoint) {
+    return [
+      {
+        name: "Server preflight",
+        ok: false,
+        detail: "Need projectId, apiKey, and endpoint. Run `mushi login` and `mushi config projectId <uuid>`."
+      }
+    ];
+  }
+  try {
+    const res = await doFetch(
+      `${config.endpoint}/v1/admin/projects/${config.projectId}/preflight`,
+      {
+        headers: {
+          Authorization: `Bearer ${config.apiKey}`,
+          "X-Mushi-Api-Key": config.apiKey,
+          "X-Mushi-Project": config.projectId
+        },
+        signal: AbortSignal.timeout(8e3)
+      }
+    );
+    if (res.ok) {
+      const body = await res.json();
+      const serverChecks = body.data?.checks ?? [];
+      return serverChecks.map((sc) => ({
+        name: `[server] ${sc.label}`,
+        ok: sc.ready,
+        detail: sc.hint
+      }));
+    }
+    const text2 = await res.text().catch(() => "");
+    return [
+      {
+        name: "Server preflight",
+        ok: false,
+        detail: `HTTP ${res.status}: ${text2.slice(0, 120)}`
+      }
+    ];
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return [{ name: "Server preflight", ok: false, detail: `Fetch failed: ${msg}` }];
+  }
+}
+async function runDoctor(config, options = {}) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const checks = [];
+  checks.push(...checkCliConfig(config));
+  if (config.endpoint) {
+    checks.push(await checkEndpointReachability(config.endpoint, doFetch));
+  }
+  const sdkCheck = await checkSdkInstall(options.cwd ?? process.cwd());
+  if (sdkCheck) checks.push(sdkCheck);
+  if (options.server) {
+    const serverChecks = await checkServerPreflight(config, doFetch);
+    checks.push(...serverChecks);
+  }
+  return { checks, ready: checks.every((c) => c.ok) };
+}
+function formatDoctorResult(result) {
+  const PASS = "\u2713";
+  const FAIL = "\u2717";
+  const lines = [];
+  for (const c of result.checks) {
+    lines.push(`${c.ok ? PASS : FAIL} ${c.name}`);
+    lines.push(`  ${c.detail}`);
+  }
+  const failed = result.checks.filter((c) => !c.ok);
+  if (failed.length === 0) {
+    lines.push("\nAll checks passed. The CLI is ready.");
+  } else {
+    lines.push(`
+${failed.length} check${failed.length === 1 ? "" : "s"} failed.`);
+    lines.push("Fix the items above and re-run `mushi doctor`.");
+  }
+  return lines.join("\n");
+}
+
 // src/index.ts
 installSignalHandlers();
 var API_TIMEOUT_MS = 15e3;
@@ -1945,6 +2267,260 @@ Examples:
     silent: opts.silent
   });
 });
+var project = program.command("project").description("Project management");
+project.command("create").description("Create a new Mushi project, mint an API key, and write config files").option("--name <name>", "Project name (skip the prompt)").option("--no-browser", "Skip opening the browser for the sign-up / magic-link step").option("--endpoint <url>", "Override API endpoint (self-hosted)").addHelpText("after", `
+Creates a project on app.mushimushi.dev, mints an API key with mcp:read+write scope,
+and writes the following to the current directory:
+  .env.local            \u2014 MUSHI_API_KEY, MUSHI_PROJECT_ID, MUSHI_API_ENDPOINT
+  .cursor/mcp.json      \u2014 pre-filled mcpServers.mushi block for Cursor
+
+Typical first-time flow:
+  npx mushi-mushi project create
+  # Browser opens \u2192 sign up / magic-link \u2192 come back to terminal
+  # CLI writes .env.local and .cursor/mcp.json
+  # mushi whoami to confirm`).action(async (opts) => {
+  const { writeFile, mkdir } = await import("fs/promises");
+  const { existsSync: existsSync5 } = await import("fs");
+  const nodePath = await import("path");
+  const endpoint = opts.endpoint ?? loadConfig().endpoint ?? "https://api.mushimushi.dev";
+  const signUpUrl = "https://kensaur.us/mushi-mushi/sign-up";
+  console.log("");
+  console.log("  Mushi project create");
+  console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  console.log("");
+  if (opts.browser !== false) {
+    console.log("  1. Opening the Mushi sign-up page in your browser...");
+    try {
+      const { exec } = await import("child_process");
+      const openCmd = process.platform === "win32" ? `start "" "${signUpUrl}"` : process.platform === "darwin" ? `open "${signUpUrl}"` : `xdg-open "${signUpUrl}"`;
+      exec(openCmd);
+    } catch {
+    }
+  } else {
+    console.log(`  1. Sign up or log in at: ${signUpUrl}`);
+  }
+  console.log("");
+  console.log("  2. Create a project in the console, then paste your credentials below.");
+  console.log("     (Settings \u2192 API Keys \u2192 New key \u2192 Copy as .env.local)");
+  console.log("");
+  const { createInterface } = await import("readline");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise((resolve2) => rl.question(q, (a) => resolve2(a.trim())));
+  const projectId = await ask("  Project ID (uuid): ");
+  const apiKey = await ask("  API key (mushi_...): ");
+  rl.close();
+  if (!projectId || !apiKey) {
+    process.stderr.write("\nerror: Project ID and API key are required.\n");
+    process.exit(2);
+  }
+  const config = loadConfig();
+  config.apiKey = apiKey;
+  config.endpoint = endpoint;
+  config.projectId = projectId;
+  saveConfig(config);
+  const cwd = process.cwd();
+  const envPath = nodePath.join(cwd, ".env.local");
+  const envLines = [
+    "# Mushi MCP \u2014 drop into .env.local (gitignored). The MCP binary picks these up on spawn.",
+    `MUSHI_API_ENDPOINT=${endpoint}`,
+    `MUSHI_PROJECT_ID=${projectId}`,
+    `MUSHI_API_KEY=${apiKey}`,
+    ""
+  ];
+  const envExisting = existsSync5(envPath);
+  await writeFile(envPath, envLines.join("\n"), "utf8");
+  console.log(`
+  \u2713 ${envExisting ? "Updated" : "Created"} .env.local`);
+  const mcpDir = nodePath.join(cwd, ".cursor");
+  await mkdir(mcpDir, { recursive: true });
+  const mcpPath = nodePath.join(mcpDir, "mcp.json");
+  const mcpJson = {
+    mcpServers: {
+      mushi: {
+        command: "npx",
+        args: ["-y", "mushi-mcp@latest"],
+        env: {
+          MUSHI_API_ENDPOINT: endpoint,
+          MUSHI_PROJECT_ID: projectId,
+          MUSHI_API_KEY: apiKey
+        }
+      }
+    }
+  };
+  const mcpExisting = existsSync5(mcpPath);
+  if (mcpExisting) {
+    try {
+      const { readFile: readFile2 } = await import("fs/promises");
+      const raw = JSON.parse(await readFile2(mcpPath, "utf8"));
+      const existing = raw;
+      existing.mcpServers = { ...existing.mcpServers ?? {}, mushi: mcpJson.mcpServers.mushi };
+      await writeFile(mcpPath, JSON.stringify(existing, null, 2) + "\n", "utf8");
+    } catch {
+      await writeFile(mcpPath, JSON.stringify(mcpJson, null, 2) + "\n", "utf8");
+    }
+  } else {
+    await writeFile(mcpPath, JSON.stringify(mcpJson, null, 2) + "\n", "utf8");
+  }
+  console.log(`  \u2713 ${mcpExisting ? "Updated" : "Created"} .cursor/mcp.json`);
+  console.log("");
+  console.log('  Done! Restart Cursor and ask: "list mushi tools"');
+  console.log("  Run `mushi whoami` to verify the connection.");
+  console.log("");
+});
+program.command("setup").description("Wire Mushi into your IDE with one command").option("--ide <ide>", "Target IDE: cursor | claude | continue | zed", "cursor").option("--project-slug <slug>", "Override the project slug in the server name (default: project ID prefix)").option("--with-rules", "Also write the .cursorrules / .claude/rules/mushi.md lesson-library hook").option("--dry-run", "Print what would be written without making changes").addHelpText("after", `
+Examples:
+  mushi setup                         # wire Cursor (default)
+  mushi setup --ide claude            # wire Claude Code
+  mushi setup --ide cursor --with-rules  # also write .cursorrules
+
+Supported IDEs:
+  cursor    \u2014 writes .cursor/mcp.json
+  claude    \u2014 writes .claude/mcp.json (Claude Code / Claude Desktop)
+  continue  \u2014 writes .continue/mcp.json
+  zed       \u2014 writes ~/.config/zed/settings.json mcpServers block
+
+The command reads credentials from ~/.mushirc (run \`mushi login\` first).`).action(async (opts) => {
+  const { writeFile, mkdir, readFile: readFile2 } = await import("fs/promises");
+  const { existsSync: existsSync5 } = await import("fs");
+  const nodePath = await import("path");
+  const os = await import("os");
+  const config = requireConfig({ needsProject: true });
+  const IDE_CONFIG = {
+    cursor: { dir: ".cursor", file: "mcp.json", format: "mcp-json" },
+    claude: { dir: ".claude", file: "mcp.json", format: "mcp-json" },
+    continue: { dir: ".continue", file: "mcp.json", format: "mcp-json" },
+    zed: { dir: nodePath.join(os.homedir(), ".config", "zed"), file: "settings.json", format: "zed" }
+  };
+  const ideEntry = IDE_CONFIG[opts.ide];
+  if (!ideEntry) {
+    process.stderr.write(`error: unsupported IDE "${opts.ide}". Supported: ${Object.keys(IDE_CONFIG).join(", ")}
+`);
+    process.exit(2);
+  }
+  const cwd = process.cwd();
+  const slug = opts.projectSlug ?? (config.projectId?.slice(0, 8) ?? "mushi");
+  const serverName = `mushi-${slug}`;
+  const mcpServerBlock = {
+    command: "npx",
+    args: ["-y", "mushi-mcp@latest"],
+    env: {
+      MUSHI_API_ENDPOINT: config.endpoint,
+      MUSHI_PROJECT_ID: config.projectId ?? "",
+      MUSHI_API_KEY: config.apiKey
+    }
+  };
+  const configDir = ideEntry.dir.startsWith("/") ? ideEntry.dir : nodePath.join(cwd, ideEntry.dir);
+  const configPath = nodePath.join(configDir, ideEntry.file);
+  if (ideEntry.format === "mcp-json") {
+    let merged = { mcpServers: {} };
+    if (existsSync5(configPath)) {
+      try {
+        const raw = await readFile2(configPath, "utf8");
+        merged = JSON.parse(raw);
+      } catch {
+      }
+    }
+    const servers = merged.mcpServers ?? {};
+    servers[serverName] = mcpServerBlock;
+    merged.mcpServers = servers;
+    const output = JSON.stringify(merged, null, 2) + "\n";
+    if (opts.dryRun) {
+      console.log(`[dry-run] Would write ${configPath}:`);
+      console.log(output);
+    } else {
+      await mkdir(configDir, { recursive: true });
+      await writeFile(configPath, output, "utf8");
+      console.log(`\u2713 Written ${configPath}`);
+    }
+  } else if (ideEntry.format === "zed") {
+    let settings = {};
+    if (existsSync5(configPath)) {
+      try {
+        const raw = await readFile2(configPath, "utf8");
+        settings = JSON.parse(raw);
+      } catch {
+      }
+    }
+    const servers = settings.context_servers ?? {};
+    servers[serverName] = {
+      command: {
+        path: "npx",
+        args: ["-y", "mushi-mcp@latest"],
+        env: {
+          MUSHI_API_ENDPOINT: config.endpoint,
+          MUSHI_PROJECT_ID: config.projectId ?? "",
+          MUSHI_API_KEY: config.apiKey
+        }
+      },
+      settings: {}
+    };
+    settings.context_servers = servers;
+    const output = JSON.stringify(settings, null, 2) + "\n";
+    if (opts.dryRun) {
+      console.log(`[dry-run] Would write ${configPath}:`);
+      console.log(output);
+    } else {
+      await mkdir(configDir, { recursive: true });
+      await writeFile(configPath, output, "utf8");
+      console.log(`\u2713 Written ${configPath}`);
+    }
+  }
+  if (opts.withRules) {
+    const rulesContent = [
+      "# Mushi Mushi \u2014 evolution-loop coding rules",
+      "#",
+      "# These rules are generated from your project's live lesson library.",
+      "# Run `mushi sync-lessons` to refresh .mushi/lessons.json",
+      "# The MCP server (mushi tools) also injects lessons dynamically at fix time.",
+      "",
+      "## Before writing a fix",
+      "",
+      "1. Call `get_fix_context` (MCP) for the report \u2014 get root cause + blast radius first.",
+      "2. Call `lessons.query` (MCP) or read .mushi/lessons.json \u2014 apply every matching rule.",
+      "3. Prefer the smallest change that makes the test pass. Don't refactor unrelated code.",
+      "",
+      "## After writing a fix",
+      "",
+      "1. Call `submit_fix_result` (MCP) with the branch, PR URL, and files changed.",
+      "2. The judge batch will score the fix overnight \u2014 high-frequency lessons surface in /admin/lessons.",
+      "",
+      "## Mushi lesson library (auto-updated by `mushi sync-lessons`)",
+      "",
+      "<!-- lessons synced from .mushi/lessons.json -->",
+      "<!-- run `mushi sync-lessons` to refresh -->",
+      ""
+    ].join("\n");
+    if (opts.ide === "cursor") {
+      const rulesPath = nodePath.join(cwd, ".cursorrules");
+      if (opts.dryRun) {
+        console.log(`[dry-run] Would write ${rulesPath}`);
+      } else {
+        await writeFile(rulesPath, rulesContent, "utf8");
+        console.log(`\u2713 Written .cursorrules`);
+      }
+    } else if (opts.ide === "claude") {
+      const rulesDir = nodePath.join(cwd, ".claude", "rules");
+      const rulesPath = nodePath.join(rulesDir, "mushi.md");
+      if (opts.dryRun) {
+        console.log(`[dry-run] Would write ${rulesPath}`);
+      } else {
+        await mkdir(rulesDir, { recursive: true });
+        await writeFile(rulesPath, rulesContent, "utf8");
+        console.log(`\u2713 Written .claude/rules/mushi.md`);
+      }
+    }
+  }
+  if (!opts.dryRun) {
+    console.log("");
+    console.log(`Done! Restart ${opts.ide === "cursor" ? "Cursor" : opts.ide === "claude" ? "Claude Code" : opts.ide} and ask: "list mushi tools"`);
+    if (!opts.withRules) {
+      console.log(`Tip: run with --with-rules to also write the lesson-library coding hook.`);
+    }
+    const configRelPath = ideEntry.dir.startsWith("/") ? configPath : nodePath.relative(cwd, configPath);
+    console.log(`
+Note: ${configRelPath} contains your Mushi API key \u2014 add it to .gitignore if this is a shared repo.`);
+  }
+});
 var fixCmd = program.command("fix").description("Dispatch an agentic fix for a report");
 fixCmd.argument("<reportId>", "Report UUID to fix").option(
   "--agent <name>",
@@ -2034,4 +2610,151 @@ Examples:
   console.error("Polling timed out after 10 minutes. The fix may still be running.");
   process.exit(1);
 });
+program.command("nudge").description(
+  "Generate a Mushi.init() snippet tuned for your release phase (alpha, beta, ga). Customises proactive triggers, cooldowns, feature-request card, and beta-mode UI."
+).option("--phase <phase>", "Release phase: alpha | beta | ga", "beta").option("--explain", "Print a human-readable summary of what the preset does").option("--max <n>", "Override maxProactivePerSession").option("--cooldown <hours>", "Override dismissCooldownHours").option("--dwell <minutes>", "Override page-dwell threshold (0 disables)").option("--welcome <seconds>", "Override first-session welcome delay (0 disables)").action((opts) => {
+  const validPhases = ["alpha", "beta", "ga"];
+  if (!validPhases.includes(opts.phase)) {
+    console.error(`Unknown phase "${opts.phase}". Use one of: ${validPhases.join(", ")}`);
+    process.exit(1);
+  }
+  const phase = opts.phase;
+  const overrides = {};
+  const parseNumericFlag = (flag, raw, min) => {
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < min) {
+      console.error(
+        `error: --${flag} must be a finite number >= ${min} (got "${raw}")`
+      );
+      process.exit(1);
+    }
+    return n;
+  };
+  if (opts.max !== void 0) overrides.maxProactivePerSession = parseNumericFlag("max", opts.max, 1);
+  if (opts.cooldown !== void 0) overrides.dismissCooldownHours = parseNumericFlag("cooldown", opts.cooldown, 0);
+  if (opts.dwell !== void 0) overrides.pageDwellMinutes = parseNumericFlag("dwell", opts.dwell, 0);
+  if (opts.welcome !== void 0) overrides.firstSessionSeconds = parseNumericFlag("welcome", opts.welcome, 0);
+  if (opts.explain) {
+    console.log(renderNudgeExplainer(phase));
+  }
+  console.log(renderNudgeSnippet({ phase, overrides }));
+});
+program.command("doctor").description(
+  "Run pre-flight checks: CLI config, endpoint reachability, API key shape, SDK install status, and (with --server) the same 4 dispatch-readiness checks shown in the Mushi console. Mirrors the in-console dispatch preflight so you can spot setup gaps before opening the admin UI."
+).option("--cwd <path>", "Run package detection from a different directory").option("--json", "Machine-readable output").option(
+  "--server",
+  "Also call GET /preflight on the backend and include the 4 dispatch checks (GitHub repo, codebase indexed, Anthropic key, autofix enabled). Requires a configured projectId and API key."
+).action(async (opts) => {
+  const config = loadConfig();
+  const result = await runDoctor(config, { cwd: opts.cwd, server: opts.server });
+  const { checks } = result;
+  if (opts.json) {
+    console.log(JSON.stringify({ checks, ready: result.ready }, null, 2));
+    if (!result.ready) process.exit(1);
+    return;
+  }
+  console.log(formatDoctorResult(result));
+  if (!result.ready) process.exit(1);
+});
+program.command("reset [projectId]").description(
+  "Archive a project and wipe its test data (codebase_files, fix_attempts, reports). Speeds up re-running the full onboarding flow from scratch. Requires `--confirm` to prevent accidents."
+).option("--confirm", "Required safety flag \u2014 must pass to proceed").option("--json", "Machine-readable output").action(async (projectId, opts) => {
+  const config = loadConfig();
+  const resolvedId = projectId ?? config.projectId;
+  if (!config.apiKey) {
+    console.error("Run `mushi login` first");
+    process.exit(1);
+  }
+  if (!resolvedId) {
+    console.error("Provide a projectId or set one via `mushi config projectId <uuid>`");
+    process.exit(1);
+  }
+  if (!opts.confirm) {
+    console.error(
+      `This will archive project ${resolvedId} and delete all its reports, fix_attempts, and codebase_files.
+Re-run with --confirm to proceed.`
+    );
+    process.exit(1);
+  }
+  const data = await apiCall(
+    `/v1/admin/projects/${resolvedId}/reset`,
+    config,
+    { method: "POST" }
+  );
+  if (opts.json) {
+    console.log(JSON.stringify(data, null, 2));
+  } else if (data.ok) {
+    console.log(`Project ${resolvedId} archived and test data wiped.`);
+  } else {
+    console.error("Reset failed:", JSON.stringify(data, null, 2));
+    process.exit(1);
+  }
+});
+var fixes = program.command("fixes").description("Fix dispatch management");
+fixes.command("tail").description(
+  "Stream SSE dispatch events for a report in real time. Useful for headless debugging without opening the browser."
+).requiredOption("--report-id <id>", "Report ID to follow").action(async (opts) => {
+  const config = loadConfig();
+  if (!config.apiKey) {
+    console.error("Run `mushi login` first");
+    process.exit(1);
+  }
+  if (!config.endpoint) {
+    console.error("No endpoint configured. Run `mushi init`");
+    process.exit(1);
+  }
+  const url = `${config.endpoint}/v1/admin/reports/${opts.reportId}/dispatch/stream`;
+  console.log(`Tailing dispatch stream for report ${opts.reportId}\u2026`);
+  console.log(`(Ctrl-C to stop)
+`);
+  const res = await fetch(url, {
+    headers: {
+      "Authorization": `Bearer ${config.apiKey}`,
+      "X-Mushi-Api-Key": config.apiKey,
+      "X-Mushi-Project": config.projectId ?? "",
+      "Accept": "text/event-stream"
+    }
+  });
+  if (!res.ok || !res.body) {
+    console.error(`Failed to connect: HTTP ${res.status}`);
+    const text2 = await res.text().catch(() => "");
+    if (text2) console.error(text2.slice(0, 300));
+    process.exit(1);
+  }
+  const decoder = new TextDecoder();
+  const reader = res.body.getReader();
+  let done = false;
+  process.on("SIGINT", () => {
+    done = true;
+    void reader.cancel();
+    console.log("\nDisconnected.");
+    process.exit(0);
+  });
+  while (!done) {
+    const { value, done: streamDone } = await reader.read();
+    if (streamDone) break;
+    const chunk = decoder.decode(value, { stream: true });
+    for (const line of chunk.split("\n")) {
+      if (line.startsWith("data: ")) {
+        const raw = line.slice(6).trim();
+        if (raw === "[DONE]") {
+          console.log("\n[stream ended]");
+          process.exit(0);
+        }
+        try {
+          const event = JSON.parse(raw);
+          const ts = (/* @__PURE__ */ new Date()).toISOString();
+          const type = event.type ?? event.event ?? "event";
+          const status = event.status ?? event.data ?? "";
+          console.log(`${ts}  ${type.padEnd(24)}  ${status}`);
+        } catch {
+          console.log(line);
+        }
+      } else if (line.startsWith("event: ")) {
+      } else if (line && !line.startsWith(":")) {
+        console.log(line);
+      }
+    }
+  }
+});
 program.parse();