@mushi-mushi/cli 0.34.0 → 0.35.0

package/README.md

@@ -4,6 +4,8 @@
 
 The `mushi` command for [Mushi Mushi](https://github.com/kensaurus/mushi-mushi). Install the SDK in your app, connect your editor, then read bugs, dispatch fixes and merge them without leaving the terminal.
 
+Docs: [CLI reference](https://kensaur.us/mushi-mushi/docs/sdks/cli)
+
 ```mermaid
 flowchart LR
     A["mushi init<br/>SDK in your app"] --> B["mushi setup<br/>editor reads diagnoses"] --> C["mushi reports<br/>see what broke"] --> D["mushi fix<br/>agent opens a draft PR"] --> E["mushi fixes merge"]
@@ -70,7 +72,7 @@ Other `init` flags: `--framework next`, `--cwd apps/web` (monorepos), `--endpoin
 | `MUSHI_NO_UPDATE_CHECK=1` | Skip the "newer version" hint |
 | `MUSHI_DEBUG=1` | Full stack traces on error |
 
-Config lives in `~/.config/mushi/config.json`, written with mode `0o600` (a legacy `~/.mushirc` is auto-migrated). `--endpoint` must be `https://` except on localhost.
+Config lives in `~/.config/mushi/config.json` (`%APPDATA%\mushi\config.json` on Windows, `$XDG_CONFIG_HOME/mushi/config.json` when that is set), written with mode `0o600` on macOS and Linux and an account-only ACL on Windows (a legacy `~/.mushirc` is auto-migrated). `--endpoint` must be `https://` except on localhost.
 
 ## Programmatic use
 

package/dist/{chunk-OS2ZLURO.js → chunk-BC3Y5C3L.js}

@@ -1,6 +1,6 @@
 import {
   MUSHI_CLI_VERSION
-} from "./chunk-CY2BHCA5.js";
+} from "./chunk-HXLBH5GE.js";
 import {
   assertEndpoint,
   normalizeEndpoint
@@ -26,11 +26,14 @@ function getEntryClass() {
   return _EntryClass ?? null;
 }
 function trySaveKeyToKeychain(apiKey, profile = "default") {
+  return saveSecret(accountName(profile), apiKey);
+}
+function saveSecret(account, apiKey) {
   if (!apiKey) return false;
   const EntryClass = getEntryClass();
   if (!EntryClass) return false;
   try {
-    const entry = new EntryClass(KEYCHAIN_SERVICE, accountName(profile));
+    const entry = new EntryClass(KEYCHAIN_SERVICE, account);
     entry.setPassword(apiKey);
     return true;
   } catch {
@@ -38,10 +41,13 @@ function trySaveKeyToKeychain(apiKey, profile = "default") {
   }
 }
 function tryLoadKeyFromKeychain(profile = "default") {
+  return loadSecret(accountName(profile));
+}
+function loadSecret(account) {
   const EntryClass = getEntryClass();
   if (!EntryClass) return null;
   try {
-    const entry = new EntryClass(KEYCHAIN_SERVICE, accountName(profile));
+    const entry = new EntryClass(KEYCHAIN_SERVICE, account);
     const key = entry.getPassword();
     return key && key.length > 0 ? key : null;
   } catch {

package/dist/chunk-DSYPYBJT.js

@@ -0,0 +1,432 @@
+#!/usr/bin/env node
+import {
+  detectFramework,
+  envVarsToWrite,
+  readPackageJson
+} from "./chunk-KOBEOGNF.js";
+import {
+  CONFIG_PATH,
+  requireUuid,
+  saveConfig,
+  savedSdkKeyFor
+} from "./chunk-T36WTCFM.js";
+import {
+  MUSHI_MCP_PIN_SPEC
+} from "./chunk-GNTEONTU.js";
+import {
+  assertEndpoint,
+  normalizeEndpoint
+} from "./chunk-LGGE3LH7.js";
+
+// src/connect.ts
+import { appendFile, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+import { join, resolve } from "path";
+
+// src/sanitize-config.ts
+var PROJECT_ID_RE = /^(?:proj_[A-Za-z0-9_-]{10,}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;
+var API_KEY_RE = /^(mushi_|mush_pk_)[A-Za-z0-9_-]{10,}$/;
+function sanitizeApiKey(raw) {
+  const key = raw.replace(/[\r\n\0]/g, "");
+  if (!API_KEY_RE.test(key)) {
+    throw new Error(
+      "Invalid API key in config \u2014 run `mushi login --api-key <key>` to refresh credentials."
+    );
+  }
+  return key;
+}
+function sanitizeProjectId(raw) {
+  const id = raw.trim();
+  if (!PROJECT_ID_RE.test(id)) {
+    throw new Error(
+      "Invalid project ID in config \u2014 expected a UUID or proj_* slug from the admin console."
+    );
+  }
+  return id;
+}
+function sanitizeEndpoint(raw) {
+  return assertEndpoint(normalizeEndpoint(raw));
+}
+function sanitizeCliCredentials(config) {
+  if (!config.endpoint || !config.apiKey || !config.projectId) {
+    throw new Error("Missing endpoint, apiKey, or projectId");
+  }
+  return {
+    endpoint: sanitizeEndpoint(config.endpoint),
+    apiKey: sanitizeApiKey(config.apiKey),
+    projectId: sanitizeProjectId(config.projectId)
+  };
+}
+function apiKeyHeaders(apiKey, projectId) {
+  const headers = {
+    Authorization: `Bearer ${apiKey}`,
+    "X-Mushi-Api-Key": apiKey
+  };
+  if (projectId) headers["X-Mushi-Project"] = projectId;
+  return headers;
+}
+
+// src/heartbeat-wait.ts
+var IngestSetupHttpError = class extends Error {
+  status;
+  constructor(status) {
+    super(`ingest-setup HTTP ${status}`);
+    this.name = "IngestSetupHttpError";
+    this.status = status;
+  }
+};
+var NON_RETRYABLE_STATUSES = /* @__PURE__ */ new Set([401, 403, 404]);
+async function fetchIngestSetup(config, doFetch = globalThis.fetch) {
+  const endpoint = sanitizeEndpoint(config.endpoint);
+  const apiKey = sanitizeApiKey(config.apiKey);
+  const projectId = config.projectId ? sanitizeProjectId(config.projectId) : void 0;
+  const res = await doFetch(`${endpoint}/v1/sync/ingest-setup`, {
+    headers: apiKeyHeaders(apiKey, projectId),
+    signal: AbortSignal.timeout(8e3)
+  });
+  if (!res.ok) {
+    if (NON_RETRYABLE_STATUSES.has(res.status)) throw new IngestSetupHttpError(res.status);
+    return null;
+  }
+  const body = await res.json();
+  return body.ok && body.data ? body.data : null;
+}
+async function waitForIngestReady(options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const maxAttempts = options.maxAttempts ?? 40;
+  const intervalMs = options.intervalMs ?? 3e3;
+  let lastPayload = null;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    if (options.signal?.aborted) {
+      return { ok: false, payload: lastPayload, attempts: attempt - 1, reason: "aborted" };
+    }
+    try {
+      lastPayload = await fetchIngestSetup(
+        { endpoint: options.endpoint, apiKey: options.apiKey, projectId: options.projectId },
+        doFetch
+      );
+      if (lastPayload) {
+        options.onPoll?.(lastPayload, attempt);
+        if (lastPayload.ready) {
+          return { ok: true, payload: lastPayload, attempts: attempt, reason: "ready" };
+        }
+        const sdkStep = lastPayload.steps.find((s) => s.id === "sdk_installed");
+        if (sdkStep?.complete) {
+          return { ok: true, payload: lastPayload, attempts: attempt, reason: "heartbeat" };
+        }
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (err instanceof IngestSetupHttpError) {
+        return { ok: false, payload: lastPayload, attempts: attempt, reason: "unauthorized", error: msg };
+      }
+      if (options.signal?.aborted) {
+        return { ok: false, payload: lastPayload, attempts: attempt, reason: "aborted", error: msg };
+      }
+      if (attempt === maxAttempts) {
+        return { ok: false, payload: lastPayload, attempts: attempt, reason: "fetch-error", error: msg };
+      }
+    }
+    if (attempt < maxAttempts) {
+      await new Promise((r) => setTimeout(r, intervalMs));
+    }
+  }
+  return { ok: false, payload: lastPayload, attempts: maxAttempts, reason: "timeout" };
+}
+
+// src/key-scopes.ts
+var SDK_KEY_SCOPES = ["report:write"];
+var CLI_KEY_SCOPES = ["report:write", "mcp:read"];
+var FULL_CLI_KEY_SCOPES = ["report:write", "mcp:read", "mcp:write"];
+var SDK_KEY_LABEL = "sdk-ingest";
+var CLI_KEY_LABEL = "cli-login";
+async function probeKeyScope(endpoint, apiKey, projectId, doFetch = globalThis.fetch) {
+  let base = endpoint;
+  while (base.endsWith("/")) base = base.slice(0, -1);
+  let res;
+  try {
+    res = await doFetch(`${base}/v1/admin/mcp/account-overview`, {
+      headers: { "X-Mushi-Api-Key": apiKey, "X-Mushi-Project": projectId },
+      signal: AbortSignal.timeout(8e3)
+    });
+  } catch (err) {
+    return { result: "unreachable", message: err instanceof Error ? err.message : String(err) };
+  }
+  if (res.ok) return { result: "mcp", status: res.status };
+  if (res.status === 401) return { result: "invalid", status: res.status };
+  if (res.status === 403) {
+    const body = await res.json().catch(() => null);
+    const code = body?.error?.code ?? body?.code;
+    if (code === "INSUFFICIENT_SCOPE") return { result: "ingest-only", status: res.status };
+  }
+  return { result: "unknown", status: res.status };
+}
+function describeUnsafeSdkKey(probe, endpoint) {
+  switch (probe.result) {
+    case "mcp":
+      return "this key can read your bug reports (mcp scope), and SDK env vars ship inside the app bundle";
+    case "invalid":
+      return "the backend rejected this key";
+    case "unreachable":
+      return `could not reach ${endpoint} to confirm the key is ingest-only (${probe.message ?? "network error"})`;
+    case "unknown":
+      return `could not confirm the key is ingest-only (HTTP ${probe.status ?? "?"})`;
+    case "ingest-only":
+      return "the key is ingest-only";
+  }
+}
+
+// src/mcp-config.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname } from "path";
+var DEFAULT_MUSHI_FEATURES = "triage,fixes,inventory,setup,docs";
+var MCP_CLIENTS = ["cursor", "claude", "continue", "zed"];
+function isMcpClient(value) {
+  return typeof value === "string" && MCP_CLIENTS.includes(value);
+}
+var MCP_CLIENT_LABEL = {
+  cursor: "Cursor",
+  claude: "Claude Code",
+  continue: "Continue",
+  zed: "Zed"
+};
+function buildHostedMcpServerBlock(url, oauth) {
+  return oauth ? { type: "http", url, oauth } : { type: "http", url };
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function writeMcpServerEntry(opts) {
+  const { configPath, serverName, serverBlock, dryRun = false } = opts;
+  let existing = null;
+  try {
+    existing = await readFile(configPath, "utf8");
+  } catch {
+    existing = null;
+  }
+  let merged = {};
+  if (existing !== null && existing.trim() !== "") {
+    let parsed;
+    try {
+      parsed = JSON.parse(existing);
+    } catch {
+      throw new Error(`${configPath} is not valid JSON \u2014 fix or remove it, then re-run (nothing was written).`);
+    }
+    if (!isPlainObject(parsed)) {
+      throw new Error(`${configPath} is not a JSON object \u2014 fix or remove it, then re-run (nothing was written).`);
+    }
+    merged = parsed;
+  }
+  const currentServers = merged.mcpServers;
+  if (currentServers !== void 0 && !isPlainObject(currentServers)) {
+    throw new Error(`${configPath} has an "mcpServers" field that is not an object \u2014 fix it, then re-run (nothing was written).`);
+  }
+  merged.mcpServers = { ...currentServers ?? {}, [serverName]: serverBlock };
+  const output = JSON.stringify(merged, null, 2) + "\n";
+  if (!dryRun) {
+    await mkdir(dirname(configPath), { recursive: true });
+    await writeFile(configPath, output, "utf8");
+  }
+  return { created: existing === null, path: configPath };
+}
+function apiKeyPlaceholderFor(client) {
+  switch (client) {
+    case "cursor":
+      return "${env:MUSHI_API_KEY}";
+    case "claude":
+      return "${MUSHI_API_KEY:-}";
+    case "continue":
+    case "zed":
+      return null;
+  }
+}
+function buildMcpServerBlock(opts) {
+  const keyValue = opts.inlineKey ? opts.apiKey : apiKeyPlaceholderFor(opts.client);
+  return {
+    command: "npx",
+    args: ["-y", MUSHI_MCP_PIN_SPEC],
+    env: {
+      MUSHI_API_ENDPOINT: opts.endpoint,
+      MUSHI_PROJECT_ID: opts.projectId,
+      ...keyValue !== null ? { MUSHI_API_KEY: keyValue } : {},
+      MUSHI_FEATURES: DEFAULT_MUSHI_FEATURES
+    }
+  };
+}
+function printKeyExportHint(client, configPath = CONFIG_PATH) {
+  console.log("");
+  console.log("  No API key was written into the MCP config (safe to commit).");
+  console.log(`  The MCP server uses the key \`mushi login\` saved in ${configPath}.`);
+  if (apiKeyPlaceholderFor(client) !== null) {
+    console.log(`  To use a different key, export MUSHI_API_KEY in the environment ${MCP_CLIENT_LABEL[client]} is launched from.`);
+  }
+  console.log("  To write the key into the file instead (keep it out of git), re-run with --inline-key.");
+}
+function buildMcpServerName(opts) {
+  if (opts.legacy) return "mushi";
+  if (opts.projectName) {
+    const slug = opts.projectName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 24);
+    return `mushi-${slug}`;
+  }
+  return `mushi-${(opts.projectId ?? "unknown").slice(0, 8)}`;
+}
+
+// src/connect.ts
+async function resolveSdkEnvKey(opts) {
+  const candidate = opts.sdkKey ?? savedSdkKeyFor(opts.baseConfig, opts.projectId) ?? opts.apiKey;
+  const probe = await opts.probe(opts.endpoint, candidate, opts.projectId);
+  if (probe.result === "ingest-only") return { ok: true, key: candidate };
+  return { ok: false, reason: describeUnsafeSdkKey(probe, opts.endpoint) };
+}
+function envKeyPresent(content, key) {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped}=`, "m").test(content);
+}
+async function mergeEnvFile(path, lines) {
+  const block = `
+# Mushi \u2014 added by mushi connect
+${lines.join("\n")}
+`;
+  let existing = null;
+  try {
+    existing = await readFile2(path, "utf8");
+  } catch {
+  }
+  if (existing !== null) {
+    const needs = lines.filter((line) => {
+      const key = line.split("=")[0];
+      return !envKeyPresent(existing, key);
+    });
+    if (needs.length === 0) return false;
+    await appendFile(path, `
+# Mushi \u2014 added by mushi connect
+${needs.join("\n")}
+`, "utf8");
+    return true;
+  }
+  await writeFile2(path, block, "utf8");
+  return true;
+}
+async function runConnect(opts, baseConfig = {}) {
+  const cwd = resolve(opts.cwd ?? process.cwd());
+  const endpoint = assertEndpoint(opts.endpoint);
+  const projectId = requireUuid(opts.projectId, "projectId");
+  const messages = [];
+  const writeEnv = opts.writeEnv !== false;
+  const sdkEnvKey = writeEnv ? await resolveSdkEnvKey({
+    sdkKey: opts.sdkKey,
+    apiKey: opts.apiKey,
+    projectId,
+    endpoint,
+    baseConfig,
+    probe: opts.probeKeyScope ?? probeKeyScope
+  }) : null;
+  const config = {
+    ...baseConfig,
+    apiKey: opts.apiKey,
+    projectId,
+    endpoint,
+    ...sdkEnvKey?.ok ? { sdkKey: { projectId, key: sdkEnvKey.key } } : {}
+  };
+  saveConfig(config);
+  messages.push(`\u2713 Credentials saved to ${CONFIG_PATH}`);
+  let envPath = null;
+  let envRefused = false;
+  if (sdkEnvKey && !sdkEnvKey.ok) {
+    envRefused = true;
+    messages.push(
+      `\u2717 Did not write SDK env vars: ${sdkEnvKey.reason}. Pass an ingest-only key with --sdk-key <key> (console \u2192 Projects \u2192 API keys, scope report:write), or run \`npx mushi-mushi\`, which mints one.`
+    );
+  } else if (sdkEnvKey?.ok) {
+    const pkg = readPackageJson(cwd);
+    const framework = detectFramework(cwd, pkg);
+    const lines = envVarsToWrite(sdkEnvKey.key, projectId, framework).split("\n");
+    envPath = join(cwd, ".env.local");
+    const wrote = await mergeEnvFile(envPath, lines);
+    messages.push(
+      wrote ? `\u2713 Env vars merged into ${envPath}` : `\u2713 Env vars already present in ${envPath} (existing values left untouched)`
+    );
+    const deps = { ...pkg?.dependencies ?? {}, ...pkg?.devDependencies ?? {} };
+    if (deps["@capacitor/core"] && deps["react"]) {
+      messages.push(
+        "\u2139 Capacitor + React detected \u2014 install @mushi-mushi/web (or @mushi-mushi/react) and call initMushi() in main.tsx. Optional @mushi-mushi/capacitor for native shell parity."
+      );
+    }
+  }
+  let mcpPath = null;
+  if (opts.wireIde !== false) {
+    const mcpDir = join(cwd, ".cursor");
+    mcpPath = join(mcpDir, "mcp.json");
+    const serverName = buildMcpServerName({ projectId });
+    const serverBlock = buildMcpServerBlock({
+      endpoint,
+      projectId,
+      apiKey: opts.apiKey,
+      client: "cursor",
+      inlineKey: false
+      // no secret in the file; the MCP server reads the saved CLI key
+    });
+    await writeMcpServerEntry({ configPath: mcpPath, serverName, serverBlock });
+    messages.push(`\u2713 Wired ${mcpPath} \u2014 restart Cursor and run "list mushi tools"`);
+    messages.push(`  The MCP server reads the key saved in ${CONFIG_PATH} (export MUSHI_API_KEY before launching Cursor to override it).`);
+  }
+  let heartbeat = null;
+  if (opts.wait) {
+    const timeoutSec = opts.waitTimeoutSec ?? 120;
+    const maxAttempts = Math.max(1, Math.ceil(timeoutSec * 1e3 / 3e3));
+    messages.push(`\u2026 Waiting for SDK heartbeat (up to ${timeoutSec}s) \u2014 start your dev server with the snippet installed`);
+    heartbeat = await waitForIngestReady({
+      endpoint,
+      apiKey: opts.apiKey,
+      projectId,
+      maxAttempts,
+      onPoll: (payload, attempt) => {
+        if (!opts.json && attempt % 3 === 0) {
+          const sdk = payload.steps.find((s) => s.id === "sdk_installed");
+          const seen = payload.diagnostic?.last_sdk_seen_at ?? "never";
+          process.stdout.write(`  poll ${attempt}: sdk_installed=${sdk?.complete ? "yes" : "no"} last_seen=${seen}
+`);
+        }
+      }
+    });
+    if (heartbeat.ok) {
+      const label = heartbeat.reason === "heartbeat" ? "SDK heartbeat detected" : "Ingest setup complete";
+      messages.push(`\u2713 ${label} \u2014 ingest pipeline is live`);
+    } else if (heartbeat.reason === "unauthorized") {
+      messages.push(
+        `\u2717 The backend rejected these credentials (${heartbeat.error ?? "auth error"}). Double-check --api-key, --project-id, and --endpoint, then re-run \`mushi connect --wait\`.`
+      );
+    } else {
+      messages.push(
+        `\u2717 No heartbeat before timeout (${heartbeat.reason}). Confirm env vars are in your build, restart the dev server, then re-run \`mushi connect --wait\`.`
+      );
+    }
+  }
+  const ok = !envRefused && (!opts.wait || Boolean(heartbeat?.ok));
+  return { ok, envPath, mcpPath, heartbeat, messages };
+}
+
+export {
+  SDK_KEY_SCOPES,
+  CLI_KEY_SCOPES,
+  FULL_CLI_KEY_SCOPES,
+  SDK_KEY_LABEL,
+  CLI_KEY_LABEL,
+  probeKeyScope,
+  describeUnsafeSdkKey,
+  sanitizeApiKey,
+  sanitizeProjectId,
+  sanitizeEndpoint,
+  sanitizeCliCredentials,
+  apiKeyHeaders,
+  fetchIngestSetup,
+  MCP_CLIENTS,
+  isMcpClient,
+  MCP_CLIENT_LABEL,
+  buildHostedMcpServerBlock,
+  writeMcpServerEntry,
+  buildMcpServerBlock,
+  printKeyExportHint,
+  buildMcpServerName,
+  resolveSdkEnvKey,
+  runConnect
+};

package/dist/chunk-GNTEONTU.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+// src/version.ts
+var MUSHI_CLI_VERSION = true ? "0.35.0" : "0.0.0-dev";
+var MUSHI_MCP_PIN_SPEC = "@mushi-mushi/mcp@0.30.0";
+
+export {
+  MUSHI_CLI_VERSION,
+  MUSHI_MCP_PIN_SPEC
+};

package/dist/chunk-HXLBH5GE.js

@@ -0,0 +1,8 @@
+// src/version.ts
+var MUSHI_CLI_VERSION = true ? "0.35.0" : "0.0.0-dev";
+var MUSHI_MCP_PIN_SPEC = "@mushi-mushi/mcp@0.30.0";
+
+export {
+  MUSHI_CLI_VERSION,
+  MUSHI_MCP_PIN_SPEC
+};