gh-stack 0.1.0 → 0.1.2

package/README.md

@@ -47,23 +47,24 @@ gh-stack status
 ### Stack Management
 
 ```
-init [--name <name>] [--description <desc>]
+init [--name <name>] [--description <desc>] [--parent <branch>]
     Create a new stack and add the current branch as the first entry.
 
-add [<branch>] [--parent <branch>] [--create] [--description <desc>]
+add [<branch>] [--parent <branch>] [--create <branch>] [--description <desc>]
     Add a branch to the current stack. Defaults to the current branch.
-    --create makes a new branch off the top of stack first.
+    --create <branch> makes a new branch off the top of stack first.
 
-remove <branch>
+remove [<branch>]
     Remove a branch from the stack and re-parent its children.
+    If omitted, an interactive selector is shown.
 ```
 
 ### Navigation
 
 ```
 show
-    Display the current stack as a tree with PR numbers, titles,
-    review status, and CI state. This is the default command.
+    Display the current stack as a tree with branch numbers,
+    PR numbers, and descriptions. This is the default command.
 
 list
     List branches with position numbers. Lightweight output for
@@ -104,6 +105,7 @@ merge [--dry-run]
     Squash-merge the stack top-down locally (PR3 -> PR2 -> PR1),
     then optionally rebase onto main. Keeps all commits local to
     avoid orphaned squash commits from GitHub-only merges.
+    Can also close intermediate PRs and archives the stack on completion.
 
 update-prs
     Update all PR descriptions with a stack visualization:
@@ -119,13 +121,25 @@ update-prs
 ### Maintenance
 
 ```
-archive [--list] [--restore <name>]
-    Manage archived stacks.
+archive [--restore <name>]
+    List archived stacks by default, or restore one by name.
 
 undo
     Restore the last snapshot taken before a destructive operation.
 ```
 
+## Not Implemented Yet
+
+These are still intended, but not shipped in `v0.1.2`:
+
+```text
+split
+    Guided helper for splitting a branch/PR into two and updating stack metadata.
+
+insert
+    Insert a branch into the middle of an existing stack and re-parent the chain.
+```
+
 ## Global Options
 
 ```

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "gh-stack",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Stacked PR manager for squash-merge workflows",
   "author": "Kiliman <kiliman@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/kiliman/gh-stack"
