@mushi-mushi/cli 0.27.0 → 0.28.0

package/dist/init.d.ts

@@ -1,5 +1,106 @@
 import { FrameworkId } from './detect.js';
 
+/**
+ * FILE: packages/cli/src/config.ts
+ * PURPOSE: CLI configuration read/write — manages persistent credentials.
+ *
+ * v0.9 — XDG Base Directory Specification compliance.
+ * The canonical config now lives at:
+ *   - Linux/macOS: $XDG_CONFIG_HOME/mushi/config.json
+ *                  (defaults to ~/.config/mushi/config.json)
+ *   - Windows:     %APPDATA%/mushi/config.json
+ *                  (defaults to ~/AppData/Roaming/mushi/config.json)
+ *   - Anywhere:    falls back to ~/.mushirc when neither exists, and
+ *                  one-way-migrates a legacy ~/.mushirc into the new
+ *                  XDG path on first run after the upgrade.
+ *
+ * Security: the file is written with 0o600 (owner read/write only) so
+ * other local users on a shared box cannot read the API key. On load,
+ * if an existing config was written before this change (0o644), we
+ * proactively chmod it down. The containing directory inherits 0o700.
+ */
+/**
+ * An ingest-only (report:write) key minted for the SDK env vars, bound to the
+ * project it belongs to so a later `mushi config projectId …` can never pair
+ * it with another project. Kept so re-running the wizard or `mushi connect
+ * --write-env` does not need a new browser sign-in just to mint one — the
+ * private `apiKey` above carries mcp:read and must never go into app env.
+ */
+interface SavedSdkKey {
+    projectId: string;
+    key: string;
+}
+interface CliConfig {
+    /** Private CLI + MCP key (report:write + mcp:read). Never written to app env. */
+    apiKey?: string;
+    endpoint?: string;
+    projectId?: string;
+    /** Public SDK ingest key for `projectId` (see {@link SavedSdkKey}). */
+    sdkKey?: SavedSdkKey;
+    /** URL of the Mushi admin console (e.g. http://localhost:6464 for local dev). */
+    consoleUrl?: string;
+    /**
+     * Random per-machine identifier sent with device-auth /start so the server
+     * can supersede this machine's earlier pending sign-in requests (a stale
+     * approval tab must not be approvable while the terminal polls a new code).
+     * Not a secret — it only groups requests from the same machine.
+     */
+    clientId?: string;
+    /**
+     * True once the one-time telemetry-transparency notice has been shown.
+     * Persisted so the notice only appears on first run.
+     */
+    telemetryNoticeShown?: boolean;
+}
+
+/**
+ * Outcome of {@link probeKeyScope}:
+ *   - `ingest-only` — the key authenticates but has no MCP scope (safe to ship)
+ *   - `mcp`         — the key can call the read APIs (must stay private)
+ *   - `invalid`     — the backend rejected the key outright
+ *   - `unreachable` — the request never got an answer
+ *   - `unknown`     — an answer that proves neither (5xx, an unexpected 403…)
+  * @internal Exported for tests only.
+  */
+type KeyScopeProbeResult = 'ingest-only' | 'mcp' | 'invalid' | 'unreachable' | 'unknown';
+interface KeyScopeProbe {
+    result: KeyScopeProbeResult;
+    /** HTTP status when the backend answered. */
+    status?: number;
+    /** Network error message when it did not. */
+    message?: string;
+}
+type ProbeKeyScope = (endpoint: string, apiKey: string, projectId: string) => Promise<KeyScopeProbe>;
+
+interface CreatedProject {
+    id: string;
+    name: string;
+    slug: string;
+    /** report:write SDK ingest key, minted server-side. Null if mint failed. */
+    apiKey: string | null;
+}
+/** Create a project (server auto-mints a key). Throws on failure. */
+declare function createProject(endpoint: string, cliToken: string, name: string, opts?: {
+    /** Narrow the auto-minted key (subset of report:write, mcp:read, mcp:write). */
+    scopes?: readonly string[];
+}): Promise<CreatedProject>;
+/**
+ * Mint a fresh report:write key for an existing project (raw keys can't be
+ * recovered, so selecting a project always mints a new one). Throws
+ * DeviceAuthRequestError on failure (after one transient retry) so the wizard
+ * can tell the user WHY minting failed instead of a bare "could not mint".
+ */
+declare function mintProjectKey(endpoint: string, cliToken: string, projectId: string, opts?: {
+    /**
+     * Narrow the minted key. Must be a subset of the server's LOGIN_SCOPES
+     * (report:write, mcp:read, mcp:write) — e.g. ['mcp:read'] for a
+     * read-only key written into an editor's mcp.json.
+     */
+    scopes?: readonly string[];
+    /** Console-visible key label, e.g. 'mcp-cursor'. Default: 'cli-login'. */
+    label?: string;
+}): Promise<string>;
+
 /**
  * FILE: packages/cli/src/init.ts
  * PURPOSE: `mushi init` wizard — detects framework, asks for credentials,
@@ -21,7 +122,76 @@ interface InitOptions {
     /** Audit an existing install (doctor checks) instead of running the wizard. */
     audit?: boolean;
 }
