mergestorm 0.2.0 → 0.3.1

package/README.md

@@ -20,29 +20,56 @@ npm install -g mergestorm
 mergestorm login
 ```
 
-### From this monorepo (development)
+### From this monorepo (development / local UI testing)
+
+You do **not** need to bump/publish npm to try shell layout changes. From the repo root:
 
 ```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
-node packages/mergestorm-cli/dist/cli.js <command>
-# or skip the build during dev (runs src/cli.ts via tsx):
-npm run dev --workspace=mergestorm -- <command>
+npm link --workspace=mergestorm
+mergestorm          # uses your local build
+# later: npm unlink -g mergestorm && npm install -g mergestorm
 ```
 
 ## Interactive shell
 
-On a TTY, bare `mergestorm` (or `mergestorm shell`) opens a branded REPL with auth/credits status, green prompt, and in-shell commands. Non-TTY (CI/pipes) prints usage instead — no hanging prompt.
+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
- __  __ ___ ___  …
-  ● msk_live_a1b2…  ·  pro  ·  standard credits: 63 of 100 left
+╭─ mergestorm v0.3.1 ──────────────────────────────────────────────────────────╮
+│      ▟██████████▛       Tips for getting started                             │
+│       ▜████████▛          review      review main...HEAD                     │
+│        ▝▜████▛▘           branches    pick a reviewed branch                 │
+│          ▜██▛             /help       list all commands                      │
+│           ██                                                                 │
+│           ▝▘            What's new in v0.3.1                                 │
+│  ● msk…  ·  maelstrom     • Full-width welcome + input                      │
+│  [████░░░░░░░░░░] 12% used                                                   │
+╰──────────────────────────────────────────────────────────────────────────────╯
+mergestorm
+╭──────────────────────────────────────────────────────────────────────────────╮
+│ › /re                                                                        │
+╰──────────────────────────────────────────────────────────────────────────────╯
+  /review       Review git diff (default main...HEAD)
 
 mergestorm> credits
-mergestorm> review
+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 work as in a regular shell. At the idle prompt, **Ctrl+C twice** (within ~1.5s) exits the shell; a single Ctrl+C clears the line and shows a confirm hint. While `review` / `status` is waiting, Ctrl+C detaches or aborts that wait (job may keep running) — it does not exit the shell. Ctrl+D on an empty line, or `exit` / `quit`, also leave the 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 usage 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):
@@ -55,8 +82,10 @@ 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
+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
 ```
