gh-stack 0.18.0 → 0.19.1

package/src/index.ts

@@ -1,24 +1,28 @@
 #!/usr/bin/env bun
 // gh-stack — Unified stacked PR manager for squash-merge workflows
 
-// Map GH_STACK_NO_COLOR → NO_COLOR so picocolors (and other tools) respect it.
-// Also pre-detect plain mode (--plain flag, GH_STACK_YES=1, or GH_STACK_PLAIN=1)
-// and set NO_COLOR *before* any import below — picocolors snapshots env at
-// load time, so this must run before the import block.
-const _earlyArgs = process.argv.slice(2);
-const _earlyPlain =
-  _earlyArgs.includes("--plain") ||
+// Map GH_STACK_NO_COLOR → NO_COLOR so picocolors (and other tools) respect it,
+// and turn colors off for plain mode (--plain, GH_STACK_YES=1, GH_STACK_PLAIN=1)
+// and --json (a machine reads the stderr logs, and error messages land inside
+// the JSON itself).
+//
+// picocolors reads NO_COLOR once, when it first loads. So this file has NO
+// static imports: those are evaluated before this body runs, and Bun evaluates
+// a CommonJS dependency like picocolors even before an earlier ESM side-effect
+// import. Everything that can pull in picocolors is imported dynamically below.
+const earlyArgs = new Set(process.argv.slice(2));
+const colorOff =
+  !!process.env.GH_STACK_NO_COLOR ||
+  earlyArgs.has("--plain") ||
+  earlyArgs.has("--json") ||
   process.env.GH_STACK_YES === "1" ||
   process.env.GH_STACK_PLAIN === "1";
-if (process.env.GH_STACK_NO_COLOR || _earlyPlain) {
-  process.env.NO_COLOR = "1";
-}
-
-import { ensureGitRepo } from "./lib/safety.ts";
-import { parseCliArgs } from "./lib/cli.ts";
-import { setAutoYes } from "./lib/ui.ts";
-import { setPlain } from "./lib/output.ts";
+if (colorOff) process.env.NO_COLOR = "1";
 
+const { ensureGitRepo } = await import("./lib/safety.ts");
+const { parseCliArgs } = await import("./lib/cli.ts");
+const { setAutoYes } = await import("./lib/ui.ts");
+const { setPlain } = await import("./lib/output.ts");
 const { version: VERSION } = await import("../package.json");
 
 const args = process.argv.slice(2);
