mergestorm 0.3.9 → 0.3.13

package/dist/commands/stack.js

@@ -1,16 +1,17 @@
-import { adoptStack, landNextStack, listStacks, restackStack, setStackAutoPromote, } from "../api.js";
+import { adoptStack, ensureUpperPark, landNextStack, listStacks, restackStack, setStackAutoPromote, } from "../api.js";
 import { loadConfig } from "../config.js";
 import { CommandError } from "../errors.js";
 import { createPr, findOpenPrNumber, requireGh } from "../gh.js";
 import { parseGithubOriginRepo } from "../git.js";
-import { branchExists, commitsAheadOf, createBranchFromHead, currentBranch, defaultLayerBranchName, deleteBranch, discoverTrunk, pushBranch, tipCommitMessage, tipCommitSubject, worktreeDirty, } from "../git-stack.js";
+import { branchExists, commitsAheadOf, createBranchFromHead, currentBranch, defaultLayerBranchName, deleteBranch, discoverTrunk, fetchRemoteBranch, 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 { isMgParkBranch, planSubmitLayerBases } from "../submit-pr-base.js";
 import { ansi } from "../ui/ansi.js";
 const STACK_USAGE = `usage:
-  mergestorm stack create [name] [--onto <branch>] [--trunk <branch>] [--json]
-  mergestorm stack submit [--json]
+  mergestorm stack create [name] [--onto <branch>] [--trunk <branch>] [--extend] [--json]
+  mergestorm stack submit [--extend] [--json]
   mergestorm stack reset --force
   mergestorm stack list [--json]
   mergestorm stack adopt <owner/repo>#<pr>
@@ -19,8 +20,55 @@ const STACK_USAGE = `usage:
   mergestorm stack auto-promote on|off <stack-id> [--json]
 
   stack submit opens PRs with a body generated from each layer tip commit.
-  stack land promotes into the review unit when one exists; otherwise lands
-  the bottom open PR (unit-less stacks).`;
+  Layers 1–2 use the git parent as GitHub base. Layer 3+ opens onto the
+  review-unit park freeze (mg-park-*) so adopt does not retarget after open.
+  Parenting onto a branch that already belongs to a registered (submitted)
+  stack requires --extend on create and submit — otherwise mg starts a new
+  stack from trunk. stack land promotes into the review unit when one exists;
+  otherwise lands the bottom open PR (unit-less stacks).`;
+/** Cap the registered-stack guard's API probe so it cannot stall local authoring. */
+const STACK_GUARD_TIMEOUT_MS = 8_000;
+/** Find a registered stack layer whose branch matches `parentBranch`. */
+export function findRegisteredParent(stacks, parentBranch, owner, repo) {
+    const want = parentBranch.trim();
+    if (!want)
+        return null;
+    for (const s of stacks) {
+        if (owner !== undefined && repo !== undefined) {
+            if (s.owner !== owner || s.repo !== repo)
+                continue;
+        }
+        for (const layer of s.layers) {
+            if (layer.branch === want) {
+                return {
+                    stackId: s.id,
+                    owner: s.owner,
+                    repo: s.repo,
+                    branch: layer.branch,
+                    prNumber: layer.prNumber,
+                    position: layer.position,
+                };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Refuse silently growing an already-registered stack.
+ * Local unsubmitted parents are fine; only API-listed layers trip this.
+ */
+export function assertMayParentOntoRegistered(parentBranch, stacks, extend, verb, owner, repo) {
+    const hit = findRegisteredParent(stacks, parentBranch, owner, repo);
+    if (!hit)
+        return null;
+    if (extend)
+        return hit;
+    const pr = hit.prNumber > 0 ? `PR #${hit.prNumber}` : "an open PR";
+    throw new CommandError(`Parent \`${hit.branch}\` is already layer ${hit.position} of registered stack ${hit.stackId} (${hit.owner}/${hit.repo}, ${pr}).\n` +
+        `Refusing to ${verb} a new layer onto that stack without an explicit opt-in.\n` +
+        `• New independent stack: check out trunk and pass \`--onto <trunk>\` (e.g. \`mg stack create --onto main\`).\n` +
+        `• Intentionally grow that stack: pass \`--extend\` on \`stack ${verb}\`.`, 1, "registered_parent");
+}
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 export function requireStackId(raw, usage) {
     const id = raw?.trim() ?? "";
@@ -70,6 +118,7 @@ export function parseStackCreateArgs(args) {
     let name;
     let onto;
     let trunk;
+    let extend = false;
     let asJson = false;
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
@@ -77,10 +126,15 @@ export function parseStackCreateArgs(args) {
             asJson = true;
             continue;
         }
+        if (a === "--extend") {
+            extend = true;
+            continue;
+        }
         if (a === "--onto") {
             const v = args[++i];
-            if (!v)
-                throw new CommandError("usage: mergestorm stack create [name] [--onto <branch>]");
+            if (!v) {
+                throw new CommandError("usage: mergestorm stack create [name] [--onto <branch>] [--trunk <branch>] [--extend]");
+            }
             onto = v;
             continue;
         }
@@ -90,8 +144,9 @@ export function parseStackCreateArgs(args) {
         }
         if (a === "--trunk") {
             const v = args[++i];
-            if (!v)
-                throw new CommandError("usage: mergestorm stack create [name] [--trunk <branch>]");
+            if (!v) {
+                throw new CommandError("usage: mergestorm stack create [name] [--onto <branch>] [--trunk <branch>] [--extend]");
+            }
             trunk = v;
             continue;
         }
@@ -103,20 +158,40 @@ export function parseStackCreateArgs(args) {
             throw new CommandError(`${STACK_USAGE}\nunknown flag: ${a}`);
         }
         if (name != null) {
-            throw new CommandError("usage: mergestorm stack create [name] [--onto <branch>] [--trunk <branch>]");
+            throw new CommandError("usage: mergestorm stack create [name] [--onto <branch>] [--trunk <branch>] [--extend]");
         }
         name = a;
     }
-    return { name, onto, trunk, asJson };
+    return { name, onto, trunk, extend, asJson };
+}
+/** Parse `stack submit` argv. Exported for tests. */
+export function parseStackSubmitArgs(args) {
+    let extend = false;
+    let asJson = false;
+    for (const a of args) {
+        if (a === "--json") {
+            asJson = true;
+            continue;
+        }
+        if (a === "--extend") {
+            extend = true;
+            continue;
+        }
+        throw new CommandError("usage: mergestorm stack submit [--extend] [--json]");
+    }
+    return { extend, asJson };
 }
 export function parseStackResetArgs(args) {
     if (args.length !== 1 || args[0] !== "--force") {
         throw new CommandError("usage: mergestorm stack reset --force\nClears only CLI-managed pre-submit state; branches, PRs, and registered stacks are unchanged.");
     }
 }
-async function cmdStackCreate(args) {
-    const { name, onto, trunk: trunkFlag, asJson } = parseStackCreateArgs(args);
-    const cwd = process.cwd();
+async function cmdStackCreate(args, deps = {}) {
+    const { name, onto, trunk: trunkFlag, extend, asJson } = parseStackCreateArgs(args);
+    const cwd = deps.cwd ?? process.cwd();
+    const listStacksFn = deps.listStacks ?? listStacks;
+    const loadConfigFn = deps.loadConfig ?? loadConfig;
+    const parseOriginFn = deps.parseGithubOriginRepo ?? parseGithubOriginRepo;
     try {
         gitTopLevel(cwd);
     }
@@ -145,6 +220,37 @@ async function cmdStackCreate(args) {
     else if (trunkFlag?.trim() && meta.trunk !== trunk) {
         throw new CommandError(`Stack trunk is ${meta.trunk}; refusing --trunk ${trunk}. Run \`mg stack reset --force\` to discard local pre-submit state.`);
     }
+    // --trunk only sets metadata; parent defaults to current branch. Call that out
+    // when someone passes --trunk while sitting on a different branch without --onto.
+    if (trunkFlag?.trim() && !onto?.trim() && parentBranch !== trunk) {
+        console.error(ansi.dim(`  note: --trunk ${trunk} does not change the parent; new layer parents onto \`${parentBranch}\`. ` +
+            `Pass \`--onto ${trunk}\` for a fresh stack from trunk.`));
+    }
+    // Block silent attach onto an already-submitted stack tip (requires --extend).
+    // --trunk is user metadata, so a registered tip must not be able to masquerade
+    // as trunk — always consult the stacks API rather than trusting parent === trunk.
+    // Best-effort: API/key failures degrade to a warning so create stays local.
+    const origin = parseOriginFn(cwd);
+    let registeredHit = null;
+    if (origin) {
+        try {
+            const cfg = await loadConfigFn();
+            const registered = await listStacksFn(cfg, { timeoutMs: STACK_GUARD_TIMEOUT_MS });
+            registeredHit = assertMayParentOntoRegistered(parentBranch, registered, extend, "create", origin.owner, origin.repo);
+        }
+        catch (err) {
+            if (err instanceof CommandError && err.code === "registered_parent")
+                throw err;
+            console.error(ansi.dim(`  warning: could not check registered stacks (${err instanceof Error ? err.message : String(err)}); ` +
+                `skipping --extend guard. Pass --extend if you intend to grow an open stack.`));
+        }
+    }
+    else {
+        console.error(ansi.dim("  warning: could not determine GitHub owner/repo from `origin`; skipping --extend guard. Pass --extend if you intend to grow an open stack."));
+    }
+    if (parentBranch === trunk && extend && !registeredHit) {
+        throw new CommandError("`--extend` is only valid when parenting onto a registered stack layer, not trunk. Omit --extend (or pass --onto <tip> --extend).");
+    }
     try {
         meta = selectStackForCreate(meta, parentBranch);
     }
@@ -174,6 +280,7 @@ async function cmdStackCreate(args) {
             branch,
             parentBranch,
             trunk: meta.trunk,
+            extend: Boolean(registeredHit),
             active: meta.active,
             stacks: meta.stacks.length,
             layers,
@@ -182,14 +289,15 @@ async function cmdStackCreate(args) {
         return;
     }
     console.log(ansi.green(`  Created ${branch} (onto ${parentBranch})`));
+    if (registeredHit) {
+        console.log(ansi.dim(`  extending registered stack ${registeredHit.stackId}` +
+            (registeredHit.prNumber > 0 ? ` (from #${registeredHit.prNumber})` : "")));
+    }
     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"));
 }
 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 { extend, asJson } = parseStackSubmitArgs(args);
     const cwd = deps.cwd ?? process.cwd();
     const gitTopLevelFn = deps.gitTopLevel ?? gitTopLevel;
     const loadStackMetaFn = deps.loadStackMeta ?? loadStackMeta;
@@ -197,6 +305,7 @@ export async function cmdStackSubmit(args, deps = {}) {
     const parseOriginFn = deps.parseGithubOriginRepo ?? parseGithubOriginRepo;
     const requireGhFn = deps.requireGh ?? requireGh;
     const branchExistsFn = deps.branchExists ?? branchExists;
+    const fetchRemoteBranchFn = deps.fetchRemoteBranch ?? fetchRemoteBranch;
     const pushBranchFn = deps.pushBranch ?? pushBranch;
     const findOpenPrNumberFn = deps.findOpenPrNumber ?? findOpenPrNumber;
     const commitsAheadOfFn = deps.commitsAheadOf ?? commitsAheadOf;
@@ -205,7 +314,9 @@ export async function cmdStackSubmit(args, deps = {}) {
     const buildPrBodyFn = deps.buildPrBodyFromCommit ?? buildPrBodyFromCommit;
     const createPrFn = deps.createPr ?? createPr;
     const loadConfigFn = deps.loadConfig ?? loadConfig;
+    const listStacksFn = deps.listStacks ?? listStacks;
     const adoptStackFn = deps.adoptStack ?? adoptStack;
+    const ensureUpperParkFn = deps.ensureUpperPark ?? ensureUpperPark;
     try {
         gitTopLevelFn(cwd);
     }
@@ -223,9 +334,41 @@ export async function cmdStackSubmit(args, deps = {}) {
     }
     const { owner, repo } = origin;
     requireGhFn(cwd);
-    const opened = [];
+    // Safety net: refuse submit that would open/register onto a registered tip
+    // without --extend. Check every layer's parent (mid-stack layers from older
+    // local state must not sail through), scoped to this repo, and fail closed
+    // when the API cannot be consulted — otherwise the attach happens anyway.
+    // meta.trunk is user metadata, so it must not exempt a registered tip from
+    // the check (a tip can masquerade as trunk via --trunk at create).
+    const parents = [...new Set(layers.map((l) => l.parentBranch || meta.trunk))];
+    let registeredHits = 0;
+    let registered = [];
+    try {
+        const cfg = await loadConfigFn();
+        registered = await listStacksFn(cfg, { timeoutMs: STACK_GUARD_TIMEOUT_MS });
+        for (const parent of parents) {
+            if (assertMayParentOntoRegistered(parent, registered, extend, "submit", owner, repo)) {
+                registeredHits += 1;
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof CommandError && err.code === "registered_parent")
+            throw err;
+        throw new CommandError(`Could not verify that the stack parents onto registered stacks (${err instanceof Error ? err.message : String(err)}); ` +
+            `refusing to submit. If a layer grows a registered stack, pass --extend (retry when the API is reachable).`);
+    }
+    if (extend && registeredHits === 0 && parents.every((p) => p === meta.trunk)) {
+        throw new CommandError("`--extend` is only valid when a layer parents onto a registered stack layer, not trunk.");
+    }
+    const plans = planSubmitLayerBases({
+        layers,
+        trunk: meta.trunk,
+        registered,
+        owner,
+        repo,
+    });
     for (const layer of layers) {
-        const base = layer.parentBranch || meta.trunk;
         if (!branchExistsFn(layer.branch, cwd)) {
             throw new CommandError(`Stack layer branch missing locally: ${layer.branch}`);
         }
@@ -236,58 +379,109 @@ export async function cmdStackSubmit(args, deps = {}) {
         catch (err) {
             throw new CommandError(err instanceof Error ? err.message : String(err));
         }
-        let prNumber = findOpenPrNumberFn(owner, repo, layer.branch, cwd);
-        let created = false;
-        if (prNumber == null) {
-            // 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;
+    }
+    const opened = [];
+    const pendingPark = plans.filter((plan) => {
+        if (findOpenPrNumberFn(owner, repo, plan.branch, cwd) != null)
+            return false;
+        return plan.githubBase == null;
+    });
+    const openLayerPr = (branch, base) => {
+        const existing = findOpenPrNumberFn(owner, repo, branch, cwd);
+        if (existing != null) {
+            console.log(ansi.dim(`  PR #${existing} already open for ${branch}`));
+            return { prNumber: existing, created: false };
+        }
+        const aheadRef = isMgParkBranch(base) ? `origin/${base}` : base;
+        if (isMgParkBranch(base)) {
             try {
-                ahead = commitsAheadOfFn(base, layer.branch, cwd);
+                fetchRemoteBranchFn(base, 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\`.`);
+                throw new CommandError(`Could not fetch park base \`${base}\` (${err instanceof Error ? err.message : String(err)}).`);
             }
-            const title = tipCommitSubjectFn(layer.branch, cwd);
-            const body = buildPrBodyFn(tipCommitMessageFn(layer.branch, cwd));
-            console.log(ansi.dim(`  Opening PR ${layer.branch} → ${base} …`));
-            prNumber = createPrFn({
+        }
+        else if (!branchExistsFn(base, cwd)) {
+            throw new CommandError(`Stack base branch missing locally: ${base}`);
+        }
+        let ahead;
+        try {
+            ahead = commitsAheadOfFn(aheadRef, branch, cwd);
+        }
+        catch (err) {
+            throw new CommandError(err instanceof Error ? err.message : String(err));
+        }
+        if (ahead < 1) {
+            throw new CommandError(`No commits on \`${branch}\` ahead of \`${base}\`. ` +
+                `Commit your changes, then retry \`mg stack submit\`.`);
+        }
+        const title = tipCommitSubjectFn(branch, cwd);
+        const body = buildPrBodyFn(tipCommitMessageFn(branch, cwd));
+        console.log(ansi.dim(`  Opening PR ${branch} → ${base} …`));
+        return {
+            prNumber: createPrFn({
                 owner,
                 repo,
                 base,
-                head: layer.branch,
+                head: branch,
                 title,
                 body,
                 cwd,
-            });
-            created = true;
-        }
-        else {
-            console.log(ansi.dim(`  PR #${prNumber} already open for ${layer.branch}`));
+            }),
+            created: true,
+        };
+    };
+    for (const plan of plans) {
+        if (plan.githubBase == null && findOpenPrNumberFn(owner, repo, plan.branch, cwd) == null) {
+            continue;
         }
-        opened.push({ branch: layer.branch, base, prNumber, created });
+        const base = plan.githubBase ?? plan.gitParent;
+        const { prNumber, created } = openLayerPr(plan.branch, base);
+        opened.push({ branch: plan.branch, base, prNumber, created });
     }
-    const registerPr = opened[0].prNumber;
     const cfg = await loadConfigFn();
-    console.log(ansi.dim(`  Registering stack via import (${owner}/${repo}#${registerPr}) …`));
-    const body = await adoptStackFn(owner, repo, registerPr, cfg);
-    if (typeof body !== "object" || body === null) {
-        throw new CommandError("Unexpected response shape from adopt API");
-    }
-    const data = body;
-    if (data.error) {
-        throw new CommandError(data.error);
+    let adoptData = null;
+    let stackId = plans.find((plan) => plan.stackId)?.stackId ?? null;
+    const registerPr = async (prNumber) => {
+        console.log(ansi.dim(`  Registering stack via import (${owner}/${repo}#${prNumber}) …`));
+        const body = await adoptStackFn(owner, repo, prNumber, cfg);
+        if (typeof body !== "object" || body === null) {
+            throw new CommandError("Unexpected response shape from adopt API");
+        }
+        const data = body;
+        if (data.error) {
+            throw new CommandError(data.error);
+        }
+        if (!data.stack) {
+            throw new CommandError("Stack was not registered");
+        }
+        adoptData = data;
+        if (typeof data.stack.id === "string" && data.stack.id) {
+            stackId = data.stack.id;
+        }
+    };
+    if (pendingPark.length > 0) {
+        if (opened.length > 0) {
+            await registerPr(opened[0].prNumber);
+        }
+        if (!stackId) {
+            throw new CommandError("Cannot mint a park freeze before the stack is registered. Open layers 1–2 first, then retry.");
+        }
+        console.log(ansi.dim(`  Ensuring upper-park freeze for stack ${stackId} …`));
+        const park = await ensureUpperParkFn(stackId, cfg);
+        for (const plan of pendingPark) {
+            const { prNumber, created } = openLayerPr(plan.branch, park.freezeBranch);
+            opened.push({ branch: plan.branch, base: park.freezeBranch, prNumber, created });
+        }
+        await registerPr(opened[opened.length - 1].prNumber);
     }
-    if (!data.stack) {
-        throw new CommandError("Stack was not registered");
+    else {
+        if (opened.length === 0) {
+            throw new CommandError("No pull requests to register after submit.");
+        }
+        await registerPr(opened[0].prNumber);
     }
-    const stackId = data.stack.id;
+    const data = adoptData;
     // Drop the submitted local stack so the next create onto trunk starts fresh.
     await saveStackMetaFn(removeActiveStack(meta), cwd);
     if (asJson) {

package/dist/commands/status.d.ts

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