+/**
+ * The keys the wizard ends up with, one per destination. `sdkKey` goes into
+ * the app's env vars, which ship inside the bundle the end user downloads, so
+ * it is report:write only. `cliKey` (report:write + mcp:read) goes to the
+ * private CLI config for `mushi` commands and the MCP server; it is absent
+ * when this run only learned an ingest key (a pasted key, for example).
+ */
+interface WizardCredentials {
+    projectId: string;
+    sdkKey: string;
+    cliKey?: string;
+}
 declare function runInit(options?: InitOptions): Promise<void>;
+type SavedCredentialsResolution = {
+    kind: 'ready';
+    credentials: WizardCredentials;
+}
+/** The saved key is the private CLI key; an SDK key still has to be minted. */
+ | {
+    kind: 'needs-sdk-key';
+    projectId: string;
+    cliKey: string;
+} | {
+    kind: 'unusable';
+    reason: string;
+};
+/**
+ * Decide what the credentials saved by `mushi login` (or an earlier wizard
+ * run) can be used for. The saved `apiKey` normally carries mcp:read, so it
+ * is never written to app env; the ingest key saved for the same project is,
+ * and so is an `apiKey` the backend confirms is ingest-only.
+ */
+declare function resolveSavedCredentials(saved: Pick<CliConfig, 'sdkKey'> & {
+    projectId: string;
+    apiKey: string;
+}, endpoint: string, probe: ProbeKeyScope): Promise<SavedCredentialsResolution>;
+interface WizardMintDeps {
+    createProject: typeof createProject;
+    mintProjectKey: typeof mintProjectKey;
+}
+type WizardMintTarget = {
+    kind: 'existing';
+    projectId: string;
+} | {
+    kind: 'new';
+    name: string;
+};
+interface WizardMintResult {
+    projectId: string;
+    /** Name the server gave a project this call created. */
+    createdName?: string;
+    sdkKey: string;
+    cliKey?: string;
+    /** Why the CLI key could not be minted. The SDK key is still usable. */
+    cliKeyError?: string;
+}
+/**
+ * Mint one key per destination after browser approval: a report:write key
+ * for the app's env vars and, unless the caller already holds one, a
+ * report:write + mcp:read key for the private CLI config. Throws when the
+ * project cannot be created or the SDK key cannot be minted; a failed CLI
+ * key is reported in `cliKeyError` instead, because the SDK install can
+ * still finish without it. Minting is not idempotent, so nothing retries.
+ */
+declare function mintWizardKeys(deps: WizardMintDeps, args: {
+    endpoint: string;
+    cliToken: string;
+    target: WizardMintTarget;
+    withCliKey: boolean;
+}): Promise<WizardMintResult>;
 /**
  * Strip whitespace, quotes, and any control characters a user might paste by
  * accident. Prevents env-file injection via newlines in a pasted secret.
@@ -37,5 +207,13 @@ declare function sanitizeSecret(raw: string): string;
  * stay on the safe side — better a false warning than a silent leak.
  */
 declare function isEnvFileCoveredByGitignore(gitignoreContent: string, envFile: string): boolean;
+/**
+ * The CLI config after a wizard run. The private key slot gets the CLI key;
+ * when this run only learned an ingest key, a key already saved for the same
+ * project is kept (it may carry mcp:read the ingest key lacks). The ingest
+ * key is saved too, bound to its project, so the next run can reuse it
+ * without a browser sign-in.
+ */
+declare function planCliConfigUpdate(existing: CliConfig, credentials: WizardCredentials, endpoint: string): CliConfig;
 
-export { type InitOptions, isEnvFileCoveredByGitignore, runInit, sanitizeSecret };
+export { type InitOptions, type SavedCredentialsResolution, type WizardCredentials, type WizardMintDeps, type WizardMintResult, type WizardMintTarget, isEnvFileCoveredByGitignore, mintWizardKeys, planCliConfigUpdate, resolveSavedCredentials, runInit, sanitizeSecret };