mergestorm 0.3.6 → 0.3.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Margin Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,46 +1,41 @@
-# mergestorm CLI
+# Mergestorm CLI
 
-Review a local git diff with MergeStorm without opening a GitHub PR — for local loops and CI. Diffs are reviewed by the same engine as PR reviews and each review consumes one standard credit.
+Review a local git diff with Mergestorm without opening a GitHub PR — for local loops and CI. Diffs are reviewed by the same engine as PR reviews and each review consumes one standard credit.
 
 Requires **Node.js 22+**.
 
 ## Install
 
-One-liner (installs the global `mergestorm` binary, then sign in via your browser):
+Recommended — install from npm (same package the one-liner uses):
 
 ```bash
-curl -fsSL https://mergestorm.ai/install.sh | bash
+npm install -g mergestorm
+mergestorm --version   # confirm install
 mergestorm login
+# or the short alias (same binary):
+mg login
 ```
 
-Or install directly with npm:
+Optional curl installer (checks Node 22+, then runs `npm install -g mergestorm`):
 
 ```bash
-npm install -g mergestorm
+curl -fsSL https://mergestorm.ai/install.sh | bash
 mergestorm login
-# or the short alias (same binary):
-mg login
 ```
 
 After install, both `mergestorm` and `mg` invoke the same CLI.
 
-### From this monorepo (development / local UI testing)
+## Source
 
