mergestorm 0.3.9 → 0.3.15

package/dist/commands/status.d.ts

@@ -1,5 +1,21 @@
+export type ParsedStatusArgs = {
+    jobId: string;
+    format: "json" | "pretty";
+    wait: boolean;
+    timeoutMs: number;
+};
 export type StatusOptions = {
-    format?: "json" | "pretty";
+    /** Oneshot defaults to json; the shell defaults to pretty. */
+    defaultFormat?: "json" | "pretty";
     signal?: AbortSignal;
+    /** When true, Ctrl+C / per-request timeout detaches instead of exiting 5. */
+    interactive?: boolean;
+    /** Test seam; production uses the two-second poll interval. */
+    pollIntervalMs?: number;
+    /** Shell: route --json through the hold-to-read panel instead of console.log. */
+    mode?: "oneshot" | "shell";
 };
-export declare function cmdStatus(jobId: string, opts?: StatusOptions): Promise<void>;
+export declare function parseStatusArgs(args: string[], defaults?: {
+    format: "json" | "pretty";
+}): ParsedStatusArgs;
+export declare function cmdStatus(args: string[], opts?: StatusOptions): Promise<void>;

package/dist/commands/status.js

@@ -1,28 +1,243 @@
-import { apiFetch } from "../api.js";
+import { getReview } from "../api.js";
 import { loadConfig } from "../config.js";
-import { CommandError } from "../errors.js";
+import { showLinePanel } from "../ui/line-tabs.js";
+import { canBrowse, formatJobDetailLines } from "./browse.js";
+import { CommandError, DetachedError, REVIEW_EXIT, isCommandErrorCode, } from "../errors.js";
 import { ansi } from "../ui/ansi.js";
 import { renderFindings } from "../ui/findings.js";
