mergestorm 0.3.8 → 0.3.13

package/dist/commands/review-client.d.ts

@@ -0,0 +1,93 @@
+import type { Config } from "../config.js";
+import type { ReviewJobRow } from "../ui/job-envelope.js";
+export declare const REVIEW_POLL_INTERVAL_MS = 2000;
+export declare const REVIEW_POLL_DEFAULT_TIMEOUT_MS = 480000;
+export declare const REVIEW_POLL_MAX_TRANSIENT_RETRIES = 3;
+export declare const REVIEW_POLL_BACKOFF_MS = 250;
+export declare const REVIEW_POLL_MAX_INTERVAL_MS = 5000;
+export declare const REVIEW_POLL_STRETCH_AFTER_MS = 60000;
+export declare const REVIEW_POLL_STRETCH_SPAN_MS = 60000;
+/** Same thread slug contract as POST /api/v1/reviews. */
+export declare const REVIEW_THREAD_SLUG_RE: RegExp;
+export declare const MAX_CONTEXT_TEXT_CHARS = 60000;
+export declare const MAX_CONTEXT_FILES = 10;
+export declare const MAX_CONTEXT_FILE_CHARS = 16000;
+export declare const MAX_CONTEXT_FILES_TOTAL = 60000;
+export declare const MAX_IDEMPOTENCY_KEY_CHARS = 128;
+export type ReviewInput = {
+    thread: string;
+    branch: string;
+    repo?: string;
+    baseLabel: string;
+    headLabel: string;
+    diff: string;
+    files: {
+        path: string;
+        content: string;
+    }[];
+};
+export declare function collectReviewInput(base: string, head: string, cwd?: string, sandboxRoot?: string): Promise<ReviewInput | null>;
+export type SubmitReviewOptions = {
+    routerMode?: string;
+    specialists?: string[];
+    context?: string;
+    contextFiles?: {
+        path: string;
+        content: string;
+    }[];
+    idempotencyKey?: string;
+    webhookUrl?: string;
+    signal?: AbortSignal;
+};
+export type ReviewContextPayload = {
+    context?: string;
+    contextFiles?: {
+        path: string;
+        content: string;
+    }[];
+};
+export type LoadReviewContextOptions = {
+    context?: string;
+    contextFiles: string[];
+    cwd?: string;
+    readStdin?: () => Promise<string>;
+    /** Reject contextFiles that resolve outside this directory (agent-driven callers). */
+    sandboxCwd?: string;
+};
+/** Load --context / --context-file and enforce the API caps client-side. */
+export declare function loadReviewContext(opts: LoadReviewContextOptions): Promise<ReviewContextPayload>;
+export declare function submitReview(cfg: Config, input: ReviewInput, opts?: SubmitReviewOptions): Promise<{
+    status: number;
+    row: ReviewJobRow;
+    retryAfterSeconds?: number;
+}>;
+/** Exponential backoff with jitter in `[0.5, 1.0]` of the base delay. */
+export declare function transientRetryWaitMs(input: {
+    retryAfterSeconds?: number;
+    failureCount: number;
+    random?: () => number;
+}): number;
+/** Keep the default 2s cadence for a minute, then ramp toward 5s. */
+export declare function stretchedPollIntervalMs(elapsedMs: number, intervalMs: number): number;
+export declare function isTransientReviewPollStatus(status: number): boolean;
+export declare function isTransientReviewPollError(err: unknown): boolean;
+export declare class ReviewPollTimeoutError extends Error {
+    readonly jobId: string;
+    readonly lastRow: ReviewJobRow;
+    constructor(jobId: string, lastRow: ReviewJobRow);
+}
+export type PollReviewOptions = {
+    timeoutMs?: number;
+    intervalMs?: number;
+    signal?: AbortSignal;
+    onTick?: (kind: "progress" | "retry") => void;
+    /** Rethrow per-request api_timeout instead of folding it into a poll timeout (interactive detach). */
+    propagateTimeout?: boolean;
+    /** Test seam; production uses `setTimeout`. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Test seam; production uses `Date.now`. */
+    now?: () => number;
+    /** Test seam for backoff jitter; production uses `Math.random`. */
+    random?: () => number;
+};
+export declare function pollReview(cfg: Config, jobId: string, opts?: PollReviewOptions): Promise<ReviewJobRow>;

package/dist/commands/review-client.js