@@ -91,6 +120,10 @@ Fetches a job by id and prints the raw JSON (status, verdict, summary, findings)
 
 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/`)
 
 Any `*.md` / `*.txt` files under `./.mergestorm/` (one level of nesting) are attached as context so the reviewer understands intent, conventions, or migration notes without you resending history.

package/dist/api.d.ts

@@ -18,16 +18,18 @@ export type MeResponse = {
     };
     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;
-            remaining: number;
+            limit: number | null;
+            remaining: number | null;
         };
         premium: {
             used: number;
-            limit: number;
-            remaining: number;
+            limit: number | null;
+            remaining: number | null;
         };
     };
 };
@@ -43,6 +45,41 @@ export type JobListItem = {
     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

@@ -69,3 +69,17 @@ export async function listJobs(limit = 10, cfg) {
     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 : [];
+}

package/dist/cli.js

@@ -2,6 +2,7 @@
 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";
@@ -22,8 +23,10 @@ function usage() {
   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
+  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
 
@@ -48,6 +51,10 @@ async function runCommand(cmd, args) {
         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") {

package/dist/commands/branches.d.ts

@@ -0,0 +1,10 @@
+import { type ThreadListItem } from "../api.js";
+/** One-line label for a branch/thread row (also used by tests). */
+export declare function formatBranchRow(item: ThreadListItem): string;
+/** Interactive list of recently reviewed branches → open chain on select. */
+export declare function cmdBranches(args?: string[]): Promise<void>;
+/**
+ * Show the review-chain timeline for a branch/thread.
+ * Defaults to `local/<current-git-branch>` when no slug is given.
+ */
+export declare function cmdChain(args?: string[]): Promise<void>;

package/dist/commands/branches.js

@@ -0,0 +1,85 @@
+import { stdin as input, stdout as output } from "node:process";
+import { listThreads } from "../api.js";
+import { loadConfig } from "../config.js";
+import { CommandError } from "../errors.js";
+import { git } from "../git.js";
+import { ansi } from "../ui/ansi.js";
+import { selectFromList } from "../ui/select.js";
+import { cmdThread, relativeWhen } from "./jobs.js";
+/** One-line label for a branch/thread row (also used by tests). */
+export function formatBranchRow(item) {
+    const name = (item.branch?.trim() || item.slug).slice(0, 36);
+    const jobs = `${item.job_count} job${item.job_count === 1 ? "" : "s"}`;
+    const verdict = item.last_verdict ?? "-";
+    const when = relativeWhen(item.last_activity_at);
+    const pr = item.owner && item.repo && item.pr_number != null
+        ? `  PR #${item.pr_number}`
+        : "";
+    const closed = item.status === "closed" ? "  closed" : "";
+    return `${name.padEnd(36)}  ${jobs.padEnd(8)}  ${verdict.padEnd(12)}  ${when}${pr}${closed}`;
+}
+function printBranchTable(items) {
+    const header = ["BRANCH / SLUG", "JOBS", "VERDICT", "WHEN", "PR"];
+    const rows = items.map((t) => [
+        (t.branch?.trim() || t.slug).slice(0, 36),
+        String(t.job_count),
+        t.last_verdict ?? "-",
+        relativeWhen(t.last_activity_at),
+        t.pr_number != null ? `#${t.pr_number}` : "-",
+    ]);
+    const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i]?.length ?? 0)));
+    const fmt = (cols) => "  " + cols.map((c, i) => c.padEnd(widths[i])).join("  ");
+    console.log(ansi.dim(fmt(header)));
+    for (const r of rows)
+        console.log(fmt(r));
+    console.log(ansi.dim("  open a chain:  chain <slug>   ·   or re-run on a TTY to pick"));
+}
+/** Interactive list of recently reviewed branches → open chain on select. */
+export async function cmdBranches(args = []) {
+    const asJson = args.includes("--json");
+    const nArg = args.find((a) => /^\d+$/.test(a));
+    const limit = nArg ? Number.parseInt(nArg, 10) : 20;
+    const cfg = await loadConfig();
+    const items = await listThreads(limit, cfg);
+    if (asJson) {
+        console.log(JSON.stringify({ items }, null, 2));
+        return;
+    }
+    if (items.length === 0) {
+        console.log(ansi.dim("  No reviewed branches yet. Run `review` on a branch first."));
+        return;
+    }
+    if (!input.isTTY || !output.isTTY) {
+        printBranchTable(items);
+        return;
+    }
+    const picked = await selectFromList({
+        title: "Recently reviewed branches",
+        items,
+        render: (item) => formatBranchRow(item),
+    });
+    if (!picked) {
+        console.log(ansi.dim("  cancelled"));
+        return;
+    }
+    await cmdThread(picked.slug, []);
+}
+/**
+ * Show the review-chain timeline for a branch/thread.
+ * Defaults to `local/<current-git-branch>` when no slug is given.
+ */
+export async function cmdChain(args = []) {
+    const asJson = args.includes("--json");
+    const positional = args.filter((a) => a !== "--json");
+    let slug = positional[0]?.trim() ?? "";
+    if (!slug) {
+        try {
+            const branch = git(["rev-parse", "--abbrev-ref", "HEAD"]).trim() || "local";
+            slug = `local/${branch}`.replace(/[^a-zA-Z0-9._/-]/g, "-").slice(0, 120);
+        }
+        catch {
+            throw new CommandError("usage: chain <slug>   (or run inside a git repo to use the current branch)");
+        }
+    }
+    await cmdThread(slug, asJson ? ["--json"] : []);
+}

package/dist/commands/credits.js

@@ -2,6 +2,7 @@ import { getMe } from "../api.js";
 import { loadConfig } from "../config.js";
 import { CommandError } from "../errors.js";
 import { ansi } from "../ui/ansi.js";
+import { formatResetLabel, usageBar } from "../ui/usage.js";
 export async function cmdCredits(args) {
     const asJson = args.includes("--json");
     const cfg = await loadConfig();
@@ -11,12 +12,17 @@ export async function cmdCredits(args) {
             "Try `mergestorm login` or open https://mergestorm.ai/billing");
     }
     if (asJson) {
-        console.log(JSON.stringify(me.usage, null, 2));
+        console.log(JSON.stringify({ usage: me.usage, resets_at: me.resets_at ?? null }, null, 2));
         return;
     }
     const s = me.usage.standard;
     const p = me.usage.premium;
