mergestorm 0.3.9 → 0.3.15

package/dist/commands/pr.d.ts

@@ -0,0 +1,22 @@
+import { type PollPrVortexReviewOptions } from "./review-client.js";
+export type ParsedPrArgs = {
+    owner: string;
+    repo: string;
+    prNumber: number;
+    format: "json" | "pretty";
+    wait: boolean;
+    afterSha?: string;
+    timeoutMs: number;
+};
+export type PrOptions = {
+    defaultFormat?: "json" | "pretty";
+    signal?: AbortSignal;
+    pollIntervalMs?: number;
+    /** Test seams for deterministic polling. */
+    poll?: Pick<PollPrVortexReviewOptions, "sleep" | "now" | "random">;
+    mode?: "oneshot" | "shell";
+};
+export declare function parsePrArgs(args: string[], defaults?: {
+    format: "json" | "pretty";
+}): ParsedPrArgs;
+export declare function cmdPr(args: string[], opts?: PrOptions): Promise<void>;

package/dist/commands/pr.js

@@ -0,0 +1,127 @@
+import { getPrVortexReview } from "../api.js";
+import { loadConfig } from "../config.js";
+import { CommandError, REVIEW_EXIT } from "../errors.js";
+import { ansi } from "../ui/ansi.js";
+import { renderFindings } from "../ui/findings.js";
+import { PrReviewPollTimeoutError, REVIEW_POLL_DEFAULT_TIMEOUT_MS, pollPrVortexReview, } from "./review-client.js";
+import { parseAdoptTarget } from "./stack.js";
+const PR_USAGE = "usage: mergestorm pr <owner/repo>#<n> [--json] [--wait] [--after-sha <sha>] [--timeout <s>]";
+function usageError(message = PR_USAGE) {
+    return new CommandError(message, REVIEW_EXIT.usage, "usage");
+}
+export function parsePrArgs(args, defaults = { format: "json" }) {
+    const target = [];
+    let format = defaults.format;
+    let wait = false;
+    let afterSha;
+    let timeoutMs = REVIEW_POLL_DEFAULT_TIMEOUT_MS;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--json") {
+            format = "json";
+            continue;
+        }
+        if (arg === "--pretty") {
+            format = "pretty";
+            continue;
+        }
+        if (arg === "--wait") {
+            wait = true;
+            continue;
+        }
+        if (arg === "--after-sha" || arg.startsWith("--after-sha=")) {
+            const value = arg === "--after-sha" ? args[++i] : arg.slice("--after-sha=".length);
+            if (!value?.trim())
+                throw usageError("--after-sha requires a non-empty SHA");
+            afterSha = value.trim();
+            if (afterSha.length < 7) {
+                throw usageError("--after-sha must be at least 7 characters");
+            }
+            if (!/^[0-9a-f]+$/i.test(afterSha)) {
+                throw usageError("--after-sha must contain only hexadecimal characters");
+            }
+            continue;
+        }
+        if (arg === "--timeout" || arg.startsWith("--timeout=")) {
+            const value = arg === "--timeout" ? args[++i] : arg.slice("--timeout=".length);
+            const seconds = Number(value);
+            if (!value || !Number.isFinite(seconds) || seconds <= 0) {
+                throw usageError("--timeout must be a positive number of seconds");
+            }
+            timeoutMs = Math.round(seconds * 1_000);
+            wait = true;
+            continue;
+        }
+        if (arg.startsWith("-"))
+            throw usageError(`unknown flag: ${arg}`);
+        target.push(arg);
+    }
+    if (afterSha && !wait)
+        throw usageError("--after-sha requires --wait");
+    if (target.length < 1 || target.length > 2)
+        throw usageError();
+    let parsed;
+    try {
+        parsed = parseAdoptTarget(target);
+    }
+    catch {
+        throw usageError();
+    }
+    return { ...parsed, format, wait, afterSha, timeoutMs };
+}
+function printPretty(envelope) {
+    console.log(`Status:        ${envelope.status}`);
+    if (envelope.verdict)
+        console.log(`Verdict:       ${ansi.bold(envelope.verdict)}`);
+    if (envelope.head_sha)
+        console.log(`Head:          ${envelope.head_sha}`);
+    console.log(`Finding count: ${envelope.finding_count}`);
+    if (envelope.skip_reason)
+        console.log(`Skip reason:   ${envelope.skip_reason}`);
+    if (envelope.summary)
+        console.log(envelope.summary);
+    renderFindings(envelope.findings, {
+        emptyMessage: envelope.status === "completed",
+    });
+}
+export async function cmdPr(args, opts = {}) {
+    const parsed = parsePrArgs(args, {
+        format: opts.defaultFormat ?? "json",
+    });
+    const cfg = await loadConfig();
+    let envelope;
+    if (parsed.wait) {
+        try {
+            envelope = await pollPrVortexReview(cfg, parsed.owner, parsed.repo, parsed.prNumber, {
+                timeoutMs: parsed.timeoutMs,
+                intervalMs: opts.pollIntervalMs,
+                afterSha: parsed.afterSha,
+                signal: opts.signal,
+                ...opts.poll,
+                onTick(kind) {
+                    if (parsed.format === "json")
+                        console.error(kind === "retry" ? "?" : ".");
+                    else
+                        process.stdout.write(kind === "retry" ? "?" : ".");
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof PrReviewPollTimeoutError) {
+                throw new CommandError(err.message, REVIEW_EXIT.timeout, "review_timeout");
+            }
+            throw err;
+        }
+        if (parsed.format === "pretty")
+            console.log("");
+    }
+    else {
+        envelope = await getPrVortexReview(parsed.owner, parsed.repo, parsed.prNumber, cfg, { signal: opts.signal });
+    }
+    if (parsed.format === "json") {
+        console.log(JSON.stringify(envelope, null, opts.mode === "shell" ? 2 : undefined));
+    }
+    else {
+        printPretty(envelope);
+    }
+}

package/dist/commands/queue.d.ts

@@ -0,0 +1,12 @@
+import { type MergeQueueEntryDto } from "../api.js";
+import { runLineTabsBrowser } from "../ui/line-tabs.js";
+/** Injectable seams for unit tests. Production callers omit deps. */
+export type QueueCmdDeps = {
+    canBrowse?: () => boolean;
+    runLineTabsBrowser?: typeof runLineTabsBrowser;
+};
+export declare const QUEUE_USAGE = "usage:\n  mergestorm queue [list] [--json]\n  mergestorm queue add <stack-id> [--json]\n  mergestorm queue rm <entry-id|stack-id> [--json]\n\n  queue lists your live merge-queue entries. rm prefers an entry id; a live\n  stack id is resolved to its queue entry before cancellation.";
+/** Entry ids win; otherwise a live stack id resolves to its entry id. */
+export declare function resolveQueueEntryId(idOrStackId: string, entries: readonly MergeQueueEntryDto[]): string;
+export declare function buildQueueListLines(entries: readonly MergeQueueEntryDto[], fullStackId?: boolean): string[];
+export declare function cmdQueue(args: string[], deps?: QueueCmdDeps): Promise<void>;

package/dist/commands/queue.js

@@ -0,0 +1,160 @@
+import { cancelMergeQueueEntry, enqueueStack, listMergeQueueEntries, } from "../api.js";
+import { loadConfig } from "../config.js";
+import { CommandError } from "../errors.js";
+import { ansi } from "../ui/ansi.js";
+import { runLineTabsBrowser } from "../ui/line-tabs.js";
+import { present } from "../ui/present.js";
+import { visibleWidth } from "../ui/width.js";
+import { canBrowse } from "./browse.js";
+const QUEUE_STATE_GLYPHS = {
+    queued: "○",
+    running: "●",
+    waiting: "◐",
+    bounced: "×",
+    landed: "✓",
+    cancelled: "·",
+};
+function queueStateGlyph(state) {
+    return QUEUE_STATE_GLYPHS[state] ?? "·";
+}
+function colorQueueGlyph(state, glyph) {
+    if (state === "running")
+        return ansi.brightGreen(glyph);
+    if (state === "waiting")
+        return ansi.yellow(glyph);
+    if (state === "bounced")
+        return ansi.red(glyph);
+    return ansi.dim(glyph);
+}
+export const QUEUE_USAGE = `usage:
+  mergestorm queue [list] [--json]
+  mergestorm queue add <stack-id> [--json]
+  mergestorm queue rm <entry-id|stack-id> [--json]
+
+  queue lists your live merge-queue entries. rm prefers an entry id; a live
+  stack id is resolved to its queue entry before cancellation.`;
+function positionalArgs(args) {
+    const unknown = args.filter((arg) => arg.startsWith("-") &&
+        arg !== "--json" &&
+        arg !== "-h" &&
+        arg !== "--help");
+    if (unknown.length > 0) {
+        throw new CommandError(`unknown queue option: ${unknown[0]}`, 2, "usage");
+    }
+    return args.filter((arg) => arg !== "--json");
+}
+function requireIdentifier(value, usage) {
+    const id = value?.trim();
+    if (!id)
+        throw new CommandError(usage, 2, "usage");
+    return id;
+}
+/** Entry ids win; otherwise a live stack id resolves to its entry id. */
+export function resolveQueueEntryId(idOrStackId, entries) {
+    const entry = entries.find((candidate) => candidate.id === idOrStackId);
+    if (entry)
+        return entry.id;
+    const stackEntry = entries.find((candidate) => candidate.stackId === idOrStackId);
+    return stackEntry?.id ?? idOrStackId;
+}
+export function buildQueueListLines(entries, fullStackId = false) {
+    if (entries.length === 0) {
+        return [
+            `  ${ansi.bold("Nothing queued")}`,
+            "",
+            `  ${ansi.brightGreen("queue add <stack-id>")}  send a stack for verified landing`,
+        ];
+    }
+    return entries.map((entry) => {
+        const reason = entry.waitReason ?? entry.bounceReason;
+        const glyph = colorQueueGlyph(entry.state, queueStateGlyph(entry.state));
+        const id = fullStackId ? entry.stackId : entry.stackId.slice(0, 8);
+        const core = `  ${String(entry.position).padStart(2)}  ` +
+            `${glyph} ${entry.state.padEnd(8)}  ${entry.owner}/${entry.repo}  ${id}` +
+            (reason ? `  ${reason}` : "");
+        const who = entry.enqueuedBy === "human" || entry.enqueuedBy === "agent"
+            ? `  by ${entry.enqueuedBy}`
+            : "";
+        const withWho = `${core}${who}`;
+        return visibleWidth(withWho) <= 75 ? withWho : core;
+    });
+}
+async function listQueue(asJson, deps = {}) {
+    const cfg = await loadConfig();
+    const entries = await listMergeQueueEntries(cfg);
+    if (asJson) {
+        console.log(JSON.stringify({ entries }, null, 2));
+        return;
+    }
+    const browse = deps.canBrowse ?? canBrowse;
+    const browseable = browse();
+    const lines = buildQueueListLines(entries, !browseable);
+    if (browseable) {
+        const runBrowser = deps.runLineTabsBrowser ?? runLineTabsBrowser;
+        await runBrowser({
+            tabs: [{ id: "queue", label: "Queue", lines }],
+        });
+        return;
+    }
+    await present("Merge queue", lines);
+}
+async function addQueue(args, asJson) {
+    const id = requireIdentifier(args[0], "usage: mergestorm queue add <stack-id> [--json]");
+    if (args.length > 1) {
+        throw new CommandError("usage: mergestorm queue add <stack-id> [--json]", 2, "usage");
+    }
+    const cfg = await loadConfig();
+    const body = await enqueueStack(id, cfg);
+    if (asJson) {
+        console.log(JSON.stringify(body, null, 2));
+        return;
+    }
+    const entry = body?.entry;
+    const duplicate = body?.duplicate === true;
+    await present("Merge queue", [
+        ansi.brightGreen(`  ${duplicate ? "Already queued" : "Queued"} ${id}` +
+            (entry?.position ? ` at position ${entry.position}` : "")),
+    ]);
+}
+async function removeQueue(args, asJson) {
+    const requested = requireIdentifier(args[0], "usage: mergestorm queue rm <entry-id|stack-id> [--json]");
+    if (args.length > 1) {
+        throw new CommandError("usage: mergestorm queue rm <entry-id|stack-id> [--json]", 2, "usage");
+    }
+    const cfg = await loadConfig();
+    const entries = await listMergeQueueEntries(cfg);
+    const entryId = resolveQueueEntryId(requested, entries);
+    const body = await cancelMergeQueueEntry(entryId, cfg);
+    if (asJson) {
+        console.log(JSON.stringify(body, null, 2));
+        return;
+    }
+    await present("Merge queue", [
+        ansi.brightGreen(`  Removed ${entryId} from the merge queue`),
+    ]);
+}
+export async function cmdQueue(args, deps = {}) {
+    const asJson = args.includes("--json");
+    const positional = positionalArgs(args);
+    const sub = positional[0]?.toLowerCase();
+    if (sub === "-h" || sub === "--help" || sub === "help") {
+        console.log(QUEUE_USAGE);
+        return;
+    }
+    if (!sub || sub === "list" || sub === "ls") {
+        if (positional.length > (sub ? 1 : 0)) {
+            throw new CommandError(QUEUE_USAGE, 2, "usage");
+        }
+        await listQueue(asJson, deps);
+        return;
+    }
+    if (sub === "add") {
+        await addQueue(positional.slice(1), asJson);
+        return;
+    }
+    if (sub === "rm" || sub === "remove") {
+        await removeQueue(positional.slice(1), asJson);
+        return;
+    }
+    throw new CommandError(`${QUEUE_USAGE}\nunknown queue subcommand: ${sub}`);
+}

package/dist/commands/registry.d.ts

@@ -22,7 +22,7 @@ export type RegistryCommand = {
  */
 export declare const COMMAND_REGISTRY: RegistryCommand[];
 export declare function findCommand(name: string): RegistryCommand | undefined;
-/** Autocomplete / `/help` list for the interactive shell. */
+/** Autocomplete / `/help` list for the interactive shell. Aliases fold onto the primary name. */
 export declare function shellCommandSpecs(): CommandSpec[];
 export declare function formatUsageBody(): string;
 /**

package/dist/commands/registry.js

@@ -1,11 +1,16 @@
 import { DEFAULT_API } from "../config.js";
 import { CommandError } from "../errors.js";
 import { cmdBranches, cmdChain } from "./branches.js";
+import { canBrowse, openTabsBrowser } from "./browse.js";
 import { cmdCredits } from "./credits.js";
 import { cmdJobs, cmdThread } from "./jobs.js";
 import { cmdLogin } from "./login.js";
 import { cmdLogout } from "./logout.js";
+import { cmdQueue } from "./queue.js";
+import { cmdPr } from "./pr.js";
 import { cmdReview } from "./review.js";
+import { cmdSettings } from "./settings.js";
+import { cmdSkill } from "./skill.js";
 import { cmdStack } from "./stack.js";
 import { cmdStatus } from "./status.js";
 import { cmdWhoami } from "./whoami.js";
@@ -41,7 +46,12 @@ export const COMMAND_REGISTRY = [
         name: "review",
         summary: "Review git diff (default origin/HEAD or main or master)",
         usage: [
-            "mergestorm review [base] [head] Review git diff base...head (default: origin/HEAD or main or master)",
+            "mergestorm review [base] [head] Review git diff base...head",
+            "  [--json] [--wait|--no-wait] [--timeout seconds]",
+            "  [--router off|standard|max|manual] [--specialists id,id]",
+            "  [--context text] [--context-file path] [--thread slug]",
+            "  [--idempotency-key k] [--webhook-url https://…]",
+            "  HTTP 429 exits 7 (rate_limited) with retry_after_seconds",
         ],
         async run(args, ctx) {
             if (ctx.mode === "shell") {
@@ -51,30 +61,56 @@ export const COMMAND_REGISTRY = [
             await cmdReview(args);
         },
     },
+    {
+        name: "pr",
+        summary: "Latest Vortex review for a GitHub PR",
+        usage: [
+            "mergestorm pr <owner/repo>#<n>  Fetch the latest Vortex PR review",
+            "  [--json] [--wait] [--after-sha <sha>] [--timeout <s>]",
+            "  Also accepts: mergestorm pr <owner/repo> <n>",
+        ],
+        async run(args, ctx) {
+            await cmdPr(args, {
+                defaultFormat: ctx.mode === "shell" ? "pretty" : "json",
+                signal: ctx.signal,
+                mode: ctx.mode,
+            });
+        },
+    },
     {
         name: "status",
-        summary: "Show a review job",
+        summary: "Job panel (id) or Status / Usage / Jobs tabs",
         usage: [
-            "mergestorm status <job_id>      Fetch a review job and print JSON (one shot)",
+            "mergestorm status <job_id>      Fetch a review job (same envelope as review --json)",
+            "  [--json] [--wait] [--timeout seconds]",
+            "  HTTP 429 exits 7 (rate_limited) with retry_after_seconds",
+            "  With no job id on a TTY: tabbed Status / Usage / Jobs / Config browser",
         ],
         async run(args, ctx) {
-            if (!args[0]) {
-                throw new CommandError(ctx.mode === "shell"
-                    ? "usage: status <job_id>"
-                    : "usage: mergestorm status <job_id>");
+            if (args.length === 0 && canBrowse()) {
+                await openTabsBrowser("status");
+                return;
             }
             if (ctx.mode === "shell") {
-                await cmdStatus(args[0], { format: "pretty", signal: ctx.signal });
+                await cmdStatus(args, {
+                    defaultFormat: "pretty",
+                    signal: ctx.signal,
+                    interactive: true,
+                    mode: "shell",
+                });
                 return;
             }
-            await cmdStatus(args[0], { format: "json" });
+            await cmdStatus(args, { defaultFormat: "json" });
         },
     },
     {
         name: "credits",
         aliases: ["usage"],
-        summary: "Credit balance with usage bars",
-        usage: ["mergestorm credits [--json]     Credit balance (usage bars)"],
+        summary: "Usage: tabbed browser (TTY) or static panel",
+        usage: [
+            "mergestorm credits [--json]     Usage panel (bar + last 5 jobs)",
+            "  On a TTY: tabbed Status / Usage / Jobs / Config browser (Usage selected)",
+        ],
         async run(args) {
             await cmdCredits(args);
         },
@@ -83,8 +119,14 @@ export const COMMAND_REGISTRY = [
         name: "jobs",
         summary: "Recent review jobs (default 10)",
         usage: ["mergestorm jobs [n] [--json]    Recent review jobs"],
-        async run(args) {
-            await cmdJobs(args);
+        async run(args, ctx) {
+            if (args.every((a) => a !== "--json") &&
+                !args.some((a) => /^\d+$/.test(a)) &&
+                canBrowse()) {
+                await openTabsBrowser("jobs");
+                return;
+            }
+            await cmdJobs(args, { mode: ctx.mode });
         },
     },
     {
@@ -92,26 +134,51 @@ export const COMMAND_REGISTRY = [
         aliases: ["chains"],
         summary: "Pick a recently reviewed branch",
         usage: ["mergestorm branches [n]         Recently reviewed branches (pick on TTY)"],
-        async run(args) {
-            await cmdBranches(args);
+        async run(args, ctx) {
+            await cmdBranches(args, { mode: ctx.mode });
         },
     },
     {
         name: "chain",
-        summary: "Show a branch review-chain timeline",
+        summary: "Branch review-chain timeline (holds until q)",
         usage: [
             "mergestorm chain [slug]         Branch review-chain timeline (default: current)",
         ],
-        async run(args) {
-            await cmdChain(args);
+        async run(args, ctx) {
+            await cmdChain(args, { mode: ctx.mode });
         },
     },
     {
         name: "whoami",
-        summary: "Key + plan + API base",
+        summary: "Key + plan (Status tab on a TTY)",
         usage: ["mergestorm whoami [--json]      Key + plan + API base"],
+        async run(args, ctx) {
+            await cmdWhoami(args, { mode: ctx.mode });
+        },
+    },
+    {
+        name: "settings",
+        summary: "Automation toggles (Config tab on a TTY)",
+        usage: [
+            "mergestorm settings [--json]    Read the automation toggles (Config tab on a TTY)",
+            "  [--auto-review on|off] [--auto-patch on|off] [--vortex-thinking on|off]",
+            "  [--repo-overview on|off] [--review-unit-land on|off]",
+            "  [--cyclone-review-unit-land on|off] [--vortex-seam on|off]",
+            "  With flags: PATCH those settings and print the stored result",
+        ],
+        async run(args, ctx) {
+            await cmdSettings(args, { mode: ctx.mode });
+        },
+    },
+    {
+        name: "skill",
+        summary: "Install mergestorm-review and mergestorm-pr-loop for Claude or Cursor",
+        usage: [
+            "mergestorm skill install --claude|--cursor  Copy the mergestorm-review and mergestorm-pr-loop skills into this repo",
+            "  [--json]",
+        ],
         async run(args) {
-            await cmdWhoami(args);
+            await cmdSkill(args);
         },
     },
     {
@@ -124,21 +191,32 @@ export const COMMAND_REGISTRY = [
                     ? "usage: thread <slug>"
                     : "usage: mergestorm thread <slug>");
             }
-            await cmdThread(args[0], args.slice(1));
+            await cmdThread(args[0], args.slice(1), { mode: ctx.mode });
+        },
+    },
+    {
+        name: "queue",
+        summary: "Merge queue: list, add a stack, or remove an entry",
+        usage: [
+            "mergestorm queue [list] [--json]  List live merge-queue entries",
+            "mergestorm queue add <stack-id> [--json]  Queue a stack for verified landing",
+            "mergestorm queue rm <entry-id|stack-id> [--json]  Remove a live queue entry",
+        ],
+        async run(args) {
+            await cmdQueue(args);
         },
     },
     {
         name: "stack",
-        summary: "Stacks: create, submit, list, adopt, restack, land",
+        summary: "Stacks: /stack how-to, list yours, create → submit",
         usage: [
-            "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 create [name]  New local stack layer ([--onto] [--trunk] [--extend])",
+            "mergestorm stack submit         Push active local stack, open PRs ([--extend])",
             "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",
         ],
         async run(args) {
             await cmdStack(args);
@@ -157,7 +235,7 @@ export const COMMAND_REGISTRY = [
 ];
 /** Shell meta commands (not dispatched via {@link COMMAND_REGISTRY}). */
 const SHELL_META = [
-    { name: "help", summary: "Show available commands" },
+    { name: "help", summary: "Tabbed help (Start / Commands / Stacks)" },
     { name: "clear", summary: "Clear screen and reprint banner" },
     { name: "exit", summary: "Leave the shell" },
     { name: "quit", summary: "Leave the shell" },
@@ -168,18 +246,22 @@ export function findCommand(name) {
     const key = name.toLowerCase();
     return COMMAND_REGISTRY.find((c) => c.name === key || (c.aliases?.includes(key) ?? false));
 }
-/** Autocomplete / `/help` list for the interactive shell. */
+/** Autocomplete / `/help` list for the interactive shell. Aliases fold onto the primary name. */
 export function shellCommandSpecs() {
-    const specs = [{ name: "help", summary: SHELL_META[0].summary }];
+    const specs = [
+        { name: "help", summary: SHELL_META[0].summary },
+        { name: "exit", summary: SHELL_META[2].summary, aliases: ["quit"] },
+    ];
     for (const c of COMMAND_REGISTRY) {
         if (SHELL_OMIT.has(c.name))
             continue;
-        specs.push({ name: c.name, summary: c.summary });
-        for (const alias of c.aliases ?? []) {
-            specs.push({ name: alias, summary: c.summary });
-        }
+        specs.push({
+            name: c.name,
+            summary: c.summary,
+            ...(c.aliases?.length ? { aliases: c.aliases } : {}),
+        });
     }
-    specs.push({ name: "clear", summary: SHELL_META[1].summary }, { name: "exit", summary: SHELL_META[2].summary }, { name: "quit", summary: SHELL_META[3].summary });
+    specs.push({ name: "clear", summary: SHELL_META[1].summary });
     return specs;
 }
 export function formatUsageBody() {