mergestorm 0.1.1 → 0.3.0

package/README.md

@@ -29,21 +29,68 @@ node packages/mergestorm-cli/dist/cli.js <command>
 npm run dev --workspace=mergestorm -- <command>
 ```
 
+## Interactive shell
+
+On a TTY, bare `mergestorm` (or `mergestorm shell`) opens a branded REPL: a boxed welcome panel (logo, auth/credits status, tips, what's new) and a bordered input box with a live `/` slash-command dropdown. Non-TTY (CI/pipes) prints usage instead — no hanging prompt.
+
+```
+╭──────────────────── mergestorm v0.3.0 ────────────────────╮
+│                     ▟██████████▛                          │
+│                      ▜████████▛                           │
+│                       ▝▜████▛▘                             │
+│                         ▜██▛                               │
+│                          ██                                │
+│                          ▝▘                                │
+│                                                             │
+│  ● msk_live_a1b2…  ·  maelstrom                            │
+│    [████████████████████░░░░░░░░░░░░] 63% used             │
+│                                                             │
+│  Tips for getting started:                                 │
+│    review      review the diff for main...HEAD             │
+│    branches    pick a recently reviewed branch             │
+│    /help       list all commands                           │
+╰─────────────────────────────────────────────────────────────╯
+mergestorm
+╭─────────────────────────╮
+│ › /re                    │
+╰─────────────────────────╯
+  ⁄review     Review git diff (default main...HEAD)
+
+mergestorm> credits
+mergestorm> branches
+mergestorm> chain
+mergestorm> exit
+```
+
+Bare command names still work exactly as before (`review`, `help`, `exit`, …) — typing `/` at the start of a line just opens the live autocomplete dropdown (filtered as you type, navigate with Up/Down, accept with Tab/Enter/Right). Arrow-key history, Ctrl+A/E, Ctrl+U/K, and Ctrl+C-to-clear all work as in a regular shell. On a dumb terminal, without color, or when piped, the box falls back to plain ASCII borders (or no shell at all for non-TTY input).
+
+`credits` / `usage` print a Claude-style meter — long bar + `N% used`, then `Resets … (UTC)` — for standard and premium. `branches` (alias `chains`) lists recently reviewed branches; on a TTY you arrow-select one to open its review-chain timeline. `chain [slug]` shows that timeline directly (defaults to `local/<current-git-branch>`).
+
 ## Commands
 
+One-shot subcommands work the same inside the shell and from argv (scripts/CI):
+
 ```
-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 its result
+mergestorm                      Interactive shell (TTY only)
+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 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)
+mergestorm chain [slug]         Branch review-chain timeline (default: current branch)
+mergestorm whoami [--json]      Key prefix, plan, API base, config path
+mergestorm thread <slug>        Jobs in a review thread
 ```
 
 ### `login`
 
 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 [Account page](https://mergestorm.ai/dashboard/account) → **API keys**).
+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)).
 
 ### `logout`
 
@@ -59,11 +106,19 @@ mergestorm review develop      # develop...HEAD
 mergestorm review main feat/x  # main...feat/x
 ```
 
-Exit code is non-zero on quota limit (402), submission failure, a `failed`/`quota_exceeded` job, or a poll timeout.
+Exit code is non-zero on quota limit (402), submission failure, a `failed`/`quota_exceeded` job, or a poll timeout. In the interactive shell, Ctrl+C during the wait detaches (job keeps running) — use `status <job_id>` later.
 
 ### `status <job_id>`
 
-Fetches a job by id and prints the raw JSON (status, verdict, summary, findings).
+Fetches a job by id and prints the raw JSON (status, verdict, summary, findings). In the shell, output is formatted for reading.
+
+### `credits` / `jobs` / `whoami`
+
+Require a logged-in key and API support for `GET /api/v1/me` and `GET /api/v1/reviews`. Older API deployments degrade gracefully (banner shows local key only).
+
+### `branches` / `chain`
+
+`branches` calls `GET /api/v1/threads` for recently active review threads (branches). On a TTY it opens an arrow-key selector; Enter loads that thread's job timeline. `chain [slug]` is the direct timeline view — omit the slug to use `local/<current-git-branch>` (same slug `review` stamps).
 
 ## Context pack (`.mergestorm/`)
 
@@ -75,6 +130,7 @@ Any `*.md` / `*.txt` files under `./.mergestorm/` (one level of nesting) are att
 |----------|---------|---------|
 | `MERGESTORM_API_KEY` | API key (overrides the stored config) | — |
 | `MERGESTORM_API_URL` | API base URL | `https://api.mergestorm.ai` |
+| `NO_COLOR` | Disable ANSI colors | — |
 
 ## See also
 

package/dist/api.d.ts

