mergestorm 0.3.7 → 0.3.9

package/dist/commands/registry.js

@@ -0,0 +1,219 @@
+import { DEFAULT_API } from "../config.js";
+import { CommandError } from "../errors.js";
+import { cmdBranches, cmdChain } from "./branches.js";
+import { cmdCredits } from "./credits.js";
+import { cmdJobs, cmdThread } from "./jobs.js";
+import { cmdLogin } from "./login.js";
+import { cmdLogout } from "./logout.js";
+import { cmdReview } from "./review.js";
+import { cmdStack } from "./stack.js";
+import { cmdStatus } from "./status.js";
+import { cmdWhoami } from "./whoami.js";
+/**
+ * Single source of truth for CLI commands (STRUCT-01).
+ * Derive oneshot usage, shell COMMANDS, and both dispatchers from this table.
+ */
+export const COMMAND_REGISTRY = [
+    {
+        name: "login",
+        summary: "Sign in via browser (or paste a key)",
+        usage: [
+            "mergestorm login                Sign in via browser and store an API key",
+            "mergestorm login --key          Paste an existing API key instead (headless/CI)",
+        ],
+        async run(args, ctx) {
+            await cmdLogin(args);
+            if (ctx.afterAuth)
+                await ctx.afterAuth();
+        },
+    },
+    {
+        name: "logout",
+        summary: "Remove the stored API key",
+        usage: ["mergestorm logout               Remove the stored API key"],
+        async run(_args, ctx) {
+            await cmdLogout();
+            if (ctx.afterAuth)
+                await ctx.afterAuth();
+        },
+    },
+    {
+        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)",
+        ],
+        async run(args, ctx) {
+            if (ctx.mode === "shell") {
+                await cmdReview(args, { signal: ctx.signal, interactive: true });
+                return;
+            }
+            await cmdReview(args);
+        },
+    },
+    {
+        name: "status",
+        summary: "Show a review job",
+        usage: [
+            "mergestorm status <job_id>      Fetch a review job and print JSON (one shot)",
+        ],
+        async run(args, ctx) {
+            if (!args[0]) {
+                throw new CommandError(ctx.mode === "shell"
+                    ? "usage: status <job_id>"
+                    : "usage: mergestorm status <job_id>");
+            }
+            if (ctx.mode === "shell") {
+                await cmdStatus(args[0], { format: "pretty", signal: ctx.signal });
+                return;
+            }
+            await cmdStatus(args[0], { format: "json" });
+        },
+    },
+    {
+        name: "credits",
+        aliases: ["usage"],
+        summary: "Credit balance with usage bars",
+        usage: ["mergestorm credits [--json]     Credit balance (usage bars)"],
+        async run(args) {
+            await cmdCredits(args);
+        },
+    },
+    {
+        name: "jobs",
+        summary: "Recent review jobs (default 10)",
+        usage: ["mergestorm jobs [n] [--json]    Recent review jobs"],
+        async run(args) {
+            await cmdJobs(args);
+        },
+    },
+    {
+        name: "branches",
+        aliases: ["chains"],
+        summary: "Pick a recently reviewed branch",
+        usage: ["mergestorm branches [n]         Recently reviewed branches (pick on TTY)"],
+        async run(args) {
+            await cmdBranches(args);
+        },
+    },
+    {
+        name: "chain",
+        summary: "Show a branch review-chain timeline",
+        usage: [
+            "mergestorm chain [slug]         Branch review-chain timeline (default: current)",
+        ],
+        async run(args) {
+            await cmdChain(args);
+        },
+    },
+    {
+        name: "whoami",
+        summary: "Key + plan + API base",
+        usage: ["mergestorm whoami [--json]      Key + plan + API base"],
+        async run(args) {
+            await cmdWhoami(args);
+        },
+    },
+    {
+        name: "thread",
+        summary: "Jobs in a review thread",
+        usage: ["mergestorm thread <slug>        Jobs in a review thread"],
+        async run(args, ctx) {
+            if (!args[0]) {
+                throw new CommandError(ctx.mode === "shell"
+                    ? "usage: thread <slug>"
+                    : "usage: mergestorm thread <slug>");
+            }
+            await cmdThread(args[0], args.slice(1));
+        },
+    },
+    {
+        name: "stack",
+        summary: "Stacks: create, submit, list, adopt, restack, land",
+        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 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);
+        },
+    },
+    {
+        name: "shell",
+        summary: "Explicit shell entry",
+        usage: ["mergestorm shell                Explicit shell entry"],
+        /** Shell entry is oneshot-only; interactive shell does not list it. */
+        async run() {
+            const { runShell } = await import("../shell.js");
+            await runShell();
+        },
+    },
+];
+/** Shell meta commands (not dispatched via {@link COMMAND_REGISTRY}). */
+const SHELL_META = [
+    { name: "help", summary: "Show available commands" },
+    { name: "clear", summary: "Clear screen and reprint banner" },
+    { name: "exit", summary: "Leave the shell" },
+    { name: "quit", summary: "Leave the shell" },
+];
+/** Commands omitted from shell autocomplete (oneshot-only entrypoints). */
+const SHELL_OMIT = new Set(["shell"]);
+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. */
+export function shellCommandSpecs() {
+    const specs = [{ name: "help", summary: SHELL_META[0].summary }];
+    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: "clear", summary: SHELL_META[1].summary }, { name: "exit", summary: SHELL_META[2].summary }, { name: "quit", summary: SHELL_META[3].summary });
+    return specs;
+}
+export function formatUsageBody() {
+    // Historical order: interactive entry → shell → version → registry (minus shell).
+    const shellEntry = COMMAND_REGISTRY.find((c) => c.name === "shell");
+    const others = COMMAND_REGISTRY.filter((c) => c.name !== "shell");
+    const cmdLines = [
+        "mergestorm                      Interactive shell (TTY)",
+        ...(shellEntry?.usage ?? []),
+        "mergestorm -v, --version        Print CLI version",
+        ...others.flatMap((c) => c.usage),
+    ]
+        .map((line) => `  ${line}`)
+        .join("\n");
+    return `${cmdLines}
+
+  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})
+`;
+}
+/**
+ * Run a registered command. Returns false when `name` is unknown
+ * (caller prints usage / shell hint).
+ */
+export async function dispatchCommand(name, args, ctx) {
+    const cmd = findCommand(name);
+    if (!cmd)
+        return false;
+    // `shell` as a subcommand is oneshot-only.
+    if (cmd.name === "shell" && ctx.mode === "shell")
+        return false;
+    await cmd.run(args, ctx);
+    return true;
+}