@@ -48,122 +52,140 @@ if (parsed.plain) {
 
 // Ensure we're in a git repo for all commands — except `learn`, which just
 // emits/installs the agent skill and is useful outside any repo (e.g. an agent
-// onboarding before cloning, or `learn --skill --global`).
-if (command !== "learn") {
+// onboarding before cloning, or `learn --skill --global`), and `config`, which
+// shows the user and env layers anywhere (and the repo layer inside a repo).
+if (command !== "learn" && command !== "config") {
   await ensureGitRepo();
 }
 
 // Route to subcommand — strip global flags from command args
 const commandArgs = parsed.commandArgs;
 
-switch (command) {
-  case "log":
-    await (await import("./commands/log.ts")).default(commandArgs);
-    break;
-
-  case "init":
-    await (await import("./commands/init.ts")).default(commandArgs);
-    break;
-
-  case "create":
-    await (await import("./commands/create.ts")).default(commandArgs);
-    break;
-
-  case "add":
-    await (await import("./commands/add.ts")).default(commandArgs);
-    break;
-
-  case "delete":
-    await (await import("./commands/delete.ts")).default(commandArgs);
-    break;
-
-  case "split":
-    await (await import("./commands/split.ts")).default(commandArgs);
-    break;
-
-  case "rename":
-    await (await import("./commands/rename.ts")).default(commandArgs);
-    break;
-
-  case "checkout":
-  case "co":
-    await (await import("./commands/checkout.ts")).default(commandArgs);
-    break;
-
-  case "ls":
-    await (await import("./commands/list.ts")).default(commandArgs);
-    break;
-
-  case "restack":
-  case "rebase":
-    await (await import("./commands/restack.ts")).default(commandArgs);
-    break;
-
-  case "sync":
-    await (await import("./commands/sync.ts")).default(commandArgs);
-    break;
-
-  case "submit":
-    await (await import("./commands/submit.ts")).default(commandArgs);
-    break;
-
-  case "status":
-    await (await import("./commands/status.ts")).default(commandArgs);
-    break;
-
-  case "merge":
-    await (await import("./commands/merge.ts")).default(commandArgs);
-    break;
-
-  case "undo":
-    await (await import("./commands/undo.ts")).default(commandArgs);
-    break;
-
-  case "doctor":
-    await (await import("./commands/doctor.ts")).default(commandArgs);
-    break;
-
-  case "update-prs":
-    await (await import("./commands/update-prs.ts")).default(commandArgs);
-    break;
-
-  case "stacks":
-    await (await import("./commands/stacks.ts")).default(commandArgs);
-    break;
-
-  case "archive":
-    await (await import("./commands/archive.ts")).default(commandArgs);
-    break;
-
-  case "up":
-    await (await import("./commands/up.ts")).default(commandArgs);
-    break;
-
-  case "down":
-    await (await import("./commands/down.ts")).default(commandArgs);
-    break;
-
-  case "top":
-    await (await import("./commands/top.ts")).default(commandArgs);
-    break;
-
-  case "bottom":
-    await (await import("./commands/bottom.ts")).default(commandArgs);
-    break;
-
-  case "learn":
-    await (await import("./commands/learn.ts")).default(commandArgs);
-    break;
-
-  case "--help":
-  case "help":
-    printHelp();
-    break;
-
-  default:
-    console.error(`Unknown command: ${command}\n`);
-    printHelp();
-    process.exit(1);
+// A config problem (malformed TOML, a non-boolean env value) is reported as
+// one clean line, whichever command hit it.
+const { ConfigError } = await import("./lib/config.ts");
+try {
+  switch (command) {
+    case "log":
+      await (await import("./commands/log.ts")).default(commandArgs);
+      break;
+
+    case "init":
+      await (await import("./commands/init.ts")).default(commandArgs);
+      break;
+
+    case "create":
+      await (await import("./commands/create.ts")).default(commandArgs);
+      break;
+
+    case "add":
+      await (await import("./commands/add.ts")).default(commandArgs);
+      break;
+
+    case "join":
+      await (await import("./commands/join.ts")).default(commandArgs);
+      break;
+
+    case "delete":
+      await (await import("./commands/delete.ts")).default(commandArgs);
+      break;
+
+    case "split":
+      await (await import("./commands/split.ts")).default(commandArgs);
+      break;
+
+    case "rename":
+      await (await import("./commands/rename.ts")).default(commandArgs);
+      break;
+
+    case "checkout":
+    case "co":
+      await (await import("./commands/checkout.ts")).default(commandArgs);
+      break;
+
+    case "ls":
+      await (await import("./commands/list.ts")).default(commandArgs);
+      break;
+
+    case "restack":
+    case "rebase":
+      await (await import("./commands/restack.ts")).default(commandArgs);
+      break;
+
+    case "sync":
+      await (await import("./commands/sync.ts")).default(commandArgs);
+      break;
+
+    case "submit":
+      await (await import("./commands/submit.ts")).default(commandArgs);
+      break;
+
+    case "status":
+      await (await import("./commands/status.ts")).default(commandArgs);
+      break;
+
+    case "merge":
+      await (await import("./commands/merge.ts")).default(commandArgs);
+      break;
+
+    case "undo":
+      await (await import("./commands/undo.ts")).default(commandArgs);
+      break;
+
+    case "doctor":
+      await (await import("./commands/doctor.ts")).default(commandArgs);
+      break;
+
+    case "update-prs":
+      await (await import("./commands/update-prs.ts")).default(commandArgs);
+      break;
+
+    case "stacks":
+      await (await import("./commands/stacks.ts")).default(commandArgs);
+      break;
+
+    case "archive":
+      await (await import("./commands/archive.ts")).default(commandArgs);
+      break;
+
+    case "up":
+      await (await import("./commands/up.ts")).default(commandArgs);
+      break;
+
+    case "down":
+      await (await import("./commands/down.ts")).default(commandArgs);
+      break;
+
+    case "top":
+      await (await import("./commands/top.ts")).default(commandArgs);
+      break;
+
+    case "bottom":
+      await (await import("./commands/bottom.ts")).default(commandArgs);
+      break;
+
+    case "learn":
+      await (await import("./commands/learn.ts")).default(commandArgs);
+      break;
+
+    case "config":
+      await (await import("./commands/config.ts")).default(commandArgs);
+      break;
+
+    case "--help":
+    case "help":
+      printHelp();
+      break;
+
+    default:
+      console.error(`Unknown command: ${command}\n`);
+      printHelp();
+      process.exit(1);
+  }
+} catch (err) {
+  if (!(err instanceof ConfigError)) throw err;
+  console.error(`gh-stack: ${err.message}`);
+  process.exit(1);
 }
 
 function printHelp() {
@@ -200,6 +222,7 @@ ${bold("STACK MANAGEMENT")}
   ${green("sync")}           Sync base with main + restack all
   ${green("merge")}          Squash-merge via GitHub (top-down, or --approved bottom-up)
   ${green("split")}          Cut a stack into two at a branch
+  ${green("join")}           Splice an existing branch/PR into a stack
   ${green("rename")}         Rename a tracked branch (keeps metadata in sync)
   ${green("delete")}         Remove a branch from the stack
 
@@ -209,6 +232,7 @@ ${bold("INFO & MAINTENANCE")}
   ${green("archive")}        Manage archived stacks
   ${green("update-prs")}     Refresh stack visualization in PR descriptions
   ${green("doctor")}         Migrate & repair stack metadata
+  ${green("config")}         Show flag defaults and where each comes from
   ${green("learn")}          Print the agent skill (--skill installs it)
 
 ${bold("GLOBAL OPTIONS")}
@@ -221,6 +245,12 @@ ${bold("ENVIRONMENT")}
   GH_STACK_YES=1       Same as --yes (also enables --plain)
   GH_STACK_PLAIN=1     Same as --plain
   GH_STACK_NO_COLOR    Disable colored output
+  GH_STACK_DRAFT=1     submit creates new PRs as drafts (0 = ready)
+  GH_STACK_NO_PUSH=1   restack/sync/merge --base never push (0 = push)
+
+${bold("CONFIG")}
+  .gh-stack.toml (repo root) and ~/.config/gh-stack/config.toml set flag
+  defaults, e.g. [submit] draft = true. Run ${green("gh-stack config")} to see them.
 `);
 }
 

package/src/lib/advance.ts

@@ -20,7 +20,7 @@ import * as p from "./output.ts";
 import pc from "picocolors";
 import * as git from "./git.ts";
 import type { StackMetadata } from "../types.ts";
-import { removeBranchFromStack } from "./metadata.ts";
+import { removeBranchFromStack, writeMetadata } from "./metadata.ts";
 import { resolveRestackBoundary } from "./snapshot.ts";
 import { setPrBase } from "./github.ts";
 
@@ -120,6 +120,17 @@ export async function resolveForkPoint(
   mergedBranch: string,
   child: string,
 ): Promise<string | null> {
+  // `gh pr merge --delete-branch` deletes the merged branch locally too, which
+  // leaves the shared resolver no ref to read snapshots against. Its pre-merge
+  // tip is in the snapshot the caller took: use the newest recorded tip the
+  // child still builds on.
+  if (!(await git.localBranchExists(mergedBranch))) {
+    for (const snap of (meta.snapshots ?? []).toReversed()) {
+      const tip = snap.branches[mergedBranch];
+      if (tip && (await git.isAncestor(tip, child))) return tip;
+    }
+    return null;
+  }
   const boundary = await resolveRestackBoundary(meta, mergedBranch, child);
   return boundary?.sha ?? null;
 }
@@ -137,6 +148,9 @@ export type AdvanceResult =
  *
  * The caller MUST have taken a snapshot first — on a rebase conflict this leaves
  * the in-progress `git rebase` for the user to resolve and returns `conflict`.
+ * Metadata still names the merged branch as the child's parent then, so the
+ * fix is to re-run the caller: this skips the finished rebase and does the rest.
+ * (`restack` would rebase the child back onto the merged branch.)
  */
 export async function advanceNewBottom(opts: {
   meta: StackMetadata;
@@ -148,34 +162,61 @@ export async function advanceNewBottom(opts: {
   recordedBase: string;
   /** false = `--no-push`: rebase + metadata only, leave origin and the PR alone (#36). */
   push?: boolean;
+  /**
+   * The child's origin tip as the remote guard checked and cleared it: the
+   * push leases on exactly that sha (see git.forcePushWithLease).
+   */
+  expect?: string;
 }): Promise<AdvanceResult> {
   const { meta, stackName, mergedBranch, child, childPr, targetRef, recordedBase } = opts;
   const push = opts.push ?? true;
+  let retargeted = false;
+
+  // Already on the target: an earlier run stopped on a conflict the user then
+  // resolved, or the branch was re-rooted by hand (#51). Its fork point is
+  // behind it now, so skip the rebase and finish the rest (push, PR base,
+  // metadata). Before a re-root the child can't contain the target, which
+  // holds the merged PR's new squash commit.
+  if (await git.isAncestor(targetRef, child)) {
+    p.log.info(
+      `${pc.yellow(child)} is already on ${pc.green(recordedBase)} — finishing its re-root`,
+    );
+  } else {
+    const forkPoint = await resolveForkPoint(meta, mergedBranch, child);
+    if (!forkPoint) return { ok: false, reason: "no-fork-point" };
+
+    // Guard: the fork-point must be an ancestor of the child, else `--onto` would
+    // replay an unrelated range. Bail loudly rather than mangle history.
+    if (!(await git.isAncestor(forkPoint, child))) {
+      return { ok: false, reason: "bad-fork-point", forkPoint };
+    }
 
-  const forkPoint = await resolveForkPoint(meta, mergedBranch, child);
-  if (!forkPoint) return { ok: false, reason: "no-fork-point" };
-
-  // Guard: the fork-point must be an ancestor of the child, else `--onto` would
-  // replay an unrelated range. Bail loudly rather than mangle history.
-  if (!(await git.isAncestor(forkPoint, child))) {
-    return { ok: false, reason: "bad-fork-point", forkPoint };
+    p.log.info(
+      `Re-rooting ${pc.yellow(child)} onto ${pc.green(recordedBase)} ${pc.dim(`(base: ${forkPoint.slice(0, 8)})`)}`,
+    );
+    const ok = await git.rebaseOnto(targetRef, forkPoint, child);
+    if (!ok) return { ok: false, reason: "conflict", forkPoint };
   }
 
-  p.log.info(
-    `Re-rooting ${pc.yellow(child)} onto ${pc.green(recordedBase)} ${pc.dim(`(base: ${forkPoint.slice(0, 8)})`)}`,
-  );
-  const ok = await git.rebaseOnto(targetRef, forkPoint, child);
-  if (!ok) return { ok: false, reason: "conflict", forkPoint };
-
   if (push) {
     // Push the rebased head first so the PR diff is clean before its base flips.
-    await git.pushStackedBranch(child);
-    if (childPr != null) {
+    // If it didn't land, leave the base alone: retargeting onto the trunk with
+    // the old head on origin would show the merged commits in the PR (#29).
+    const pushed = await git.forcePushWithLease(child, { expect: opts.expect });
+    if (!pushed.ok) {
+      p.log.error(
+        `Push of ${pc.yellow(child)} failed — PR${childPr != null ? ` #${childPr}` : ""} left on ${mergedBranch} for now. The next push of ${child} that lands (gh-stack restack --resume, sync) retargets it.`,
+      );
+      for (const line of git.pushFailureHint(child, pushed)) console.log(`  ${line}`);
+    } else if (childPr != null) {
       const moved = await setPrBase(childPr, recordedBase);
       if (moved) {
+        retargeted = true;
         p.log.success(`PR #${childPr} base → ${pc.green(recordedBase)}`);
       } else {
-        p.log.warn(`Could not retarget PR #${childPr} — set its base to ${recordedBase} manually`);
+        p.log.warn(
+          `Could not retarget PR #${childPr} — the next push of ${child} retries, or set its base to ${recordedBase} manually`,
+        );
       }
     }
   } else if (childPr != null) {
@@ -190,5 +231,14 @@ export async function advanceNewBottom(opts: {
   // parent (the trunk) and writes. Done after the git work succeeds so a failure
   // never leaves metadata describing a state git didn't reach.
   await removeBranchFromStack(meta, stackName, mergedBranch);
+
+  // Record where the child's PR really points. Until it's retargeted it still
+  // targets the merged branch, and the next successful push of the child
+  // retargets it (restack's pushStep), so it's never left there.
+  const entry = meta.stacks[stackName]?.branches[child];
+  if (entry && childPr != null) {
+    entry.prBase = retargeted ? recordedBase : mergedBranch;
+    await writeMetadata(meta);
+  }
   return { ok: true };
 }