gh-stack 0.1.1 → 0.2.0

package/src/commands/submit.ts

@@ -0,0 +1,310 @@
+// gh-stack submit — Push branches and create/update PRs
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { $ } from "bun";
+import * as git from "../lib/git.ts";
+import { findStackForBranch, getOrderedBranches, writeMetadata } from "../lib/metadata.ts";
+import { ensureMetadata } from "../lib/safety.ts";
+import { isAutoYes } from "../lib/ui.ts";
+import { getPrNumber, getPrInfo, getPrBody, updatePrBody, reviewEmoji } from "../lib/github.ts";
+import { buildStackViz } from "./update-prs.ts";
+
+const HELP = `
+gh-stack submit — Push branches and create/update PRs
+
+USAGE
+  gh-stack submit [options]
+
+Pushes all branches from trunk to the current branch, creating PRs
+for branches that don't have them and updating stack visualization
+in all PR descriptions. Idempotent — safe to run repeatedly.
+
+OPTIONS
+  -d, --draft      Create new PRs as drafts
+  -n, --no-edit    Don't prompt for PR titles (auto-generate from branch name)
+      --dry-run    Show what would happen without doing anything
+
+EXAMPLES
+  gh-stack submit                # Push + create PRs interactively
+  gh-stack submit -n             # Push + create PRs with auto-titles
+  gh-stack submit --draft        # Create new PRs as drafts
+  gh-stack submit --dry-run      # Preview what would happen
+`;
+
+/**
+ * Generate a PR title from a branch name.
+ * Strips common prefixes like "kiliman/", replaces hyphens with spaces,
+ * and capitalizes the first letter.
+ */
+function branchToTitle(branch: string): string {
+  // Strip common prefixes like "kiliman/", "user/"
+  let name = branch.includes("/") ? branch.split("/").slice(1).join("/") : branch;
+  // Replace hyphens with spaces
+  name = name.replace(/-/g, " ");
+  // Capitalize first letter
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+
+/**
+ * Push a branch to origin with upstream tracking and force-with-lease.
+ */
+async function pushBranch(branch: string): Promise<boolean> {
+  try {
+    await $`git push -u --force-with-lease origin ${branch}`.quiet();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export default async function submit(args: string[]): Promise<void> {
+  if (args.includes("--help")) {
+    console.log(HELP);
+    return;
+  }
+
+  const draftFlag = args.includes("--draft") || args.includes("-d");
+  const dryRun = args.includes("--dry-run");
+  const noEdit = args.includes("--no-edit") || args.includes("-n") || isAutoYes();
+
+  const meta = await ensureMetadata();
+  const branch = await git.currentBranch();
+  const stackName = findStackForBranch(meta, branch);
+
+  if (!stackName) {
+    p.cancel(`Branch ${pc.blue(branch)} not found in any stack`);
+    process.exit(1);
+  }
+
+  const stack = meta.stacks[stackName]!;
+  const ordered = getOrderedBranches(stack);
+
+  // Determine downstack scope: branches from trunk up to and including current
+  const currentIndex = ordered.indexOf(branch);
+  const scope = currentIndex >= 0 ? ordered.slice(0, currentIndex + 1) : ordered;
+
+  p.intro(pc.cyan("Submit Stack"));
+  p.log.info(`Stack: ${pc.yellow(stackName)}`);
+  p.log.info(
+    `Scope: ${scope.length} of ${ordered.length} branch(es) (downstack from ${pc.blue(branch)})`,
+  );
+  console.log();
+
+  if (dryRun) {
+    p.log.info(pc.dim("Dry run — no changes will be made"));
+    console.log();
+  }
+
+  // ── Phase 1: Push branches and create/update PRs ──
+  let pushed = 0;
+  let created = 0;
+  let existing = 0;
+  let metadataChanged = false;
+
+  for (const branchName of scope) {
+    const branchMeta = stack.branches[branchName]!;
+    const parentBranch = branchMeta.parent;
+
+    // ── Push ──
+    if (dryRun) {
+      p.log.step(`${pc.dim("push")} ${branchName} → origin/${branchName}`);
+    } else {
+      const s = p.spinner();
+      s.start(`Pushing ${pc.blue(branchName)}...`);
+      const ok = await pushBranch(branchName);
+      if (ok) {
+        s.stop(`Pushed ${pc.blue(branchName)}`);
+        pushed++;
+      } else {
+        s.stop(pc.red(`Failed to push ${branchName}`));
+        p.cancel(`Push failed for ${pc.blue(branchName)}. Aborting.`);
+        process.exit(1);
+      }
+    }
+
+    // ── Check for existing PR ──
+    let prNumber = branchMeta.pr ?? null;
+
+    if (!prNumber && !dryRun) {
+      prNumber = await getPrNumber(branchName);
+      if (prNumber) {
+        // Found an existing PR not tracked in metadata — save it
+        branchMeta.pr = prNumber;
+        metadataChanged = true;
+      }
+    }
+
+    if (prNumber) {
+      // ── Existing PR: update base if needed ──
+      existing++;
+      if (dryRun) {
+        p.log.step(`${pc.dim("exists")} PR #${prNumber} for ${branchName}`);
+      } else {
+        // Ensure the PR base is correct
+        try {
+          await $`gh pr edit ${prNumber} --base ${parentBranch}`.quiet();
+        } catch {
+          // Best effort — base might already be correct
+        }
+        p.log.info(`${pc.dim("✓")} PR #${prNumber} for ${pc.blue(branchName)}`);
+      }
+    } else {
+      // ── Create new PR ──
+      const defaultTitle = branchToTitle(branchName);
+      let title = defaultTitle;
+
+      if (!noEdit && !dryRun) {
+        const input = await p.text({
+          message: `PR title for ${pc.blue(branchName)}`,
+          initialValue: defaultTitle,
+          placeholder: defaultTitle,
+        });
+        if (p.isCancel(input)) {
+          p.cancel("Cancelled");
+          process.exit(0);
+        }
+        title = (input as string).trim() || defaultTitle;
+      }
+
+      if (dryRun) {
+        p.log.step(
+          `${pc.dim("create")} PR for ${branchName} → ${parentBranch} "${title}"${draftFlag ? " (draft)" : ""}`,
+        );
+        created++;
+      } else {
+        const s = p.spinner();
+        s.start(`Creating PR for ${pc.blue(branchName)}...`);
+
+        const ghArgs = [
+          "pr",
+          "create",
+          "--base",
+          parentBranch,
+          "--head",
+          branchName,
+          "--title",
+          title,
+          "--body",
+          "",
+        ];
+        if (draftFlag) ghArgs.push("--draft");
+
+        const proc = Bun.spawn(["gh", ...ghArgs], {
+          stdout: "pipe",
+          stderr: "pipe",
+        });
+        const output = await new Response(proc.stdout).text();
+        const exitCode = await proc.exited;
+
+        if (exitCode === 0) {
+          // Extract PR number from URL output
+          const prUrl = output.trim();
+          const prNumMatch = prUrl.match(/\/pull\/(\d+)/);
+          const newPrNumber = prNumMatch ? parseInt(prNumMatch[1]!, 10) : null;
+
+          if (newPrNumber) {
+            branchMeta.pr = newPrNumber;
+            metadataChanged = true;
+            s.stop(`Created PR #${newPrNumber} for ${pc.blue(branchName)}`);
+          } else {
+            s.stop(`Created PR for ${pc.blue(branchName)} (could not parse PR number)`);
+          }
+          created++;
+        } else {
+          const stderr = await new Response(proc.stderr).text();
+          s.stop(pc.red(`Failed to create PR for ${branchName}`));
+          p.log.error(stderr.trim());
+        }
+      }
+    }
+  }
+
+  // Save metadata if we discovered or created PRs
+  if (metadataChanged && !dryRun) {
+    await writeMetadata(meta);
+  }
+
+  console.log();
+
+  if (dryRun) {
+    p.outro(
+      pc.dim(
+        `Dry run complete: would push ${scope.length}, create ${created}, update ${existing} PR(s)`,
+      ),
+    );
+    return;
+  }
+
+  // ── Phase 2: Update stack visualization in all PR descriptions ──
+  p.log.info(pc.cyan("Updating stack visualization..."));
+
+  // Collect PR info for ALL branches in the stack (not just scope)
+  interface BranchPrInfo {
+    branch: string;
+    prNumber: number | null;
+    prTitle: string;
+    prUrl: string | null;
+    reviewEmojiStr: string;
+  }
+
+  const branchInfos: BranchPrInfo[] = [];
+
+  for (const branchName of ordered) {
+    const branchMeta = stack.branches[branchName]!;
+    const prNum = branchMeta.pr ?? null;
+    let prTitle = branchMeta.description || branchName;
+    let prUrl: string | null = null;
+    let review = "PENDING";
+
+    if (prNum) {
+      const info = await getPrInfo(prNum);
+      if (info) {
+        prTitle = info.title || prTitle;
+        prUrl = info.url;
+        review = info.reviewDecision || "PENDING";
+      }
+    }
+
+    branchInfos.push({
+      branch: branchName,
+      prNumber: prNum,
+      prTitle,
+      prUrl,
+      reviewEmojiStr: reviewEmoji(review),
+    });
+  }
+
+  // Update each PR that has a number
+  let vizUpdated = 0;
+
+  for (let i = 0; i < branchInfos.length; i++) {
+    const info = branchInfos[i]!;
+    if (!info.prNumber) continue;
+
+    const stackViz = buildStackViz(branchInfos, i);
+
+    const currentBody = await getPrBody(info.prNumber);
+    if (currentBody === null) continue;
+
+    // Remove existing stack section
+    let updatedBody = currentBody;
+    const stackSectionIdx = updatedBody.indexOf("### 📚 Stacked on");
+    if (stackSectionIdx !== -1) {
+      updatedBody = updatedBody.slice(0, stackSectionIdx).trimEnd();
+    }
+
+    // Append new stack section
+    const newBody = updatedBody ? `${updatedBody}\n\n${stackViz}` : stackViz;
+
+    const ok = await updatePrBody(info.prNumber, newBody);
+    if (ok) vizUpdated++;
+  }
+
+  // ── Summary ──
+  console.log();
+  p.outro(
+    pc.green(
+      `Done! Pushed ${pushed} branch(es), created ${created} PR(s), updated ${vizUpdated} description(s)`,
+    ),
+  );
+}

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) {
@@ -98,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/top.ts

@@ -0,0 +1,79 @@
+// gh-stack top — Jump to the tip of the stack
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import * as git from "../lib/git.ts";
+import {
+  findStackForBranch,
+  getOrderedBranches,
+  getChildren,
+  writeMetadata,
+} from "../lib/metadata.ts";
+import { ensureMetadata } from "../lib/safety.ts";
+
+export default async function top(args: string[]): Promise<void> {
+  if (args.includes("--help")) {
+    console.log(`
+gh-stack top — Jump to the tip of the stack
+
+USAGE
+  gh-stack top
+
+Switches to the topmost (leaf) branch of the current stack.
+Prompts if there are multiple leaf branches.
+`);
+    return;
+  }
+
+  const meta = await ensureMetadata();
+  const currentBranch = await git.currentBranch();
+  const stackName = findStackForBranch(meta, currentBranch);
+
+  if (!stackName) {
+    p.cancel(`Branch ${pc.yellow(currentBranch)} is not in any stack`);
+    process.exit(1);
+  }
+
+  const stack = meta.stacks[stackName]!;
+  const ordered = getOrderedBranches(stack);
+
+  // Find leaf branches (no children)
+  const leaves = ordered.filter((b) => getChildren(stack, b).length === 0);
+
+  if (leaves.length === 0) {
+    p.log.warn("No branches in stack");
+    return;
+  }
+
+  let target: string;
+  if (leaves.length === 1) {
+    target = leaves[0]!;
+  } else {
+    const result = await p.select({
+      message: "Multiple tips — which branch?",
+      options: leaves.map((l) => ({
+        value: l,
+        label: l,
+        hint: stack.branches[l]?.pr ? `#${stack.branches[l]!.pr}` : undefined,
+      })),
+    });
+    if (p.isCancel(result)) {
+      p.cancel("Cancelled");
+      process.exit(0);
+    }
+    target = result as string;
+  }
+
+  if (target === currentBranch) {
+    p.log.info(`Already at the top: ${pc.yellow(currentBranch)}`);
+    return;
+  }
+
+  await git.checkout(target);
+
+  // Update tracking
+  stack.last_branch = target;
+  meta.current_stack = stackName;
+  await writeMetadata(meta);
+
+  p.log.success(`On ${pc.yellow(target)}`);
+}

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/up.ts

@@ -0,0 +1,82 @@
+// gh-stack up — Move to child branch (upstack)
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import * as git from "../lib/git.ts";
+import { findStackForBranch, getChildren, writeMetadata } from "../lib/metadata.ts";
+import { ensureMetadata } from "../lib/safety.ts";
+
+export default async function up(args: string[]): Promise<void> {
+  if (args.includes("--help")) {
+    console.log(`
+gh-stack up — Move to child branch (upstack)
+
+USAGE
+  gh-stack up [steps]
+
+OPTIONS
+  [steps]    Number of levels to move up (default: 1)
+`);
+    return;
+  }
+
+  const steps = parseInt(args[0] || "1", 10);
+  if (isNaN(steps) || steps < 1) {
+    p.cancel("Invalid step count");
+    process.exit(1);
+  }
+
+  const meta = await ensureMetadata();
+  let currentBranch = await git.currentBranch();
+  const stackName = findStackForBranch(meta, currentBranch);
+
+  if (!stackName) {
+    p.cancel(`Branch ${pc.yellow(currentBranch)} is not in any stack`);
+    process.exit(1);
+  }
+
+  const stack = meta.stacks[stackName]!;
+
+  for (let i = 0; i < steps; i++) {
+    const children = getChildren(stack, currentBranch);
+
+    if (children.length === 0) {
+      if (i === 0) {
+        p.log.warn(`${pc.yellow(currentBranch)} is already at the top of the stack`);
+      } else {
+        p.log.info(`Reached top of stack at ${pc.yellow(currentBranch)} after ${i} step(s)`);
+      }
+      return;
+    }
+
+    let target: string;
+    if (children.length === 1) {
+      target = children[0]!;
+    } else {
+      // Multiple children — prompt
+      const result = await p.select({
+        message: "Multiple children — which branch?",
+        options: children.map((c) => ({
+          value: c,
+          label: c,
+          hint: stack.branches[c]?.pr ? `#${stack.branches[c]!.pr}` : undefined,
+        })),
+      });
+      if (p.isCancel(result)) {
+        p.cancel("Cancelled");
+        process.exit(0);
+      }
+      target = result as string;
+    }
+
+    currentBranch = target;
+  }
+
+  await git.checkout(currentBranch);
+
+  // Update tracking
+  stack.last_branch = currentBranch;
+  meta.current_stack = stackName;
+  await writeMetadata(meta);
+
+  p.log.success(`On ${pc.yellow(currentBranch)}`);
+}

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,30 +36,30 @@ 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":
-    await (await import("./commands/show.ts")).default(commandArgs);
+  case "log":
+    await (await import("./commands/log.ts")).default(commandArgs);
     break;
 
   case "init":
     await (await import("./commands/init.ts")).default(commandArgs);
     break;
 
-  case "add":
-    await (await import("./commands/add.ts")).default(commandArgs);
+  case "create":
+    await (await import("./commands/create.ts")).default(commandArgs);
     break;
 
-  case "remove":
-    await (await import("./commands/remove.ts")).default(commandArgs);
+  case "delete":
+    await (await import("./commands/delete.ts")).default(commandArgs);
     break;
 
-  case "switch":
-    await (await import("./commands/switch.ts")).default(commandArgs);
+  case "checkout":
+  case "co":
+    await (await import("./commands/checkout.ts")).default(commandArgs);
     break;
 
-  case "list":
   case "ls":
     await (await import("./commands/list.ts")).default(commandArgs);
     break;
@@ -71,8 +73,8 @@ switch (command) {
     await (await import("./commands/sync.ts")).default(commandArgs);
     break;
 
-  case "update-prs":
-    await (await import("./commands/update-prs.ts")).default(commandArgs);
+  case "submit":
+    await (await import("./commands/submit.ts")).default(commandArgs);
     break;
 
   case "status":
@@ -91,6 +93,22 @@ switch (command) {
     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 "--help":
   case "help":
     printHelp();
@@ -109,18 +127,34 @@ gh-stack v${VERSION} — Stacked PR manager for squash-merge workflows
 ${bold("USAGE")}
   gh-stack <command> [options]
 
-${bold("COMMANDS")}
-  ${green("show")}           Display current stack tree ${dim("(default)")}
-  ${green("list")}           List branches with numbers ${dim("(alias: ls)")}
-  ${green("init")}           Create a new stack
-  ${green("add")}            Add a branch to the current stack
-  ${green("remove")}         Remove a branch from the stack
-  ${green("switch")}         Switch branch or stack
+${bold("TERMS")}
+  trunk       Base branch of the repository (usually main)
+  stack       A chain of dependent branches
+  upstack     Branches that depend on the current branch (children)
+  downstack   Branches the current branch depends on (ancestors)
+
+${bold("CORE WORKFLOW")}
+  ${green("init")}           Create a new stack from the current branch
+  ${green("create")}         Create a new branch and add to the stack
+  ${green("submit")}         Push branches and create/update PRs
+  ${green("log")}            Display current stack tree ${dim("(default)")}
+
+${bold("STACK NAVIGATION")}
+  ${green("checkout")}       Switch to a branch or stack ${dim("(alias: co)")}
+  ${green("up")}             Move to child branch (upstack)
+  ${green("down")}           Move to parent branch (downstack)
+  ${green("top")}            Jump to the tip of the stack
+  ${green("bottom")}         Jump to the base of the stack
+  ${green("ls")}             List branches with numbers
+
+${bold("STACK MANAGEMENT")}
   ${green("restack")}        Rebase children onto updated parents
   ${green("sync")}           Sync base with main + restack all
-  ${green("update-prs")}     Update PR descriptions with stack viz
-  ${green("status")}         PR dashboard (CI, reviews)
   ${green("merge")}          Local squash-merge top-down
+  ${green("delete")}         Remove a branch from the stack
+
+${bold("INFO & MAINTENANCE")}
+  ${green("status")}         PR dashboard (CI, reviews)
   ${green("undo")}           Restore from last snapshot
   ${green("archive")}        Manage archived stacks