@mushi-mushi/cli 0.23.0 → 0.24.0

package/dist/index.js

@@ -12,6 +12,7 @@ import {
   detectFramework,
   detectPackageManager,
   die,
+  ensureClientId,
   envVarsToWrite,
   fetchIngestSetup,
   fmtDate,
@@ -36,7 +37,7 @@ import {
   sanitizeProjectId,
   saveConfig,
   writeMcpServerEntry
-} from "./chunk-GSQO35YD.js";
+} from "./chunk-BWASDQI6.js";
 import {
   TEST_REPORT_FETCH_TIMEOUT_MS,
   assertEndpoint,
@@ -56,6 +57,7 @@ import { join as join2 } from "path";
 
 // src/device-auth.ts
 var DEVICE_FETCH_TIMEOUT_MS = 15e3;
+var DEFAULT_SLOW_DOWN_MS = 5e3;
 function trimTrailingSlash(endpoint) {
   let end = endpoint.length;
   while (end > 0 && endpoint.charCodeAt(end - 1) === 47) end--;
@@ -70,15 +72,18 @@ async function deviceFetch(url, init = {}) {
     clearTimeout(timer);
   }
 }
-async function startDeviceAuth(endpoint) {
+async function startDeviceAuth(endpoint, clientId) {
   const base = trimTrailingSlash(endpoint);
   const res = await deviceFetch(`${base}/v1/cli/auth/device/start`, {
     method: "POST",
-    headers: { "Content-Type": "application/json" }
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(clientId ? { client_id: clientId } : {})
   });
   const json = await res.json().catch(() => null);
   if (!res.ok || !json?.ok || !json.data) {
-    throw new Error(json?.error?.message ?? `Could not start browser sign-in (HTTP ${res.status}).`);
+    throw new Error(
+      json?.error?.message ?? `Could not start browser sign-in (HTTP ${res.status}).`
+    );
   }
   return json.data;
 }
@@ -97,6 +102,12 @@ async function pollDeviceToken(endpoint, deviceCode) {
     switch (json.error) {
       case "authorization_pending":
         return { status: "pending" };
+      case "slow_down": {
+        const retryAfterHeader = res.headers?.get?.("Retry-After");
+        const retryAfterSeconds = retryAfterHeader ? Number(retryAfterHeader) : NaN;
+        const retryAfterMs = Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0 ? retryAfterSeconds * 1e3 : DEFAULT_SLOW_DOWN_MS;
+        return { status: "slow_down", retryAfterMs };
+      }
       case "access_denied":
         return { status: "denied" };
       case "expired_token":
@@ -105,20 +116,27 @@ async function pollDeviceToken(endpoint, deviceCode) {
         return {
           status: "error",
           message: json.error_description ?? json.error ?? `HTTP ${res.status}`,
-          // 5xx is a server hiccup the next poll may clear; a 4xx is a definitive
-          // rejection (already claimed / invalid_grant) that won't fix itself.
-          retryable: res.status >= 500
+          // 5xx is a server hiccup the next poll may clear; 408 (gateway
+          // timeout) is equally transient. Any other 4xx is a definitive
+          // rejection (already claimed / invalid_grant) that won't fix
+          // itself. (429/slow_down is handled above as its own outcome.)
+          retryable: res.status >= 500 || res.status === 408
         };
     }
   } catch (err) {
-    return { status: "error", message: err instanceof Error ? err.message : String(err), retryable: true };
+    return {
+      status: "error",
+      message: err instanceof Error ? err.message : String(err),
+      retryable: true
+    };
   }
 }
 var defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var deviceAuthRetryDelayMs = 1e3;
 async function waitForCliToken(endpoint, session, opts = {}) {
   const sleep = opts.sleep ?? defaultSleep;
   const now = opts.now ?? Date.now;
-  const intervalMs = (session.interval || 5) * 1e3;
+  let intervalMs = (session.interval || 5) * 1e3;
   const deadline = now() + (session.expires_in || 600) * 1e3;
   const maxConsecutiveErrors = opts.maxConsecutiveErrors ?? 5;
   let consecutiveErrors = 0;
@@ -136,6 +154,11 @@ async function waitForCliToken(endpoint, session, opts = {}) {
         consecutiveErrors = 0;
         opts.onPending?.();
         continue;
+      case "slow_down":
+        consecutiveErrors = 0;
+        intervalMs = Math.max(intervalMs, outcome.retryAfterMs);
+        opts.onSlowDown?.(outcome.retryAfterMs);
+        continue;
       case "denied":
         throw new Error("Login was denied in the browser.");
       case "expired":
@@ -160,19 +183,51 @@ function cliAuthHeaders(cliToken) {
     Authorization: `Bearer ${cliToken}`
   };
 }
+var DeviceAuthRequestError = class extends Error {
+  step;
+  status;
+  retryable;
+  constructor(step, message, status) {
+    super(message);
+    this.name = "DeviceAuthRequestError";
+    this.step = step;
+    this.status = status;
+    this.retryable = status === void 0 || status >= 500 || status === 408;
+  }
+};
+async function withOneRetry(run) {
+  try {
+    return await run();
+  } catch (err) {
+    if (err instanceof DeviceAuthRequestError && err.retryable) {
+      if (deviceAuthRetryDelayMs > 0) {
+        await defaultSleep(deviceAuthRetryDelayMs);
+      }
+      return run();
+    }
+    throw err;
+  }
+}
 async function listProjects(endpoint, cliToken) {
   const base = trimTrailingSlash(endpoint);
-  try {
-    const res = await deviceFetch(`${base}/v1/cli/projects`, { headers: cliAuthHeaders(cliToken) });
+  return withOneRetry(async () => {
+    let res;
+    try {
+      res = await deviceFetch(`${base}/v1/cli/projects`, { headers: cliAuthHeaders(cliToken) });
+    } catch (err) {
+      throw new DeviceAuthRequestError(
+        "list_projects",
+        `Could not reach ${base}/v1/cli/projects: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
     const json = await res.json().catch(() => null);
     if (res.ok && json?.ok) return json.data?.projects ?? [];
-  } catch (err) {
-    console.error(
-      "[mushi] Failed to list projects:",
-      err instanceof Error ? err.message : err
+    throw new DeviceAuthRequestError(
+      "list_projects",
+      json?.error?.message ?? `Could not list projects (HTTP ${res.status}).`,
+      res.status
     );
-  }
-  return [];
+  });
 }
 async function createProject(endpoint, cliToken, name) {
   const base = trimTrailingSlash(endpoint);
@@ -190,17 +245,28 @@ async function createProject(endpoint, cliToken, name) {
 }
 async function mintProjectKey(endpoint, cliToken, projectId) {
   const base = trimTrailingSlash(endpoint);
-  try {
-    const res = await deviceFetch(`${base}/v1/cli/projects/${projectId}/keys`, {
-      method: "POST",
-      headers: cliAuthHeaders(cliToken),
-      body: JSON.stringify({})
-    });
+  return withOneRetry(async () => {
+    let res;
+    try {
+      res = await deviceFetch(`${base}/v1/cli/projects/${projectId}/keys`, {
+        method: "POST",
+        headers: cliAuthHeaders(cliToken),
+        body: JSON.stringify({})
+      });
+    } catch (err) {
+      throw new DeviceAuthRequestError(
+        "mint_key",
+        `Could not reach ${base}/v1/cli/projects/\u2026/keys: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
     const json = await res.json().catch(() => null);
-    if (res.ok && json?.ok) return json.data?.key ?? null;
-  } catch {
-  }
-  return null;
+    if (res.ok && json?.ok && json.data?.key) return json.data.key;
+    throw new DeviceAuthRequestError(
+      "mint_key",
+      json?.error?.message ?? `Could not mint an SDK key (HTTP ${res.status}).`,
+      res.ok ? void 0 : res.status
+    );
+  });
 }
 
 // src/freshness.ts
@@ -431,7 +497,10 @@ async function runInit(options = {}) {
   const detected = detectFramework(cwd, pkg);
   const framework = await chooseFramework(detected, options);
   const consoleBase = await resolveConsoleUrl({ cwd });
-  const endpoint = resolveCloudEndpoint(options.endpoint);
+  const endpoint = resolveCloudEndpoint(
+    options.endpoint ?? process.env.MUSHI_API_ENDPOINT?.trim() ?? loadConfig().endpoint
+  );
+  options = { ...options, endpoint };
   const credentials = await acquireCredentials(options, consoleBase, endpoint);
   await verifyCredentials(credentials, options, consoleBase);
   const pm = detectPackageManager(cwd);
@@ -441,8 +510,16 @@ async function runInit(options = {}) {
   } else {
     p.log.info(`Skipped install. Run \`${installCommand(pm, packagesToInstall)}\` yourself.`);
   }
-  await writeEnvFile(cwd, credentials.apiKey, credentials.projectId, framework, endpoint, Boolean(options.yes));
+  await writeEnvFile(
+    cwd,
+    credentials.apiKey,
+    credentials.projectId,
+    framework,
+    endpoint,
+    Boolean(options.yes)
+  );
   persistCliConfig(credentials.apiKey, credentials.projectId, endpoint);
+  emitWizardFunnelEvent(credentials, endpoint, "wizard_env_written", { framework: framework.id });
   const enableRewards = await maybeEnableRewards(options);
   printNextSteps(framework, consoleBase, enableRewards);
   await maybeSendTestReport(credentials, { ...options, endpoint, consoleBase });
@@ -514,7 +591,9 @@ async function acquireCredentials(options, consoleBase, endpoint) {
   if (options.yes) {
     const creds = await runBrowserSignIn(options, endpoint, consoleBase);
     if (creds) return creds;
-    p.log.warn("Browser sign-in didn't complete \u2014 switching to manual entry.");
+    p.log.warn(
+      "Browser sign-in didn't complete \u2014 switching to manual entry. Run `npx mushi-mushi doctor --auth` to diagnose the sign-in path."
+    );
   } else {
     const method = await p.select({
       message: "Connect this app to Mushi",
@@ -539,17 +618,19 @@ async function acquireCredentials(options, consoleBase, endpoint) {
     if (method === "browser") {
       const creds = await runBrowserSignIn(options, endpoint, consoleBase);
       if (creds) return creds;
-      p.log.warn("Browser sign-in didn't complete \u2014 switching to manual entry.");
+      p.log.warn(
+        "Browser sign-in didn't complete \u2014 switching to manual entry. Run `npx mushi-mushi doctor --auth` to diagnose the sign-in path."
+      );
     }
   }
-  return collectCredentialsManually(options, consoleBase);
+  return collectCredentialsManually(options, consoleBase, endpoint);
 }
 async function runBrowserSignIn(options, endpoint, consoleBase) {
   const startSpin = p.spinner();
   startSpin.start("Starting secure browser sign-in\u2026");
   let session;
   try {
-    session = await startDeviceAuth(endpoint);
+    session = await startDeviceAuth(endpoint, ensureClientId());
   } catch (err) {
     startSpin.stop("Could not start browser sign-in.");
     p.log.warn(err instanceof Error ? err.message : String(err));
@@ -580,7 +661,9 @@ async function runBrowserSignIn(options, endpoint, consoleBase) {
     fetchSpin.start("Loading your projects\u2026");
     try {
       projects = await listProjects(endpoint, cliToken);
-      fetchSpin.stop(projects.length > 0 ? `Found ${projects.length} project(s).` : "No projects yet.");
+      fetchSpin.stop(
+        projects.length > 0 ? `Found ${projects.length} project(s).` : "No projects yet."
+      );
     } catch (err) {
       fetchSpin.stop("Could not load projects \u2014 you can still create a new one.");
       p.log.warn(err instanceof Error ? err.message : String(err));
@@ -628,34 +711,50 @@ async function runBrowserSignIn(options, endpoint, consoleBase) {
     const keySpin = p.spinner();
     keySpin.start("Minting SDK key\u2026");
     try {
-      const minted = await mintProjectKey(endpoint, cliToken, projectId);
-      apiKey = minted ?? void 0;
-      if (!apiKey) {
-        keySpin.stop("Could not mint an API key.");
-        p.log.warn(
-          `Open the console Verify tab to generate a key manually: ${consoleUrl(consoleBase, "/onboarding?tab=verify")}`
-        );
-        return null;
-      }
+      apiKey = await mintProjectKey(endpoint, cliToken, projectId);
       keySpin.stop("SDK key ready.");
     } catch (err) {
       keySpin.stop("Could not mint an API key.");
       p.log.warn(err instanceof Error ? err.message : String(err));
+      p.log.warn(
+        `You're signed in, but key minting failed. Generate one manually in the console Verify tab: ${consoleUrl(consoleBase, "/onboarding?tab=verify")}`
+      );
       return null;
     }
   }
   if (!projectId || !apiKey) return null;
   return { apiKey, projectId };
 }
-async function collectCredentialsManually(options, consoleBase) {
+async function collectCredentialsManually(options, consoleBase, endpoint) {
   const existing = loadConfig();
-  const rawProjectId = options.projectId ?? existing.projectId ?? await promptText({
+  let savedProjectId = existing.projectId;
+  let savedApiKey = existing.apiKey;
+  if (!options.projectId && !options.apiKey && savedProjectId && savedApiKey) {
+    p.log.info(
+      `Found saved credentials from a previous sign-in (project ${sanitizeSecret(savedProjectId).slice(0, 8)}\u2026).`
+    );
+    const checkSpin = p.spinner();
+    checkSpin.start("Checking saved credentials\u2026");
+    const check = await apiCall("/v1/sync/whoami", {
+      apiKey: sanitizeSecret(savedApiKey),
+      projectId: sanitizeSecret(savedProjectId),
+      endpoint
+    });
+    if (check.ok) {
+      checkSpin.stop(`Saved credentials still work (${check.data.project_name}).`);
+    } else {
+      checkSpin.stop("Saved credentials no longer authenticate \u2014 enter fresh ones below.");
+      savedProjectId = void 0;
+      savedApiKey = void 0;
+    }
+  }
+  const rawProjectId = options.projectId ?? savedProjectId ?? await promptText({
     message: "Project ID",
     placeholder: "e.g. bdafa28d-b153-482f-bd4f-42981f3fd3a4",
     hint: projectIdHint(consoleBase),
     validate: (v) => PROJECT_ID_PATTERN.test(v.trim()) ? void 0 : "Expected a UUID \u2014 copy it from the Projects page or the panel right after you create a project."
   });
-  const rawApiKey = options.apiKey ?? existing.apiKey ?? await promptText({
+  const rawApiKey = options.apiKey ?? savedApiKey ?? await promptText({
     message: "API key",
     placeholder: "mushi_xxxxxxxxxxxx",
     hint: apiKeyHint(consoleBase),
@@ -679,17 +778,30 @@ async function verifyCredentials(credentials, options, consoleBase) {
   const endpoint = resolveCloudEndpoint(options.endpoint);
   const spinner3 = p.spinner();
   spinner3.start("Verifying credentials\u2026");
-  const result = await apiCall(
-    "/v1/sync/whoami",
-    { apiKey: credentials.apiKey, projectId: credentials.projectId, endpoint }
-  );
+  const result = await apiCall("/v1/sync/whoami", {
+    apiKey: credentials.apiKey,
+    projectId: credentials.projectId,
+    endpoint
+  });
   if (!result.ok) {
     spinner3.stop("Credentials could not be verified.");
     p.log.error(result.error?.message ?? "Authentication failed.");
-    p.log.info(`Double-check values in the console:
-  ${cliSetupDeepLink(consoleBase)}`);
+    p.log.warn("Setup did NOT complete: nothing was installed and no env vars were written.");
+    p.log.info(
+      [
+        "To recover:",
+        '  \u2022 Re-run `npx mushi-mushi` and choose "Sign in with your browser", or',
+        `  \u2022 Double-check the Project ID / API key in the console: ${cliSetupDeepLink(consoleBase)}`
+      ].join("\n")
+    );
     throw new Error("Credential verification failed \u2014 fix Project ID / API key and re-run.");
   }
+  if (result.data.project_id && result.data.project_id !== credentials.projectId) {
+    p.log.warn(
+      `Project ID ${redact(credentials.projectId)} doesn't match this API key's project \u2014 using the key's actual project (${result.data.project_name}) instead.`
+    );
+    credentials.projectId = result.data.project_id;
+  }
   spinner3.stop(`Connected to ${result.data.project_name}`);
 }
 function sanitizeSecret(raw) {
@@ -825,6 +937,20 @@ function persistCliConfig(apiKey, projectId, endpoint) {
   const existing = loadConfig();
   saveConfig({ ...existing, apiKey, projectId, endpoint });
 }
+function emitWizardFunnelEvent(credentials, endpoint, event, metadata = {}) {
+  if (process.env.MUSHI_NO_TELEMETRY) return;
+  void fetch(`${endpoint.replace(/\/$/, "")}/v1/cli/funnel`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Mushi-Api-Key": credentials.apiKey,
+      "X-Mushi-Project": credentials.projectId
+    },
+    body: JSON.stringify({ event, source: "cli", metadata }),
+    signal: AbortSignal.timeout(4e3)
+  }).catch(() => {
+  });
+}
 function printNextSteps(framework, consoleBase, enableRewards = false) {
   p.note(framework.snippet(), "Add this to your app:");
   if (enableRewards) {
@@ -858,7 +984,7 @@ async function maybeOfferConnect(credentials, options, _consoleBase) {
   if (p.isCancel(answer) || !answer) return;
   const endpoint = resolveCloudEndpoint(options.endpoint);
   try {
-    const { runConnect: runConnect2 } = await import("./connect-XFVSH4JZ.js");
+    const { runConnect: runConnect2 } = await import("./connect-KKN62YK2.js");
     await runConnect2({
       apiKey: credentials.apiKey,
       projectId: credentials.projectId,
@@ -869,12 +995,8 @@ async function maybeOfferConnect(credentials, options, _consoleBase) {
       wait: true
     });
   } catch (err) {
-    p.log.warn(
-      err instanceof Error ? err.message : String(err)
-    );
-    p.log.info(
-      "You can run manually: mushi connect --write-env --wire-ide --wait"
-    );
+    p.log.warn(err instanceof Error ? err.message : String(err));
+    p.log.info("You can run manually: mushi connect --write-env --wire-ide --wait");
   }
 }
 async function maybeEnableRewards(options) {
@@ -1201,7 +1323,7 @@ Examples:
     }
     let deviceData;
     try {
-      deviceData = await startDeviceAuth(endpoint);
+      deviceData = await startDeviceAuth(endpoint, ensureClientId());
     } catch (err) {
       process.stderr.write(`
 error: Could not start login session: ${err instanceof Error ? err.message : String(err)}
@@ -2208,7 +2330,7 @@ Typical first-time flow:
     console.log("");
     let session;
     try {
-      session = await startDeviceAuth(endpoint);
+      session = await startDeviceAuth(endpoint, ensureClientId());
     } catch (err) {
       process.stderr.write(`
 error: Could not start browser sign-in: ${err instanceof Error ? err.message : String(err)}
@@ -3141,6 +3263,88 @@ async function checkEndpointReachability(endpoint, doFetch = globalThis.fetch) {
     return { name: "Endpoint reachable", ok: false, detail: `Fetch failed: ${msg}` };
   }
 }
+async function checkCliAuthPath(config, doFetch = globalThis.fetch) {
+  const checks = [];
+  if (!config.endpoint) {
+    return [
+      {
+        name: "Sign-in route reachable",
+        ok: false,
+        detail: "No endpoint configured \u2014 run `npx mushi-mushi` or pass MUSHI_API_ENDPOINT."
+      }
+    ];
+  }
+  const base = sanitizeEndpoint(config.endpoint);
+  let dateHeader = null;
+  try {
+    const res = await doFetch(`${base}/v1/cli/auth/device/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ device_code: "doctor-probe" }),
+      signal: AbortSignal.timeout(8e3)
+    });
+    dateHeader = res.headers?.get?.("date") ?? null;
+    const signInRouteReachable = res.status === 400 || res.status === 429;
+    checks.push({
+      name: "Sign-in route reachable",
+      ok: signInRouteReachable,
+      detail: signInRouteReachable ? `POST ${base}/v1/cli/auth/device/token \u2192 ${res.status} (route deployed and answering)` : `POST ${base}/v1/cli/auth/device/token \u2192 ${res.status} \u2014 expected HTTP 400 (invalid device_code) or 429 (slow_down); the API may be down or mis-deployed.`
+    });
+  } catch (err) {
+    checks.push({
+      name: "Sign-in route reachable",
+      ok: false,
+      detail: `Fetch failed: ${err instanceof Error ? err.message : String(err)} \u2014 check network/proxy/firewall to ${base}.`
+    });
+  }
+  if (dateHeader) {
+    const serverMs = Date.parse(dateHeader);
+    if (!Number.isNaN(serverMs)) {
+      const skewSec = Math.round(Math.abs(Date.now() - serverMs) / 1e3);
+      const ok = skewSec <= 120;
+      checks.push({
+        name: "System clock in sync",
+        ok,
+        warn: !ok && skewSec <= 300,
+        detail: ok ? `Local clock within ${skewSec}s of the server.` : `Local clock is ${skewSec}s off the server \u2014 sign-in codes expire fast; fix your system time.`
+      });
+    }
+  }
+  if (config.apiKey && config.projectId) {
+    try {
+      const res = await doFetch(`${base}/v1/sync/whoami`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...apiKeyHeaders(config.apiKey, config.projectId)
+        },
+        body: JSON.stringify({}),
+        signal: AbortSignal.timeout(8e3)
+      });
+      const json = await res.json().catch(() => null);
+      const ok = res.ok && json?.ok === true;
+      checks.push({
+        name: "Saved credentials valid",
+        ok,
+        detail: ok ? `API key resolves to project "${json?.data?.project_name ?? config.projectId}".` : `${json?.error?.message ?? `whoami \u2192 HTTP ${res.status}`} \u2014 re-run \`npx mushi-mushi\` to sign in again.`
+      });
+    } catch (err) {
+      checks.push({
+        name: "Saved credentials valid",
+        ok: false,
+        detail: `whoami fetch failed: ${err instanceof Error ? err.message : String(err)}`
+      });
+    }
+  } else {
+    checks.push({
+      name: "Saved credentials valid",
+      ok: true,
+      warn: true,
+      detail: "No saved CLI credentials yet \u2014 normal before the first successful sign-in."
+    });
+  }
+  return checks;
+}
 async function checkSdkInstall(cwd) {
   try {
     const { readFile: readFile3 } = await import("fs/promises");
@@ -3177,13 +3381,10 @@ async function checkServerPreflight(config, doFetch = globalThis.fetch) {
   }
   try {
     const { endpoint, apiKey, projectId } = sanitizeCliCredentials(config);
-    const res = await doFetch(
-      `${endpoint}/v1/admin/projects/${projectId}/preflight`,
-      {
-        headers: apiKeyHeaders(apiKey, projectId),
-        signal: AbortSignal.timeout(8e3)
-      }
-    );
+    const res = await doFetch(`${endpoint}/v1/admin/projects/${projectId}/preflight`, {
+      headers: apiKeyHeaders(apiKey, projectId),
+      signal: AbortSignal.timeout(8e3)
+    });
     if (res.ok) {
       const body = await res.json();
       const serverChecks = body.data?.checks ?? [];
@@ -3239,7 +3440,13 @@ async function checkIngestSetup(config, doFetch = globalThis.fetch) {
       doFetch
     );
     if (!data) {
-      return [{ name: "Ingest setup", ok: false, detail: "Request to /v1/sync/ingest-setup failed or returned invalid payload" }];
+      return [
+        {
+          name: "Ingest setup",
+          ok: false,
+          detail: "Request to /v1/sync/ingest-setup failed or returned invalid payload"
+        }
+      ];
     }
     const steps = data.steps ?? [];
     const checks = steps.filter((s) => s.required).map((s) => ({
@@ -3275,22 +3482,27 @@ async function checkQaStoriesHealth(config, doFetch = globalThis.fetch) {
   try {
     const { endpoint, apiKey, projectId } = sanitizeCliCredentials(config);
     const headers = apiKeyHeaders(apiKey, projectId);
-    const storiesRes = await doFetch(
-      `${endpoint}/v1/admin/projects/${projectId}/qa-coverage`,
-      {
-        headers,
-        signal: AbortSignal.timeout(8e3)
-      }
-    );
+    const storiesRes = await doFetch(`${endpoint}/v1/admin/projects/${projectId}/qa-coverage`, {
+      headers,
+      signal: AbortSignal.timeout(8e3)
+    });
     if (!storiesRes.ok) {
-      checks.push({ name: "[qa] Fetch QA stories", ok: false, detail: `HTTP ${storiesRes.status}` });
+      checks.push({
+        name: "[qa] Fetch QA stories",
+        ok: false,
+        detail: `HTTP ${storiesRes.status}`
+      });
       return checks;
     }
     const storiesBody = await storiesRes.json();
     const stories = storiesBody.data?.coverage ?? [];
     const enabled = stories.filter((s) => s.enabled);
     if (enabled.length === 0) {
-      checks.push({ name: "[qa] Enabled QA stories", ok: true, detail: "No enabled stories \u2014 create one at /qa-coverage" });
+      checks.push({
+        name: "[qa] Enabled QA stories",
+        ok: true,
+        detail: "No enabled stories \u2014 create one at /qa-coverage"
+      });
       return checks;
     }
     checks.push({
@@ -3359,7 +3571,9 @@ async function checkHostAppWiring(cwd) {
       }
     }
     const hasProjectId = /VITE_MUSHI_PROJECT_ID=|NEXT_PUBLIC_MUSHI_PROJECT_ID=|MUSHI_PROJECT_ID=/.test(envContent);
-    const hasApiKey = /VITE_MUSHI_API_KEY=|NEXT_PUBLIC_MUSHI_API_KEY=|MUSHI_API_KEY=/.test(envContent);
+    const hasApiKey = /VITE_MUSHI_API_KEY=|NEXT_PUBLIC_MUSHI_API_KEY=|MUSHI_API_KEY=/.test(
+      envContent
+    );
     checks.push({
       name: "[host] Mushi env vars in .env.local",
       ok: hasProjectId && hasApiKey,
@@ -3404,10 +3618,7 @@ async function checkMcpConfig(config, cwd, doFetch = globalThis.fetch) {
   const { join: join4, resolve: resolve3 } = await import("path");
   const { homedir } = await import("os");
   const root = resolve3(cwd);
-  const candidates = [
-    join4(root, ".cursor", "mcp.json"),
-    join4(homedir(), ".cursor", "mcp.json")
-  ];
+  const candidates = [join4(root, ".cursor", "mcp.json"), join4(homedir(), ".cursor", "mcp.json")];
   let mcpPath = null;
   let mcpRaw = null;
   for (const candidate of candidates) {
@@ -3445,11 +3656,17 @@ async function checkMcpConfig(config, cwd, doFetch = globalThis.fetch) {
   try {
     mcpConfig = JSON.parse(mcpRaw);
   } catch {
-    checks.push({ name: "[mcp] mcp.json valid JSON", ok: false, detail: "mcp.json is not valid JSON \u2014 regenerate with `mushi setup`." });
+    checks.push({
+      name: "[mcp] mcp.json valid JSON",
+      ok: false,
+      detail: "mcp.json is not valid JSON \u2014 regenerate with `mushi setup`."
+    });
     return checks;
   }
   const servers = mcpConfig.mcpServers ?? {};
-  const mushiEntries = Object.entries(servers).filter(([k]) => k === "mushi" || k.startsWith("mushi-"));
+  const mushiEntries = Object.entries(servers).filter(
+    ([k]) => k === "mushi" || k.startsWith("mushi-")
+  );
   if (mushiEntries.length === 0) {
     checks.push({
       name: "[mcp] mushi server entry",
@@ -3569,7 +3786,9 @@ async function checkOnboardingStatus(config, _consoleBase, cwd, doFetch = global
       } catch {
       }
     }
-    const hasEnvVars = /(?:VITE_|NEXT_PUBLIC_|EXPO_PUBLIC_|NUXT_PUBLIC_)?MUSHI_PROJECT_ID=/.test(envContent);
+    const hasEnvVars = /(?:VITE_|NEXT_PUBLIC_|EXPO_PUBLIC_|NUXT_PUBLIC_)?MUSHI_PROJECT_ID=/.test(
+      envContent
+    );
     if (!hasEnvVars) {
       return {
         nextAction: "Write env vars to your app: run `npx mushi-mushi` or `mushi connect --write-env`",
@@ -3658,6 +3877,9 @@ async function runDoctor(config, options = {}) {
     const mcpChecks = await checkMcpConfig(config, options.cwd ?? process.cwd(), doFetch);
     checks.push(...mcpChecks);
   }
+  if (isFull || options.auth) {
+    checks.push(...await checkCliAuthPath(config, doFetch));
+  }
   const heartbeatPassed = checks.some((c) => c.name === "[ingest] Last SDK heartbeat" && c.ok);
   if (heartbeatPassed) {
     const idx = checks.findIndex((c) => c.name === "SDK installed in this repo" && !c.ok);
@@ -3690,8 +3912,10 @@ function formatDoctorResult(result) {
   const warned = result.checks.filter((c) => c.ok && c.warn);
   if (failed.length === 0) {
     if (warned.length > 0) {
-      lines.push(`
-All checks passed with ${warned.length} advisory warning${warned.length === 1 ? "" : "s"}. The CLI is ready.`);
+      lines.push(
+        `
+All checks passed with ${warned.length} advisory warning${warned.length === 1 ? "" : "s"}. The CLI is ready.`
+      );
     } else {
       lines.push("\nAll checks passed. The CLI is ready.");
     }
@@ -3716,6 +3940,9 @@ function registerDoctorCommand(program2) {
   ).option(
     "--mcp",
     "Check Cursor MCP config: verify mushi-* server entry, credentials, and probe account-overview connectivity."
+  ).option(
+    "--auth",
+    "Diagnose the browser sign-in handshake: device-auth route reachability, system clock skew, and saved-credential validity. Run this when `npx mushi-mushi` browser sign-in does not complete."
   ).option(
     "--fix",
     "Apply safe local fixes when checks fail: write missing .env.local lines and wire Cursor MCP config."
@@ -3725,54 +3952,60 @@ function registerDoctorCommand(program2) {
   ).option(
     "--full",
     "Run ALL check categories (server, ingest, host-app, mcp, qa-stories) in one shot. Good for first-run diagnostics. Exit 0 only when all checks pass."
-  ).action(async (opts) => {
-    const config = loadConfig();
-    if (opts.onboarding) {
-      const cwd = opts.cwd ?? process.cwd();
-      const consoleBase = await resolveConsoleUrl({ cwd });
-      const status = await checkOnboardingStatus(config, consoleBase, cwd);
-      const base = consoleBase.replace(/\/$/, "");
-      if (status.done) {
-        console.log(`OK  Setup complete. ${status.nextAction}`);
-        console.log(`    ${base}${status.ctaPath}`);
-      } else {
-        console.log(`\u2192 Next: ${status.nextAction}`);
-        console.log(`    Open: ${base}${status.ctaPath}`);
+  ).action(
+    async (opts) => {
+      const config = loadConfig();
+      if (opts.onboarding) {
+        const cwd = opts.cwd ?? process.cwd();
+        const consoleBase = await resolveConsoleUrl({ cwd });
+        const status = await checkOnboardingStatus(config, consoleBase, cwd);
+        const base = consoleBase.replace(/\/$/, "");
+        if (status.done) {
+          console.log(`OK  Setup complete. ${status.nextAction}`);
+          console.log(`    ${base}${status.ctaPath}`);
+        } else {
+          console.log(`\u2192 Next: ${status.nextAction}`);
+          console.log(`    Open: ${base}${status.ctaPath}`);
+        }
+        if (!status.done) process.exit(1);
+        return;
       }
-      if (!status.done) process.exit(1);
-      return;
-    }
-    const doctorOpts = {
-      cwd: opts.cwd,
-      server: opts.server,
-      ingest: opts.ingest,
-      qaStories: opts.qaStories,
-      hostApp: opts.hostApp,
-      mcp: opts.mcp,
-      full: opts.full
-    };
-    let result = await runDoctor(config, doctorOpts);
-    if (!result.ready && opts.fix && config.apiKey && config.projectId && config.endpoint) {
-      const connectResult = await runConnect({
-        apiKey: config.apiKey,
-        projectId: config.projectId,
-        endpoint: config.endpoint,
-        cwd: opts.cwd ?? process.cwd(),
-        writeEnv: true,
-        wireIde: true
-      }, config);
-      for (const msg of connectResult.messages) console.log(msg);
-      result = await runDoctor(config, { ...doctorOpts, mcp: opts.mcp });
-    }
-    const { checks } = result;
-    if (opts.json) {
-      console.log(JSON.stringify({ checks, ready: result.ready }, null, 2));
+      const doctorOpts = {
+        cwd: opts.cwd,
+        server: opts.server,
+        ingest: opts.ingest,
+        qaStories: opts.qaStories,
+        hostApp: opts.hostApp,
+        mcp: opts.mcp,
+        auth: opts.auth,
+        full: opts.full
+      };
+      let result = await runDoctor(config, doctorOpts);
+      if (!result.ready && opts.fix && config.apiKey && config.projectId && config.endpoint) {
+        const connectResult = await runConnect(
+          {
+            apiKey: config.apiKey,
+            projectId: config.projectId,
+            endpoint: config.endpoint,
+            cwd: opts.cwd ?? process.cwd(),
+            writeEnv: true,
+            wireIde: true
+          },
+          config
+        );
+        for (const msg of connectResult.messages) console.log(msg);
+        result = await runDoctor(config, { ...doctorOpts, mcp: opts.mcp });
+      }
+      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);
-      return;
     }
-    console.log(formatDoctorResult(result));
-    if (!result.ready) process.exit(1);
-  });
+  );
 }
 
 // src/commands/reset-cli.ts
@@ -4789,6 +5022,131 @@ Examples:
   });
 }
 
+// src/commands/completion-cli.ts
+import { Argument } from "commander";
+
+// src/completion.ts
+var SUPPORTED_SHELLS = ["bash", "zsh", "fish"];
+function isSupportedShell(value) {
+  return SUPPORTED_SHELLS.includes(value);
+}
+function buildCommandTree(program2) {
+  return program2.commands.filter((cmd) => cmd.name() !== "help").map((cmd) => ({
+    name: cmd.name(),
+    subcommands: cmd.commands.filter((sub) => sub.name() !== "help").map((sub) => sub.name()).sort()
+  })).sort((a, b) => a.name.localeCompare(b.name));
+}
+var COMPLETION_ARG_VALUES = [...SUPPORTED_SHELLS];
+function subcommandsFor(tree, name) {
+  if (name === "completion") return COMPLETION_ARG_VALUES;
+  return tree.find((n) => n.name === name)?.subcommands ?? [];
+}
+function generateBash(tree) {
+  const topLevel = tree.map((n) => n.name).join(" ");
+  const cases = tree.map((n) => {
+    const subs = subcommandsFor(tree, n.name);
+    if (subs.length === 0) return null;
+    return `    ${n.name})
+      COMPREPLY=( $(compgen -W "${subs.join(" ")}" -- "$cur") )
+      ;;`;
+  }).filter((line) => line !== null).join("\n");
+  return `###-begin-mushi-completion-###
+# mushi(1) completion \u2014 https://github.com/kensaurus/mushi-mushi
+# Install: mushi completion bash >> ~/.bashrc   (then restart your shell)
+_mushi_completion() {
+  local cur
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  COMPREPLY=()
+
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "${topLevel}" -- "$cur") )
+    return 0
+  fi
+
+  case "\${COMP_WORDS[1]}" in
+${cases}
+    *)
+      ;;
+  esac
+}
+complete -F _mushi_completion mushi
+###-end-mushi-completion-###
+`;
+}
+function generateZsh(tree) {
+  const topLevel = tree.map((n) => n.name).join(" ");
+  const cases = tree.map((n) => {
+    const subs = subcommandsFor(tree, n.name);
+    if (subs.length === 0) return null;
+    return `    ${n.name})
+      local -a subcmds; subcmds=(${subs.join(" ")})
+      _describe '${n.name} subcommand' subcmds
+      ;;`;
+  }).filter((line) => line !== null).join("\n");
+  return `#compdef mushi
+# mushi(1) completion \u2014 https://github.com/kensaurus/mushi-mushi
+# Install: mushi completion zsh > "\${fpath[1]}/_mushi"   (then restart your shell)
+_mushi() {
+  local -a top_level
+  top_level=(${topLevel})
+
+  if (( CURRENT == 2 )); then
+    _describe 'command' top_level
+    return
+  fi
+
+  case "\${words[2]}" in
+${cases}
+    *)
+      ;;
+  esac
+}
+
+_mushi
+`;
+}
+function generateFish(tree) {
+  const topLevel = tree.map((n) => n.name).join(" ");
+  const lines = [
+    "# mushi(1) completion \u2014 https://github.com/kensaurus/mushi-mushi",
+    "# Install: mushi completion fish > ~/.config/fish/completions/mushi.fish",
+    `complete -c mushi -f -n "__fish_use_subcommand" -a "${topLevel}"`
+  ];
+  for (const n of tree) {
+    const subs = subcommandsFor(tree, n.name);
+    if (subs.length === 0) continue;
+    lines.push(`complete -c mushi -f -n "__fish_seen_subcommand_from ${n.name}" -a "${subs.join(" ")}"`);
+  }
+  return lines.join("\n") + "\n";
+}
+function generateCompletionScript(shell, tree) {
+  switch (shell) {
+    case "bash":
+      return generateBash(tree);
+    case "zsh":
+      return generateZsh(tree);
+    case "fish":
+      return generateFish(tree);
+  }
+}
+
+// src/commands/completion-cli.ts
+function registerCompletionCommand(program2) {
+  program2.command("completion").description("Print a shell completion script for bash, zsh, or fish").addArgument(new Argument("<shell>", "Target shell").choices([...SUPPORTED_SHELLS])).addHelpText("after", `
+Examples:
+  eval "$(mushi completion bash)"                      # try it for the current session
+  mushi completion bash >> ~/.bashrc                   # bash: persist across sessions
+  mushi completion zsh > "\${fpath[1]}/_mushi"           # zsh: needs a dir already on $fpath
+  mushi completion fish > ~/.config/fish/completions/mushi.fish`).action((shell) => {
+    if (!isSupportedShell(shell)) {
+      console.error(`Unsupported shell "${shell}". Supported: ${SUPPORTED_SHELLS.join(", ")}`);
+      process.exit(2);
+    }
+    const tree = buildCommandTree(program2);
+    console.log(generateCompletionScript(shell, tree));
+  });
+}
+
 // src/index.ts
 installSignalHandlers();
 var program = new Command().name("mushi").description("Mushi CLI \u2014 set up the SDK, triage a report, fix from your editor").version(MUSHI_CLI_VERSION).addHelpText("after", `
@@ -4827,6 +5185,7 @@ registerQaCommands(program);
 registerAuditCommands(program);
 registerSkillsCommands(program);
 registerBillingCommands(program);
+registerCompletionCommand(program);
 program.parseAsync().catch((err) => {
   printAndExit(err);
 });