package/dist/commands/review.d.ts

@@ -1,11 +1,20 @@
+/**
+ * Diff base when the user omits args[0]. Prefers origin/HEAD / main / master
+ * via discoverTrunk (same as stack create) instead of hardcoding "main".
+ */
+export declare function resolveReviewBase(explicit: string | undefined, cwd?: string): string;
 export type ReviewOptions = {
     signal?: AbortSignal;
     /** When true, show Ctrl+C detach hint during poll. */
     interactive?: boolean;
 };
-/** Parse `origin` remote into GitHub owner/repo when possible. */
-export declare function parseGithubOriginRepo(cwd?: string): {
-    owner: string;
-    repo: string;
-} | null;
+/** Max consecutive transient poll failures before surfacing an error. */
+export declare const REVIEW_POLL_MAX_TRANSIENT_RETRIES = 3;
+export declare function reviewStatusHint(jobId: string): string;
+/** Append recovery hint once a job id exists (idempotent). */
+export declare function withReviewJobRecovery(message: string, jobId: string): string;
+/** HTTP statuses worth retrying during review poll (not 401/402/404). */
+export declare function isTransientReviewPollStatus(status: number): boolean;
+/** Network / request-timeout errors worth retrying during review poll. */
+export declare function isTransientReviewPollError(err: unknown): boolean;
 export declare function cmdReview(args: string[], opts?: ReviewOptions): Promise<void>;

package/dist/commands/review.js

@@ -1,21 +1,22 @@
 import { apiFetch, getMe } from "../api.js";
 import { loadConfig } from "../config.js";
-import { CommandError, DetachedError } from "../errors.js";
-import { collectChangedFiles, git } from "../git.js";
+import { CommandError, DetachedError, isCommandErrorCode } from "../errors.js";
+import { collectChangedFiles, git, parseGithubOriginRepo } from "../git.js";
+import { discoverTrunk } from "../git-stack.js";
 import { ansi } from "../ui/ansi.js";