+    "url": "git+https://github.com/kiliman/gh-stack.git"
   },
   "keywords": [
     "git",

package/src/commands/add.ts

@@ -3,9 +3,9 @@ import * as p from "@clack/prompts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { addBranchToStack, getTopOfStack, getOrderedBranches } from "../lib/metadata.ts";
-import { ensureMetadata, ensureCurrentStack } from "../lib/safety.ts";
+import { ensureMetadata, ensureCurrentStack, ensureValidStack } from "../lib/safety.ts";
 import { getPrNumber } from "../lib/github.ts";
-import { selectParent } from "../lib/ui.ts";
+import { isAutoYes, selectParent } from "../lib/ui.ts";
 import type { Branch } from "../types.ts";
 
 export default async function add(args: string[]): Promise<void> {
@@ -48,6 +48,7 @@ OPTIONS
 
   const meta = await ensureMetadata();
   const stackName = ensureCurrentStack(meta);
+  await ensureValidStack(meta, stackName);
   const stack = meta.stacks[stackName]!;
 
   p.intro(pc.cyan(`Add branch to ${pc.yellow(stackName)}`));
@@ -95,6 +96,8 @@ OPTIONS
 
     if (ordered.length === 0) {
       parent = "main";
+    } else if (isAutoYes()) {
+      parent = getTopOfStack(stack) ?? "main";
     } else {
       parent = (await selectParent(stack, branchToAdd)) ?? undefined;
       if (!parent) {

package/src/commands/list.ts

@@ -26,7 +26,8 @@ ALIASES
   const currentBranch = await git.currentBranch();
 
   // Find which stack contains the current branch
-  let stackName = findStackForBranch(meta, currentBranch);
+  const branchStackName = findStackForBranch(meta, currentBranch);
+  let stackName = branchStackName;
   if (!stackName) stackName = meta.current_stack;
 
   if (!stackName || !meta.stacks[stackName]) {
@@ -39,7 +40,9 @@ ALIASES
 
   // Update tracking
   meta.current_stack = stackName;
-  stack.last_branch = currentBranch;
+  if (branchStackName === stackName) {
+    stack.last_branch = currentBranch;
+  }
   await writeMetadata(meta);
 
   // Header

package/src/commands/merge.ts

@@ -4,7 +4,7 @@ import * as p from "@clack/prompts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { findStackForBranch, getOrderedBranches, writeMetadata } from "../lib/metadata.ts";
-import { ensureMetadata, ensureCleanWorkingTree } from "../lib/safety.ts";
+import { ensureMetadata, ensureCleanWorkingTree, ensureValidStack } from "../lib/safety.ts";
 import { takeSnapshot } from "../lib/snapshot.ts";
 import { closePr } from "../lib/github.ts";
 import { confirmAction } from "../lib/ui.ts";
@@ -39,6 +39,7 @@ This keeps all commits local (avoiding orphaned squash commits).
   }
 
   const stack = meta.stacks[stackName]!;
+  await ensureValidStack(meta, stackName);
   const ordered = getOrderedBranches(stack);
 
   if (ordered.length <= 1) {

package/src/commands/remove.ts

@@ -2,7 +2,7 @@
 import * as p from "@clack/prompts";
 import pc from "picocolors";
 import { removeBranchFromStack, getChildren } from "../lib/metadata.ts";
-import { ensureMetadata, ensureCurrentStack } from "../lib/safety.ts";
+import { ensureMetadata, ensureCurrentStack, ensureValidStack } from "../lib/safety.ts";
 import { takeSnapshot } from "../lib/snapshot.ts";
 import { selectBranch } from "../lib/ui.ts";
 import * as git from "../lib/git.ts";
@@ -23,6 +23,7 @@ If no branch is specified, shows interactive selector.
 
   const meta = await ensureMetadata();
   const stackName = ensureCurrentStack(meta);
+  await ensureValidStack(meta, stackName);
   const stack = meta.stacks[stackName]!;
   const currentBranch = await git.currentBranch();
 

package/src/commands/restack.ts

@@ -10,7 +10,12 @@ import {
   loadRestackState,
   clearRestackState,
 } from "../lib/metadata.ts";
-import { ensureMetadata, ensureCleanWorkingTree, ensureNotMain } from "../lib/safety.ts";
+import {
+  ensureMetadata,
+  ensureCleanWorkingTree,
+  ensureNotMain,
+  ensureValidStack,
+} from "../lib/safety.ts";
 import { takeSnapshot } from "../lib/snapshot.ts";
 import { confirmAction } from "../lib/ui.ts";
 import type { StackMetadata } from "../types.ts";
@@ -72,7 +77,7 @@ ALIASES
   }
 
   // Cleanup tags
-  await git.deleteTagsMatching("stack-sync-*");
+  await git.deleteTagsMatching(git.STACK_SYNC_TAG_GLOB);
 
   p.outro(pc.green("Stack Restack Complete!"));
 }
@@ -142,7 +147,7 @@ async function handleResume(
       const parent = stack.branches[branch]?.parent;
       if (!parent) continue;
 
-      const tagName = `stack-sync-base-${git.sanitizeBranchForTag(branch)}`;
+      const tagName = git.tempBaseTagName(branch);
       if (await git.tagExists(tagName)) {
         const tagSha = await git.revParse(tagName);
         console.log(
@@ -183,6 +188,7 @@ async function handleFreshRestack(
   }
 
   const stack = meta.stacks[stackName]!;
+  await ensureValidStack(meta, stackName);
 
   // Check for stale tags from previous runs
   await handleStaleTags();
@@ -235,25 +241,27 @@ async function handleFreshRestack(
     console.log();
   }
 
-  // Take snapshot before destructive operation
-  await takeSnapshot(meta, stackName, "restack");
+  if (!dryRun) {
+    // Take snapshot before destructive operation
+    await takeSnapshot(meta, stackName, "restack");
 
-  // Create temporary tags for stable base references
-  p.log.info("Creating temporary base tags...");
-  for (const branch of chain) {
-    const parent = stack.branches[branch]?.parent;
-    if (!parent) continue;
-
-    const mb = await git.mergeBase(branch, parent);
-    if (mb) {
-      const tagName = `stack-sync-base-${git.sanitizeBranchForTag(branch)}`;
-      await git.createTag(tagName, mb);
-      console.log(
-        `  ${pc.green("✓")} Tagged base for ${branch}: ${pc.cyan(tagName)} (${mb.slice(0, 8)})`,
-      );
+    // Create temporary tags for stable base references
+    p.log.info("Creating temporary base tags...");
+    for (const branch of chain) {
+      const parent = stack.branches[branch]?.parent;
+      if (!parent) continue;
+
+      const mb = await git.mergeBase(branch, parent);
+      if (mb) {
+        const tagName = git.tempBaseTagName(branch);
+        await git.createTag(tagName, mb);
+        console.log(
+          `  ${pc.green("✓")} Tagged base for ${branch}: ${pc.cyan(tagName)} (${mb.slice(0, 8)})`,
+        );
+      }
     }
+    console.log();
   }
-  console.log();
 
   // Process the chain
   await processChain(meta, stackName, chain, 0, rebasedBranches, dryRun, verbose);
@@ -317,7 +325,7 @@ async function processChain(
     });
 
     // Use temporary tag as stable base reference
-    const tagName = `stack-sync-base-${git.sanitizeBranchForTag(branch)}`;
+    const tagName = git.tempBaseTagName(branch);
     let success: boolean;
 
     if (await git.tagExists(tagName)) {
@@ -431,11 +439,11 @@ async function promptPush(branch: string): Promise<void> {
 async function handleStaleTags(): Promise<void> {
   try {
     const { $ } = await import("bun");
-    const result = await $`git tag -l "stack-sync-*"`.text();
+    const result = await $`git tag -l ${git.STACK_SYNC_TAG_GLOB}`.text();
     const tags = result.trim();
     if (!tags) return;
 
-    p.log.warn("Found stale stack-sync-* tags from a previous run");
+    p.log.warn(`Found stale ${git.STACK_SYNC_TAG_GLOB} tags from a previous run`);
     console.log();
 
     const action = await p.select({
@@ -460,7 +468,7 @@ async function handleStaleTags(): Promise<void> {
 
     if (action === "clean") {
       p.log.info("Cleaning up stale tags...");
-      await git.deleteTagsMatching("stack-sync-*");
+      await git.deleteTagsMatching(git.STACK_SYNC_TAG_GLOB);
       p.log.success("Tags cleaned");
     }
 

package/src/commands/show.ts

@@ -29,7 +29,8 @@ export default async function show(_args: string[]): Promise<void> {
   const branch = await git.currentBranch();
 
   // Find which stack contains the current branch
-  let stackName = findStackForBranch(meta, branch);
+  const branchStackName = findStackForBranch(meta, branch);
+  let stackName = branchStackName;
 
   if (!stackName) {
     // Fall back to current_stack
@@ -51,7 +52,9 @@ export default async function show(_args: string[]): Promise<void> {
 
   // Update current_stack and last_branch
   meta.current_stack = stackName;
-  stack.last_branch = branch;
+  if (branchStackName === stackName) {
+    stack.last_branch = branch;
+  }
   await writeMetadata(meta);
 
   // Header

package/src/commands/sync.ts

@@ -3,7 +3,7 @@ import * as p from "@clack/prompts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { findStackForBranch, getOrderedBranches, saveRestackState } from "../lib/metadata.ts";
-import { ensureMetadata, ensureCleanWorkingTree } from "../lib/safety.ts";
+import { ensureMetadata, ensureCleanWorkingTree, ensureValidStack } from "../lib/safety.ts";
 import { takeSnapshot } from "../lib/snapshot.ts";
 import { confirmAction } from "../lib/ui.ts";
 
@@ -36,6 +36,7 @@ with the base branch included.
   }
 
   const stack = meta.stacks[stackName]!;
+  await ensureValidStack(meta, stackName);
   const ordered = getOrderedBranches(stack);
 
   if (ordered.length === 0) {
@@ -54,6 +55,28 @@ with the base branch included.
     process.exit(1);
   }
 
+  if (dryRun) {
+    p.log.warn("[DRY RUN] No changes will be made");
+    p.log.info("Planned operations:");
+    console.log(`  ${pc.yellow("1.")} Fetch latest ${pc.cyan("origin/main")}`);
+    console.log(
+      `  ${pc.yellow("2.")} Rebase ${pc.yellow(baseBranch)} onto ${pc.cyan("origin/main")}`,
+    );
+
+    const children = ordered.slice(1);
+    if (children.length === 0) {
+      console.log(`  ${pc.yellow("3.")} No child branches to restack`);
+    } else {
+      console.log(`  ${pc.yellow("3.")} Restack child branches in order:`);
+      for (const branch of children) {
+        const parent = stack.branches[branch]?.parent || "(unknown)";
+        console.log(`     ${pc.yellow("→")} ${branch} ${pc.blue(`(parent: ${parent})`)}`);
+      }
+    }
+    p.outro(pc.green("Sync dry run complete"));
+    return;
+  }
+
   // Fetch main
   const fetchSpinner = p.spinner();
   fetchSpinner.start("Fetching latest main...");
@@ -76,7 +99,7 @@ with the base branch included.
     const parentRef = parent === "main" ? "origin/main" : parent;
     const mb = await git.mergeBase(branch, parentRef);
     if (mb) {
-      const tagName = `stack-sync-base-${git.sanitizeBranchForTag(branch)}`;
+      const tagName = git.tempBaseTagName(branch);
       await git.createTag(tagName, mb);
       console.log(
         `  ${pc.green("✓")} Tagged base for ${branch}: ${pc.cyan(tagName)} (${mb.slice(0, 8)})`,

package/src/commands/undo.ts

@@ -1,5 +1,6 @@
 // gh-stack undo — Restore from last snapshot
 import * as p from "@clack/prompts";
+import * as git from "../lib/git.ts";
 import pc from "picocolors";
 import { ensureMetadata, ensureCleanWorkingTree } from "../lib/safety.ts";
 import { getLastSnapshot, popSnapshot } from "../lib/snapshot.ts";
@@ -47,10 +48,21 @@ a destructive operation (restack, merge, sync, remove).
     process.exit(0);
   }
 
+  let activeBranch: string | null = null;
+  try {
+    activeBranch = await git.currentBranch();
+  } catch {
+    // Detached HEAD is fine — we can restore all branches with branch -f.
+  }
+
   // Restore each branch HEAD
   for (const [branch, sha] of Object.entries(snapshot.branches)) {
     try {
-      await $`git branch -f ${branch} ${sha}`.quiet();
+      if (branch === activeBranch) {
+        await $`git reset --hard ${sha}`.quiet();
+      } else {
+        await $`git branch -f ${branch} ${sha}`.quiet();
+      }
       p.log.success(`Restored ${pc.yellow(branch)} → ${sha.slice(0, 8)}`);
     } catch {
       p.log.error(`Failed to restore ${branch}`);

package/src/commands/update-prs.ts

@@ -46,6 +46,7 @@ showing the tree structure, PR links, and review status.
     branch: string;
     prNumber: number | null;
     prTitle: string;
+    prUrl: string | null;
     reviewEmojiStr: string;
   }
 
@@ -55,12 +56,14 @@ showing the tree structure, PR links, and review status.
     const branchMeta = stack.branches[branchName]!;
     const prNumber = branchMeta.pr ?? null;
     let prTitle = branchMeta.description || branchName;
+    let prUrl: string | null = null;
     let review = "PENDING";
 
     if (prNumber) {
       const info = await getPrInfo(prNumber);
       if (info) {
         prTitle = info.title || prTitle;
+        prUrl = info.url;
         review = info.reviewDecision || "PENDING";
       }
     }
@@ -69,6 +72,7 @@ showing the tree structure, PR links, and review status.
       branch: branchName,
       prNumber,
       prTitle,
+      prUrl,
       reviewEmojiStr: reviewEmoji(review),
     });
   }
@@ -131,10 +135,11 @@ interface BranchPrInfo {
   branch: string;
   prNumber: number | null;
   prTitle: string;
+  prUrl: string | null;
   reviewEmojiStr: string;
 }
 
-function buildStackViz(branches: BranchPrInfo[], targetIndex: number): string {
+export function buildStackViz(branches: BranchPrInfo[], targetIndex: number): string {
   const lines: string[] = ["### 📚 Stacked on", ""];
 
   if (branches.length === 1) {
@@ -154,7 +159,7 @@ function buildStackViz(branches: BranchPrInfo[], targetIndex: number): string {
     // PR link
     let prLink: string;
     if (info.prNumber) {
-      prLink = `<a href="https://github.com/beehiiv/swarm/pull/${info.prNumber}">#${info.prNumber}</a>`;
+      prLink = info.prUrl ? `<a href="${info.prUrl}">#${info.prNumber}</a>` : `#${info.prNumber}`;
     } else {
       prLink = "(no PR yet)";
     }

package/src/index.ts

@@ -7,26 +7,28 @@ if (process.env.GH_STACK_NO_COLOR) {
 }
 
 import { ensureGitRepo } from "./lib/safety.ts";
+import { parseCliArgs } from "./lib/cli.ts";
 import { setAutoYes } from "./lib/ui.ts";
 
 const { version: VERSION } = await import("../package.json");
 
 const args = process.argv.slice(2);
-const command = args[0] || "show";
+const parsed = parseCliArgs(args, process.env);
+const command = parsed.command;
 
 // Handle global flags
-if (args.includes("--version") || args.includes("-V")) {
+if (parsed.showVersion) {
   console.log(`gh-stack v${VERSION}`);
   process.exit(0);
 }
 
-if (args.includes("--help") && !args[0]) {
+if (parsed.showGlobalHelp) {
   printHelp();
   process.exit(0);
 }
 
 // Global --yes flag: skip all interactive confirmations (for agents/CI)
-if (args.includes("--yes") || args.includes("-y") || process.env.GH_STACK_YES === "1") {
+if (parsed.autoYes) {
   setAutoYes(true);
 }
 
@@ -34,7 +36,7 @@ if (args.includes("--yes") || args.includes("-y") || process.env.GH_STACK_YES ==
 await ensureGitRepo();
 
 // Route to subcommand — strip global flags from command args
-const commandArgs = args.slice(1).filter((a) => a !== "--yes" && a !== "-y");
+const commandArgs = parsed.commandArgs;
 
 switch (command) {
   case "show":

package/src/lib/cli.ts

@@ -0,0 +1,32 @@
+export interface ParsedCliArgs {
+  command: string;
+  commandArgs: string[];
+  autoYes: boolean;
+  showVersion: boolean;
+  showGlobalHelp: boolean;
+}
+
+const LEADING_GLOBAL_FLAGS = new Set(["--yes", "-y", "--help", "--version", "-V"]);
+
+export function parseCliArgs(rawArgs: string[], env: NodeJS.ProcessEnv): ParsedCliArgs {
+  let commandIndex = 0;
+  const leadingFlags = new Set<string>();
+
+  while (commandIndex < rawArgs.length && LEADING_GLOBAL_FLAGS.has(rawArgs[commandIndex]!)) {
+    leadingFlags.add(rawArgs[commandIndex]!);
+    commandIndex++;
+  }
+
+  const command = rawArgs[commandIndex] || "show";
+  const commandArgs = rawArgs
+    .slice(commandIndex + 1)
+    .filter((arg) => arg !== "--yes" && arg !== "-y");
+
+  return {
+    command,
+    commandArgs,
+    autoYes: rawArgs.includes("--yes") || rawArgs.includes("-y") || env.GH_STACK_YES === "1",
+    showVersion: leadingFlags.has("--version") || leadingFlags.has("-V"),
+    showGlobalHelp: !rawArgs[commandIndex] && leadingFlags.has("--help"),
+  };
+}

package/src/lib/git.ts

@@ -1,5 +1,9 @@
 // Git command helpers using Bun's shell API
 import { $ } from "bun";
+import { createHash } from "node:crypto";
+
+export const STACK_SYNC_TAG_PREFIX = "stack-sync-base";
+export const STACK_SYNC_TAG_GLOB = `${STACK_SYNC_TAG_PREFIX}-*`;
 
 /**
  * Get the current branch name.
@@ -141,6 +145,16 @@ export async function remoteBranchExists(branch: string): Promise<boolean> {
   return exitCode === 0;
 }
 
+/**
+ * Check if a branch exists locally.
+ */
+export async function localBranchExists(branch: string): Promise<boolean> {
+  const { exitCode } = await $`git show-ref --verify --quiet refs/heads/${branch}`
+    .nothrow()
+    .quiet();
+  return exitCode === 0;
+}
+
 /**
  * Create a temporary tag at a specific commit.
  */
@@ -230,8 +244,16 @@ export async function commitCount(from: string, to: string): Promise<number> {
 }
 
 /**
- * Sanitize a branch name for use in tag names.
+ * Build a deterministic temp tag name for a branch.
+ * Includes a readable slug plus a stable hash to avoid collisions.
  */
-export function sanitizeBranchForTag(branch: string): string {
-  return branch.replace(/[^a-zA-Z0-9-]/g, "_");
+export function tempBaseTagName(branch: string): string {
+  const slug =
+    branch
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 24) || "branch";
+  const hash = createHash("sha256").update(branch).digest("hex").slice(0, 10);
+  return `${STACK_SYNC_TAG_PREFIX}-${slug}-${hash}`;
 }

package/src/lib/safety.ts

@@ -1,7 +1,7 @@
 // Pre-flight safety checks
 import * as git from "./git.ts";
 import { metadataExists, readMetadata, findStackForBranch } from "./metadata.ts";
-import type { StackMetadata } from "../types.ts";
+import type { StackMetadata, Stack } from "../types.ts";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
 
@@ -96,3 +96,111 @@ export function ensureNotMain(branch: string): void {
     process.exit(1);
   }
 }
+
+/**
+ * Validate stack metadata before destructive operations.
+ */
+export async function validateStack(meta: StackMetadata, stackName: string): Promise<string[]> {
+  const stack = meta.stacks[stackName];
+  if (!stack) return [`Stack "${stackName}" not found`];
+
+  const branchNames = Object.keys(stack.branches);
+  const errors: string[] = [];
+
+  for (const branchName of branchNames) {
+    const branch = stack.branches[branchName]!;
+
+    if (!(await git.localBranchExists(branchName))) {
+      errors.push(`Branch "${branchName}" does not exist locally`);
+    }
+
+    if (branch.parent === branchName) {
+      errors.push(`Branch "${branchName}" cannot be its own parent`);
+    }
+
+    if (branch.parent !== "main" && branch.parent !== "master" && !stack.branches[branch.parent]) {
+      errors.push(`Branch "${branchName}" has unknown parent "${branch.parent}"`);
+    }
+  }
+
+  errors.push(...validateStackGraph(stack));
+  return errors;
+}
+
+export async function ensureValidStack(meta: StackMetadata, stackName: string): Promise<void> {
+  const errors = await validateStack(meta, stackName);
+  if (errors.length === 0) return;
+
+  p.cancel(`Invalid stack metadata for ${pc.yellow(stackName)}`);
+  console.log();
+  for (const error of errors) {
+    console.log(`  ${pc.red("•")} ${error}`);
+  }
+  console.log();
+  console.log(
+    pc.dim("Fix .git/gh-stack-metadata.json or repair the local branches before retrying."),
+  );
+  process.exit(1);
+}
+
+function validateStackGraph(stack: Stack): string[] {
+  const branchNames = Object.keys(stack.branches);
+  if (branchNames.length === 0) return [];
+
+  const errors: string[] = [];
+  const roots = branchNames.filter((branchName) => {
+    const parent = stack.branches[branchName]!.parent;
+    return parent === "main" || parent === "master";
+  });
+
+  if (roots.length === 0) {
+    errors.push("Stack has no root branch with parent main/master");
+  }
+  if (roots.length > 1) {
+    errors.push(`Stack must have exactly one root branch; found ${roots.length}`);
+  }
+
+  const childrenByParent = new Map<string, string[]>();
+  for (const [branchName, branch] of Object.entries(stack.branches)) {
+    const siblings = childrenByParent.get(branch.parent) ?? [];
+    siblings.push(branchName);
+    childrenByParent.set(branch.parent, siblings);
+  }
+
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+
+  function walk(branchName: string) {
+    if (visiting.has(branchName)) {
+      errors.push(`Cycle detected involving "${branchName}"`);
+      return;
+    }
+    if (visited.has(branchName)) return;
+
+    visiting.add(branchName);
+    for (const child of childrenByParent.get(branchName) ?? []) {
+      walk(child);
+    }
+    visiting.delete(branchName);
+    visited.add(branchName);
+  }
+
+  for (const root of roots) {
+    walk(root);
+  }
+
+  // If the graph is malformed, walk any remaining nodes so we can report
+  // cycles/unreachable branches instead of stopping at the root error.
+  for (const branchName of branchNames) {
+    if (!visited.has(branchName)) {
+      walk(branchName);
+    }
+  }
+
+  if (visited.size !== branchNames.length) {
+    const unreachable = branchNames.filter((branchName) => !visited.has(branchName));
+    errors.push(`Unreachable or cyclic branches detected: ${unreachable.join(", ")}`);
+  }
+
+  return errors;
+}