mergestorm 0.3.9 → 0.3.15

package/README.md

@@ -28,7 +28,7 @@ After install, both `mergestorm` and `mg` invoke the same CLI.
 ## Source
 
 Public source (MIT): [github.com/marginsystems/mergestorm-cli](https://github.com/marginsystems/mergestorm-cli).
-Tags there match npm versions (`v0.3.9`, …). Clone, install, and build:
+Tags there match npm versions (`v0.3.13`, …). Clone, install, and build:
 
 ```bash
 git clone https://github.com/marginsystems/mergestorm-cli.git
@@ -41,18 +41,16 @@ node dist/cli.js --help
 
 ## Interactive shell
 
-On a TTY, bare `mergestorm` (or `mergestorm shell`) opens a branded REPL: a **full-width** welcome panel (logo + status on the left, tips / what's new on the right) and a **full-width** bordered input box with a live `/` slash-command dropdown. Non-TTY (CI/pipes) prints usage instead — no hanging prompt.
+On a TTY, bare `mergestorm` (or `mergestorm shell`) opens a branded REPL: a compact **full-width** welcome panel (mark, version, status, usage bar) and a **full-width** bordered input box with a live `/` slash-command dropdown. The welcome panel reflows on terminal resize instead of wrapping or smearing. Non-TTY (CI/pipes) prints usage instead — no hanging prompt.
 
 ```
-╭─ mergestorm v0.3.9 ──────────────────────────────────────────────────────────╮
-│      ▟██████████▛       Tips for getting started                             │
-│       ▜████████▛          review      review origin/HEAD or main             │
-│        ▝▜████▛▘           stack       create → submit → restack → land       │
-│          ▜██▛             /help       list all commands                      │
-│           ██                                                                 │
-│           ▝▘            What's new in v0.3.9                                 │
-│  ● msk…  ·  maelstrom     • MIT license + public source (mergestorm-cli)       │
-│  [████░░░░░░░░░░] 12% used                                                   │
+╭──────────────────────────────────────────────────────────────────────────────╮
+│ ▟██▛  mergestorm v0.3.15                                                     │
+│  ▜▙   ● msk_live_…  · maelstrom                                              │
+│       [████████░░░░░░░░░░░░░░░░░░░░░░] 25% used · Resets Sep 5, 10:53am (UTC)│
+│                                                                              │
+│       review a diff · usage for tabs · /help for all commands                │
+│       New in v0.3.15: PR wait + settings + both skills in the npm tarball    │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 mergestorm
 ╭──────────────────────────────────────────────────────────────────────────────╮
@@ -60,15 +58,15 @@ mergestorm
 ╰──────────────────────────────────────────────────────────────────────────────╯
   /review       Review git diff (default origin/HEAD or main or master)
 
-mergestorm> credits
+mergestorm> usage
 mergestorm> branches
 mergestorm> chain
 mergestorm> exit
 ```
 
-Bare command names still work exactly as before (`review`, `help`, `exit`, …) — typing `/` at the start of a line just opens the live autocomplete dropdown (filtered as you type, navigate with Up/Down, accept with Tab/Enter/Right). Arrow-key history, Ctrl+A/E, Ctrl+U/K work as in a regular shell. At the idle prompt, **Ctrl+C twice** (within ~1.5s) exits the shell; a single Ctrl+C clears the line and shows a confirm hint. While `review` / `status` is waiting, Ctrl+C detaches or aborts that wait (job may keep running) — it does not exit the shell. Ctrl+D on an empty line, or `exit` / `quit`, also leave the shell. On a dumb terminal, without color, or when piped, the box falls back to plain ASCII borders (or no shell at all for non-TTY input).
+Bare command names still work exactly as before (`review`, `help`, `exit`, …) — typing `/` at the start of a line opens a compact autocomplete overlay (aliases folded onto the primary name, Up/Down scroll a viewport, Esc dismisses, Tab completes, Enter accepts a prefix or submits an exact name as typed, Left/Right move the cursor). Arrow-key history, Ctrl+A/E, Ctrl+U/K work as in a regular shell. At the idle prompt, **Ctrl+C twice** (within ~1.5s) exits the shell; a single Ctrl+C clears the line and shows a confirm hint. While `review` / `status` is waiting, Ctrl+C detaches or aborts that wait (job may keep running) — it does not exit the shell. Ctrl+D on an empty line, or `exit` / `quit`, also leave the shell. On a dumb terminal, without color, or when piped, the box falls back to plain ASCII borders (or no shell at all for non-TTY input).
 
-`credits` / `usage` print a usage meter — long bar + `N% used`, then `Resets … (UTC)` — for standard and premium. `branches` (alias `chains`) lists recently reviewed branches; on a TTY you arrow-select one to open its review-chain timeline. `chain [slug]` shows that timeline directly (defaults to `local/<current-git-branch>`).
+`credits` / `usage` on a TTY open a tabbed **Status / Usage / Jobs** browser (Usage selected): Left/Right switch tabs, Up/Down scroll or select, Enter on a job opens its `status` detail in place, Esc backs out, `q` closes. `status` with no job id opens the same browser on the Status tab. Piped / non-TTY output keeps the static panel: key · plan, a credit bar sized to the terminal, `Resets … (UTC)`, then the last five jobs; `--json` adds `recent_jobs` and is unchanged. `branches` (alias `chains`) lists recently reviewed branches; on a TTY you arrow-select one to open its review-chain timeline. `chain [slug]` shows that timeline directly (defaults to `local/<current-git-branch>`).
 
 ## Commands
 
@@ -81,26 +79,29 @@ mergestorm login                Sign in via browser; stores an API key in ~/.mer
 mergestorm login --key          Paste an existing API key instead (headless/CI)
 mergestorm logout               Remove the stored API key
 mergestorm review [base] [head] Review git diff base...head (default: origin/HEAD or main or master)
-mergestorm status <job_id>      Fetch a review job and print JSON (one shot)
-mergestorm credits [--json]     Standard + premium credit balance (usage bars)
+mergestorm status <job_id>      Fetch a review job (envelope; --json --wait --timeout)
+mergestorm status               Tabbed Status / Usage / Jobs browser (TTY)
+mergestorm credits [--json]     Usage panel (bar + last 5 jobs); tabbed browser on a TTY
 mergestorm jobs [n] [--json]    Recent review jobs (default 10, max 50)
 mergestorm branches [n]         Recently reviewed branches (arrow-pick on TTY)
 mergestorm chain [slug]         Branch review-chain timeline (default: current branch)
 mergestorm whoami [--json]      Key prefix, plan, API base, config path
+mergestorm skill install --claude|--cursor  Copy the mergestorm-review and mergestorm-pr-loop skills into this repo
 mergestorm thread <slug>        Jobs in a review thread
-mergestorm stack create [name]  New local stack layer (optional `--onto` / `--trunk`)
-mergestorm stack submit         Push layers, open chained PRs (`gh`), register via adopt
+mergestorm stack create [name]  New local stack layer (optional `--onto` / `--trunk` / `--extend`)
+mergestorm stack submit         Push layers, open PRs (`gh`), register via adopt (optional `--extend`)
 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 descendants
 mergestorm stack land <stack-id>     Land / promote (into review unit when present)
-mergestorm stack auto-promote on|off <stack-id>  Toggle auto-promote when green
 mergestorm stack reset --force  Clear local authoring state (not branches/PRs)
 ```
 
-`mg` is a short alias for `mergestorm` (same binary), e.g. `mg stack create`. Happy path: **create → commit → submit → restack → land**. On review-unit stacks, `stack land` **promotes** the tip into the unit (same gates as the dashboard); otherwise it lands the bottom open PR. `stack auto-promote` turns on land-when-green for a registered stack (`auto-land` remains a deprecated alias). `stack adopt` is for importing a chain that already exists on GitHub (legacy / Graphite). Restack/land use the same login key (`/api/v1/stacks`).
+`mg` is a short alias for `mergestorm` (same binary), e.g. `mg stack create`. Happy path: **create → commit → submit → restack → land**. On review-unit stacks, `stack land` **promotes** the tip into the unit (same gates as the dashboard); otherwise it lands the bottom open PR. `stack adopt` is for importing a chain that already exists on GitHub (legacy / Graphite). Restack/land use the same login key (`/api/v1/stacks`). Unattended landing is `mg queue add`.
+
+`stack create` checks out a new branch from the current tip (or `--onto <branch>`), discovers trunk (`main` / `master` / `origin/HEAD`, overridable with `--trunk`), and records `{ branch, parentBranch }` in CLI-managed state under **`~/.mergestorm/stacks/<repo-id>/stack.json`**. The CLI updates this automatically; never edit it. Linked worktrees share state, while independent clones remain isolated. Creating onto trunk with a non-empty active stack starts a new one. `--trunk` only sets trunk metadata — it does **not** change the parent; use `--onto main` (etc.) for a fresh stack from trunk.
 
-`stack create` is local-only: it checks out a new branch from the current tip (or `--onto <branch>`), discovers trunk (`main` / `master` / `origin/HEAD`, overridable with `--trunk`), and records `{ branch, parentBranch }` in CLI-managed state under **`~/.mergestorm/stacks/<repo-id>/stack.json`**. The CLI updates this automatically; never edit it. Linked worktrees share state, while independent clones remain isolated. Creating onto trunk with a non-empty active stack starts a new one. No repository file, GitHub call, or API call is made.
+If the parent branch is already a layer of a **registered** (submitted) stack, `create` and `submit` refuse unless you pass **`--extend`**. That blocks accidentally gluing an unrelated PR onto an open unit. Growing a registered stack on purpose: `mg stack create --onto <tip> --extend` → commit → `mg stack submit --extend`.
 
 `stack submit` walks the **active** local stack: `git push -u origin` each layer, opens a PR with `gh` (`--base` = parent or trunk; skips heads that already have an open PR; body from the tip commit — Summary + Test plan, preserving Fixes/Closes/Resolves), registers the stack with `POST /api/v1/stacks/adopt` internally (Mergestorm API key), then drops that local stack entry so the next create onto trunk is clean. Push/PR auth is your local `git` + `gh auth` — not a GitHub App installation token.
 
@@ -118,19 +119,38 @@ Removes `~/.mergestorm/config.json` so the stored key is no longer used.
 
 ### `review [base] [head]`
 
-Collects `git diff base...head` (default: discovered trunk — `origin/HEAD`, `main`, or `master`), attaches the changed file contents (up to 40 files, skipping files > 400 KB), submits the job, and polls until it finishes (~3 min max). The thread slug is derived from the current branch (`local/<branch>`), so repeated runs on the same branch chain their findings. Programmatic callers can provide explicit review context through the Review Jobs API.
+Collects `git diff base...head` (default: discovered trunk — `origin/HEAD`, `main`, or `master`), attaches the changed file contents (up to 40 files, skipping files > 400 KB), submits the job, and polls until it finishes (~8 min max — Core plus a Max fleet can exceed 3 minutes). The thread slug defaults to the current branch (`local/<branch>`); pass `--thread` to override so follow-ups chain on a chosen slug. The CLI does not scan `.mergestorm/context/`.
 
 ```bash
 mergestorm review              # discovered trunk (origin/HEAD, main, or master)...HEAD
 mergestorm review develop      # develop...HEAD
 mergestorm review main feat/x  # main...feat/x
+mergestorm review main --router max
+mergestorm review main --router manual --specialists security,frontend
+mergestorm review --json --context "focus on auth" --context-file docs/adr/007.md
 ```
 
-Exit code is non-zero on quota limit (402), submission failure, a `failed`/`quota_exceeded` job, or a poll timeout. In the interactive shell, Ctrl+C during the wait detaches (job keeps running) — use `status <job_id>` later.
+`--router` is the same smart-router mode as Agents settings (`off` / `standard` / `max` / `manual`). `--specialists` pins or invokes lanes on that request (comma-separated). Omit both to use the signed-in user's saved fleet settings (paid default is Standard, same as the dashboard). Manual accepts up to 5 lane ids — the same cap as Agents (the smart router caps `standard` at 3 and `max` at 5).
+
+`--context` is author guidance (or `--context -` to read stdin). `--context-file` is repeatable up to 10 files (16 KB each, 60 KB total). `--idempotency-key` replays a prior 202 for the same key. `--webhook-url` must be https; the one-time `webhook_secret` is printed only in `--json` output. Webhook delivery is best-effort (no retry).
+
+Exit codes for `review` and `status`:
+
+| Exit | Meaning |
+|------|---------|
+| 0 | Success (`completed` or `no_changes`) |
+| 2 | Usage / bad flags |
+| 3 | Quota (`402` or `quota_exceeded`) |
+| 4 | Failed job or other submission error |
+| 5 | Poll / request timeout |
+| 6 | Auth (missing or invalid API key) |
+| 7 | Rate limited (`429`) — wait `retry_after_seconds`, or check a running review with `mergestorm jobs` / `status` |
+
+In the interactive shell, Ctrl+C during the wait detaches (job keeps running) — use `status <job_id>` later.
 
 ### `status <job_id>`
 
-Fetches a job by id and prints the raw JSON (status, verdict, summary, findings). In the shell, output is formatted for reading.
+Fetches a job by id. One-shot default (and `--json` in either mode) prints the same `mergestorm.review_job/v1` object as `review --json`. `--wait [--timeout seconds]` polls until the job finishes; timeout is exit 5 with the id in the object. In the shell, default output is pretty (requested vs run specialists and credits).
 
 ### `credits` / `jobs` / `whoami`
 
@@ -148,6 +168,29 @@ Require a logged-in key and API support for `GET /api/v1/me` and `GET /api/v1/re
 | `MERGESTORM_API_URL` | API base URL | `https://api.mergestorm.ai` |
 | `NO_COLOR` | Disable ANSI colors | — |
 
+## Verify (public source vs npm)
+
+Build **only** from [marginsystems/mergestorm-cli](https://github.com/marginsystems/mergestorm-cli). Tags there (`vX.Y.Z`) match npm versions. Compare your local pack to the registry hashes below (or `npm view mergestorm@VERSION dist`).
+
+| npm | Public git tag | Public commit | npm `dist.shasum` (sha1) | npm `dist.integrity` |
+|-----|----------------|---------------|--------------------------|----------------------|
+| `0.3.9` | [`v0.3.9`](https://github.com/marginsystems/mergestorm-cli/tree/v0.3.9) | `89eaebc29cf793db52baf3e9af0f2bed6e42e458` | `f904f4f642a07c0f9716fe36ed9e5a813be47530` | `sha512-zkbEhwkog13xC70LcM77bWFzLTyoE7Q81daaxz/1Gk3IqVyEoyhKpR+PAtfTp+Mk3MqJ7yVhvZ8/9UG4hpT/Dw==` |
+
+```bash
+git clone https://github.com/marginsystems/mergestorm-cli.git
+cd mergestorm-cli
+git checkout v0.3.9
+git rev-parse HEAD   # expect 89eaebc29cf793db52baf3e9af0f2bed6e42e458
+npm ci
+npm run build
+npm pack
+shasum -a 1 mergestorm-0.3.9.tgz
+# expect f904f4f642a07c0f9716fe36ed9e5a813be47530
+# also: npm view mergestorm@0.3.9 dist.shasum dist.integrity
+```
+
+After each release, the new row’s git commit is the public `v*` tag tip; shasum/integrity come from the npm registry for that version.
+
 ## See also
 
 - [Public source — mergestorm-cli](https://github.com/marginsystems/mergestorm-cli)

package/dist/api.d.ts

@@ -1,4 +1,6 @@
 import { type Config } from "./config.js";
+import type { MergeQueueEntryDto, StackDto } from "./stack-dto.js";
+export type { MergeQueueBounceDetail, MergeQueueBounceKind, MergeQueueEnqueuedBy, MergeQueueEnqueuedVia, MergeQueueEntryDto, MergeQueueEntryState, StackBranchState, StackCiStatus, StackDto, StackLayerChecks, StackLayerDto, StackReviewStatus, StackTempestStatus, StackUnitDto, StackUnitMemberDto, } from "./stack-dto.js";
 /** Default per-request timeout so a hung API cannot stall the shell/CI forever. */
 export declare const DEFAULT_API_TIMEOUT_MS = 30000;
 /** Message prefix of the CommandError thrown when a request exceeds its timeout. */
@@ -8,10 +10,17 @@ export type ApiFetchInit = RequestInit & {
     /** Override {@link DEFAULT_API_TIMEOUT_MS}. */
     timeoutMs?: number;
 };
-export declare function apiFetch(cfg: Config, route: string, init?: ApiFetchInit): Promise<{
+export type ApiFetchResult = {
     status: number;
     body: unknown;
-}>;
+    retryAfterSeconds?: number;
+};
+/** Prefer the larger of `Retry-After` and JSON `retry_after_seconds`. */
+export declare function parseRetryAfterSeconds(input: {
+    header?: string | null;
+    body?: unknown;
+}): number | undefined;
+export declare function apiFetch(cfg: Config, route: string, init?: ApiFetchInit): Promise<ApiFetchResult>;
 export declare function devicePost(base: string, route: string, json: unknown, opts?: {
     timeoutMs?: number;
     signal?: AbortSignal;
@@ -28,7 +37,7 @@ export type MeResponse = {
     };
     plan_key: string;
     plan_label_key?: string;
-    /** Start of next UTC month (usage meters reset). Older APIs omit this. */
+    /** When the current credit window ends (signup anniversary or Stripe period). Older APIs omit this. */
     resets_at?: string;
     usage: {
         standard: {
@@ -36,11 +45,6 @@ export type MeResponse = {
             limit: number | null;
             remaining: number | null;
         };
-        premium: {
-            used: number;
-            limit: number | null;
-            remaining: number | null;
-        };
     };
 };
 export type JobListItem = {
@@ -53,7 +57,9 @@ export type JobListItem = {
     head_label: string | null;
     created_at: string;
     finished_at: string | null;
-    credits: number;
+    credits: {
+        standard: number;
+    } | null;
 };
 export type ThreadListItem = {
     slug: string;
@@ -88,50 +94,110 @@ export type ThreadDetail = {
         finished_at?: string | null;
     }[];
 };
-/** Fetch /api/v1/me; returns null on 404/network so callers can degrade. */
-export declare function getMe(cfg?: Config, opts?: {
-    timeoutMs?: number;
-}): Promise<MeResponse | null>;
-export declare function listJobs(limit?: number, cfg?: Config): Promise<JobListItem[]>;
-export type StackLayerDto = {
-    branch: string;
-    parentBranch: string | null;
-    prNumber: number;
-    position: number;
-    state: string;
-    title: string | null;
-    htmlUrl: string | null;
-    ciStatus: string;
-    reviewStatus: string;
-    checks: {
-        total: number;
-        success: number;
-        pending: number;
-        failure: number;
-        failingName: string | null;
-    } | null;
-    conflictDetail: string | null;
-    lastRestackedSha: string | null;
+export type PrReviewFinding = {
+    path?: string;
+    line?: number;
+    severity: string;
+    body: string;
+    title?: string;
+    specialist?: string;
 };
-export type StackDto = {
+export type PrReviewFindings = {
+    specialists_run?: string[];
+    inline?: PrReviewFinding[];
+    off_diff?: PrReviewFinding[];
+    offDiff?: PrReviewFinding[];
+    patchPolicy?: unknown;
+};
+export type PrVortexReview = {
+    schema: "mergestorm.pr_review/v1";
     id: string;
     owner: string;
     repo: string;
-    trunkBranch: string;
-    autoPromoteWhenGreen: boolean;
-    layers: StackLayerDto[];
+    pr_number: number;
+    status: string;
+    raw_status?: string;
+    phase: string | null;
+    verdict: string | null;
+    summary?: string | null;
+    head_sha: string | null;
+    review_count: number;
+    skip_reason: string | null;
+    reviewed_at: string | null;
+    finding_count: number;
+    findings: PrReviewFindings | null;
+    patch_policy: unknown | null;
+};
+/**
+ * Bearer-writable settings keys, mirroring the `/api/v1/settings` allowlist.
+ * The connected flags are read-only there and deliberately absent here.
+ */
+export declare const SETTINGS_WRITABLE_KEYS: readonly ["auto_review_enabled", "auto_patch_enabled", "vortex_show_thinking_traces", "repo_overview_enabled", "review_unit_land_prs_enabled", "cyclone_review_unit_land_prs_enabled", "vortex_seam_specialist_enabled"];
+export type SettingsWritableKey = (typeof SETTINGS_WRITABLE_KEYS)[number];
+export type SettingsPatch = Partial<Record<SettingsWritableKey, boolean>>;
+/** GET and PATCH `/api/v1/settings` both answer with this shape. */
+export type SettingsResponse = Record<SettingsWritableKey, boolean> & {
+    cyclone_connected: boolean;
+    github_connected: boolean;
 };
+/**
+ * Fetch Bearer /api/v1/settings; null on 404/network/timeouts so panels can
+ * degrade (same contract as {@link getMe}), while 401 still surfaces.
+ */
+export declare function getSettings(cfg?: Config, opts?: {
+    timeoutMs?: number;
+}): Promise<SettingsResponse | null>;
+/**
+ * PATCH Bearer /api/v1/settings and return the stored result. Rejections
+ * (unknown key, cyclone_not_connected, …) surface the API's own `message`
+ * so the CLI never invents a reason.
+ */
+export declare function patchSettings(patch: SettingsPatch, cfg?: Config, opts?: {
+    timeoutMs?: number;
+}): Promise<SettingsResponse>;
+/** Fetch /api/v1/me; returns null on 404/network so callers can degrade. */
+export declare function getMe(cfg?: Config, opts?: {
+    timeoutMs?: number;
+}): Promise<MeResponse | null>;
+export declare function listJobs(limit?: number, cfg?: Config, opts?: {
+    timeoutMs?: number;
+}): Promise<JobListItem[]>;
+/** Fetch one review job (Bearer GET /api/v1/reviews/:id). */
+export declare function getReview(jobId: string, cfg?: Config, opts?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<unknown>;
+/** Fetch the latest Vortex pass for one GitHub PR. */
+export declare function getPrVortexReview(owner: string, repo: string, prNumber: number, cfg?: Config, opts?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<PrVortexReview>;
 /** List stacks (Bearer GET /api/v1/stacks). */
-export declare function listStacks(cfg?: Config): Promise<StackDto[]>;
+export declare function listStacks(cfg?: Config, opts?: {
+    timeoutMs?: number;
+}): Promise<StackDto[]>;
+/** Fetch one owned stack with enriched GitHub checks and agent state. */
+export declare function getEnrichedStack(stackId: string, cfg?: Config, opts?: {
+    timeoutMs?: number;
+}): Promise<StackDto | null>;
 /** Adopt an open PR chain (Bearer POST /api/v1/stacks/adopt). */
 export declare function adoptStack(owner: string, repo: string, prNumber: number, cfg?: Config): Promise<unknown>;
+/** Mint or reuse the PR3+ park freeze (Bearer POST /api/v1/stacks/:id/ensure-upper-park). */
+export declare function ensureUpperPark(stackId: string, cfg?: Config): Promise<{
+    freezeBranch: string;
+    created: boolean;
+}>;
 /** Restack descendants (Bearer POST /api/v1/stacks/:id/restack). */
 export declare function restackStack(stackId: string, cfg?: Config): Promise<unknown>;
 /** Land the bottom open layer (Bearer POST /api/v1/stacks/:id/land-next). */
 export declare function landNextStack(stackId: string, cfg?: Config, opts?: {
     prNumber?: number;
 }): Promise<unknown>;
-/** Toggle auto-promote when green (Bearer PATCH /api/v1/stacks/:id). */
-export declare function setStackAutoPromote(stackId: string, autoPromoteWhenGreen: boolean, cfg?: Config): Promise<unknown>;
+/** List the authenticated user's live merge-queue entries. */
+export declare function listMergeQueueEntries(cfg?: Config): Promise<MergeQueueEntryDto[]>;
+/** Enqueue a stack for verified landing. */
+export declare function enqueueStack(stackId: string, cfg?: Config): Promise<unknown>;
+/** Cancel a live merge-queue entry by entry id. */
+export declare function cancelMergeQueueEntry(entryId: string, cfg?: Config): Promise<unknown>;
 /** Recently reviewed branches/threads (Bearer GET /api/v1/threads). */
 export declare function listThreads(limit?: number, cfg?: Config): Promise<ThreadListItem[]>;