-    console.log(`  Standard   ${s.used} used / ${s.limit}    (${s.remaining} remaining)`);
-    console.log(`  Premium     ${p.used} used / ${p.limit}     (${p.remaining} remaining)`);
-    console.log(ansi.dim("  Resets with your billing cycle · manage at https://mergestorm.ai/billing"));
+    // Claude Usage tab layout: label → long bar + "N% used" → Resets line.
+    console.log(`  ${ansi.bold("Standard")}`);
+    console.log(`  ${usageBar(s.used, s.limit)}`);
+    console.log("");
+    console.log(`  ${ansi.bold("Premium")}`);
+    console.log(`  ${usageBar(p.used, p.limit)}`);
+    console.log("");
+    console.log(`  ${ansi.dim(formatResetLabel(me.resets_at))}`);
 }

package/dist/commands/jobs.d.ts

@@ -1,2 +1,6 @@
+import { type ThreadDetail } from "../api.js";
+export declare function relativeWhen(iso: string): string;
 export declare function cmdJobs(args: string[]): Promise<void>;
+/** Numbered chain timeline for a thread (branch/PR meta when present). */
+export declare function formatThreadTimeline(data: ThreadDetail): string[];
 export declare function cmdThread(slug: string, args?: string[]): Promise<void>;

package/dist/commands/jobs.js

@@ -2,7 +2,7 @@ import { apiFetch, listJobs } from "../api.js";
 import { loadConfig } from "../config.js";
 import { CommandError } from "../errors.js";
 import { ansi } from "../ui/ansi.js";