@@ -0,0 +1,85 @@
+import { type Config } from "./config.js";
+export declare function apiFetch(cfg: Config, route: string, init?: RequestInit & {
+    json?: unknown;
+}): Promise<{
+    status: number;
+    body: unknown;
+}>;
+export declare function devicePost(base: string, route: string, json: unknown): Promise<{
+    status: number;
+    body: any;
+}>;
+export type MeResponse = {
+    key: {
+        prefix: string;
+        name: string;
+        created_at: string;
+        last_used_at: string | null;
+    };
+    plan_key: string;
+    plan_label_key?: string;
+    /** Start of next UTC month (usage meters reset). Older APIs omit this. */
+    resets_at?: string;
+    usage: {
+        standard: {
+            used: number;
+            limit: number | null;
+            remaining: number | null;
+        };
+        premium: {
+            used: number;
+            limit: number | null;
+            remaining: number | null;
+        };
+    };
+};
+export type JobListItem = {
+    job_id: string;
+    thread_slug: string | null;
+    status: string;
+    verdict: string | null;
+    summary: string | null;
+    base_label: string | null;
+    head_label: string | null;
+    created_at: string;
+    finished_at: string | null;
+    credits: number;
+};
+export type ThreadListItem = {
+    slug: string;
+    branch: string | null;
+    owner: string | null;
+    repo: string | null;
+    pr_number: number | null;
+    status: string;
+    job_count: number;
+    last_verdict: string | null;
+    last_activity_at: string;
+};
+export type ThreadDetail = {
+    thread_id: string;
+    slug: string;
+    source?: string;
+    branch: string | null;
+    owner: string | null;
+    repo: string | null;
+    pr_number: number | null;
+    status: string;
+    pr_linked_at: string | null;
+    job_count: number;
+    created_at: string;
+    jobs: {
+        job_id: string;
+        status: string;
+        summary?: string | null;
+        verdict?: string | null;
+        thread_job_number?: number | null;
+        created_at: string;
+        finished_at?: string | null;
+    }[];
+};
+/** 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 listJobs(limit?: number, cfg?: Config): Promise<JobListItem[]>;
+/** Recently reviewed branches/threads (Bearer GET /api/v1/threads). */
+export declare function listThreads(limit?: number, cfg?: Config): Promise<ThreadListItem[]>;

package/dist/api.js

@@ -0,0 +1,85 @@
+import { apiBase, loadConfig, resolveApiKey } from "./config.js";
+import { CommandError } from "./errors.js";
+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.");
+    }
+    const headers = {
+        Authorization: `Bearer ${key}`,
+        ...init.headers,
+    };
+    let body = init.body;
+    if (init.json !== undefined) {
+        headers["Content-Type"] = "application/json";
+        body = JSON.stringify(init.json);
+    }
+    const res = await fetch(`${apiBase(cfg)}${route}`, { ...init, headers, body });
+    const text = await res.text();
+    let parsed = text;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // keep text
+    }
+    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();
+    let parsed = text;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // keep text
+    }
+    return { status: res.status, body: parsed };
+}
+/** Fetch /api/v1/me; returns null on 404/network so callers can degrade. */
+export async function getMe(cfg) {
+    const resolved = cfg ?? (await loadConfig());
+    try {
+        const { status, body } = await apiFetch(resolved, "/api/v1/me");
+        if (status === 404)
+            return null;
+        if (status !== 200)
+            return null;
+        return body;
+    }
+    catch {
+        return null;
+    }
+}
+export async function listJobs(limit = 10, cfg) {
+    const resolved = cfg ?? (await loadConfig());
+    const capped = Math.min(Math.max(limit, 1), 50);
+    const { status, body } = await apiFetch(resolved, `/api/v1/reviews?limit=${capped}`);
+    if (status === 404) {
+        throw new CommandError("Job list is not available on this server yet. Update the API or use the dashboard.");
+    }
+    if (status !== 200) {
+        throw new CommandError(`Failed to list jobs (HTTP ${status}): ${JSON.stringify(body)}`);
+    }
+    const items = body.items;
+    return Array.isArray(items) ? items : [];
+}
+/** Recently reviewed branches/threads (Bearer GET /api/v1/threads). */
+export async function listThreads(limit = 20, cfg) {
+    const resolved = cfg ?? (await loadConfig());
+    const capped = Math.min(Math.max(limit, 1), 50);
+    const { status, body } = await apiFetch(resolved, `/api/v1/threads?limit=${capped}`);
+    if (status === 404) {
+        throw new CommandError("Branch list is not available on this server yet. Deploy the API update or use the dashboard.");
+    }
+    if (status !== 200) {
+        throw new CommandError(`Failed to list branches (HTTP ${status}): ${JSON.stringify(body)}`);
+    }
+    const items = body.items;
+    return Array.isArray(items) ? items : [];
+}