mergestorm 0.3.9 → 0.3.15

package/dist/shell.js

@@ -5,18 +5,15 @@ import { dispatchCommand, shellCommandSpecs, } from "./commands/registry.js";
 import { ansi } from "./ui/ansi.js";
 import { printBannerHeader, shellPrompt } from "./ui/banner.js";
 import { CTRL_C_EXIT_HINT, CtrlCExitGate } from "./ui/ctrl-c-exit.js";
+import { openHelpBrowser } from "./commands/help.js";
+import { showLinePanel } from "./ui/line-tabs.js";
 import { askLine, PromptClosedError } from "./ui/prompt.js";
-/** Shell autocomplete + `/help` — derived from the command registry (STRUCT-01). */
-export const COMMANDS = shellCommandSpecs();
-function printHelp() {
-    const rows = COMMANDS.map((c) => `  ${ansi.green("/" + c.name.padEnd(10))} ${c.summary}`).join("\n");
-    console.log(`
-  ${ansi.bold("Commands")}
-${rows}
-
-  Dashboard: https://mergestorm.ai/settings#api
-`);
+async function showShellNotice(title, message) {
+    const lines = message.split("\n").flatMap((line) => (line ? [`  ${line}`] : [""]));
+    await showLinePanel(title, [...lines, "", `  ${ansi.dim("q to return")}`]);
 }
+/** Shell autocomplete + `/help` � derived from the command registry (STRUCT-01). */
+export const COMMANDS = shellCommandSpecs();
 /** Strips an optional leading "/" so both "review" and "/review" work. */
 export function parseLine(line) {
     let trimmed = line.trim();
@@ -31,10 +28,22 @@ export function parseLine(line) {
     return { cmd, args: parts.slice(1) };
 }
 export async function runShell() {
-    try {
-        await printBannerHeader();
-    }
-    catch { /* banner is best-effort */ }
+    // Idle is always the home screen: header + docked prompt. Command TUIs
+    // (usage / credits / status) and printed output become scrollback when
+    // the next askLine homes + ED 0. Do not retire the header after the
+    // first command � that is what floated a bare prompt at the top.
+    let banner = null;
+    const showBanner = async () => {
+        try {
+            banner = await printBannerHeader({ paint: false });
+        }
+        catch {
+            // Keep the previous chrome on a transient refresh failure rather than
+            // blanking the always-on home header.
+        }
+        return banner;
+    };
+    banner = await showBanner();
     const history = [];
     let busyAbort = null;
     const idleCtrlC = new CtrlCExitGate();
@@ -68,6 +77,11 @@ export async function runShell() {
                     prompt: shellPrompt(loggedIn),
                     history,
                     commands: COMMANDS,
+                    ...(banner
+                        ? {
+                            header: (columns, variant) => banner.rows(columns, variant),
+                        }
+                        : {}),
                 });
             }
             catch (err) {
@@ -87,15 +101,12 @@ export async function runShell() {
             if (cmd === "exit" || cmd === "quit")
                 break;
             if (cmd === "help" || cmd === "?") {
-                printHelp();
+                await openHelpBrowser();
                 continue;
             }
             if (cmd === "clear") {
                 output.write("");
-                try {
-                    await printBannerHeader();
-                }
-                catch { /* banner is best-effort */ }
+                await showBanner();
                 continue;
             }
             busyAbort = new AbortController();
@@ -104,33 +115,33 @@ export async function runShell() {
                     mode: "shell",
                     signal: busyAbort.signal,
                     afterAuth: async () => {
-                        try {
-                            await printBannerHeader();
-                        }
-                        catch { /* banner is best-effort */ }
+                        await showBanner();
                     },
                 });
                 if (!ok) {
-                    console.error(ansi.dim(`unknown command "${cmd}" -- type help`));
+                    await showShellNotice("Error", `unknown command "${cmd}"\ntype help for the list`);
                 }
             }
             catch (err) {
                 if (err instanceof DetachedError) {
-                    console.log(`\n${ansi.yellow(err.message)}`);
+                    await showShellNotice("Detached", err.message);
                 }
                 else if (err instanceof CommandError) {
-                    console.error(ansi.red(err.message));
+                    await showShellNotice("Error", err.message);
                 }
                 else if (err instanceof Error && err.name === "AbortError") {
-                    console.log(ansi.dim("\naborted"));
+                    await showShellNotice("Aborted", "aborted");
                 }
                 else {
-                    console.error(ansi.red(err instanceof Error ? err.message : String(err)));
+                    await showShellNotice("Error", err instanceof Error ? err.message : String(err));
                 }
             }
             finally {
                 busyAbort = null;
             }
+            // Re-capture the home header so usage/credits shown above the prompt
+            // reflect what the command just consumed (e.g. review spending a credit).
+            await showBanner();
         }
     }
     finally {

package/dist/stack-dto.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Wire types returned by the stack list/enrich HTTP endpoints.
+ *
+ * `api/src/stacks.ts#loadStackDtos` is the producer. Keep this file
+ * dependency-free and byte-for-byte aligned with the canonical wire contract.
+ */
+export type StackBranchState = "clean" | "needs_restack" | "restacking" | "conflict" | "merged" | "closed";
+export type StackCiStatus = "success" | "pending" | "failure" | "neutral" | "none" | "unknown";
+export type StackReviewStatus = "approved" | "changes_requested" | "reviewed" | "failed" | "none" | "unknown";
+/** `failed` is the newest Vortex `pr_reviews` row. Work paints Review failed. */
+export type StackVortexStatus = "reviewing" | "seam_pending" | "all_clear" | "findings" | "throttled" | "failed";
+export type StackCycloneStatus = "patching" | "awaiting_fix";
+export type StackTempestStatus = "reviewing" | "findings" | "clear" | "failed" | "stale";
+export type StackAgentName = "vortex" | "cyclone" | "tempest";
+/**
+ * One live-or-resting agent run for a PR (#1119): a dumb projection of one
+ * ledger row (webhook job / lease / review-state / pr_reviews). Two live
+ * Vortex jobs on two SHAs → two runs → two chips. Carries only safe facts —
+ * never job ids, holders, or error strings.
+ */
+export type StackAgentRun = {
+    agent: StackAgentName;
+    /** Agent-specific status, e.g. "reviewing" / "patching" / "all_clear". */
+    status: string;
+    /** Full SHA when known. UI shortens to 7. */
+    sha: string | null;
+    startedAt?: string | null;
+    finishedAt?: string | null;
+    /**
+     * Vortex in-flight sub-state from pr_reviews.phase (#1189): "fanout" while
+     * Core + specialists run in parallel, "synthesizing" during consolidation.
+     * Only on live `reviewing` runs; unknown values fall back to plain Reviewing.
+     */
+    phase?: string | null;
+    /**
+     * Actionable finding count from the latest `pr_reviews.findings` payload
+     * (#1248). Info-only notes (Continue, Decision required) are excluded.
+     * Only on resting Vortex `findings` runs.
+     */
+    findingCount?: number | null;
+};
+export type StackLayerChecks = {
+    total: number;
+    success: number;
+    pending: number;
+    failure: number;
+    failingName: string | null;
+    /**
+     * True when the persisted `ci_checks` carries a `namedRuns` seed (enrich
+     * writes it so CI webhook deliveries fold into the snapshot). Pre-seeding
+     * rows are false — the webhook cannot fold into them, so the interval poll
+     * must keep enriching until the first enrich seeds one (#1602). Status-only
+     * layers (empty `namedRuns` over a non-empty rollup) are also false — the
+     * webhook refuses to fold into an empty map, so the poll keeps enriching
+     * them (#1602).
+     */
+    namedRunsSeeded?: boolean;
+    /**
+     * True when the persisted `namedRuns` carries the reserved synthetic
+     * "commit status" run at a pending/failure verdict. Webhook deliveries
+     * re-key by check/context name and can never advance that seed, so the
+     * interval poll must keep enriching until the next enrich re-seeds it green
+     * (or drops it). Absent (false) when the seed is green — folds keep that
+     * layer fresh (#1602).
+     */
+    combinedStatusSeeded?: boolean;
+};
+/** Closing / Development-sidebar issue. Cap 3 on the wire. */
+export type StackLinkedIssue = {
+    number: number;
+    title: string | null;
+};
+/** Cyclone merge-conflict specialist resolution for this PR (#973). */
+export type StackLayerConflictResolution = {
+    resolvedAt: string;
+    /** Branch the conflicts were resolved against (stacks parent or GitHub base). */
+    baseBranch: string | null;
+    /** Conflicted paths the specialist resolved; the writer caps the list. */
+    files: string[];
+    /** Head commit of the pushed resolution, when known. */
+    headSha: string | null;
+    /**
+     * Chat dispatch that triggered the run (#973). Traces a mark to the job that
+     * pushed it; null when the row predates dispatch tracing (or had no job).
+     */
+    dispatchId: string | null;
+};
+export type StackLayerDto = {
+    branch: string;
+    parentBranch: string | null;
+    prNumber: number;
+    /** Persisted PR timing and diff snapshots from pr_stats. */
+    openedAt: string | null;
+    mergedAt: string | null;
+    closedAt: string | null;
+    additions: number | null;
+    deletions: number | null;
+    openAdditions: number | null;
+    openDeletions: number | null;
+    position: number;
+    state: StackBranchState;
+    title: string | null;
+    htmlUrl: string | null;
+    ciStatus: StackCiStatus;
+    reviewStatus: StackReviewStatus;
+    checks: StackLayerChecks | null;
+    /** null on the fast list or when no Vortex/seam signal exists. */
+    vortexStatus: StackVortexStatus | null;
+    /** null on the fast list or when no Cyclone signal exists. */
+    cycloneStatus: StackCycloneStatus | null;
+    /** null when no Tempest signal exists. Fast list and enrich both paint this from pr_reviews (#876). */
+    tempestStatus: StackTempestStatus | null;
+    /**
+     * Ledger-backed agent runs, one per live row (#1119). Fast list and enrich
+     * both paint this from our tables only — never GitHub. The per-agent status
+     * fields above stay as a rollup of the newest run for older clients.
+     * Undefined = producer predates runs (clients fall back to the rollup).
+     */
+    agentRuns?: StackAgentRun[];
+    conflictDetail: string | null;
+    lastRestackedSha: string | null;
+    /** GitHub PR mergeability from enrich; null when unknown. */
+    mergeable: boolean | null;
+    /** GitHub REST mergeable_state; null when unknown. */
+    mergeableState: string | null;
+    /** Most recently observed PR head SHA. */
+    headSha?: string | null;
+    /** Head SHA that produced mergeable / mergeableState. */
+    mergeableHeadSha?: string | null;
+    /** GitHub PR draft flag from enrich; the auto-land watcher never enqueues a draft. */
+    draft?: boolean | null;
+    /**
+     * Vortex-style linked issues (keywords + Development sidebar), cap 3.
+     * null until first enrich finds any; kept on merged unit members (unlike CI).
+     */
+    linkedIssues?: StackLinkedIssue[] | null;
+    /**
+     * Specialist lanes Vortex launched on this PR (smart router / Manual).
+     * Fast list and enrich both fill from vortex_pr_review_state (#896 / #915).
+     * Durable after merge — terminal layers keep the last run so Work can grey
+     * the marks on a done-growing unit member instead of dropping them (#1021).
+     */
+    specialistsRun?: string[] | null;
+    /** Published invocation count per specialist lane. Frontend paint follows separately. */
+    specialistRunCounts?: Record<string, number> | null;
+    /** Number of published reviews Core participated in for this PR. */
+    coreRuns?: number | null;
+    /**
+     * Cyclone's merge-conflict specialist resolved this PR (#973). Fast list and
+     * enrich both paint from cyclone_conflict_resolutions; null on terminal
+     * layers and when the specialist never ran.
+     */
+    conflictResolution?: StackLayerConflictResolution | null;
+};
+export type StackUnitMemberDto = {
+    prNumber: number;
+    /** Persisted PR timing and diff snapshots from pr_stats. */
+    openedAt: string | null;
+    mergedAt: string | null;
+    closedAt: string | null;
+    additions: number | null;
+    deletions: number | null;
+    openAdditions: number | null;
+    openDeletions: number | null;
+    branch: string;
+    position: number;
+    seamState: string;
+    seamReviewedSha: string | null;
+    promotedHeadSha: string | null;
+    promotedAt: string;
+    /**
+     * GitHub PR title snapshotted at promote / enrich (#965).
+     * Survives stack_branches dropping the open-chain row. null until first write.
+     */
+    title?: string | null;
+    /**
+     * Linked issues snapshotted onto the member at promote / enrich (#936).
+     * Survives stack_branches dropping the open-chain row. null until first write.
+     */
+    linkedIssues?: StackLinkedIssue[] | null;
+    /**
+     * Vortex specialist lanes that ran on this PR (#1021). Painted from
+     * vortex_pr_review_state on the fast list — the open layer is gone after
+     * promote, so the member must carry the marks for the greyed-out row.
+     */
+    specialistsRun?: string[] | null;
+    /** Published invocation count per specialist lane. */
+    specialistRunCounts?: Record<string, number> | null;
+    /** Number of published reviews Core participated in for this PR. */
+    coreRuns?: number | null;
+};
+export type StackUnitDto = {
+    id: string;
+    uNumber: number;
+    state: string;
+    branch: string;
+    landTarget: string;
+    members: StackUnitMemberDto[];
+    landPrNumber: number | null;
+    tempestLandStatus: string | null;
+    landingBlockReason: string | null;
+    /**
+     * Land-PR chrome. Fast list hydrates last-known CI/title/mergeable/issues from
+     * `review_units` (#878 / #892) and may attach a tempest-only stub (#876). Enrich
+     * refreshes GitHub and writes back. Null when the land PR is an open stack
+     * layer (chips live on `layers`) or the unit has no land PR.
+     */
+    landPr: StackLayerDto | null;
+};
+export type StackDto = {
+    id: string;
+    owner: string;
+    repo: string;
+    trunkBranch: string;
+    /** Real trunk the review unit eventually lands into. */
+    landTarget: string;
+    /**
+     * Dashboard-only archive (#963): set hides the stack from the active Work
+     * list; GitHub PRs stay open. Only PATCH /stacks/:id toggles it.
+     */
+    archivedAt: string | null;
+    /**
+     * Auto land (#1511): enqueue this unit-less single-PR stack when eligible.
+     * Missing on older payloads is off.
+     */
+    autoEnqueueWhenReady?: boolean;
+    layers: StackLayerDto[];
+    /** Present when a review-unit row exists for this stack. */
+    unit?: StackUnitDto;
+};
+export type MergeQueueEntryState = "queued" | "running" | "waiting" | "landed" | "bounced" | "cancelled";
+export type MergeQueueEnqueuedBy = "human" | "agent";
+export type MergeQueueEnqueuedVia = "dashboard" | "cli" | "chat" | "api" | "mcp";
+export type MergeQueueBounceKind = "ci_failure" | "ci_timeout" | "head_moved" | "tempest_findings" | "seam_findings" | "restack_conflict" | "pr_draft" | "merge_failed" | "gh_error";
+/** Structured bounce handoff — enough for the bar chip and the chat quote. */
+export type MergeQueueBounceDetail = {
+    kind: MergeQueueBounceKind;
+    prNumber?: number;
+    headSha?: string;
+    failingCheck?: string;
+    conflictBranch?: string;
+    conflictDetail?: string;
+    message?: string;
+};
+export type MergeQueueEntryDto = {
+    id: string;
+    stackId: string;
+    owner: string;
+    repo: string;
+    state: MergeQueueEntryState;
+    /** 1-based FIFO among this user's live entries; `0` on bounced history rows (MQ-7). */
+    position: number;
+    waitReason: string | null;
+    bounceReason: string | null;
+    bounceDetail: MergeQueueBounceDetail | null;
+    enqueuedBy: MergeQueueEnqueuedBy;
+    enqueuedVia: MergeQueueEnqueuedVia;
+    enqueuedAt: string;
+    attempts: number;
+    landedPrNumbers: number[];
+    /** Combined PR head the queue verified. Null until the worker records it. */
+    verifyHeadSha: string | null;
+    /** Target tip included in the verified PR head. Null until recorded. */
+    verifyBaseSha: string | null;
+    finishedAt: string | null;
+};

package/dist/stack-dto.js

@@ -0,0 +1,7 @@
+/**
+ * Wire types returned by the stack list/enrich HTTP endpoints.
+ *
+ * `api/src/stacks.ts#loadStackDtos` is the producer. Keep this file
+ * dependency-free and byte-for-byte aligned with the canonical wire contract.
+ */
+export {};

package/dist/submit-pr-base.d.ts

@@ -0,0 +1,31 @@
+/**
+ * GitHub PR base for `stack submit` (#1104).
+ *
+ * Git parent stays the previous layer (local rebase / `--onto`). Position 3+
+ * must open onto the review-unit park freeze so adopt does not retarget after
+ * `opened` and double-wake Vortex.
+ */
+import type { StackDto } from "./api.js";
+export declare const MG_PARK_PREFIX = "mg-park-";
+export declare function isMgParkBranch(branch: string): boolean;
+/** Live freeze already used as a GitHub base on this stack, if any. */
+export declare function parkFreezeBranchFromStack(stack: StackDto): string | null;
+export type SubmitLayerPlan = {
+    branch: string;
+    gitParent: string;
+    position: number;
+    /** GitHub `--base` when known. `null` means mint the freeze first. */
+    githubBase: string | null;
+    needsPark: boolean;
+    stackId: string | null;
+};
+export declare function planSubmitLayerBases(input: {
+    layers: readonly {
+        branch: string;
+        parentBranch: string;
+    }[];
+    trunk: string;
+    registered: readonly StackDto[];
+    owner: string;
+    repo: string;
+}): SubmitLayerPlan[];

package/dist/submit-pr-base.js

@@ -0,0 +1,69 @@
+function registeredParentHit(stacks, parentBranch, owner, repo) {
+    const want = parentBranch.trim();
+    if (!want)
+        return null;
+    for (const stack of stacks) {
+        if (stack.owner !== owner || stack.repo !== repo)
+            continue;
+        for (const layer of stack.layers) {
+            if (layer.branch === want) {
+                return { stackId: stack.id, position: layer.position };
+            }
+        }
+    }
+    return null;
+}
+export const MG_PARK_PREFIX = "mg-park-";
+export function isMgParkBranch(branch) {
+    return branch.trim().toLowerCase().startsWith(MG_PARK_PREFIX);
+}
+/** Live freeze already used as a GitHub base on this stack, if any. */
+export function parkFreezeBranchFromStack(stack) {
+    for (const layer of stack.layers) {
+        const parent = layer.parentBranch?.trim() ?? "";
+        if (isMgParkBranch(parent))
+            return parent;
+    }
+    return null;
+}
+export function planSubmitLayerBases(input) {
+    const { layers, trunk, registered, owner, repo } = input;
+    const localIndex = new Map(layers.map((layer, i) => [layer.branch, i]));
+    const plans = [];
+    for (let i = 0; i < layers.length; i++) {
+        const layer = layers[i];
+        const gitParent = layer.parentBranch.trim() || trunk;
+        const priorLocal = localIndex.get(gitParent);
+        let position;
+        let stackId = null;
+        if (priorLocal !== undefined && plans[priorLocal]) {
+            position = plans[priorLocal].position + 1;
+            stackId = plans[priorLocal].stackId;
+        }
+        else {
+            const hit = registeredParentHit(registered, gitParent, owner, repo);
+            if (hit) {
+                position = hit.position + 1;
+                stackId = hit.stackId;
+            }
+            else {
+                position = 1;
+            }
+        }
+        const stack = stackId
+            ? registered.find((row) => row.id === stackId) ?? null
+            : null;
+        const existingPark = stack ? parkFreezeBranchFromStack(stack) : null;
+        const needsPark = position >= 3;
+        const githubBase = needsPark ? existingPark : gitParent;
+        plans.push({
+            branch: layer.branch,
+            gitParent,
+            position,
+            githubBase,
+            needsPark,
+            stackId,
+        });
+    }
+    return plans;
+}

package/dist/ui/ansi.d.ts

@@ -9,4 +9,6 @@ export declare const ansi: {
     brightGreen: (t: string) => string;
     invert: (t: string) => string;
     boldGreen: (t: string) => string;
+    /** Prompt / mark ink. Never 32 — that reads as sick dark green. */
+    boldBrightGreen: (t: string) => string;
 };

package/dist/ui/ansi.js

@@ -24,4 +24,6 @@ export const ansi = {
     brightGreen: (t) => wrap("92", t),
     invert: (t) => wrap("7", t),
     boldGreen: (t) => (computeEnabled() ? `${t}` : t),
+    /** Prompt / mark ink. Never 32 — that reads as sick dark green. */
+    boldBrightGreen: (t) => (computeEnabled() ? `${t}` : t),
 };

package/dist/ui/banner.d.ts

@@ -1,4 +1,36 @@
+import { type MeResponse } from "../api.js";
 /** Used by the non-interactive `usage()` path in cli.ts — the boxed banner is shell-only. */
 export declare function printWordmark(): void;
-export declare function printBannerHeader(): Promise<void>;
-export declare function shellPrompt(loggedIn: boolean): string;
+/** Everything the welcome panel needs, captured once so redraws stay sync. */
+export type BannerState = {
+    version: string;
+    me: MeResponse | null;
+    key: string | undefined;
+    keyInvalid: boolean;
+};
+/** Full welcome, mid pane, or Claude-style short chrome that still shows the mark. */
+export type BannerDensity = "full" | "compact" | "mini" | "nano";
+/** `true` = compact. Strings pick the short-pane densities. */
+export type BannerVariant = boolean | "mini" | "nano";
+/** Handle returned by {@link printBannerHeader}; `rows` reflows for a resize. */
+export type BannerHandle = {
+    rows(columns?: number, variant?: BannerVariant): string[];
+};
+/**
+ * The whole welcome panel as rows, reflowed to `columns`. Every row fits in
+ * `columns - 1` cells so a redraw's cursor math stays honest; below
+ * MIN_BOXED_COLUMNS the frame drops away instead of wrapping.
+ */
+export declare function buildBannerRows(state: BannerState, columns?: number, opts?: {
+    compact?: boolean;
+    density?: BannerDensity;
+}): string[];
+/**
+ * Print the welcome panel and return a handle whose `rows()` reflows the
+ * same data for a new width (used by the prompt's resize redraw).
+ */
+export declare function printBannerHeader(opts?: {
+    /** When false, only build the handle; the prompt paints the rows. */
+    paint?: boolean;
+}): Promise<BannerHandle>;
+export declare function shellPrompt(_loggedIn: boolean): string;