-function relativeWhen(iso) {
+export function relativeWhen(iso) {
     const t = new Date(iso).getTime();
     if (Number.isNaN(t))
         return "—";
@@ -45,7 +45,37 @@ export async function cmdJobs(args) {
     console.log(ansi.dim(fmt(header)));
     for (const r of rows)
         console.log(fmt(r));
-    console.log(ansi.dim("  full history: https://mergestorm.ai/dashboard/api"));
+    console.log(ansi.dim("  branches: `branches` · full history: https://mergestorm.ai/dashboard/api"));
+}
+/** Numbered chain timeline for a thread (branch/PR meta when present). */
+export function formatThreadTimeline(data) {
+    const lines = [];
+    const title = data.branch?.trim()
+        ? `${data.branch}  (${data.slug})`
+        : data.slug;
+    lines.push(`  ${ansi.bold(title)} · ${data.job_count} job(s) · ${data.status}`);
+    if (data.owner && data.repo) {
+        const pr = data.pr_number != null
+            ? `https://github.com/${data.owner}/${data.repo}/pull/${data.pr_number}`
+            : `${data.owner}/${data.repo}`;
+        lines.push(`  ${ansi.dim(pr)}`);
+    }
+    const jobs = [...(data.jobs ?? [])].sort((a, b) => {
+        const an = a.thread_job_number ?? Infinity;
+        const bn = b.thread_job_number ?? Infinity;
+        if (an !== bn)
+            return an - bn;
+        return new Date(a.created_at).getTime() - new Date(b.created_at).getTime();
+    });
+    if (jobs.length === 0) {
+        lines.push(ansi.dim("  (no jobs in this chain yet)"));
+        return lines;
+    }
+    for (const j of jobs) {
+        const n = j.thread_job_number != null ? `#${j.thread_job_number}` : "#?";
+        lines.push(`  ${n.padEnd(4)}  ${j.job_id.slice(0, 8)}  ${(j.status ?? "-").padEnd(12)}  ${(j.verdict ?? "-").padEnd(16)}  ${relativeWhen(j.created_at)}`);
+    }
+    return lines;
 }
 export async function cmdThread(slug, args = []) {
     const asJson = args.includes("--json");
@@ -62,8 +92,16 @@ export async function cmdThread(slug, args = []) {
         return;
     }
     const data = body;
-    console.log(`  Thread ${ansi.bold(data.slug)} · ${data.job_count} job(s)`);
-    for (const j of data.jobs ?? []) {
-        console.log(`  ${j.job_id.slice(0, 8)}  ${j.status.padEnd(12)}  ${(j.verdict ?? "-").padEnd(16)}  ${relativeWhen(j.created_at)}`);
+    for (const line of formatThreadTimeline({
+        ...data,
+        branch: data.branch ?? null,
+        owner: data.owner ?? null,
+        repo: data.repo ?? null,
+        pr_number: data.pr_number ?? null,
+        status: data.status ?? "active",
+        pr_linked_at: data.pr_linked_at ?? null,
+        jobs: data.jobs ?? [],
+    })) {
+        console.log(line);
     }
 }

package/dist/commands/login.js

@@ -20,6 +20,8 @@ function openBrowser(url) {
     }
 }
 async function loginWithKey(existingRl) {
+    if (!existingRl)
+        input.resume();
     const rl = existingRl ?? createInterface({ input, output });
     const ownRl = !existingRl;
     try {

package/dist/commands/review.d.ts

@@ -3,4 +3,9 @@ export type ReviewOptions = {
     /** When true, show Ctrl+C detach hint during poll. */
     interactive?: boolean;
 };
+/** Parse `origin` remote into GitHub owner/repo when possible. */
+export declare function parseGithubOriginRepo(): {
+    owner: string;
+    repo: string;
+} | null;
 export declare function cmdReview(args: string[], opts?: ReviewOptions): Promise<void>;

package/dist/commands/review.js

@@ -3,6 +3,21 @@ import { loadConfig } from "../config.js";
 import { CommandError, DetachedError } from "../errors.js";
 import { collectChangedFiles, collectContextFiles, git } from "../git.js";
 import { ansi } from "../ui/ansi.js";
+/** Parse `origin` remote into GitHub owner/repo when possible. */
+export function parseGithubOriginRepo() {
+    try {
+        const url = git(["remote", "get-url", "origin"]).trim();
+        if (!url)
+            return null;
+        const m = url.match(/^(?:https?:\/\/|git@)?github\.com[:/]([A-Za-z0-9_-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?\/?$/i);
+        if (!m?.[1] || !m[2])
+            return null;
+        return { owner: m[1], repo: m[2] };
+    }
+    catch {
+        return null;
+    }
+}
 function sleep(ms, signal) {
     return new Promise((resolve, reject) => {
         if (signal?.aborted) {
@@ -32,11 +47,14 @@ export async function cmdReview(args, opts = {}) {
     const context_files = await collectContextFiles(process.cwd());
     const branch = git(["rev-parse", "--abbrev-ref", "HEAD"]).trim() || "local";
     const thread = `local/${branch}`.replace(/[^a-zA-Z0-9._/-]/g, "-").slice(0, 120);
+    const originRepo = parseGithubOriginRepo();
     console.log(`Submitting review (${Buffer.byteLength(diff, "utf8")} byte diff, ${files.length} file(s), ${context_files.length} context file(s))…`);
     const { status, body } = await apiFetch(cfg, "/api/v1/reviews", {
         method: "POST",
         json: {
             thread,
+            branch,
+            ...(originRepo ? { repo: `${originRepo.owner}/${originRepo.repo}` } : {}),
             base_label: base,
             head_label: head,
             diff,
@@ -90,9 +108,11 @@ export async function cmdReview(args, opts = {}) {
             if (opts.interactive && meBefore) {
                 const meAfter = await getMe(cfg);
                 if (meAfter) {
-                    const used = Math.max(0, meBefore.usage.standard.remaining - meAfter.usage.standard.remaining);
+                    const beforeLeft = meBefore.usage.standard.remaining ?? 0;
+                    const afterLeft = meAfter.usage.standard.remaining ?? 0;
+                    const used = Math.max(0, beforeLeft - afterLeft);
                     if (used > 0) {
-                        console.log(ansi.dim(`\n${used} credit${used === 1 ? "" : "s"} used · ${meAfter.usage.standard.remaining} remaining`));
+                        console.log(ansi.dim(`\n${used} credit${used === 1 ? "" : "s"} used · ${afterLeft} remaining`));
                     }
                 }
             }

package/dist/shell.d.ts

@@ -1 +1,8 @@
+import { type CommandSpec } from "./ui/prompt.js";
+export declare const COMMANDS: CommandSpec[];
+/** Strips an optional leading "/" so both "review" and "/review" work. */
+export declare function parseLine(line: string): {
+    cmd: string;
+    args: string[];
+} | null;
 export declare function runShell(): Promise<void>;