gh-stack 0.7.1 → 0.9.0

package/src/commands/submit.ts

@@ -11,9 +11,9 @@ import {
 } from "../lib/metadata.ts";
 import { isAutoYes } from "../lib/ui.ts";
 import type { StackMetadata } from "../types.ts";
-import { getPrNumber, getPrInfo, getPrBody, updatePrBody, reviewEmoji } from "../lib/github.ts";
+import { getPrNumber } from "../lib/github.ts";
 import { resolveOrCreateStack } from "../lib/chain.ts";
-import { buildStackViz } from "./update-prs.ts";
+import { refreshStackViz, branchToTitle } from "./update-prs.ts";
 
 const HELP = `
 gh-stack submit — Push branches and create/update PRs
@@ -51,15 +51,6 @@ EXAMPLES
  * 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);
-}
-
 /**
  * Check if a local branch is up-to-date with its remote counterpart.
  */
@@ -136,7 +127,7 @@ export default async function submit(args: string[]): Promise<void> {
   // Reconstruct the stack from local branch ancestry so the end state is
   // always stack registered + branches pushed + PRs created — no need to
   // remember to run `gh-stack init` first.
-  let heal: { trunk: string; chain: string[]; created: boolean; added: string[] } | null = null;
+  let heal: { base: string; chain: string[]; created: boolean; added: string[] } | null = null;
   if (!stackName) {
     const trunk = await git.trunkBranch();
 
@@ -157,7 +148,7 @@ export default async function submit(args: string[]): Promise<void> {
 
     stackName = resolution.stackName;
     heal = {
-      trunk,
+      base: resolution.base,
       chain: resolution.chain,
       created: resolution.created,
       added: resolution.addedBranches,
@@ -183,13 +174,15 @@ export default async function submit(args: string[]): Promise<void> {
         `No stack found — created ${pc.yellow(stackName)} from ${heal.chain.length} local branch(es)`,
       );
     } else if (heal.added.length > 0) {
+      const baseNote =
+        heal.base === "main" || heal.base === "master" ? "" : ` (base: ${heal.base})`;
       p.log.success(
-        `Reconciled ${heal.added.length} untracked branch(es) into ${pc.yellow(stackName)}`,
+        `Adopted ${heal.added.length} untracked branch(es) into ${pc.yellow(stackName)}${pc.dim(baseNote)}`,
       );
     }
 
     console.log();
-    console.log(`  ${pc.dim(heal.trunk)}`);
+    console.log(`  ${pc.dim(heal.base)}`);
     for (let i = 0; i < heal.chain.length; i++) {
       const b = heal.chain[i]!;
       const isLast = i === heal.chain.length - 1;
@@ -256,16 +249,21 @@ export default async function submit(args: string[]): Promise<void> {
     }
 
     if (prNumber) {
-      // ── Existing PR: update base if needed ──
+      // ── Existing PR: update base only if the parent actually changed ──
       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
+        // Skip the network round-trip when the base we last set still matches
+        // the current parent — the common case on a re-submit (issue #16).
+        if (branchMeta.prBase !== parentBranch) {
+          try {
+            await $`gh pr edit ${prNumber} --base ${parentBranch}`.quiet();
+            branchMeta.prBase = parentBranch;
+            metadataChanged = true;
+          } catch {
+            // Best effort — base might already be correct
+          }
         }
         p.log.info(`${pc.dim("✓")} PR #${prNumber} for ${pc.blue(branchName)}`);
       }
