gh-stack 0.1.2 → 0.2.0

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/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

@@ -39,27 +39,27 @@ await ensureGitRepo();
 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;
@@ -73,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":
@@ -93,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();
@@ -111,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
 

package/src/lib/cli.ts

@@ -17,7 +17,7 @@ export function parseCliArgs(rawArgs: string[], env: NodeJS.ProcessEnv): ParsedC
     commandIndex++;
   }
 
-  const command = rawArgs[commandIndex] || "show";
+  const command = rawArgs[commandIndex] || "log";
   const commandArgs = rawArgs
     .slice(commandIndex + 1)
     .filter((arg) => arg !== "--yes" && arg !== "-y");

package/src/lib/git.ts

@@ -40,9 +40,12 @@ export async function gitDir(): Promise<string> {
 
 /**
  * Check if working tree is clean (no uncommitted changes).
+ * Refreshes the index first to avoid false positives from stale stat info.
  */
 export async function isCleanWorkingTree(): Promise<boolean> {
   try {
+    // Refresh index to avoid false positives from stat changes (timestamps, etc.)
+    await $`git update-index -q --refresh`.quiet().nothrow();
     await $`git diff-index --quiet HEAD --`.quiet();
     return true;
   } catch {
@@ -243,6 +246,14 @@ export async function commitCount(from: string, to: string): Promise<number> {
   }
 }
 
+/**
+ * Get all local branch names.
+ */
+export async function allLocalBranches(): Promise<string[]> {
+  const result = await $`git branch --format=${"%(refname:short)"}`.text();
+  return result.trim().split("\n").filter(Boolean);
+}
+
 /**
  * Build a deterministic temp tag name for a branch.
  * Includes a readable slug plus a stable hash to avoid collisions.

package/src/lib/safety.ts

@@ -58,7 +58,7 @@ export async function ensureBranchInStack(meta: StackMetadata): Promise<string>
 
   if (!stackName) {
     p.cancel(
-      `Branch ${pc.blue(branch)} is not in any stack.\n\n  Add it with:\n    ${pc.green("gh-stack add")}\n\n  Or create a new stack:\n    ${pc.green("gh-stack init")}`,
+      `Branch ${pc.blue(branch)} is not in any stack.\n\n  Add it with:\n    ${pc.green("gh-stack create")}\n\n  Or create a new stack:\n    ${pc.green("gh-stack init")}`,
     );
     process.exit(1);
   }

package/src/commands/add.ts

@@ -1,140 +0,0 @@
-// gh-stack add — Add a branch to the current stack
-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, ensureValidStack } from "../lib/safety.ts";
-import { getPrNumber } from "../lib/github.ts";
-import { isAutoYes, selectParent } from "../lib/ui.ts";
-import type { Branch } from "../types.ts";
-
-export default async function add(args: string[]): Promise<void> {
-  // Parse flags
-  let parentFlag: string | undefined;
-  let descFlag: string | undefined;
-  let createFlag: string | undefined;
-  let branchArg: string | undefined;
-
-  for (let i = 0; i < args.length; i++) {
-    switch (args[i]) {
-      case "--parent":
-        parentFlag = args[++i];
-        break;
-      case "--description":
-        descFlag = args[++i];
-        break;
-      case "--create":
-        createFlag = args[++i];
-        break;
-      case "--help":
-        console.log(`
-gh-stack add — Add a branch to the current stack
-
-USAGE
-  gh-stack add [<branch>] [options]
-
-OPTIONS
-  --parent <branch>     Parent branch (default: top of stack)
-  --create <branch>     Create new branch off top of stack and add it
-  --description <desc>  Description for the branch
-`);
-        return;
-      default:
-        if (!args[i]!.startsWith("--")) {
-          branchArg = args[i];
-        }
-    }
-  }
-
-  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)}`));
-
-  let branchToAdd: string;
-
-  // --create: make a new branch off the top of the stack
-  if (createFlag) {
-    const topBranch = getTopOfStack(stack);
-    if (!topBranch) {
-      p.cancel("Stack has no branches yet. Add the base branch first.");
-      process.exit(1);
-    }
-
-    const currentBranch = await git.currentBranch();
-    if (currentBranch !== topBranch) {
-      p.log.info(`Switching to ${pc.yellow(topBranch)}...`);
-      await git.checkout(topBranch);
-    }
-
-    p.log.info(`Creating branch off top of stack: ${pc.yellow(topBranch)}`);
-    await git.createBranch(createFlag);
-    p.log.success(`Created branch: ${pc.yellow(createFlag)}`);
-
-    branchToAdd = createFlag;
-    parentFlag = topBranch;
-  } else {
-    branchToAdd = branchArg || (await git.currentBranch());
-  }
-
-  // Check if branch is already in the stack
-  if (stack.branches[branchToAdd]) {
-    p.cancel(`Branch ${pc.yellow(branchToAdd)} is already in stack ${pc.blue(stackName)}`);
-    process.exit(1);
-  }
-
-  console.log(`  Adding: ${pc.yellow(branchToAdd)}`);
-  console.log();
-
-  // Get parent
-  let parent = parentFlag;
-  if (!parent) {
-    // Default to top of stack
-    const ordered = getOrderedBranches(stack);
-
-    if (ordered.length === 0) {
-      parent = "main";
-    } else if (isAutoYes()) {
-      parent = getTopOfStack(stack) ?? "main";
-    } else {
-      parent = (await selectParent(stack, branchToAdd)) ?? undefined;
-      if (!parent) {
-        p.cancel("Cancelled");
-        process.exit(0);
-      }
-    }
-  }
-
-  p.log.info(`Parent: ${pc.yellow(parent)}`);
-
-  // Auto-detect PR number
-  const s = p.spinner();
-  s.start("Looking for PR...");
-  const prNumber = await getPrNumber(branchToAdd);
-  s.stop(prNumber ? `Found PR #${prNumber}` : "No PR found");
-
-  // Get description
-  let description = descFlag;
-  if (description === undefined && !createFlag) {
-    const result = await p.text({
-      message: "Branch description (optional)",
-      placeholder: "e.g., API layer",
-    });
-    if (!p.isCancel(result)) {
-      description = (result as string) || undefined;
-    }
-  }
-
-  // Add branch
-  const branchData: Branch = {
-    parent,
-    ...(prNumber && { pr: prNumber }),
-    ...(description && { description }),
-  };
-
-  await addBranchToStack(meta, stackName, branchToAdd, branchData);
-
-  p.outro(pc.green(`Added ${pc.yellow(branchToAdd)} to stack ${pc.blue(stackName)}`));
-}