@@ -0,0 +1,289 @@
+import { readFile, realpath } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { apiFetch } from "../api.js";
+import { CommandError, REVIEW_EXIT, isCommandErrorCode, rateLimitedMessage } from "../errors.js";
+import { changedNamesInSandbox, collectChangedFiles, git, parseGithubOriginRepo, repoRoot, } from "../git.js";
+export const REVIEW_POLL_INTERVAL_MS = 2_000;
+export const REVIEW_POLL_DEFAULT_TIMEOUT_MS = 480_000;
+export const REVIEW_POLL_MAX_TRANSIENT_RETRIES = 3;
+export const REVIEW_POLL_BACKOFF_MS = 250;
+export const REVIEW_POLL_MAX_INTERVAL_MS = 5_000;
+export const REVIEW_POLL_STRETCH_AFTER_MS = 60_000;
+export const REVIEW_POLL_STRETCH_SPAN_MS = 60_000;
+/** Same thread slug contract as POST /api/v1/reviews. */
+export const REVIEW_THREAD_SLUG_RE = /^[a-zA-Z0-9][a-zA-Z0-9._/-]{0,119}$/;
+export const MAX_CONTEXT_TEXT_CHARS = 60_000;
+export const MAX_CONTEXT_FILES = 10;
+export const MAX_CONTEXT_FILE_CHARS = 16_000;
+export const MAX_CONTEXT_FILES_TOTAL = 60_000;
+export const MAX_IDEMPOTENCY_KEY_CHARS = 128;
+export async function collectReviewInput(base, head, cwd = process.cwd(), sandboxRoot) {
+    let diff;
+    try {
+        const names = await changedNamesInSandbox(base, head, cwd, sandboxRoot);
+        if (names.length === 0) {
+            diff = "";
+        }
+        else {
+            const root = repoRoot(cwd);
+            const specs = names.map((name) => `:(literal)${relative(cwd, join(root, name))}`);
+            diff = git(["diff", `${base}...${head}`, "--", ...specs], cwd);
+        }
+    }
+    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.`, 2, "usage");
+    }
+    if (!diff.trim())
+        return null;
+    const files = await collectChangedFiles(base, head, cwd, sandboxRoot);
+    const branch = git(["rev-parse", "--abbrev-ref", "HEAD"], cwd).trim() || "local";
+    const thread = `local/${branch}`.replace(/[^a-zA-Z0-9._/-]/g, "-").slice(0, 120);
+    const originRepo = parseGithubOriginRepo(cwd);
+    return {
+        thread,
+        branch,
+        ...(originRepo ? { repo: `${originRepo.owner}/${originRepo.repo}` } : {}),
+        baseLabel: base,
+        headLabel: head,
+        diff,
+        files,
+    };
+}
+async function defaultReadStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+function contextUsage(message) {
+    return new CommandError(message, REVIEW_EXIT.usage, "usage");
+}
+/** Load --context / --context-file and enforce the API caps client-side. */
+export async function loadReviewContext(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    let context;
+    if (opts.context !== undefined) {
+        const raw = opts.context === "-"
+            ? await (opts.readStdin ?? defaultReadStdin)()
+            : opts.context;
+        context = raw.trim();
+        if (!context) {
+            throw contextUsage("--context is empty");
+        }
+        if (context.length > MAX_CONTEXT_TEXT_CHARS) {
+            throw contextUsage(`--context is ${context.length} chars; max is ${MAX_CONTEXT_TEXT_CHARS}`);
+        }
+    }
+    if (opts.contextFiles.length > MAX_CONTEXT_FILES) {
+        throw contextUsage(`--context-file may be repeated at most ${MAX_CONTEXT_FILES} times`);
+    }
+    const contextFiles = [];
+    let total = 0;
+    for (const rawPath of opts.contextFiles) {
+        const abs = resolve(cwd, rawPath);
+        if (opts.sandboxCwd) {
+            let sandboxReal;
+            let targetReal;
+            try {
+                [sandboxReal, targetReal] = await Promise.all([
+                    realpath(resolve(opts.sandboxCwd)),
+                    realpath(abs),
+                ]);
+            }
+            catch {
+                throw contextUsage(`--context-file ${rawPath} must be inside the working directory`);
+            }
+            const relToSandbox = relative(sandboxReal, targetReal);
+            if (relToSandbox === ".." || relToSandbox.startsWith(`..${sep}`)) {
+                throw contextUsage(`--context-file ${rawPath} must be inside the working directory`);
+            }
+        }
+        let content;
+        try {
+            content = await readFile(abs, "utf8");
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            throw contextUsage(`could not read --context-file ${rawPath}: ${detail}`);
+        }
+        if (content.length > MAX_CONTEXT_FILE_CHARS) {
+            throw contextUsage(`--context-file ${rawPath} is ${content.length} chars; max is ${MAX_CONTEXT_FILE_CHARS} per file`);
+        }
+        total += content.length;
+        if (total > MAX_CONTEXT_FILES_TOTAL) {
+            throw contextUsage(`--context-file total is ${total} chars; max is ${MAX_CONTEXT_FILES_TOTAL}`);
+        }
+        contextFiles.push({ path: relative(cwd, abs), content });
+    }
+    return {
+        ...(context ? { context } : {}),
+        ...(contextFiles.length > 0 ? { contextFiles } : {}),
+    };
+}
+export async function submitReview(cfg, input, opts = {}) {
+    const { status, body, retryAfterSeconds } = await apiFetch(cfg, "/api/v1/reviews", {
+        method: "POST",
+        json: {
+            thread: input.thread,
+            branch: input.branch,
+            ...(input.repo ? { repo: input.repo } : {}),
+            base_label: input.baseLabel,
+            head_label: input.headLabel,
+            diff: input.diff,
+            files: input.files,
+            ...(opts.routerMode ? { router_mode: opts.routerMode } : {}),
+            ...(opts.specialists?.length ? { specialists: opts.specialists } : {}),
+            ...(opts.context ? { context: opts.context } : {}),
+            ...(opts.contextFiles?.length ? { context_files: opts.contextFiles } : {}),
+            ...(opts.idempotencyKey ? { idempotency_key: opts.idempotencyKey } : {}),
+            ...(opts.webhookUrl ? { webhook_url: opts.webhookUrl } : {}),
+        },
+        signal: opts.signal,
+    });
+    return {
+        status,
+        row: body && typeof body === "object" ? body : {},
+        ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {}),
+    };
+}
+/** Exponential backoff with jitter in `[0.5, 1.0]` of the base delay. */
+export function transientRetryWaitMs(input) {
+    const exp = REVIEW_POLL_BACKOFF_MS * 2 ** Math.max(0, input.failureCount - 1);
+    const jitter = 0.5 + (input.random ?? Math.random)() * 0.5;
+    const backoff = Math.min(REVIEW_POLL_MAX_INTERVAL_MS, Math.round(exp * jitter));
+    const fromHeader = input.retryAfterSeconds != null && Number.isFinite(input.retryAfterSeconds)
+        ? Math.round(input.retryAfterSeconds * 1000)
+        : 0;
+    return Math.max(fromHeader, backoff);
+}
+/** Keep the default 2s cadence for a minute, then ramp toward 5s. */
+export function stretchedPollIntervalMs(elapsedMs, intervalMs) {
+    if (intervalMs !== REVIEW_POLL_INTERVAL_MS)
+        return intervalMs;
+    if (elapsedMs < REVIEW_POLL_STRETCH_AFTER_MS)
+        return intervalMs;
+    const t = Math.min(1, (elapsedMs - REVIEW_POLL_STRETCH_AFTER_MS) / REVIEW_POLL_STRETCH_SPAN_MS);
+    return Math.round(intervalMs + t * (REVIEW_POLL_MAX_INTERVAL_MS - intervalMs));
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(Object.assign(new Error("Aborted"), { name: "AbortError" }));
+            return;
+        }
+        const cleanup = () => signal?.removeEventListener("abort", onAbort);
+        const timer = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            cleanup();
+            reject(Object.assign(new Error("Aborted"), { name: "AbortError" }));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+export function isTransientReviewPollStatus(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+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);
+}
+export class ReviewPollTimeoutError extends Error {
+    jobId;
+    lastRow;
+    constructor(jobId, lastRow) {
+        super(`Timed out waiting for review ${jobId}`);
+        this.name = "ReviewPollTimeoutError";
+        this.jobId = jobId;
+        this.lastRow = lastRow;
+    }
+}
+export async function pollReview(cfg, jobId, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? REVIEW_POLL_DEFAULT_TIMEOUT_MS;
+    const intervalMs = opts.intervalMs ?? REVIEW_POLL_INTERVAL_MS;
+    const now = opts.now ?? Date.now;
+    const wait = opts.sleep ?? sleep;
+    const startedAt = now();
+    const deadline = startedAt + timeoutMs;
+    let transientFailures = 0;
+    let lastRow = { job_id: jobId, status: "queued" };
+    const sleepBeforeRetry = async (retryAfterSeconds) => {
+        const waitMs = Math.min(transientRetryWaitMs({
+            retryAfterSeconds,
+            failureCount: transientFailures,
+            random: opts.random,
+        }), Math.max(0, deadline - now()));
+        if (waitMs > 0)
+            await wait(waitMs, opts.signal);
+    };
+    while (now() < deadline) {
+        let poll;
+        try {
+            poll = await apiFetch(cfg, `/api/v1/reviews/${jobId}`, {
+                signal: opts.signal,
+                timeoutMs: Math.max(1, Math.min(30_000, deadline - now())),
+            });
+        }
+        catch (err) {
+            if (isTransientReviewPollError(err) &&
+                transientFailures < REVIEW_POLL_MAX_TRANSIENT_RETRIES) {
+                transientFailures += 1;
+                opts.onTick?.("retry");
+                await sleepBeforeRetry();
+                continue;
+            }
+            if (isCommandErrorCode(err, "api_timeout")) {
+                if (opts.propagateTimeout)
+                    throw err;
+                break;
+            }
+            if (isTransientReviewPollError(err)) {
+                const detail = err instanceof Error ? err.message : String(err);
+                throw new CommandError(`Poll failed: ${detail}`, REVIEW_EXIT.failed, "review_failed");
+            }
+            throw err;
+        }
+        if (poll.status !== 200) {
+            if (isTransientReviewPollStatus(poll.status) &&
+                transientFailures < REVIEW_POLL_MAX_TRANSIENT_RETRIES) {
+                transientFailures += 1;
+                opts.onTick?.("retry");
+                await sleepBeforeRetry(poll.retryAfterSeconds);
+                continue;
+            }
+            if (poll.status === 429) {
+                const message = rateLimitedMessage(poll.retryAfterSeconds);
+                throw new CommandError(message, REVIEW_EXIT.rate_limited, "rate_limited", {
+                    retryAfterSeconds: poll.retryAfterSeconds,
+                });
+            }
+            throw new CommandError(`Poll failed: ${JSON.stringify(poll.body, null, 2)}`, REVIEW_EXIT.failed, "review_failed");
+        }
+        transientFailures = 0;
+        lastRow =
+            poll.body && typeof poll.body === "object"
+                ? { ...poll.body, job_id: jobId }
+                : { job_id: jobId, status: "failed", error: "Invalid review response" };
+        if (lastRow.status === "queued" || lastRow.status === "in_progress") {
+            opts.onTick?.("progress");
+            const waitMs = Math.min(stretchedPollIntervalMs(now() - startedAt, intervalMs), Math.max(0, deadline - now()));
+            if (waitMs > 0)
+                await wait(waitMs, opts.signal);
+            continue;
+        }
+        return lastRow;
+    }
+    throw new ReviewPollTimeoutError(jobId, lastRow);
+}

package/dist/commands/review.d.ts

@@ -1,20 +1,44 @@
+import { REVIEW_POLL_MAX_TRANSIENT_RETRIES, isTransientReviewPollError, isTransientReviewPollStatus } from "./review-client.js";
+export { REVIEW_POLL_MAX_TRANSIENT_RETRIES, isTransientReviewPollError, isTransientReviewPollStatus, };
+/** Same public specialist allowlist as the API contract and migration 117. */
+export declare const VORTEX_ROUTER_MODES: readonly ["off", "standard", "max", "manual"];
+/** Standard/Max fleet caps; Manual is capped at Max. */
+export declare const VORTEX_ROUTER_CAPS: {
+    readonly standard: 3;
+    readonly max: 5;
+};
+export declare const VORTEX_SPECIALIST_IDS: readonly ["security", "performance", "architecture", "tests", "data", "api", "frontend"];
+type VortexRouterMode = (typeof VORTEX_ROUTER_MODES)[number];
+type VortexSpecialistId = (typeof VORTEX_SPECIALIST_IDS)[number];
 /**
  * Diff base when the user omits args[0]. Prefers origin/HEAD / main / master
  * via discoverTrunk (same as stack create) instead of hardcoding "main".
  */
+export type ParsedReviewArgs = {
+    base?: string;
+    head?: string;
+    router?: VortexRouterMode;
+    specialists: VortexSpecialistId[];
+    format: "pretty" | "json";
+    wait: boolean;
+    timeoutMs: number;
+    context?: string;
+    contextFiles: string[];
+    idempotencyKey?: string;
+    webhookUrl?: string;
+    thread?: string;
+};
+/** Parse the human and machine-safe `review` flags. */
+export declare function parseReviewArgs(args: string[]): ParsedReviewArgs;
 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;
+    /** Test seam; production uses the two-second poll interval. */
+    pollIntervalMs?: number;
 };
-/** 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>;