gh-stack 0.17.2 → 0.19.0

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 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";
 
@@ -146,8 +146,17 @@ export async function advanceNewBottom(opts: {
   childPr: number | null;
   targetRef: string;
   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;
 
   const forkPoint = await resolveForkPoint(meta, mergedBranch, child);
   if (!forkPoint) return { ok: false, reason: "no-fork-point" };
@@ -164,20 +173,47 @@ export async function advanceNewBottom(opts: {
   const ok = await git.rebaseOnto(targetRef, forkPoint, child);
   if (!ok) return { ok: false, reason: "conflict", forkPoint };
 
-  // Push the rebased head first so the PR diff is clean before its base flips.
-  await git.pushStackedBranch(child);
-  if (childPr != null) {
-    const moved = await setPrBase(childPr, recordedBase);
-    if (moved) {
-      p.log.success(`PR #${childPr} base → ${pc.green(recordedBase)}`);
-    } else {
-      p.log.warn(`Could not retarget PR #${childPr} — set its base to ${recordedBase} manually`);
+  if (push) {
+    // Push the rebased head first so the PR diff is clean before its base flips.
+    // 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} — the next push of ${child} retries, or set its base to ${recordedBase} manually`,
+        );
+      }
     }
+  } else if (childPr != null) {
+    // Retargeting the base without pushing the rebased head would show the
+    // merged commits in the PR diff, so leave both for `submit` to reconcile.
+    p.log.info(
+      `Not pushing ${pc.yellow(child)} or retargeting PR #${childPr} (--no-push) — ${pc.green("gh-stack submit")} publishes both`,
+    );
   }
 
   // Metadata last: re-parents child (and siblings) onto the merged branch's
   // 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 };
 }

package/src/lib/chain.ts

@@ -53,6 +53,26 @@ export async function detectBranchChain(currentBranch: string, trunk: string): P
   return chain;
 }
 
+/**
+ * Local branches (other than trunk) whose tip is the SAME commit as `branch`.
+ * A branch with no commits of its own sits at its parent's tip rather than
+ * above it, so `detectBranchChain` can't see the parent — and from ancestry
+ * alone the two are indistinguishable. Callers use this to warn instead of
+ * silently rooting the branch at trunk. (#37)
+ */
+export async function colocatedBranches(branch: string, trunk: string): Promise<string[]> {
+  const tip = await git.revParse(branch);
+  const excluded = new Set([branch, trunk, "main", "master"]);
+  const out: string[] = [];
+  for (const [other, sha] of await git.localBranchTips()) {
+    if (excluded.has(other) || sha !== tip) continue;
+    // A branch sitting on trunk's tip isn't a stack parent, just trunk.
+    if (await git.isAncestor(other, trunk)) continue;
+    out.push(other);
+  }
+  return out;
+}
+
 export interface StackResolution {
   stackName: string;
   base: string; // effective base of the resulting stack (for display)