mergestorm 0.3.3 → 0.3.4

package/README.md

@@ -48,14 +48,14 @@ mergestorm          # uses your local build
 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.
 
 ```
-╭─ mergestorm v0.3.3 ──────────────────────────────────────────────────────────╮
+╭─ mergestorm v0.3.4 ──────────────────────────────────────────────────────────╮
 │      ▟██████████▛       Tips for getting started                             │
 │       ▜████████▛          review      review main...HEAD                     │
-│        ▝▜████▛▘           stack       list / adopt / restack / land          │
+│        ▝▜████▛▘           stack       create → submit → restack → land       │
 │          ▜██▛             /help       list all commands                      │
 │           ██                                                                 │
-│           ▝▘            What's new in v0.3.3                                 │
-│  ● msk…  ·  maelstrom     • stack list / adopt / restack / land              │
+│           ▝▘            What's new in v0.3.4                                 │
+│  ● msk…  ·  maelstrom     • stack create / submit (author with mg)           │
 │  [████░░░░░░░░░░] 12% used                                                   │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 mergestorm
@@ -92,14 +92,20 @@ 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 thread <slug>        Jobs in a review thread
-mergestorm stack list [--json]  List adopted stacks
-mergestorm stack adopt <owner/repo>#<pr>  Adopt an open PR chain
+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 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 the bottom open PR
 mergestorm stack auto-land on|off <stack-id>  Toggle auto-land when green
 ```
 