-export async function cmdStatus(jobId, opts = {}) {
-    const format = opts.format ?? "json";
-    const cfg = await loadConfig();
-    const { status, body } = await apiFetch(cfg, `/api/v1/reviews/${jobId}`, {
-        signal: opts.signal,
-    });
-    if (status !== 200) {
-        throw new CommandError(JSON.stringify(body, null, 2));
+import { toReviewJobEnvelope, } from "../ui/job-envelope.js";
+import { REVIEW_POLL_DEFAULT_TIMEOUT_MS, ReviewPollTimeoutError, pollReview, } from "./review-client.js";
+const STATUS_USAGE = "usage: mergestorm status <job_id> [--json] [--wait] [--timeout seconds]";
+function usageError(message = STATUS_USAGE) {
+    return new CommandError(message, REVIEW_EXIT.usage, "usage");
+}
+export function parseStatusArgs(args, defaults = { format: "json" }) {
+    let jobId;
+    let format = defaults.format;
+    let wait = false;
+    let timeoutMs = REVIEW_POLL_DEFAULT_TIMEOUT_MS;
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (a === "--json") {
+            format = "json";
+            continue;
+        }
+        if (a === "--pretty") {
+            format = "pretty";
+            continue;
+        }
+        if (a === "--wait") {
+            wait = true;
+            continue;
+        }
+        if (a === "--no-wait") {
+            wait = false;
+            continue;
+        }
+        if (a === "--timeout" || a.startsWith("--timeout=")) {
+            const value = a === "--timeout" ? args[++i] : a.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 (a.startsWith("-")) {
+            throw usageError(`unknown flag: ${a}`);
+        }
+        if (jobId)
+            throw usageError();
+        jobId = a;
+    }
+    if (!jobId)
+        throw usageError();
+    return { jobId, format, wait, timeoutMs };
+}
+function printPretty(row) {
+    const envelope = toReviewJobEnvelope(row);
+    console.log(`Status:  ${envelope.status}`);
+    if (envelope.verdict)
+        console.log(`Verdict: ${ansi.bold(envelope.verdict)}`);
+    if (envelope.router_mode)
+        console.log(`Router:  ${envelope.router_mode}`);
+    if (envelope.specialists_requested.length > 0) {
+        console.log(`Requested: ${envelope.specialists_requested.join(", ")}`);
+    }
+    if (envelope.specialists_run.length > 0) {
+        console.log(`Run:       ${envelope.specialists_run.join(", ")}`);
+    }
+    if (envelope.credits) {
+        console.log(`Credits:   ${envelope.credits.standard} standard`);
     }
-    if (format === "json") {
-        console.log(JSON.stringify(body, null, 2));
+    if (envelope.summary)
+        console.log(envelope.summary);
+    if (envelope.error)
+        console.log(ansi.red(`Error: ${envelope.error}`));
+    renderFindings(envelope.findings, {
+        emptyMessage: envelope.status === "completed",
+    });
+}
+async function showPretty(row) {
+    if (canBrowse()) {
+        await showLinePanel("Job", formatJobDetailLines(row));
         return;
     }
-    const row = body;
-    console.log(`Status:  ${row.status}`);
-    if (row.verdict)
-        console.log(`Verdict: ${ansi.bold(row.verdict)}`);
-    if (row.summary)
-        console.log(row.summary);
-    if (row.error)
-        console.log(ansi.red(`Error: ${row.error}`));
-    renderFindings(row.findings, { emptyMessage: row.status === "completed" });
+    printPretty(row);
+}
+export async function cmdStatus(args, opts = {}) {
+    const parsed = parseStatusArgs(args, {
+        format: opts.defaultFormat ?? "json",
+    });
+    const json = parsed.format === "json";
+    const interactive = Boolean(opts.interactive && !json);
+    const fallback = { jobId: parsed.jobId };
+    let jsonPrinted = false;
+    const printJson = async (row, extra = {}) => {
+        const text = JSON.stringify(toReviewJobEnvelope(row, { ...fallback, ...extra }), null, opts.mode === "shell" ? 2 : undefined);
+        if (opts.mode === "shell") {
+            await showLinePanel("Job", text.split("\n"));
+        }
+        else {
+            console.log(text);
+        }
+        jsonPrinted = true;
+    };
+    try {
+        const cfg = await loadConfig();
+        if (!parsed.wait) {
+            let body;
+            try {
+                body = await getReview(parsed.jobId, cfg, { signal: opts.signal });
+            }
+            catch (err) {
+                if (err instanceof CommandError &&
+                    (err.code === "auth_invalid" || err.code === "missing_api_key")) {
+                    throw err;
+                }
+                if (err instanceof Error && err.name === "AbortError")
+                    throw err;
+                if (isCommandErrorCode(err, "api_timeout")) {
+                    if (json)
+                        await printJson(null, { status: "in_progress", error: err.message });
+                    throw new CommandError(err.message, REVIEW_EXIT.timeout, "review_timeout");
+                }
+                if (isCommandErrorCode(err, "rate_limited")) {
+                    if (json) {
+                        await printJson(null, {
+                            status: "rate_limited",
+                            error: err.message,
+                            retryAfterSeconds: err.retryAfterSeconds,
+                        });
+                    }
+                    else {
+                        console.log(`Status:  rate_limited`);
+                        console.log(err.message);
+                    }
+                    throw err;
+                }
+                throw new CommandError(err instanceof Error ? err.message : String(err), REVIEW_EXIT.failed, "review_failed");
+            }
+            const row = body && typeof body === "object"
+                ? { ...body, job_id: parsed.jobId }
+                : { job_id: parsed.jobId, status: "failed", error: "Invalid review response" };
+            if (row.status === "failed" || row.status === "quota_exceeded") {
+                if (json)
+                    await printJson(row);
+                else
+                    await showPretty(row);
+                throw new CommandError(`Review ${row.status}: ${row.error ?? ""}`, row.status === "quota_exceeded" ? REVIEW_EXIT.quota : REVIEW_EXIT.failed, row.status === "quota_exceeded" ? "review_quota" : "review_failed");
+            }
+            if (json)
+                await printJson(row);
+            else
+                await showPretty(row);
+            return;
+        }
+        if (!json) {
+            const waitHint = interactive
+                ? ` Waiting… (${ansi.dim("ctrl+c to detach — job keeps running")})`
+                : " Waiting…";
+            console.log(`Job ${parsed.jobId}.${waitHint}`);
+        }
+        let row;
+        try {
+            row = await pollReview(cfg, parsed.jobId, {
+                timeoutMs: parsed.timeoutMs,
+                intervalMs: opts.pollIntervalMs,
+                signal: opts.signal,
+                propagateTimeout: interactive,
+                onTick(kind) {
+                    if (json)
+                        console.error(kind === "retry" ? "?" : ".");
+                    else
+                        process.stdout.write(kind === "retry" ? "?" : ".");
+                },
+            });
+        }
+        catch (err) {
+            if (opts.interactive && err instanceof Error && err.name === "AbortError") {
+                throw new DetachedError(parsed.jobId);
+            }
+            if (interactive && isCommandErrorCode(err, "api_timeout")) {
+                throw new DetachedError(parsed.jobId);
+            }
+            if (err instanceof ReviewPollTimeoutError) {
+                const message = `Timed out waiting for review ${parsed.jobId}`;
+                if (json) {
+                    await printJson(err.lastRow, {
+                        jobId: parsed.jobId,
+                        status: err.lastRow.status ?? "in_progress",
+                        error: "Timed out waiting for review.",
+                    });
+                }
+                throw new CommandError(message, REVIEW_EXIT.timeout, "review_timeout");
+            }
+            if (isCommandErrorCode(err, "rate_limited")) {
+                if (json) {
+                    await printJson(null, {
+                        status: "rate_limited",
+                        error: err.message,
+                        retryAfterSeconds: err.retryAfterSeconds,
+                    });
+                }
+                else {
+                    console.log(`Status:  rate_limited`);
+                    console.log(err.message);
+                }
+                throw err;
+            }
+            throw err;
+        }
+        if (!json)
+            console.log("");
+        if (row.status === "failed" || row.status === "quota_exceeded") {
+            const message = `Review ${row.status}: ${row.error ?? ""}`;
+            if (json)
+                await printJson(row);
+            else
+                await showPretty(row);
+            throw new CommandError(message, row.status === "quota_exceeded" ? REVIEW_EXIT.quota : REVIEW_EXIT.failed, row.status === "quota_exceeded" ? "review_quota" : "review_failed");
+        }
+        if (json)
+            await printJson(row);
+        else
+            await showPretty(row);
+    }
+    catch (err) {
+        if (err instanceof DetachedError)
+            throw err;
+        if (json &&
+            !jsonPrinted &&
+            !(err instanceof Error && err.name === "AbortError")) {
+            const message = err instanceof Error ? err.message : String(err);
+            await printJson(null, { status: "failed", error: message });
+        }
+        if (err instanceof CommandError &&
+            (err.code === "auth_invalid" || err.code === "missing_api_key")) {
+            throw new CommandError(err.message, REVIEW_EXIT.auth, err.code);
+        }
+        throw err;
+    }
 }

package/dist/commands/whoami.d.ts

@@ -1 +1,3 @@
-export declare function cmdWhoami(args: string[]): Promise<void>;
+export declare function cmdWhoami(args: string[], opts?: {
+    mode?: "oneshot" | "shell";
+}): Promise<void>;

package/dist/commands/whoami.js

@@ -2,13 +2,19 @@ import { getMe } from "../api.js";
 import { apiBase, configPath, loadConfig, resolveApiKey, keyDisplay } from "../config.js";
 import { CommandError } from "../errors.js";
 import { ansi } from "../ui/ansi.js";
-export async function cmdWhoami(args) {
+import { present } from "../ui/present.js";
+import { canBrowse, openTabsBrowser } from "./browse.js";
+export async function cmdWhoami(args, opts = {}) {
     const asJson = args.includes("--json");
     const cfg = await loadConfig();
     const key = resolveApiKey(cfg);
     if (!key) {
         throw new CommandError("Not logged in. Run `mergestorm login`.");
     }
+    if (!asJson && canBrowse()) {
+        await openTabsBrowser("status");
+        return;
+    }
     const me = await getMe(cfg);
     const payload = {
         key_prefix: me?.key.prefix ?? keyDisplay(key),
@@ -20,16 +26,24 @@ export async function cmdWhoami(args) {
         usage: me?.usage ?? null,
     };
     if (asJson) {
-        console.log(JSON.stringify(payload, null, 2));
+        const text = JSON.stringify(payload, null, 2);
+        if (opts.mode === "shell") {
+            await present("Account", text.split("\n"));
+            return;
+        }
+        console.log(text);
         return;
     }
-    console.log(`  Key      ${ansi.bold(String(payload.key_prefix))}${payload.key_name ? ` (${payload.key_name})` : ""}`);
+    const lines = [
+        `  Key      ${ansi.bold(String(payload.key_prefix))}${payload.key_name ? ` (${payload.key_name})` : ""}`,
+    ];
     if (payload.plan_key) {
-        console.log(`  Plan     ${payload.plan_label_key ?? payload.plan_key}`);
+        lines.push(`  Plan     ${payload.plan_label_key ?? payload.plan_key}`);
     }
-    console.log(`  API      ${payload.api_base}`);
-    console.log(`  Config   ${payload.config_path}`);
+    lines.push(`  API      ${payload.api_base}`);
+    lines.push(`  Config   ${payload.config_path}`);
     if (!me) {
-        console.log(ansi.dim("  (live account details unavailable — older API or offline)"));
+        lines.push(ansi.dim("  (live account details unavailable — older API or offline)"));
     }
+    await present("Account", lines);
 }

package/dist/errors.d.ts

@@ -2,13 +2,29 @@
  * Stable machine codes for CommandError control flow.
  * UX copy in `message` may change freely; match on `code`, never on message text.
  */
-export type CommandErrorCode = "auth_invalid" | "api_timeout" | "not_a_repo" | "missing_api_key";
+export type CommandErrorCode = "auth_invalid" | "api_timeout" | "not_a_repo" | "not_found" | "missing_api_key" | "registered_parent" | "usage" | "review_quota" | "review_failed" | "review_timeout" | "rate_limited";
+/** Stable one-shot exit codes for machine callers of `mergestorm review`. */
+export declare const REVIEW_EXIT: {
+    readonly success: 0;
+    readonly usage: 2;
+    readonly quota: 3;
+    readonly failed: 4;
+    readonly timeout: 5;
+    readonly auth: 6;
+    readonly rate_limited: 7;
+};
+export type CommandErrorExtras = {
+    retryAfterSeconds?: number;
+};
 /** Thrown by command handlers; one-shot mode maps `exitCode` onto process.exitCode. */
 export declare class CommandError extends Error {
     readonly exitCode: number;
     readonly code?: CommandErrorCode;
-    constructor(message: string, exitCode?: number, code?: CommandErrorCode);
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, exitCode?: number, code?: CommandErrorCode, extras?: CommandErrorExtras);
 }
+export declare const RATE_LIMITED_HINT = "Rate limited. Wait for a running review or mergestorm jobs.";
+export declare function rateLimitedMessage(retryAfterSeconds?: number): string;
 export declare function isCommandErrorCode(err: unknown, code: CommandErrorCode): err is CommandError;
 /** Review/status poll aborted by Ctrl+C — shell returns to the prompt. */
 export declare class DetachedError extends Error {

package/dist/errors.js

@@ -1,14 +1,35 @@
+/** Stable one-shot exit codes for machine callers of `mergestorm review`. */
+export const REVIEW_EXIT = {
+    success: 0,
+    usage: 2,
+    quota: 3,
+    failed: 4,
+    timeout: 5,
+    auth: 6,
+    rate_limited: 7,
+};
 /** Thrown by command handlers; one-shot mode maps `exitCode` onto process.exitCode. */
 export class CommandError extends Error {
     exitCode;
     code;
-    constructor(message, exitCode = 1, code) {
+    retryAfterSeconds;
+    constructor(message, exitCode = 1, code, extras) {
         super(message);
         this.name = "CommandError";
         this.exitCode = exitCode;
         this.code = code;
+        if (extras?.retryAfterSeconds !== undefined) {
+            this.retryAfterSeconds = extras.retryAfterSeconds;
+        }
     }
 }
+export const RATE_LIMITED_HINT = "Rate limited. Wait for a running review or mergestorm jobs.";
+export function rateLimitedMessage(retryAfterSeconds) {
+    if (retryAfterSeconds == null || !Number.isFinite(retryAfterSeconds)) {
+        return RATE_LIMITED_HINT;
+    }
+    return `${RATE_LIMITED_HINT} Retry after ${Math.ceil(retryAfterSeconds)}s.`;
+}
 export function isCommandErrorCode(err, code) {
     return err instanceof CommandError && err.code === code;
 }

package/dist/git-stack.d.ts

@@ -23,6 +23,8 @@ export declare function defaultLayerBranchName(explicit?: string): string;
  * (`git rev-list --count base..head`). Used by stack submit to refuse empty layers.
  */
 export declare function commitsAheadOf(base: string, head: string, cwd?: string): number;
+/** Fetch one remote branch so submit can count commits ahead of a park freeze. */
+export declare function fetchRemoteBranch(name: string, cwd?: string): void;
 /** Push branch to origin and set upstream. */
 export declare function pushBranch(branch: string, cwd?: string): void;
 /** First line of the tip commit on `branch` (for PR title). */

package/dist/git-stack.js

@@ -107,6 +107,10 @@ export function commitsAheadOf(base, head, cwd = process.cwd()) {
     }
     return n;
 }
+/** Fetch one remote branch so submit can count commits ahead of a park freeze. */
+export function fetchRemoteBranch(name, cwd = process.cwd()) {
+    git(["fetch", "origin", name], cwd);
+}
 /** Push branch to origin and set upstream. */
 export function pushBranch(branch, cwd = process.cwd()) {
     try {

package/dist/git.d.ts

@@ -4,7 +4,18 @@ export declare function parseGithubOriginRepo(cwd?: string): {
     owner: string;
     repo: string;
 } | null;
-export declare function collectChangedFiles(base: string, head: string, cwd?: string): Promise<{
+/**
+ * Repo-root absolute path for the current working tree.
+ * Kept local (not imported from repo-identity) to avoid a git ↔ repo-identity cycle.
+ */
+export declare function repoRoot(cwd?: string): string;
+/**
+ * Repo-root-relative names of files changed between base and head that resolve
+ * inside the sandbox root. Bounds both the uploaded file contents and the diff
+ * itself to the sandbox so tracked files outside it never reach the API.
+ */
+export declare function changedNamesInSandbox(base: string, head: string, cwd?: string, sandboxRoot?: string): Promise<string[]>;
+export declare function collectChangedFiles(base: string, head: string, cwd?: string, sandboxRoot?: string): Promise<{
     path: string;
     content: string;
 }[]>;

package/dist/git.js

@@ -1,6 +1,6 @@
 import { spawnSync } from "node:child_process";
 import { realpathSync } from "node:fs";
-import { readFile, stat } from "node:fs/promises";
+import { readFile, realpath, stat } from "node:fs/promises";
 import path from "node:path";
 export function git(args, cwd = process.cwd()) {
     try {
@@ -33,15 +33,61 @@ export function parseGithubOriginRepo(cwd = process.cwd()) {
  * Repo-root absolute path for the current working tree.
  * Kept local (not imported from repo-identity) to avoid a git ↔ repo-identity cycle.
  */
-function repoRoot(cwd = process.cwd()) {
+export function repoRoot(cwd = process.cwd()) {
     return realpathSync(git(["rev-parse", "--show-toplevel"], cwd).trim());
 }
-export async function collectChangedFiles(base, head, cwd = process.cwd()) {
+/**
+ * Repo-root-relative names of files changed between base and head that resolve
+ * inside the sandbox root. Bounds both the uploaded file contents and the diff
+ * itself to the sandbox so tracked files outside it never reach the API.
+ */
+export async function changedNamesInSandbox(base, head, cwd = process.cwd(), sandboxRoot) {
     const root = repoRoot(cwd);
-    const names = git(["diff", "--name-only", "--diff-filter=ACMR", `${base}...${head}`], cwd)
-        .split("\n")
-        .map((s) => s.trim())
+    const bound = sandboxRoot ? await realpath(path.resolve(sandboxRoot)) : root;
+    // D/T are included so deletions and type changes stay in the review diff,
+    // even though their contents cannot be read from the working tree for upload.
+    // -z disables core.quotePath quoting and NUL-terminates names, so paths with
+    // spaces or non-ASCII characters survive the split verbatim.
+    const names = git(["diff", "--name-only", "-z", "--diff-filter=ACMRDT", `${base}...${head}`], cwd)
+        .split("\0")
         .filter(Boolean);
+    const kept = [];
+    for (const name of names) {
+        const abs = path.join(root, name);
+        let real;
+        try {
+            real = await realpath(abs);
+        }
+        catch {
+            // Deleted from the working tree: resolve the nearest existing ancestor so
+            // the path can still be bounded against the sandbox for the diff pathspec.
+            let ancestor = path.dirname(abs);
+            let realAncestor;
+            while (!realAncestor) {
+                try {
+                    realAncestor = await realpath(ancestor);
+                }
+                catch {
+                    const up = path.dirname(ancestor);
+                    if (up === ancestor)
+                        throw new Error(`cannot resolve ${abs}`);
+                    ancestor = up;
+                }
+            }
+            real = path.join(realAncestor, path.relative(ancestor, abs));
+        }
+        const relToBound = path.relative(bound, real);
+        if (relToBound === ".." || relToBound.startsWith(`..${path.sep}`)) {
+            console.warn(`Warning: skipping ${name} for review upload: it resolves outside the ${sandboxRoot ? "sandbox root" : "repo root"}`);
+            continue;
+        }
+        kept.push(name);
+    }
+    return kept;
+}
+export async function collectChangedFiles(base, head, cwd = process.cwd(), sandboxRoot) {
+    const root = repoRoot(cwd);
+    const names = await changedNamesInSandbox(base, head, cwd, sandboxRoot);
     const files = [];
     for (const name of names.slice(0, 40)) {
         const abs = path.join(root, name);
@@ -53,7 +99,6 @@ export async function collectChangedFiles(base, head, cwd = process.cwd()) {
             files.push({ path: name, content });
         }
         catch {
-            // deleted or unreadable — do not silently drop without a hint
             console.warn(`Warning: could not read ${name} for review upload (resolved from repo root); skipping file contents`);
         }
     }

package/dist/shell.d.ts

@@ -1,4 +1,4 @@
-/** Shell autocomplete + `/help` — derived from the command registry (STRUCT-01). */
+/** Shell autocomplete + `/help` � derived from the command registry (STRUCT-01). */
 export declare const COMMANDS: import("./ui/prompt.js").CommandSpec[];
 /** Strips an optional leading "/" so both "review" and "/review" work. */
 export declare function parseLine(line: string): {