-/** Parse `origin` remote into GitHub owner/repo when possible. */
-export function parseGithubOriginRepo(cwd = process.cwd()) {
+import { renderFindings } from "../ui/findings.js";
+/**
+ * Diff base when the user omits args[0]. Prefers origin/HEAD / main / master
+ * via discoverTrunk (same as stack create) instead of hardcoding "main".
+ */
+export function resolveReviewBase(explicit, cwd = process.cwd()) {
+    if (explicit)
+        return explicit;
     try {
-        const url = git(["remote", "get-url", "origin"], cwd).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] };
+        return discoverTrunk(cwd);
     }
     catch {
-        return null;
+        throw new CommandError("Could not discover trunk branch. Pass an explicit base: mergestorm review <base> [head]");
     }
 }
 function sleep(ms, signal) {
@@ -32,13 +33,56 @@ function sleep(ms, signal) {
         signal?.addEventListener("abort", onAbort, { once: true });
     });
 }
+/** Max consecutive transient poll failures before surfacing an error. */
+export const REVIEW_POLL_MAX_TRANSIENT_RETRIES = 3;
+export function reviewStatusHint(jobId) {
+    return `Check: mergestorm status ${jobId}`;
+}
+/** Append recovery hint once a job id exists (idempotent). */
+export function withReviewJobRecovery(message, jobId) {
+    const hint = reviewStatusHint(jobId);
+    if (message.includes(`mergestorm status ${jobId}`))
+        return message;
+    return `${message.replace(/\s+$/, "")}\n${hint}`;
+}
+/** HTTP statuses worth retrying during review poll (not 401/402/404). */
+export function isTransientReviewPollStatus(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+/** Network / request-timeout errors worth retrying during review poll. */
+export function isTransientReviewPollError(err) {
+    if (!(err instanceof Error))
+        return false;
+    if (err.name === "AbortError")
+        return false;
+    if (err instanceof CommandError) {
+        return err.code === "api_timeout";
+    }
+    if (err instanceof TypeError && /fetch|network|connection/i.test(err.message))
+        return true;
+    return /fetch failed|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|socket hang up/i.test(err.message);
+}
+function asPollCommandError(err, jobId) {
+    if (err instanceof CommandError) {
+        return new CommandError(withReviewJobRecovery(err.message, jobId), err.exitCode, err.code);
+    }
+    const detail = err instanceof Error ? err.message : String(err);
+    return new CommandError(withReviewJobRecovery(`Poll failed: ${detail}`, jobId));
+}
 export async function cmdReview(args, opts = {}) {
-    const base = args[0] || "main";
+    const base = resolveReviewBase(args[0]);
     const head = args[1] || "HEAD";
     const cfg = await loadConfig();
     const meBefore = opts.interactive ? await getMe(cfg) : null;
     console.log(`Collecting diff ${base}...${head} …`);
-    const diff = git(["diff", `${base}...${head}`]);
+    let diff;
+    try {
+        diff = git(["diff", `${base}...${head}`]);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new CommandError(`Could not diff ${base}...${head}: ${detail}. Try \`mergestorm review <base>\` with your trunk branch.`);
+    }
     if (!diff.trim()) {
         console.log("No changes to review.");
         return;
@@ -72,13 +116,41 @@ export async function cmdReview(args, opts = {}) {
         ? ` Waiting… (${ansi.dim("ctrl+c to detach — job keeps running")})`
         : " Waiting…";
     console.log(`Job ${job.job_id} (${job.status}).${waitHint}`);
+    let transientFailures = 0;
     try {
         for (let i = 0; i < 90; i += 1) {
             await sleep(2000, opts.signal);
-            const poll = await apiFetch(cfg, `/api/v1/reviews/${job.job_id}`, { signal: opts.signal });
+            let poll;
+            try {
+                poll = await apiFetch(cfg, `/api/v1/reviews/${job.job_id}`, { signal: opts.signal });
+            }
+            catch (err) {
+                if (opts.interactive && err instanceof Error && err.name === "AbortError") {
+                    throw err;
+                }
+                if (opts.interactive && isCommandErrorCode(err, "api_timeout")) {
+                    throw err;
+                }
+                if (isTransientReviewPollError(err) &&
+                    transientFailures < REVIEW_POLL_MAX_TRANSIENT_RETRIES) {
+                    transientFailures += 1;
+                    if (opts.interactive)
+                        process.stdout.write("?");
+                    continue;
+                }
+                throw asPollCommandError(err, job.job_id);
+            }
             if (poll.status !== 200) {
-                throw new CommandError(`Poll failed: ${JSON.stringify(poll.body, null, 2)}`);
+                if (isTransientReviewPollStatus(poll.status) &&
+                    transientFailures < REVIEW_POLL_MAX_TRANSIENT_RETRIES) {
+                    transientFailures += 1;
+                    if (opts.interactive)
+                        process.stdout.write("?");
+                    continue;
+                }
+                throw new CommandError(withReviewJobRecovery(`Poll failed: ${JSON.stringify(poll.body, null, 2)}`, job.job_id));
             }
+            transientFailures = 0;
             const row = poll.body;
             if (row.status === "queued" || row.status === "in_progress") {
                 process.stdout.write(".");
@@ -86,23 +158,11 @@ export async function cmdReview(args, opts = {}) {
             }
             console.log("");
             if (row.status === "failed" || row.status === "quota_exceeded") {
-                throw new CommandError(`Review ${row.status}: ${row.error ?? ""}`);
+                throw new CommandError(withReviewJobRecovery(`Review ${row.status}: ${row.error ?? ""}`, job.job_id));
             }
             console.log(`\nVerdict: ${ansi.bold(row.verdict ?? "comment")}`);
             console.log(row.summary ?? "");
-            const inline = row.findings?.inline ?? [];
-            const off = row.findings?.off_diff ?? row.findings?.offDiff ?? [];
-            for (const c of inline) {
-                console.log(`\n[${c.severity}] ${c.path}:${c.line}${c.title ? ` — ${c.title}` : ""}`);
-                console.log(c.body);
-            }
-            for (const c of off) {
-                console.log(`\n[${c.severity}] off-diff ${c.path ?? ""}`);
-                console.log(c.body);
-            }
-            if (inline.length === 0 && off.length === 0) {
-                console.log("\nNo findings.");
-            }
+            renderFindings(row.findings, { emptyMessage: true });
             if (opts.interactive && meBefore) {
                 const meAfter = await getMe(cfg);
                 if (meAfter) {
@@ -121,7 +181,13 @@ export async function cmdReview(args, opts = {}) {
         if (opts.interactive && err instanceof Error && err.name === "AbortError") {
             throw new DetachedError(job.job_id);
         }
+        if (opts.interactive && isCommandErrorCode(err, "api_timeout")) {
+            throw new DetachedError(job.job_id);
+        }
+        if (err instanceof CommandError) {
+            throw new CommandError(withReviewJobRecovery(err.message, job.job_id), err.exitCode, err.code);
+        }
         throw err;
     }
-    throw new CommandError(`Timed out waiting for review. Check: mergestorm status ${job.job_id}`);
+    throw new CommandError(withReviewJobRecovery("Timed out waiting for review.", job.job_id));
 }

package/dist/commands/stack.d.ts

@@ -1,3 +1,10 @@
+import { adoptStack } from "../api.js";
+import { loadConfig } from "../config.js";
+import { createPr, findOpenPrNumber } from "../gh.js";
+import { parseGithubOriginRepo } from "../git.js";
+import { branchExists, commitsAheadOf, pushBranch, tipCommitMessage, tipCommitSubject } from "../git-stack.js";
+import { buildPrBodyFromCommit } from "../pr-body.js";
+import { loadStackMeta, saveStackMeta } from "../stack-meta.js";
 export declare function requireStackId(raw: string | undefined, usage: string): string;
 /** Parse `owner/repo#12` or `owner/repo 12`. */
 export declare function parseAdoptTarget(args: string[]): {
@@ -13,4 +20,24 @@ export declare function parseStackCreateArgs(args: string[]): {
     asJson: boolean;
 };
 export declare function parseStackResetArgs(args: string[]): void;
+/** Injectable seams for unit tests (STRUCT-04). Production callers omit deps. */
+export type StackSubmitDeps = {
+    cwd?: string;
+    gitTopLevel?: (cwd?: string) => string;
+    loadStackMeta?: typeof loadStackMeta;
+    saveStackMeta?: typeof saveStackMeta;
+    parseGithubOriginRepo?: typeof parseGithubOriginRepo;
+    requireGh?: (cwd?: string) => void;
+    branchExists?: typeof branchExists;
+    pushBranch?: typeof pushBranch;
+    findOpenPrNumber?: typeof findOpenPrNumber;
+    commitsAheadOf?: typeof commitsAheadOf;
+    tipCommitSubject?: typeof tipCommitSubject;
+    tipCommitMessage?: typeof tipCommitMessage;
+    buildPrBodyFromCommit?: typeof buildPrBodyFromCommit;
+    createPr?: typeof createPr;
+    loadConfig?: typeof loadConfig;
+    adoptStack?: typeof adoptStack;
+};
+export declare function cmdStackSubmit(args: string[], deps?: StackSubmitDeps): Promise<void>;
 export declare function cmdStack(args: string[]): Promise<void>;

package/dist/commands/stack.js

@@ -2,12 +2,12 @@ import { adoptStack, landNextStack, listStacks, restackStack, setStackAutoPromot
 import { loadConfig } from "../config.js";
 import { CommandError } from "../errors.js";
 import { createPr, findOpenPrNumber, requireGh } from "../gh.js";
-import { branchExists, createBranchFromHead, currentBranch, defaultLayerBranchName, deleteBranch, discoverTrunk, pushBranch, tipCommitMessage, tipCommitSubject, worktreeDirty, } from "../git-stack.js";
+import { parseGithubOriginRepo } from "../git.js";
+import { branchExists, commitsAheadOf, createBranchFromHead, currentBranch, defaultLayerBranchName, deleteBranch, discoverTrunk, pushBranch, tipCommitMessage, tipCommitSubject, worktreeDirty, } from "../git-stack.js";
 import { buildPrBodyFromCommit } from "../pr-body.js";
 import { gitTopLevel } from "../repo-identity.js";
 import { activeLayers, appendLayer, emptyStackMeta, loadStackMeta, removeActiveStack, resetStackMeta, saveStackMeta, selectStackForCreate, } from "../stack-meta.js";
 import { ansi } from "../ui/ansi.js";
-import { parseGithubOriginRepo } from "./review.js";
 const STACK_USAGE = `usage:
   mergestorm stack create [name] [--onto <branch>] [--trunk <branch>] [--json]
   mergestorm stack submit [--json]
@@ -185,49 +185,79 @@ async function cmdStackCreate(args) {
     console.log(ansi.dim(`  trunk: ${meta.trunk} · local stacks: ${meta.stacks.length} · active layers: ${layers.length}`));
     console.log(ansi.dim("  authoring state: managed automatically outside the repository"));
 }
-async function cmdStackSubmit(args) {
+export async function cmdStackSubmit(args, deps = {}) {
     const asJson = args.includes("--json");
     if (args.some((a) => a !== "--json")) {
         throw new CommandError("usage: mergestorm stack submit [--json]");
     }
-    const cwd = process.cwd();
+    const cwd = deps.cwd ?? process.cwd();
+    const gitTopLevelFn = deps.gitTopLevel ?? gitTopLevel;
+    const loadStackMetaFn = deps.loadStackMeta ?? loadStackMeta;
+    const saveStackMetaFn = deps.saveStackMeta ?? saveStackMeta;
+    const parseOriginFn = deps.parseGithubOriginRepo ?? parseGithubOriginRepo;
+    const requireGhFn = deps.requireGh ?? requireGh;
+    const branchExistsFn = deps.branchExists ?? branchExists;
+    const pushBranchFn = deps.pushBranch ?? pushBranch;
+    const findOpenPrNumberFn = deps.findOpenPrNumber ?? findOpenPrNumber;
+    const commitsAheadOfFn = deps.commitsAheadOf ?? commitsAheadOf;
+    const tipCommitSubjectFn = deps.tipCommitSubject ?? tipCommitSubject;
+    const tipCommitMessageFn = deps.tipCommitMessage ?? tipCommitMessage;
+    const buildPrBodyFn = deps.buildPrBodyFromCommit ?? buildPrBodyFromCommit;
+    const createPrFn = deps.createPr ?? createPr;
+    const loadConfigFn = deps.loadConfig ?? loadConfig;
+    const adoptStackFn = deps.adoptStack ?? adoptStack;
     try {
-        gitTopLevel(cwd);
+        gitTopLevelFn(cwd);
     }
     catch {
         throw new CommandError("Not in a git repository. Run `mg stack submit` from inside the repo whose stack you want to push.");
     }
-    const meta = await loadStackMeta(cwd);
+    const meta = await loadStackMetaFn(cwd);
     const layers = meta ? activeLayers(meta) : [];
     if (!meta || layers.length === 0) {
         throw new CommandError("No local stack layers. Run `mg stack create` (then commit your code) before `stack submit`.");
     }
-    const origin = parseGithubOriginRepo(cwd);
+    const origin = parseOriginFn(cwd);
     if (!origin) {
         throw new CommandError("Could not parse GitHub owner/repo from `origin`. Set a github.com remote and retry.");
     }
     const { owner, repo } = origin;
-    requireGh(cwd);
+    requireGhFn(cwd);
     const opened = [];
     for (const layer of layers) {
         const base = layer.parentBranch || meta.trunk;
-        if (!branchExists(layer.branch, cwd)) {
+        if (!branchExistsFn(layer.branch, cwd)) {
             throw new CommandError(`Stack layer branch missing locally: ${layer.branch}`);
         }
         console.log(ansi.dim(`  Pushing ${layer.branch} …`));
         try {
-            pushBranch(layer.branch, cwd);
+            pushBranchFn(layer.branch, cwd);
         }
         catch (err) {
             throw new CommandError(err instanceof Error ? err.message : String(err));
         }
-        let prNumber = findOpenPrNumber(owner, repo, layer.branch, cwd);
+        let prNumber = findOpenPrNumberFn(owner, repo, layer.branch, cwd);
         let created = false;
         if (prNumber == null) {
-            const title = tipCommitSubject(layer.branch, cwd);
-            const body = buildPrBodyFromCommit(tipCommitMessage(layer.branch, cwd));
+            // Refuse empty layers before `gh pr create` dumps opaque stderr.
+            if (!branchExistsFn(base, cwd)) {
+                throw new CommandError(`Stack base branch missing locally: ${base}`);
+            }
+            let ahead;
+            try {
+                ahead = commitsAheadOfFn(base, layer.branch, cwd);
+            }
+            catch (err) {
+                throw new CommandError(err instanceof Error ? err.message : String(err));
+            }
+            if (ahead < 1) {
+                throw new CommandError(`No commits on \`${layer.branch}\` ahead of \`${base}\`. ` +
+                    `Commit your changes, then retry \`mg stack submit\`.`);
+            }
+            const title = tipCommitSubjectFn(layer.branch, cwd);
+            const body = buildPrBodyFn(tipCommitMessageFn(layer.branch, cwd));
             console.log(ansi.dim(`  Opening PR ${layer.branch} → ${base} …`));
-            prNumber = createPr({
+            prNumber = createPrFn({
                 owner,
                 repo,
                 base,
@@ -244,9 +274,9 @@ async function cmdStackSubmit(args) {
         opened.push({ branch: layer.branch, base, prNumber, created });
     }
     const registerPr = opened[0].prNumber;
-    const cfg = await loadConfig();
+    const cfg = await loadConfigFn();
     console.log(ansi.dim(`  Registering stack via import (${owner}/${repo}#${registerPr}) …`));
-    const body = await adoptStack(owner, repo, registerPr, cfg);
+    const body = await adoptStackFn(owner, repo, registerPr, cfg);
     if (typeof body !== "object" || body === null) {
         throw new CommandError("Unexpected response shape from adopt API");
     }
@@ -259,7 +289,7 @@ async function cmdStackSubmit(args) {
     }
     const stackId = data.stack.id;
     // Drop the submitted local stack so the next create onto trunk starts fresh.
-    await saveStackMeta(removeActiveStack(meta), cwd);
+    await saveStackMetaFn(removeActiveStack(meta), cwd);
     if (asJson) {
         console.log(JSON.stringify({
             owner,
@@ -281,7 +311,7 @@ async function cmdStackSubmit(args) {
     else {
         console.log(ansi.dim("  Stack registration returned no stack ID"));
     }
-    console.log(ansi.dim("  Dashboard: https://mergestorm.ai/dashboard/stacks"));
+    console.log(ansi.dim("  Dashboard: https://mergestorm.ai/dashboard"));
 }
 async function cmdStackReset(args) {
     parseStackResetArgs(args);
@@ -299,7 +329,7 @@ async function cmdStackList(args) {
     if (stacks.length === 0) {
         console.log(ansi.dim("  No stacks yet. Author with `stack create` → commit → `stack submit`."));
         console.log(ansi.dim("  Import an existing chain only: `stack adopt owner/repo#pr`"));
-        console.log(ansi.dim("  Dashboard: https://mergestorm.ai/dashboard/stacks"));
+        console.log(ansi.dim("  Dashboard: https://mergestorm.ai/dashboard"));
         return;
     }
     for (const s of stacks) {
@@ -307,7 +337,7 @@ async function cmdStackList(args) {
             console.log(line);
         console.log("");
     }
-    console.log(ansi.dim("  Dashboard: https://mergestorm.ai/dashboard/stacks"));
+    console.log(ansi.dim("  Dashboard: https://mergestorm.ai/dashboard"));
 }
 async function cmdStackAdopt(args) {
     const asJson = args.includes("--json");
@@ -334,7 +364,7 @@ async function cmdStackAdopt(args) {
     if (stack?.trunkBranch) {
         console.log(ansi.dim(`  trunk: ${stack.trunkBranch}`));
     }
-    console.log(ansi.dim("  Dashboard: https://mergestorm.ai/dashboard/stacks"));
+    console.log(ansi.dim("  Dashboard: https://mergestorm.ai/dashboard"));
 }
 async function cmdStackRestack(args) {
     const asJson = args.includes("--json");
@@ -352,7 +382,7 @@ async function cmdStackLand(args) {
     const asJson = args.includes("--json");
     const id = requireStackId(args.find((a) => a !== "--json"), "usage: mergestorm stack land <stack-id>");
     const cfg = await loadConfig();
-    // Server routes unit stacks to promote-next (#244 / AUD-07).
+    // Server routes unit stacks to promote-next (land tip into review unit).
     const body = await landNextStack(id, cfg);
     if (asJson) {
         console.log(JSON.stringify(body, null, 2));
@@ -393,8 +423,10 @@ async function cmdStackAutoLand(args) {
 export async function cmdStack(args) {
     const sub = args[0]?.toLowerCase();
     const rest = args.slice(1);
-    if (!sub || sub === "-h" || sub === "--help") {
-        throw new CommandError(STACK_USAGE);
+    // Help must exit 0 — print usage, do not throw CommandError.
+    if (!sub || sub === "-h" || sub === "--help" || sub === "help") {
+        console.log(STACK_USAGE);
+        return;
     }
     if (sub === "create")
         return cmdStackCreate(rest);

package/dist/commands/status.js

@@ -2,6 +2,7 @@ import { apiFetch } from "../api.js";
 import { loadConfig } from "../config.js";
 import { CommandError } 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();
@@ -23,17 +24,5 @@ export async function cmdStatus(jobId, opts = {}) {
         console.log(row.summary);
     if (row.error)
         console.log(ansi.red(`Error: ${row.error}`));
-    const inline = row.findings?.inline ?? [];
-    const off = row.findings?.off_diff ?? row.findings?.offDiff ?? [];
-    for (const c of inline) {
-        console.log(`\n[${c.severity}] ${c.path}:${c.line}${c.title ? ` — ${c.title}` : ""}`);
-        console.log(c.body);
-    }
-    for (const c of off) {
-        console.log(`\n[${c.severity}] off-diff ${c.path ?? ""}`);
-        console.log(c.body);
-    }
-    if (inline.length === 0 && off.length === 0 && row.status === "completed") {
-        console.log("\nNo findings.");
-    }
+    renderFindings(row.findings, { emptyMessage: row.status === "completed" });
 }