-`mg` is a short alias for `mergestorm` (same binary), e.g. `mg stack list`. Stack ops use the same login key as review commands (`/api/v1/stacks`).
+`mg` is a short alias for `mergestorm` (same binary), e.g. `mg stack create`. Happy path: **create → commit → submit → restack → land**. `stack adopt` is for importing a chain that already exists on GitHub (legacy / Graphite). Restack/land use the same login key (`/api/v1/stacks`).
+
+`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 appends `{ branch, parentBranch }` under **`.mergestorm/stack.json`**. No GitHub or API calls.
+
+`stack submit` walks that meta: `git push -u origin` each layer, opens a PR with `gh` (`--base` = parent or trunk; skips heads that already have an open PR), then registers the stack with `POST /api/v1/stacks/adopt` internally (Mergestorm API key). Push/PR auth is your local `git` + `gh auth` — not a Cyclone app token.
 
 ### `login`
 

package/dist/api.js

@@ -93,7 +93,7 @@ export async function adoptStack(owner, repo, prNumber, cfg) {
         throw new CommandError("Stacks API is not available on this server yet. Deploy the API update or use the dashboard.");
     }
     if (status !== 200) {
-        throw new CommandError(`Failed to adopt stack (HTTP ${status}): ${JSON.stringify(body)}`);
+        throw new CommandError(`Failed to import stack (HTTP ${status}): ${JSON.stringify(body)}`);
     }
     return body;
 }

package/dist/cli.js

@@ -30,8 +30,10 @@ function usage() {
   mergestorm chain [slug]         Branch review-chain timeline (default: current)
   mergestorm whoami [--json]      Key + plan + API base
   mergestorm thread <slug>        Jobs in a review thread
-  mergestorm stack list [--json]  List adopted stacks
-  mergestorm stack adopt <owner/repo>#<pr>  Adopt an open PR chain
+  mergestorm stack create [name]  New local stack layer (.mergestorm/stack.json)
+  mergestorm stack submit         Push layers, open chained PRs, register stack
+  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 the bottom open PR
   mergestorm stack auto-land on|off <stack-id>  Toggle auto-land when green

package/dist/commands/stack.d.ts

@@ -5,4 +5,11 @@ export declare function parseAdoptTarget(args: string[]): {
     repo: string;
     prNumber: number;
 };
+/** Parse `stack create` argv into options. Exported for tests. */
+export declare function parseStackCreateArgs(args: string[]): {
+    name?: string;
+    onto?: string;
+    trunk?: string;
+    asJson: boolean;
+};
 export declare function cmdStack(args: string[]): Promise<void>;

package/dist/commands/stack.js

@@ -1,8 +1,14 @@
 import { adoptStack, landNextStack, listStacks, restackStack, setStackAutoLand, } from "../api.js";
 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, tipCommitSubject, worktreeDirty, } from "../git-stack.js";
+import { appendLayer, loadStackMeta, saveStackMeta, } 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]
   mergestorm stack list [--json]
   mergestorm stack adopt <owner/repo>#<pr>
   mergestorm stack restack <stack-id> [--json]
@@ -52,6 +58,195 @@ function formatStackHuman(s) {
     }
     return lines;
 }
+/** Parse `stack create` argv into options. Exported for tests. */
+export function parseStackCreateArgs(args) {
+    let name;
+    let onto;
+    let trunk;
+    let asJson = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--json") {
+            asJson = true;
+            continue;
+        }
+        if (a === "--onto") {
+            const v = args[++i];
+            if (!v)
+                throw new CommandError("usage: mergestorm stack create [name] [--onto <branch>]");
+            onto = v;
+            continue;
+        }
+        if (a.startsWith("--onto=")) {
+            onto = a.slice("--onto=".length);
+            continue;
+        }
+        if (a === "--trunk") {
+            const v = args[++i];
+            if (!v)
+                throw new CommandError("usage: mergestorm stack create [name] [--trunk <branch>]");
+            trunk = v;
+            continue;
+        }
+        if (a.startsWith("--trunk=")) {
+            trunk = a.slice("--trunk=".length);
+            continue;
+        }
+        if (a.startsWith("-")) {
+            throw new CommandError(`${STACK_USAGE}\nunknown flag: ${a}`);
+        }
+        if (name != null) {
+            throw new CommandError("usage: mergestorm stack create [name] [--onto <branch>] [--trunk <branch>]");
+        }
+        name = a;
+    }
+    return { name, onto, trunk, asJson };
+}
+async function cmdStackCreate(args) {
+    const { name, onto, trunk: trunkFlag, asJson } = parseStackCreateArgs(args);
+    const cwd = process.cwd();
+    if (worktreeDirty(cwd)) {
+        throw new CommandError("Working tree is dirty. Commit or stash changes before `stack create`.");
+    }
+    const parentBranch = onto?.trim() || currentBranch(cwd);
+    if (!parentBranch) {
+        throw new CommandError("Detached HEAD. Check out a branch (or pass --onto <branch>) before `stack create`.");
+    }
+    if (!branchExists(parentBranch, cwd)) {
+        throw new CommandError(`Parent branch not found: ${parentBranch}`);
+    }
+    const branch = defaultLayerBranchName(name);
+    if (branchExists(branch, cwd)) {
+        throw new CommandError(`Branch already exists: ${branch}`);
+    }
+    let meta = await loadStackMeta(cwd);
+    const trunk = trunkFlag?.trim() || meta?.trunk || discoverTrunk(cwd);
+    if (!meta) {
+        meta = { version: 1, trunk, layers: [] };
+    }
+    else if (trunkFlag?.trim() && meta.trunk !== trunk) {
+        throw new CommandError(`Stack trunk is ${meta.trunk}; refusing --trunk ${trunk}. Edit .mergestorm/stack.json or start fresh.`);
+    }
+    // Parent must be trunk or an existing layer (linear local stack).
+    if (meta.layers.length > 0 &&
+        parentBranch !== meta.trunk &&
+        !meta.layers.some((l) => l.branch === parentBranch)) {
+        throw new CommandError(`Parent ${parentBranch} is not trunk (${meta.trunk}) or a stack layer. Use --onto <branch>.`);
+    }
+    try {
+        createBranchFromHead(branch, cwd);
+    }
+    catch (err) {
+        throw new CommandError(err instanceof Error ? err.message : String(err));
+    }
+    let next;
+    try {
+        next = appendLayer(meta, { branch, parentBranch });
+        await saveStackMeta(next, cwd);
+    }
+    catch (err) {
+        try {
+            deleteBranch(branch, cwd);
+        }
+        catch { /* rollback best-effort */ }
+        throw new CommandError(err instanceof Error ? err.message : String(err));
+    }
+    if (asJson) {
+        console.log(JSON.stringify({ branch, parentBranch, trunk: next.trunk, meta: next }, null, 2));
+        return;
+    }
+    console.log(ansi.green(`  Created ${branch} (onto ${parentBranch})`));
+    console.log(ansi.dim(`  trunk: ${next.trunk} · layers: ${next.layers.length}`));
+    console.log(ansi.dim(`  meta: .mergestorm/stack.json`));
+}
+async function cmdStackSubmit(args) {
+    const asJson = args.includes("--json");
+    if (args.some((a) => a !== "--json")) {
+        throw new CommandError("usage: mergestorm stack submit [--json]");
+    }
+    const cwd = process.cwd();
+    const meta = await loadStackMeta(cwd);
+    if (!meta || meta.layers.length === 0) {
+        throw new CommandError("No local stack layers. Run `mg stack create` (and commit) before `stack submit`.");
+    }
+    const origin = parseGithubOriginRepo();
+    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);
+    const opened = [];
+    for (const layer of meta.layers) {
+        const base = layer.parentBranch || meta.trunk;
+        if (!branchExists(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);
+        }
+        catch (err) {
+            throw new CommandError(err instanceof Error ? err.message : String(err));
+        }
+        let prNumber = findOpenPrNumber(owner, repo, layer.branch, cwd);
+        let created = false;
+        if (prNumber == null) {
+            const title = tipCommitSubject(layer.branch, cwd);
+            console.log(ansi.dim(`  Opening PR ${layer.branch} → ${base} …`));
+            prNumber = createPr({
+                owner,
+                repo,
+                base,
+                head: layer.branch,
+                title,
+                body: "",
+                cwd,
+            });
+            created = true;
+        }
+        else {
+            console.log(ansi.dim(`  PR #${prNumber} already open for ${layer.branch}`));
+        }
+        opened.push({ branch: layer.branch, base, prNumber, created });
+    }
+    const registerPr = opened[0].prNumber;
+    const cfg = await loadConfig();
+    console.log(ansi.dim(`  Registering stack via import (${owner}/${repo}#${registerPr}) …`));
+    const body = await adoptStack(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);
+    }
+    if (!data.stack) {
+        throw new CommandError("Stack was not registered");
+    }
+    const stackId = data.stack.id;
+    if (asJson) {
+        console.log(JSON.stringify({
+            owner,
+            repo,
+            layers: opened,
+            stackId: stackId ?? null,
+            trunk: data.stack?.trunkBranch ?? meta.trunk,
+            chain: data.chain ?? null,
+        }, null, 2));
+        return;
+    }
+    for (const row of opened) {
+        const verb = row.created ? "opened" : "exists";
+        console.log(ansi.green(`  #${row.prNumber}  ${row.branch} → ${row.base}  (${verb})`));
+    }
+    if (stackId) {
+        console.log(ansi.green(`  Registered stack ${stackId}`));
+    }
+    else {
+        console.log(ansi.dim("  Stack registration returned no stack ID"));
+    }
+    console.log(ansi.dim("  Dashboard: https://mergestorm.ai/dashboard/stacks"));
+}
 async function cmdStackList(args) {
     const asJson = args.includes("--json");
     const cfg = await loadConfig();
@@ -61,7 +256,8 @@ async function cmdStackList(args) {
         return;
     }
     if (stacks.length === 0) {
-        console.log(ansi.dim("  No stacks yet. Adopt one: `stack adopt owner/repo#pr`"));
+        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"));
         return;
     }
@@ -91,7 +287,7 @@ async function cmdStackAdopt(args) {
     const data = body;
     const stack = data.stack;
     const chain = data.chain;
-    console.log(ansi.green(`  Adopted ${owner}/${repo}#${prNumber}` +
+    console.log(ansi.green(`  Imported ${owner}/${repo}#${prNumber}` +
         (stack?.id ? ` → ${stack.id}` : "") +
         (Array.isArray(chain) ? ` (${chain.length} layer(s))` : "")));
     if (stack?.trunkBranch) {
@@ -149,6 +345,10 @@ export async function cmdStack(args) {
     if (!sub || sub === "-h" || sub === "--help") {
         throw new CommandError(STACK_USAGE);
     }
+    if (sub === "create")
+        return cmdStackCreate(rest);
+    if (sub === "submit")
+        return cmdStackSubmit(rest);
     if (sub === "list" || sub === "ls")
         return cmdStackList(rest);
     if (sub === "adopt")

package/dist/gh.d.ts

@@ -0,0 +1,20 @@
+export declare function runGh(args: string[], cwd?: string): {
+    ok: true;
+    stdout: string;
+} | {
+    ok: false;
+    stderr: string;
+    status: number | null;
+};
+export declare function requireGh(cwd?: string): void;
+/** Open PR number for `head` branch in owner/repo, or null. */
+export declare function findOpenPrNumber(owner: string, repo: string, headBranch: string, cwd?: string): number | null;
+export declare function createPr(input: {
+    owner: string;
+    repo: string;
+    base: string;
+    head: string;
+    title: string;
+    body?: string;
+    cwd?: string;
+}): number;

package/dist/gh.js

@@ -0,0 +1,89 @@
+import { spawnSync } from "node:child_process";
+import { CommandError } from "./errors.js";
+export function runGh(args, cwd = process.cwd()) {
+    const result = spawnSync("gh", args, { cwd, encoding: "utf8" });
+    if (result.error) {
+        const msg = result.error.message || String(result.error);
+        if (result.error.code === "ENOENT") {
+            return { ok: false, stderr: "gh not found", status: null };
+        }
+        return { ok: false, stderr: msg, status: result.status };
+    }
+    if (result.status !== 0) {
+        return {
+            ok: false,
+            stderr: (result.stderr || result.stdout || `gh ${args.join(" ")} failed`).trim(),
+            status: result.status,
+        };
+    }
+    return { ok: true, stdout: result.stdout ?? "" };
+}
+export function requireGh(cwd = process.cwd()) {
+    const check = runGh(["--version"], cwd);
+    if (!check.ok) {
+        throw new CommandError("GitHub CLI (`gh`) is required for `stack submit`. Install https://cli.github.com and run `gh auth login`.");
+    }
+    const auth = runGh(["auth", "status"], cwd);
+    if (!auth.ok) {
+        throw new CommandError("`gh` is installed but not authenticated. Run `gh auth login`, then retry `stack submit`.");
+    }
+}
+/** Open PR number for `head` branch in owner/repo, or null. */
+export function findOpenPrNumber(owner, repo, headBranch, cwd = process.cwd()) {
+    const res = runGh([
+        "pr",
+        "list",
+        "--repo",
+        `${owner}/${repo}`,
+        "--head",
+        headBranch,
+        "--state",
+        "open",
+        "--json",
+        "number",
+        "--limit",
+        "1",
+    ], cwd);
+    if (!res.ok) {
+        throw new CommandError(`Failed to list PRs for ${headBranch}: ${res.stderr}`);
+    }
+    try {
+        const rows = JSON.parse(res.stdout);
+        const n = rows[0]?.number;
+        return typeof n === "number" && n > 0 ? n : null;
+    }
+    catch (e) {
+        throw new CommandError(`Failed to parse PR list response: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+export function createPr(input) {
+    const cwd = input.cwd ?? process.cwd();
+    const args = [
+        "pr",
+        "create",
+        "--repo",
+        `${input.owner}/${input.repo}`,
+        "--base",
+        input.base,
+        "--head",
+        input.head,
+        "--title",
+        input.title,
+        "--body",
+        input.body ?? "",
+    ];
+    const res = runGh(args, cwd);
+    if (!res.ok) {
+        throw new CommandError(`Failed to open PR ${input.head} → ${input.base}: ${res.stderr}`);
+    }
+    // stdout is typically the PR URL
+    const url = res.stdout.trim();
+    const m = /\/pull\/(\d+)/.exec(url);
+    if (m?.[1])
+        return Number(m[1]);
+    // Fallback: re-list
+    const n = findOpenPrNumber(input.owner, input.repo, input.head, cwd);
+    if (n != null)
+        return n;
+    throw new CommandError(`Opened PR at ${url || "(unknown URL)"} but could not determine PR number. Check your repository's pull requests.`);
+}

package/dist/git-stack.d.ts

@@ -0,0 +1,18 @@
+/** Current branch name, or null when detached. */
+export declare function currentBranch(cwd?: string): string | null;
+/** True when the worktree has staged/unstaged/untracked changes. */
+export declare function worktreeDirty(cwd?: string): boolean;
+/**
+ * Resolve trunk branch: --trunk flag, then origin/HEAD, then main/master if present.
+ */
+export declare function discoverTrunk(cwd?: string): string;
+export declare function branchExists(name: string, cwd?: string): boolean;
+export declare function deleteBranch(name: string, cwd?: string): void;
+export declare function createBranchFromHead(name: string, cwd?: string): void;
+/** Slugify a free-form name into a safe branch segment. */
+export declare function slugifyBranchName(raw: string): string;
+export declare function defaultLayerBranchName(explicit?: string): string;
+/** Push branch to origin and set upstream. */
+export declare function pushBranch(branch: string, cwd?: string): void;
+/** First line of the tip commit on `branch` (for PR title). */
+export declare function tipCommitSubject(branch: string, cwd?: string): string;

package/dist/git-stack.js

@@ -0,0 +1,99 @@
+import { git } from "./git.js";
+/** Current branch name, or null when detached. */
+export function currentBranch(cwd = process.cwd()) {
+    try {
+        const name = git(["rev-parse", "--abbrev-ref", "HEAD"], cwd).trim();
+        if (!name || name === "HEAD")
+            return null;
+        return name;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when the worktree has staged/unstaged/untracked changes. */
+export function worktreeDirty(cwd = process.cwd()) {
+    const out = git(["status", "--porcelain"], cwd);
+    return out.trim().length > 0;
+}
+/**
+ * Resolve trunk branch: --trunk flag, then origin/HEAD, then main/master if present.
+ */
+export function discoverTrunk(cwd = process.cwd()) {
+    try {
+        const sym = git(["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], cwd).trim();
+        // origin/main → main
+        const m = /^origin\/(.+)$/.exec(sym);
+        if (m?.[1])
+            return m[1];
+    }
+    catch {
+        // no origin/HEAD
+    }
+    for (const candidate of ["main", "master"]) {
+        try {
+            git(["rev-parse", "--verify", candidate], cwd);
+            return candidate;
+        }
+        catch {
+            // try next
+        }
+    }
+    throw new Error("Could not discover trunk branch. Pass --trunk <name> or set origin/HEAD.");
+}
+export function branchExists(name, cwd = process.cwd()) {
+    try {
+        git(["rev-parse", "--verify", "--quiet", `refs/heads/${name}`], cwd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function deleteBranch(name, cwd = process.cwd()) {
+    git(["branch", "-D", name], cwd);
+}
+export function createBranchFromHead(name, cwd = process.cwd()) {
+    git(["checkout", "-b", name], cwd);
+}
+/** Slugify a free-form name into a safe branch segment. */
+export function slugifyBranchName(raw) {
+    const s = raw
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9/_-]+/g, "-")
+        .replace(/\/+/g, "/")
+        .replace(/^-+|-+$/g, "");
+    return s || `layer-${Date.now().toString(36)}`;
+}
+export function defaultLayerBranchName(explicit) {
+    if (explicit?.trim()) {
+        const s = slugifyBranchName(explicit);
+        return s.includes("/") ? s : `ms/${s}`;
+    }
+    return `ms/${new Date().toISOString().slice(0, 10)}-${Date.now().toString(36).slice(-4)}`;
+}
+/** Push branch to origin and set upstream. */
+export function pushBranch(branch, cwd = process.cwd()) {
+    try {
+        git(["push", "-u", "origin", branch], cwd);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`git push failed for ${branch}. Check remote auth (SSH key or credential helper).\n${msg}`);
+    }
+}
+/** First line of the tip commit on `branch` (for PR title). */
+export function tipCommitSubject(branch, cwd = process.cwd()) {
+    try {
+        const s = git(["log", "-1", "--format=%s", branch], cwd).trim();
+        if (s)
+            return s;
+        console.warn(`Warning: no commit message on ${branch}; using branch name as PR title`);
+        return branch;
+    }
+    catch {
+        console.warn(`Warning: could not read commit message on ${branch}; using branch name as PR title`);
+        return branch;
+    }
+}

package/dist/shell.js

@@ -28,7 +28,7 @@ export const COMMANDS = [
     { name: "chain", summary: "Show a branch review-chain timeline" },
     { name: "whoami", summary: "Key + plan + API base" },
     { name: "thread", summary: "Jobs in a review thread" },
-    { name: "stack", summary: "Stacks: list, adopt, restack, land, auto-land" },
+    { name: "stack", summary: "Stacks: create, submit, list, adopt, restack, land" },
     { name: "clear", summary: "Clear screen and reprint banner" },
     { name: "exit", summary: "Leave the shell" },
     { name: "quit", summary: "Leave the shell" },

package/dist/stack-meta.d.ts

@@ -0,0 +1,15 @@
+export type StackLayerMeta = {
+    branch: string;
+    /** Parent branch name (trunk for the bottom layer). */
+    parentBranch: string;
+};
+export type StackMeta = {
+    version: 1;
+    trunk: string;
+    layers: StackLayerMeta[];
+};
+export declare const STACK_META_REL: string;
+export declare function stackMetaPath(cwd?: string): string;
+export declare function loadStackMeta(cwd?: string): Promise<StackMeta | null>;
+export declare function saveStackMeta(meta: StackMeta, cwd?: string): Promise<void>;
+export declare function appendLayer(meta: StackMeta, layer: StackLayerMeta): StackMeta;

package/dist/stack-meta.js

@@ -0,0 +1,41 @@
+/**
+ * Local stack metadata for `mg stack create` / `submit`.
+ * Stored at `.mergestorm/stack.json` in the repo root.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+export const STACK_META_REL = path.join(".mergestorm", "stack.json");
+export function stackMetaPath(cwd = process.cwd()) {
+    return path.join(cwd, STACK_META_REL);
+}
+export async function loadStackMeta(cwd = process.cwd()) {
+    try {
+        const raw = await readFile(stackMetaPath(cwd), "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed ||
+            parsed.version !== 1 ||
+            typeof parsed.trunk !== "string" ||
+            !Array.isArray(parsed.layers) ||
+            !parsed.layers.every(l => typeof l.branch === 'string' && typeof l.parentBranch === 'string')) {
+            return null;
+        }
+        return parsed;
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+export async function saveStackMeta(meta, cwd = process.cwd()) {
+    const file = stackMetaPath(cwd);
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, `${JSON.stringify(meta, null, 2)}\n`, "utf8");
+}
+export function appendLayer(meta, layer) {
+    if (meta.layers.some((l) => l.branch === layer.branch)) {
+        throw new Error(`branch already in stack: ${layer.branch}`);
+    }
+    return { ...meta, layers: [...meta.layers, layer] };
+}

package/dist/ui/banner.js

@@ -38,6 +38,10 @@ const WHATS_NEW = {
     "0.3.3": [
         "`stack list` / `adopt` / `restack` / `land` / `auto-land`",
     ],
+    "0.3.4": [
+        "`stack create` / `submit` — author stacks with `mg` (not Graphite)",
+        "Adopt is import-only; happy path is create → submit → restack → land",
+    ],
 };
 function formatStatusLines(me, key, barWidth) {
     if (!key) {
@@ -61,7 +65,7 @@ function tipsLines() {
     return [
         ansi.dim("Tips for getting started"),
         `  ${ansi.green("review")}      review main...HEAD`,
-        `  ${ansi.green("branches")}    pick a reviewed branch`,
+        `  ${ansi.green("stack")}       create → submit → restack → land`,
         `  ${ansi.green("/help")}       list all commands`,
     ];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mergestorm",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "MergeStorm CLI — interactive shell and one-shot review commands",
   "type": "module",
   "bin": {
@@ -24,7 +24,7 @@
     "dev": "tsx src/cli.ts",
     "start": "node dist/cli.js",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsx --test src/**/*.test.ts"
+    "test": "tsx --test src/*.test.ts src/**/*.test.ts"
   },
   "engines": {
     "node": ">=22.0.0"