-You do **not** need to bump/publish npm to try shell layout changes. From the repo root:
+Public source (MIT): [github.com/marginsystems/mergestorm-cli](https://github.com/marginsystems/mergestorm-cli).
+Tags there match npm versions (`v0.3.8`, …).
 
 ```bash
-# Fastest — runs TypeScript via tsx (no build, no version bump):
-npm run dev --workspace=mergestorm
-
-# Or build once, then run the compiled binary:
-npm run build --workspace=mergestorm
-node packages/mergestorm-cli/dist/cli.js
-
-# Optional: expose a local binary as `mergestorm` without publishing
-npm run build --workspace=mergestorm
-npm link --workspace=mergestorm
-mergestorm          # uses your local build
-# later: npm unlink -g mergestorm && npm install -g mergestorm
+git clone https://github.com/marginsystems/mergestorm-cli.git
+cd mergestorm-cli
+npm install
+npm run build
+node dist/cli.js --help
 ```
 
 ## Interactive shell
@@ -48,21 +43,21 @@ mergestorm          # uses your local build
 On a TTY, bare `mergestorm` (or `mergestorm shell`) opens a branded REPL: a **full-width** welcome panel (logo + status on the left, tips / what's new on the right) and a **full-width** bordered input box with a live `/` slash-command dropdown. Non-TTY (CI/pipes) prints usage instead — no hanging prompt.
 
 ```
-╭─ mergestorm v0.3.6 ──────────────────────────────────────────────────────────╮
+╭─ mergestorm v0.3.8 ──────────────────────────────────────────────────────────╮
 │      ▟██████████▛       Tips for getting started                             │
-│       ▜████████▛          review      review main...HEAD                     │
+│       ▜████████▛          review      review origin/HEAD or main             │
 │        ▝▜████▛▘           stack       create → submit → restack → land       │
 │          ▜██▛             /help       list all commands                      │
 │           ██                                                                 │
-│           ▝▘            What's new in v0.3.6                                 │
-│  ● msk…  ·  maelstrom     • stack state under ~/.mergestorm/stacks/          │
+│           ▝▘            What's new in v0.3.8                                 │
+│  ● msk…  ·  maelstrom     • MIT license + public source (mergestorm-cli)       │
 │  [████░░░░░░░░░░] 12% used                                                   │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 mergestorm
 ╭──────────────────────────────────────────────────────────────────────────────╮
 │ › /re                                                                        │
 ╰──────────────────────────────────────────────────────────────────────────────╯
-  /review       Review git diff (default main...HEAD)
+  /review       Review git diff (default origin/HEAD or main or master)
 
 mergestorm> credits
 mergestorm> branches
@@ -84,8 +79,8 @@ mergestorm shell                Explicit shell entry
 mergestorm login                Sign in via browser; stores an API key in ~/.mergestorm/config.json
 mergestorm login --key          Paste an existing API key instead (headless/CI)
 mergestorm logout               Remove the stored API key
-mergestorm review [base] [head] Review git diff base...head (default: main...HEAD)
-mergestorm status <job_id>      Poll a review job and print JSON
+mergestorm review [base] [head] Review git diff base...head (default: origin/HEAD or main or master)
+mergestorm status <job_id>      Fetch a review job and print JSON (one shot)
 mergestorm credits [--json]     Standard + premium credit balance (usage bars)
 mergestorm jobs [n] [--json]    Recent review jobs (default 10, max 50)
 mergestorm branches [n]         Recently reviewed branches (arrow-pick on TTY)
@@ -97,16 +92,16 @@ mergestorm stack submit         Push layers, open chained PRs (`gh`), register v
 mergestorm stack list [--json]  List registered stacks
 mergestorm stack adopt <owner/repo>#<pr>  Import an existing open PR chain
 mergestorm stack restack <stack-id>  Restack descendants
-mergestorm stack land <stack-id>     Land the bottom open PR
-mergestorm stack auto-land on|off <stack-id>  Toggle auto-land when green
+mergestorm stack land <stack-id>     Land / promote (into review unit when present)
+mergestorm stack auto-promote on|off <stack-id>  Toggle auto-promote when green
 mergestorm stack reset --force  Clear local authoring state (not branches/PRs)
 ```
 
-`mg` is a short alias for `mergestorm` (same binary), e.g. `mg stack create`. Happy path: **create → commit → submit → restack → land**. `stack adopt` is for importing a chain that already exists on GitHub (legacy / Graphite). Restack/land use the same login key (`/api/v1/stacks`).
+`mg` is a short alias for `mergestorm` (same binary), e.g. `mg stack create`. Happy path: **create → commit → submit → restack → land**. On review-unit stacks, `stack land` **promotes** the tip into the unit (same gates as the dashboard); otherwise it lands the bottom open PR. `stack auto-promote` turns on land-when-green for a registered stack (`auto-land` remains a deprecated alias). `stack adopt` is for importing a chain that already exists on GitHub (legacy / Graphite). Restack/land use the same login key (`/api/v1/stacks`).
 
 `stack create` is local-only: it checks out a new branch from the current tip (or `--onto <branch>`), discovers trunk (`main` / `master` / `origin/HEAD`, overridable with `--trunk`), and records `{ branch, parentBranch }` in CLI-managed state under **`~/.mergestorm/stacks/<repo-id>/stack.json`**. The CLI updates this automatically; never edit it. Linked worktrees share state, while independent clones remain isolated. Creating onto trunk with a non-empty active stack starts a new one. No repository file, GitHub call, or API call is made.
 
-`stack submit` walks the **active** local stack: `git push -u origin` each layer, opens a PR with `gh` (`--base` = parent or trunk; skips heads that already have an open PR; body from the tip commit — Summary + Test plan, preserving Fixes/Closes/Resolves), registers the stack with `POST /api/v1/stacks/adopt` internally (Mergestorm API key), then drops that local stack entry so the next create onto trunk is clean. Push/PR auth is your local `git` + `gh auth` — not a Cyclone app token.
+`stack submit` walks the **active** local stack: `git push -u origin` each layer, opens a PR with `gh` (`--base` = parent or trunk; skips heads that already have an open PR; body from the tip commit — Summary + Test plan, preserving Fixes/Closes/Resolves), registers the stack with `POST /api/v1/stacks/adopt` internally (Mergestorm API key), then drops that local stack entry so the next create onto trunk is clean. Push/PR auth is your local `git` + `gh auth` — not a GitHub App installation token.
 
 Legacy repo-local `.mergestorm/stack.json` state migrates automatically on the next stack command. If local authoring state is stale or malformed, use `mg stack reset --force`; this clears only pre-submit CLI state and never deletes branches, PRs, or registered stacks.
 
@@ -114,7 +109,7 @@ Legacy repo-local `.mergestorm/stack.json` state migrates automatically on the n
 
 Runs a browser device-authorization flow: prints a short code, opens `https://mergestorm.ai/cli/auth`, and — once you approve — mints and stores an API key in `~/.mergestorm/config.json` (mode `600`). No key copy/paste needed.
 
-For headless or CI environments, use `mergestorm login --key` to paste an existing `msk_live_…` key (create one on the dashboard [API tab](https://mergestorm.ai/dashboard/api)).
+For headless or CI environments, use `mergestorm login --key` to paste an existing `msk_live_…` key (create one on the dashboard [API tab](https://mergestorm.ai/dashboard/api)). On a TTY the paste is hidden (not echoed); the CLI verifies the key with the API before saving.
 
 ### `logout`
 
@@ -122,10 +117,10 @@ Removes `~/.mergestorm/config.json` so the stored key is no longer used.
 
 ### `review [base] [head]`
 
-Collects `git diff base...head` (default `main...HEAD`), attaches the changed file contents (up to 40 files, skipping files > 400 KB), submits the job, and polls until it finishes (~3 min max). The thread slug is derived from the current branch (`local/<branch>`), so repeated runs on the same branch chain their findings. Programmatic callers can provide explicit review context through the Review Jobs API.
+Collects `git diff base...head` (default: discovered trunk — `origin/HEAD`, `main`, or `master`), attaches the changed file contents (up to 40 files, skipping files > 400 KB), submits the job, and polls until it finishes (~3 min max). The thread slug is derived from the current branch (`local/<branch>`), so repeated runs on the same branch chain their findings. Programmatic callers can provide explicit review context through the Review Jobs API.
 
 ```bash
-mergestorm review              # main...HEAD
+mergestorm review              # discovered trunk (origin/HEAD, main, or master)...HEAD
 mergestorm review develop      # develop...HEAD
 mergestorm review main feat/x  # main...feat/x
 ```
@@ -154,5 +149,6 @@ Require a logged-in key and API support for `GET /api/v1/me` and `GET /api/v1/re
 
 ## See also
 
-- [Review Jobs API reference](https://github.com/marginsystems/mergestorm/blob/main/docs/review-jobs-api.md) — raw HTTP endpoints, webhook signing, thread chains, quota.
+- [Public source — mergestorm-cli](https://github.com/marginsystems/mergestorm-cli)
 - [Docs — Review Jobs API & CLI](https://mergestorm.ai/docs#review-jobs-api) — product docs on the site.
+- [npm — mergestorm](https://www.npmjs.com/package/mergestorm)

package/dist/api.d.ts

@@ -1,11 +1,21 @@
 import { type Config } from "./config.js";
-export declare function apiFetch(cfg: Config, route: string, init?: RequestInit & {
+/** Default per-request timeout so a hung API cannot stall the shell/CI forever. */
+export declare const DEFAULT_API_TIMEOUT_MS = 30000;
+/** Message prefix of the CommandError thrown when a request exceeds its timeout. */
+export declare const API_TIMEOUT_PREFIX = "Request timed out after";
+export type ApiFetchInit = RequestInit & {
     json?: unknown;
-}): Promise<{
+    /** Override {@link DEFAULT_API_TIMEOUT_MS}. */
+    timeoutMs?: number;
+};
+export declare function apiFetch(cfg: Config, route: string, init?: ApiFetchInit): Promise<{
     status: number;
     body: unknown;
 }>;
-export declare function devicePost(base: string, route: string, json: unknown): Promise<{
+export declare function devicePost(base: string, route: string, json: unknown, opts?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<{
     status: number;
     body: any;
 }>;
@@ -79,7 +89,9 @@ export type ThreadDetail = {
     }[];
 };
 /** Fetch /api/v1/me; returns null on 404/network so callers can degrade. */
-export declare function getMe(cfg?: Config): Promise<MeResponse | null>;
+export declare function getMe(cfg?: Config, opts?: {
+    timeoutMs?: number;
+}): Promise<MeResponse | null>;
 export declare function listJobs(limit?: number, cfg?: Config): Promise<JobListItem[]>;
 export type StackLayerDto = {
     branch: string;

package/dist/api.js

@@ -1,21 +1,77 @@
 import { apiBase, loadConfig, resolveApiKey } from "./config.js";
 import { CommandError } from "./errors.js";
+/** Default per-request timeout so a hung API cannot stall the shell/CI forever. */
+export const DEFAULT_API_TIMEOUT_MS = 30_000;
+/** Message prefix of the CommandError thrown when a request exceeds its timeout. */
+export const API_TIMEOUT_PREFIX = "Request timed out after";
+function isAbortLike(err) {
+    return (err instanceof Error &&
+        (err.name === "AbortError" || err.name === "TimeoutError"));
+}
+/**
+ * Combine an optional caller signal with a ref'd timeout.
+ * (Built-in `AbortSignal.timeout` unrefs its timer, which can leave hung
+ * fetches without a live timer in edge cases / tests.)
+ */
+function withRequestSignal(userSignal, timeoutMs) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => {
+        ac.abort(new DOMException("The operation was aborted due to timeout", "TimeoutError"));
+    }, timeoutMs);
+    const onUserAbort = () => {
+        ac.abort(userSignal.reason);
+    };
+    if (userSignal) {
+        if (userSignal.aborted)
+            onUserAbort();
+        else
+            userSignal.addEventListener("abort", onUserAbort, { once: true });
+    }
+    return {
+        signal: ac.signal,
+        dispose: () => {
+            clearTimeout(timer);
+            userSignal?.removeEventListener("abort", onUserAbort);
+        },
+    };
+}
+/** Map hung-request aborts to CommandError; preserve caller cancel (Ctrl+C detach). */
+function rethrowFetchAbort(err, timeoutMs) {
+    if (isAbortLike(err)) {
+        if (err.name === "AbortError")
+            throw err;
+        throw new CommandError(`${API_TIMEOUT_PREFIX} ${Math.round(timeoutMs / 1000)}s. Check network connectivity and API status.`, 1, "api_timeout");
+    }
+    throw err;
+}
 export async function apiFetch(cfg, route, init = {}) {
     const key = resolveApiKey(cfg);
     if (!key) {
-        throw new CommandError("No API key. Run `mergestorm login` or set MERGESTORM_API_KEY.");
+        throw new CommandError("No API key. Run `mergestorm login` or set MERGESTORM_API_KEY.", 1, "missing_api_key");
     }
+    const { json, timeoutMs = DEFAULT_API_TIMEOUT_MS, signal: userSignal, ...rest } = init;
     const headers = {
         Authorization: `Bearer ${key}`,
-        ...init.headers,
+        ...rest.headers,
     };
-    let body = init.body;
-    if (init.json !== undefined) {
+    let body = rest.body;
+    if (json !== undefined) {
         headers["Content-Type"] = "application/json";
-        body = JSON.stringify(init.json);
+        body = JSON.stringify(json);
+    }
+    const { signal, dispose } = withRequestSignal(userSignal, timeoutMs);
+    let res;
+    let text = "";
+    try {
+        res = await fetch(`${apiBase(cfg)}${route}`, { ...rest, headers, body, signal });
+        text = await res.text();
+    }
+    catch (err) {
+        rethrowFetchAbort(err, timeoutMs);
+    }
+    finally {
+        dispose();
     }
-    const res = await fetch(`${apiBase(cfg)}${route}`, { ...init, headers, body });
-    const text = await res.text();
     let parsed = text;
     try {
         parsed = JSON.parse(text);
@@ -23,15 +79,31 @@ export async function apiFetch(cfg, route, init = {}) {
     catch {
         // keep text
     }
+    if (res.status === 401) {
+        throw new CommandError("API key invalid or revoked. Run `mergestorm login`.", 1, "auth_invalid");
+    }
     return { status: res.status, body: parsed };
 }
-export async function devicePost(base, route, json) {
-    const res = await fetch(`${base}${route}`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(json),
-    });
-    const text = await res.text();
+export async function devicePost(base, route, json, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_API_TIMEOUT_MS;
+    const { signal, dispose } = withRequestSignal(opts.signal, timeoutMs);
+    let res;
+    let text = "";
+    try {
+        res = await fetch(`${base}${route}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(json),
+            signal,
+        });
+        text = await res.text();
+    }
+    catch (err) {
+        rethrowFetchAbort(err, timeoutMs);
+    }
+    finally {
+        dispose();
+    }
     let parsed = text;
     try {
         parsed = JSON.parse(text);
@@ -42,17 +114,26 @@ export async function devicePost(base, route, json) {
     return { status: res.status, body: parsed };
 }
 /** Fetch /api/v1/me; returns null on 404/network so callers can degrade. */
-export async function getMe(cfg) {
+export async function getMe(cfg, opts) {
     const resolved = cfg ?? (await loadConfig());
     try {
-        const { status, body } = await apiFetch(resolved, "/api/v1/me");
+        const { status, body } = await apiFetch(resolved, "/api/v1/me", {
+            timeoutMs: opts?.timeoutMs,
+        });
         if (status === 404)
             return null;
         if (status !== 200)
             return null;
         return body;
     }
-    catch {
+    catch (err) {
+        // 401 (and missing-key) must surface — do not misdiagnose as offline/old API.
+        // Timeouts degrade like other network failures (banner / soft probes).
+        if (err instanceof CommandError) {
+            if (err.code === "api_timeout")
+                return null;
+            throw err;
+        }
         return null;
     }
 }

package/dist/cli.js

@@ -1,84 +1,32 @@
 #!/usr/bin/env node
 import { stdin as input, stdout as output } from "node:process";
-import { DEFAULT_API } from "./config.js";
 import { CommandError } from "./errors.js";
-import { cmdBranches, cmdChain } from "./commands/branches.js";
-import { cmdCredits } from "./commands/credits.js";
-import { cmdJobs, cmdThread } from "./commands/jobs.js";
-import { cmdLogin } from "./commands/login.js";
-import { cmdLogout } from "./commands/logout.js";
-import { cmdReview } from "./commands/review.js";
-import { cmdStack } from "./commands/stack.js";
-import { cmdStatus } from "./commands/status.js";
-import { cmdWhoami } from "./commands/whoami.js";
+import { dispatchCommand, formatUsageBody, } from "./commands/registry.js";
+import { isSupportedNode, unsupportedNodeMessage, } from "./node-version.js";
 import { runShell } from "./shell.js";
 import { ansi } from "./ui/ansi.js";
 import { printWordmark } from "./ui/banner.js";
+import { cliVersion } from "./version.js";
+if (!isSupportedNode()) {
+    console.error(unsupportedNodeMessage());
+    process.exit(1);
+}
 function usage() {
     printWordmark();
     console.log(`Usage:
-  mergestorm                      Interactive shell (TTY)
-  mergestorm shell                Explicit shell entry
-  mergestorm login                Sign in via browser and store an API key
-  mergestorm login --key          Paste an existing API key instead (headless/CI)
-  mergestorm logout               Remove the stored API key
-  mergestorm review [base] [head] Review git diff base...head (default: main...HEAD)
-  mergestorm status <job_id>      Poll a review job (JSON)
-  mergestorm credits [--json]     Credit balance (usage bars)
-  mergestorm jobs [n] [--json]    Recent review jobs
-  mergestorm branches [n]         Recently reviewed branches (pick on TTY)
-  mergestorm chain [slug]         Branch review-chain timeline (default: current)
-  mergestorm whoami [--json]      Key + plan + API base
-  mergestorm thread <slug>        Jobs in a review thread
-  mergestorm stack create [name]  New local stack layer (CLI-managed authoring state)
-  mergestorm stack submit         Push active local stack, open PRs, register stack
-  mergestorm stack reset --force  Clear this repo's pre-submit authoring state
-  mergestorm stack list [--json]  List registered stacks
-  mergestorm stack adopt <owner/repo>#<pr>  Import an existing open PR chain
-  mergestorm stack restack <stack-id>   Restack stack descendants
-  mergestorm stack land <stack-id>      Land bottom PR (or promote into unit)
-  mergestorm stack auto-promote on|off <stack-id>  Toggle auto-promote when green
-
-  mg is a short alias for mergestorm (same binary).
-
-Env:
-  MERGESTORM_API_KEY   API key (overrides config)
-  MERGESTORM_API_URL   API base (default ${DEFAULT_API})
+${formatUsageBody()}
 `);
 }
 async function runCommand(cmd, args) {
-    if (cmd === "login")
-        return cmdLogin(args);
-    if (cmd === "logout")
-        return cmdLogout();
-    if (cmd === "review")
-        return cmdReview(args);
-    if (cmd === "status") {
-        if (!args[0])
-            throw new CommandError("usage: mergestorm status <job_id>");
-        return cmdStatus(args[0], { format: "json" });
+    if (cmd === "help" || cmd === "?") {
+        usage();
+        return;
     }
-    if (cmd === "credits" || cmd === "usage")
-        return cmdCredits(args);
-    if (cmd === "jobs")
-        return cmdJobs(args);
-    if (cmd === "branches" || cmd === "chains")
-        return cmdBranches(args);
-    if (cmd === "chain")
-        return cmdChain(args);
-    if (cmd === "whoami")
-        return cmdWhoami(args);
-    if (cmd === "thread") {
-        if (!args[0])
-            throw new CommandError("usage: mergestorm thread <slug>");
-        return cmdThread(args[0], args.slice(1));
+    const ok = await dispatchCommand(cmd, args, { mode: "oneshot" });
+    if (!ok) {
+        usage();
+        throw new CommandError(`unknown command: ${cmd}`);
     }
-    if (cmd === "stack")
-        return cmdStack(args);
-    if (cmd === "shell")
-        return runShell();
-    usage();
-    throw new CommandError(`unknown command: ${cmd}`);
 }
 async function main() {
     const [, , cmd, ...args] = process.argv;
@@ -90,10 +38,14 @@ async function main() {
         usage();
         return;
     }
-    if (cmd === "-h" || cmd === "--help") {
+    if (cmd === "-h" || cmd === "--help" || cmd === "help" || cmd === "?") {
         usage();
         return;
     }
+    if (cmd === "-v" || cmd === "--version" || cmd === "version") {
+        console.log(cliVersion());
+        return;
+    }
     try {
         await runCommand(cmd, args);
     }

package/dist/commands/login.d.ts

@@ -1,2 +1,8 @@
-import { Interface } from "node:readline/promises";
-export declare function cmdLogin(args: string[], rl?: Interface): Promise<void>;
+import { type Config } from "../config.js";
+import { type MeResponse } from "../api.js";
+/**
+ * Probe /api/v1/me with an in-memory config. Does not write disk.
+ * Throws CommandError when the key must not be saved.
+ */
+export declare function validateApiKey(cfg: Config): Promise<MeResponse>;
+export declare function cmdLogin(args: string[]): Promise<void>;

package/dist/commands/login.js

@@ -1,11 +1,10 @@
 import { spawn } from "node:child_process";
 import { platform } from "node:os";
-import { createInterface } from "node:readline/promises";
-import { stdin as input, stdout as output } from "node:process";
 import { apiBase, configPath, loadConfig, saveConfig } from "../config.js";
-import { devicePost } from "../api.js";
+import { devicePost, getMe } from "../api.js";
 import { CommandError } from "../errors.js";
 import { ansi } from "../ui/ansi.js";
+import { readSecretLine } from "../ui/secret-input.js";
 function openBrowser(url) {
     const os = platform();
     const cmd = os === "darwin" ? "open" : os === "win32" ? "cmd" : "xdg-open";
@@ -19,29 +18,42 @@ function openBrowser(url) {
         // URL is printed for manual open
     }
 }
-async function loginWithKey(existingRl) {
-    if (!existingRl)
-        input.resume();
-    const rl = existingRl ?? createInterface({ input, output });
-    const ownRl = !existingRl;
+/**
+ * Probe /api/v1/me with an in-memory config. Does not write disk.
+ * Throws CommandError when the key must not be saved.
+ */
+export async function validateApiKey(cfg) {
     try {
-        const key = (await rl.question("Paste your MergeStorm API key (msk_live_...): ")).trim();
-        if (!key.startsWith("msk_live_")) {
-            throw new CommandError("Key should start with msk_live_");
+        const me = await getMe(cfg);
+        if (!me) {
+            throw new CommandError("Could not verify API key (API unreachable or too old). Key was not saved.");
         }
-        const cfg = await loadConfig();
-        cfg.apiKey = key;
-        await saveConfig(cfg);
-        console.log(`Saved to ${configPath()}`);
+        return me;
     }
-    finally {
-        if (ownRl)
-            rl.close();
+    catch (err) {
+        if (err instanceof CommandError && err.code === "auth_invalid") {
+            throw new CommandError("API key invalid or revoked. Key was not saved. Check the key and run `mergestorm login --key` again.", 1, "auth_invalid");
+        }
+        throw err;
+    }
+}
+async function loginWithKey() {
+    // Always use muted secret input on TTY so the key never lands in
+    // question()/history echo.
+    const key = (await readSecretLine("Paste your Mergestorm API key (msk_live_...): ")).trim();
+    if (!key.startsWith("msk_live_")) {
+        throw new CommandError("Key should start with msk_live_");
     }
+    const cfg = await loadConfig();
+    cfg.apiKey = key;
+    const me = await validateApiKey(cfg);
+    await saveConfig(cfg);
+    const prefix = me.key?.prefix?.trim() || "msk_live_…";
+    console.log(`Verified ${prefix}… · saved to ${configPath()}`);
 }
-export async function cmdLogin(args, rl) {
+export async function cmdLogin(args) {
     if (args.includes("--key")) {
-        await loginWithKey(rl);
+        await loginWithKey();
         return;
     }
     const cfg = await loadConfig();

package/dist/commands/registry.d.ts

@@ -0,0 +1,32 @@
+import type { CommandSpec } from "../ui/prompt.js";
+/** Shared dispatch context for oneshot argv and the interactive shell. */
+export type CommandContext = {
+    mode: "oneshot" | "shell";
+    signal?: AbortSignal;
+    /** Shell: refresh banner after login/logout. */
+    afterAuth?: () => Promise<void>;
+};
+export type RegistryCommand = {
+    name: string;
+    /** Alternate names that resolve to the same handler (also listed in shell autocomplete). */
+    aliases?: string[];
+    /** Short line for shell `/help` and autocomplete. */
+    summary: string;
+    /** Lines under oneshot `Usage:` (already prefixed with `mergestorm …`). */
+    usage: string[];
+    run: (args: string[], ctx: CommandContext) => Promise<void>;
+};
+/**
+ * Single source of truth for CLI commands (STRUCT-01).
+ * Derive oneshot usage, shell COMMANDS, and both dispatchers from this table.
+ */
+export declare const COMMAND_REGISTRY: RegistryCommand[];
+export declare function findCommand(name: string): RegistryCommand | undefined;
+/** Autocomplete / `/help` list for the interactive shell. */
+export declare function shellCommandSpecs(): CommandSpec[];
+export declare function formatUsageBody(): string;
+/**
+ * Run a registered command. Returns false when `name` is unknown
+ * (caller prints usage / shell hint).
+ */
+export declare function dispatchCommand(name: string, args: string[], ctx: CommandContext): Promise<boolean>;