@@ -327,6 +325,8 @@ export default async function submit(args: string[]): Promise<void> {
 
           if (newPrNumber) {
             branchMeta.pr = newPrNumber;
+            branchMeta.prTitle = title;
+            branchMeta.prBase = parentBranch;
             metadataChanged = true;
             s.stop(`Created PR #${newPrNumber} for ${pc.blue(branchName)}`);
           } else {
@@ -342,11 +342,6 @@ export default async function submit(args: string[]): Promise<void> {
     }
   }
 
-  // Save metadata if we discovered or created PRs
-  if (metadataChanged && !dryRun) {
-    await writeMetadata(meta);
-  }
-
   console.log();
 
   if (dryRun) {
@@ -358,76 +353,23 @@ export default async function submit(args: string[]): Promise<void> {
     return;
   }
 
-  // ── Phase 2: Update stack visualization in all PR descriptions ──
+  // ── Phase 2: Refresh the stack visualization (renders locally, PATCHes only
+  // the PRs whose block actually changed; see issue #16). ──
   p.log.info(pc.cyan("Updating stack visualization..."));
+  const viz = await refreshStackViz(meta, stack, ordered);
 
-  // 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++;
+  // One persist for everything we cached this run (discovered PRs, base edits,
+  // backfilled titles, viz hashes).
+  if (metadataChanged || viz.dirty) {
+    await writeMetadata(meta);
   }
 
   // ── Summary ──
   console.log();
   p.outro(
     pc.green(
-      `Done! Pushed ${pushed} branch(es), created ${created} PR(s), updated ${vizUpdated} description(s)`,
+      `Done! Pushed ${pushed} branch(es), created ${created} PR(s), updated ${viz.updated} description(s)` +
+        (viz.unchanged > 0 ? `, ${viz.unchanged} unchanged` : ""),
     ),
   );
 }

package/src/commands/sync.ts

@@ -2,7 +2,12 @@
 import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
-import { findStackForBranch, getOrderedBranches, saveRestackState } from "../lib/metadata.ts";
+import {
+  findStackForBranch,
+  getOrderedBranches,
+  saveRestackState,
+  stackBase,
+} from "../lib/metadata.ts";
 import { ensureMetadata, ensureCleanWorkingTree, ensureValidStack } from "../lib/safety.ts";
 import { takeSnapshot } from "../lib/snapshot.ts";
 import { confirmAction } from "../lib/ui.ts";
@@ -56,12 +61,27 @@ with the base branch included.
 
   p.intro(pc.cyan("Git Stack Sync"));
 
-  // Find the base branch (first branch, parent = main)
+  // Find the root branch (whose parent is the stack's base)
+  const base = stackBase(stack);
+  const baseIsTrunk = base === "main" || base === "master";
   const baseBranch = ordered[0]!;
   const baseParent = stack.branches[baseBranch]?.parent;
 
-  if (baseParent !== "main") {
-    p.cancel(`Base branch ${pc.yellow(baseBranch)} doesn't have main as parent`);
+  // sync only makes sense for trunk-rooted stacks — it fetches main and
+  // rebases onto it. A split stack is rooted on a branch in another stack, so
+  // syncing it means restacking onto that base (handled by `restack`), or
+  // re-rooting onto main once the parent stack has merged.
+  if (!baseIsTrunk) {
+    p.cancel(
+      `${pc.yellow(stackName)} is based on ${pc.yellow(base)}, not main — sync doesn't apply.\n\n` +
+        `  • Parent moved? Restack onto it:   ${pc.green("gh-stack restack")}\n` +
+        `  • Parent stack merged to main?     ${pc.green("gh-stack restack --onto main")}`,
+    );
+    process.exit(1);
+  }
+
+  if (baseParent !== base) {
+    p.cancel(`Root branch ${pc.yellow(baseBranch)} doesn't have ${base} as parent`);
     process.exit(1);
   }
 

package/src/commands/update-prs.ts

@@ -1,11 +1,162 @@
 // gh-stack update-prs — Update PR descriptions with stack visualization
-// Port of reference/gh-stack-update-pr.sh
+//
+// The visualization is rendered entirely from local metadata (PR number,
+// cached title, stack position) plus a single repo-identity lookup for URLs —
+// no per-PR API call. `submit` reuses `refreshStackViz` and skips PATCHing any
+// PR whose rendered block hasn't changed (see issue #16). Review/CI status is
+// intentionally NOT shown here; that's tracked out-of-band.
 import * as p from "../lib/output.ts";
 import pc from "picocolors";
+import { createHash } from "node:crypto";
 import * as git from "../lib/git.ts";
-import { findStackForBranch, getOrderedBranches } from "../lib/metadata.ts";
+import {
+  findStackForBranch,
+  getOrderedBranches,
+  stackBase,
+  writeMetadata,
+} from "../lib/metadata.ts";
 import { ensureMetadata } from "../lib/safety.ts";
-import { getPrInfo, getPrBody, updatePrBody, reviewEmoji } from "../lib/github.ts";
+import { getPrInfo, getPrBody, updatePrBody, getRepoNwo, prUrlFor } from "../lib/github.ts";
+import type { StackMetadata, Stack } from "../types.ts";
+
+/** The ref a stack is rooted on, for rendering the base node of the viz. */
+export interface BaseRef {
+  label: string; // "main" or a branch name (for split stacks)
+  prNumber?: number | null;
+  prUrl?: string | null;
+}
+
+export interface BranchPrInfo {
+  branch: string;
+  prNumber: number | null;
+  prTitle: string;
+  prUrl: string | null;
+}
+
+/** Derive a readable PR title from a branch name (fallback when uncached). */
+export function branchToTitle(branch: string): string {
+  let name = branch.includes("/") ? branch.split("/").slice(1).join("/") : branch;
+  name = name.replace(/-/g, " ");
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+
+/**
+ * Resolve the base node for a stack's visualization. For a split stack whose
+ * base is a branch in another stack, link to that branch's PR. The URL is
+ * constructed locally from the repo identity — no API call.
+ */
+export async function resolveBaseRef(
+  meta: StackMetadata,
+  stack: Stack,
+  nwo: string | null,
+): Promise<BaseRef> {
+  const base = stackBase(stack);
+  if (base === "main" || base === "master") return { label: base };
+
+  const ownerName = findStackForBranch(meta, base);
+  const prNumber = ownerName ? (meta.stacks[ownerName]?.branches[base]?.pr ?? null) : null;
+  return { label: base, prNumber, prUrl: prNumber ? prUrlFor(nwo, prNumber) : null };
+}
+
+/** Build a BranchPrInfo from metadata alone (no network). */
+function toBranchInfo(stack: Stack, branch: string, nwo: string | null): BranchPrInfo {
+  const bm = stack.branches[branch]!;
+  const prNumber = bm.pr ?? null;
+  return {
+    branch,
+    prNumber,
+    prTitle: bm.prTitle || bm.description || branchToTitle(branch),
+    prUrl: prNumber ? prUrlFor(nwo, prNumber) : null,
+  };
+}
+
+/**
+ * Fill in missing cached PR titles (one-time, e.g. right after migrating to v3
+ * or adopting existing PRs). Fetches only the branches that lack a title, in
+ * parallel; subsequent submits read straight from the cache. Returns true if
+ * any title was written.
+ */
+async function backfillTitles(stack: Stack, ordered: string[]): Promise<boolean> {
+  const missing = ordered.filter((b) => {
+    const bm = stack.branches[b]!;
+    return bm.pr != null && !bm.prTitle;
+  });
+  if (missing.length === 0) return false;
+
+  await mapLimit(missing, 8, async (branch) => {
+    const bm = stack.branches[branch]!;
+    const info = await getPrInfo(bm.pr!);
+    if (info?.title) bm.prTitle = info.title;
+  });
+  return true;
+}
+
+function vizHash(viz: string): string {
+  return createHash("sha1").update(viz).digest("hex");
+}
+
+/** Splice the rendered viz block into a PR body, replacing any existing one. */
+function mergeViz(body: string, viz: string): string {
+  let base = body;
+  const idx = base.indexOf("### 📚 Stacked on");
+  if (idx !== -1) base = base.slice(0, idx).trimEnd();
+  return base ? `${base}\n\n${viz}` : viz;
+}
+
+export interface VizResult {
+  updated: number; // PRs whose description we PATCHed
+  unchanged: number; // PRs skipped because their rendered block was identical
+  skipped: number; // branches with no PR
+  dirty: boolean; // metadata mutated (caller should persist)
+}
+
+/**
+ * Refresh the stack visualization across a stack's PRs. Renders every block
+ * locally, then PATCHes only the PRs whose block actually changed (unless
+ * `force`), running the surviving PATCHes concurrently.
+ */
+export async function refreshStackViz(
+  meta: StackMetadata,
+  stack: Stack,
+  ordered: string[],
+  opts: { force?: boolean } = {},
+): Promise<VizResult> {
+  const force = opts.force ?? false;
+  const nwo = await getRepoNwo();
+
+  let dirty = await backfillTitles(stack, ordered);
+
+  const branchInfos = ordered.map((b) => toBranchInfo(stack, b, nwo));
+  const baseRef = await resolveBaseRef(meta, stack, nwo);
+
+  // Render every block locally and decide what needs writing — no network yet.
+  const plans = branchInfos
+    .map((info, i) => ({ info, i }))
+    .filter(({ info }) => info.prNumber != null)
+    .map(({ info, i }) => {
+      const viz = buildStackViz(branchInfos, i, baseRef);
+      const hash = vizHash(viz);
+      const bm = stack.branches[info.branch]!;
+      return { info, viz, hash, bm, needsUpdate: force || bm.vizHash !== hash };
+    });
+
+  const toUpdate = plans.filter((plan) => plan.needsUpdate);
+  const unchanged = plans.length - toUpdate.length;
+  const skipped = branchInfos.length - plans.length;
+
+  const oks = await mapLimit(toUpdate, 8, async (plan) => {
+    const body = await getPrBody(plan.info.prNumber!);
+    if (body === null) return false;
+    const ok = await updatePrBody(plan.info.prNumber!, mergeViz(body, plan.viz));
+    if (ok) plan.bm.vizHash = plan.hash;
+    return ok;
+  });
+
+  const updated = oks.filter(Boolean).length;
+  if (updated > 0) dirty = true;
+
+  return { updated, unchanged, skipped, dirty };
+}
 
 export default async function updatePrs(args: string[]): Promise<void> {
   if (args.includes("--help")) {
@@ -13,14 +164,16 @@ export default async function updatePrs(args: string[]): Promise<void> {
 gh-stack update-prs — Update PR descriptions with stack visualization
 
 USAGE
-  gh-stack update-prs
+  gh-stack update-prs [--force]
 
 Updates all PRs in the current stack with a standardized stack section
-showing the tree structure, PR links, and review status.
+showing the tree structure, PR links, and per-PR stack index. By default
+PRs whose rendered block is unchanged are skipped; --force rewrites all.
 `);
     return;
   }
 
+  const force = args.includes("--force");
   const meta = await ensureMetadata();
   const branch = await git.currentBranch();
   const stackName = findStackForBranch(meta, branch);
@@ -38,117 +191,43 @@ showing the tree structure, PR links, and review status.
   p.log.info(`Found ${ordered.length} branch(es) in stack`);
   console.log();
 
-  // Collect PR info for all branches
   const s = p.spinner();
-  s.start("Fetching PR info from GitHub...");
-
-  interface BranchPrInfo {
-    branch: string;
-    prNumber: number | null;
-    prTitle: string;
-    prUrl: string | null;
-    reviewEmojiStr: string;
-  }
+  s.start("Updating PR descriptions...");
+  const result = await refreshStackViz(meta, stack, ordered, { force });
+  s.stop("Done");
 
-  const branchInfos: BranchPrInfo[] = [];
-
-  for (const branchName of ordered) {
-    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";
-      }
-    }
-
-    branchInfos.push({
-      branch: branchName,
-      prNumber,
-      prTitle,
-      prUrl,
-      reviewEmojiStr: reviewEmoji(review),
-    });
-  }
-
-  s.stop("Fetched PR info");
-
-  // Update each PR
-  let updated = 0;
-  let skipped = 0;
-
-  for (let targetIdx = 0; targetIdx < branchInfos.length; targetIdx++) {
-    const target = branchInfos[targetIdx]!;
-
-    if (!target.prNumber) {
-      p.log.info(`${pc.dim("⏭")} ${target.branch} — no PR, skipping`);
-      skipped++;
-      continue;
-    }
-
-    // Build stack visualization for this PR
-    const stackViz = buildStackViz(branchInfos, targetIdx);
-
-    // Get current PR body and replace/append stack section
-    const currentBody = await getPrBody(target.prNumber);
-    if (currentBody === null) {
-      p.log.warn(`Could not fetch body for PR #${target.prNumber}`);
-      skipped++;
-      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;
-
-    // Update PR
-    const ok = await updatePrBody(target.prNumber, newBody);
-    if (ok) {
-      p.log.success(`PR #${target.prNumber} ${target.prTitle}`);
-      updated++;
-    } else {
-      p.log.error(`Failed to update PR #${target.prNumber}`);
-    }
-  }
+  if (result.dirty) await writeMetadata(meta);
 
   console.log();
   p.outro(
     pc.green(
-      `Done! Updated ${updated} PR(s)${skipped > 0 ? `, skipped ${skipped} without PRs` : ""}`,
+      `Updated ${result.updated} PR(s)` +
+        (result.unchanged > 0 ? `, ${result.unchanged} unchanged` : "") +
+        (result.skipped > 0 ? `, ${result.skipped} without PRs` : ""),
     ),
   );
 }
 
-interface BranchPrInfo {
-  branch: string;
-  prNumber: number | null;
-  prTitle: string;
-  prUrl: string | null;
-  reviewEmojiStr: string;
-}
-
-export function buildStackViz(branches: BranchPrInfo[], targetIndex: number): string {
+export function buildStackViz(
+  branches: BranchPrInfo[],
+  targetIndex: number,
+  base: BaseRef = { label: "main" },
+): string {
   const lines: string[] = ["### 📚 Stacked on", ""];
 
+  // Base node: link to the base PR if there is one (split stacks), else the
+  // plain ref name. `**bold**` renders in markdown but not inside <pre>.
+  const baseLink = base.prNumber
+    ? `${base.prUrl ? `<a href="${base.prUrl}">#${base.prNumber}</a>` : `#${base.prNumber}`} ${base.label}`
+    : null;
+
   if (branches.length === 1) {
-    lines.push("- ⚫ **main**");
+    lines.push(`- ⚫ ${baseLink ?? `**${base.label}**`}`);
     return lines.join("\n");
   }
 
   lines.push("<pre>");
-  lines.push("⚫ main");
+  lines.push(`⚫ ${baseLink ?? base.label}`);
   lines.push("┃");
 
   for (let i = 0; i < branches.length; i++) {
@@ -170,7 +249,9 @@ export function buildStackViz(branches: BranchPrInfo[], targetIndex: number): st
     // Tree character
     const tree = isLast ? "┗━" : "┣━";
 
-    lines.push(`${tree} ${info.reviewEmojiStr} ${prLink} ${info.prTitle}${marker}`);
+    // Leading `N.` is the branch's 1-based position in the stack — makes it
+    // easy to tell which PR is #6 in a 12-PR stack at a glance.
+    lines.push(`${tree} ${i + 1}. ${prLink} ${info.prTitle}${marker}`);
 
     if (!isLast) {
       lines.push("┃");
@@ -180,3 +261,23 @@ export function buildStackViz(branches: BranchPrInfo[], targetIndex: number): st
   lines.push("</pre>");
   return lines.join("\n");
 }
+
+/** Run `fn` over `items` with at most `limit` concurrent in flight. */
+async function mapLimit<T, R>(
+  items: T[],
+  limit: number,
+  fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  const results = Array.from<R>({ length: items.length });
+  let next = 0;
+  async function worker(): Promise<void> {
+    while (true) {
+      const i = next++;
+      if (i >= items.length) return;
+      results[i] = await fn(items[i]!, i);
+    }
+  }
+  const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
+  await Promise.all(workers);
+  return results;
+}

package/src/index.ts

@@ -69,6 +69,10 @@ switch (command) {
     await (await import("./commands/delete.ts")).default(commandArgs);
     break;
 
+  case "split":
+    await (await import("./commands/split.ts")).default(commandArgs);
+    break;
+
   case "checkout":
   case "co":
     await (await import("./commands/checkout.ts")).default(commandArgs);
@@ -103,6 +107,14 @@ switch (command) {
     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 "archive":
     await (await import("./commands/archive.ts")).default(commandArgs);
     break;
@@ -165,12 +177,15 @@ ${bold("STACK MANAGEMENT")}
   ${green("restack")}        Rebase children onto updated parents
   ${green("sync")}           Sync base with main + restack all
   ${green("merge")}          Local squash-merge top-down
+  ${green("split")}          Cut a stack into two at a branch
   ${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
+  ${green("update-prs")}     Refresh stack visualization in PR descriptions
+  ${green("doctor")}         Migrate & repair stack metadata
 
 ${bold("GLOBAL OPTIONS")}
   --yes, -y        Skip confirmations ${dim("(for agents/CI)")}