gh-stack 0.11.0 → 0.12.0

package/README.md

@@ -85,8 +85,9 @@ create <branch-name> [--description <desc>]
 
 submit [-d|--draft] [-n|--no-edit] [-t|--title <t>] [-b|--body <b>] [--body-file <f>] [--dry-run]
     Push all downstack branches to GitHub, create PRs for branches
-    that don't have them, and update all PR descriptions with stack
-    visualization. Idempotent — safe to run repeatedly.
+    that don't have them, number each PR title with its stack position
+    `(N/M)`, and update all PR descriptions with stack visualization.
+    Idempotent — safe to run repeatedly.
 
     Self-healing: if the current branch isn't tracked in a stack yet,
     submit auto-detects the chain from trunk → current, registers (or
@@ -279,19 +280,36 @@ gh-stack solves this by snapshotting every branch's tip **before** any destructi
 
 Snapshots also power `gh-stack undo`, so the same data structure does double duty.
 
+### Stack Position in PR Titles
+
+`submit` keeps each PR's **title** suffixed with its stack position as `(N/M)`,
+so you can see the order from a bare "needs your review" list — where only
+titles show, not descriptions — and review bottom-up:
+
+```
+feat(paid-subs): tiers overview list [BEE-20531] (1/4)
+feat(paid-subs): tier detail page [BEE-20550] (2/4)
+feat(paid-subs): tier create wizard [BEE-20579] (3/4)
+feat(paid-subs): advanced settings step [BEE-20587] (4/4)
+```
+
+Parentheses (not brackets) avoid colliding with `[BEE-1234]` ticket tags. It's
+self-healing and idempotent: re-running `submit` after adding or reordering a
+branch renumbers the whole stack, and a no-op re-submit changes nothing. The
+position is the only managed part of the title — your text (and ticket tags)
+are preserved. Single-PR stacks get no suffix.
+
 ### Stack Visualization
 
-`submit` automatically adds a stack section to all PR descriptions, with each
-branch numbered by its position in the stack (handy for spotting "which one is
-PR 6 of 12"):
+`submit` also adds a stack section to every PR description:
 
 ```
 ### 📚 Stacked on
 ⚫ main
 ┃
-┣━ 1. #123 Backend models
+┣━ #123 feat: backend models (1/2)
 ┃
-┗━ 2. #124 Frontend UI 👈
+┗━ #124 feat: frontend UI (2/2) 👈
 ```
 
 The block is rendered entirely from local metadata plus one repo-identity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gh-stack",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Stacked PR manager for squash-merge workflows",
   "author": "Kiliman <kiliman@gmail.com>",
   "license": "MIT",

package/src/commands/submit.ts

@@ -13,7 +13,7 @@ import { isAutoYes } from "../lib/ui.ts";
 import type { StackMetadata } from "../types.ts";
 import { getPrNumber } from "../lib/github.ts";
 import { resolveOrCreateStack } from "../lib/chain.ts";
-import { refreshStackViz, branchToTitle } from "./update-prs.ts";
+import { reconcilePrTitles, refreshStackViz, branchToTitle } from "./update-prs.ts";
 
 const HELP = `
 gh-stack submit — Push branches and create/update PRs
@@ -353,14 +353,17 @@ export default async function submit(args: string[]): Promise<void> {
     return;
   }
 
-  // ── 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..."));
+  // ── Phase 2: Reconcile PR titles (stack position) then refresh the stack
+  // visualization. Titles first so the viz renders the numbered titles. Both
+  // render locally and only hit the network for PRs that actually changed
+  // (see issue #16), so a no-op re-submit is free. ──
+  p.log.info(pc.cyan("Updating PR titles & stack visualization..."));
+  const titles = await reconcilePrTitles(stack, ordered);
   const viz = await refreshStackViz(meta, stack, ordered);
 
   // One persist for everything we cached this run (discovered PRs, base edits,
-  // backfilled titles, viz hashes).
-  if (metadataChanged || viz.dirty) {
+  // backfilled/renumbered titles, viz hashes).
+  if (metadataChanged || titles.dirty || viz.dirty) {
     await writeMetadata(meta);
   }
 
@@ -368,7 +371,7 @@ export default async function submit(args: string[]): Promise<void> {
   console.log();
   p.outro(
     pc.green(
-      `Done! Pushed ${pushed} branch(es), created ${created} PR(s), updated ${viz.updated} description(s)` +
+      `Done! Pushed ${pushed} branch(es), created ${created} PR(s), updated ${viz.updated} description(s), ${titles.updated} title(s)` +
         (viz.unchanged > 0 ? `, ${viz.unchanged} unchanged` : ""),
     ),
   );

package/src/commands/update-prs.ts

@@ -16,8 +16,15 @@ import {
   writeMetadata,
 } from "../lib/metadata.ts";
 import { ensureMetadata } from "../lib/safety.ts";
-import { getPrInfo, getPrBody, updatePrBody, getRepoNwo, prUrlFor } from "../lib/github.ts";
-import type { StackMetadata, Stack } from "../types.ts";
+import {
+  getPrInfo,
+  getPrBody,
+  updatePrBody,
+  updatePrTitle,
+  getRepoNwo,
+  prUrlFor,
+} from "../lib/github.ts";
+import type { StackMetadata, Stack, Branch } from "../types.ts";
 
 /** The ref a stack is rooted on, for rendering the base node of the viz. */
 export interface BaseRef {
@@ -103,6 +110,66 @@ function mergeViz(body: string, viz: string): string {
   return base ? `${base}\n\n${viz}` : viz;
 }
 
+// ── PR-title stack numbering ──
+//
+// The stack position lives in the PR title as a ` (N/M)` suffix so reviewers
+// can see order from a bare "needs review" list (parens, not brackets, to avoid
+// colliding with `[BEE-1234]` ticket tags). The cached `prTitle` tracks exactly
+// what's on GitHub; we recover the base title by stripping the suffix and
+// re-applying the current position, so reordering/adding a branch renumbers the
+// whole stack and a no-op re-submit touches nothing.
+
+/** Matches a trailing ` (N/M)` stack-position suffix, e.g. " (2/4)". */
+const SEQ_SUFFIX = /\s*\(\d+\/\d+\)\s*$/;
+
+/** Strip a trailing ` (N/M)` suffix to recover the base PR title. */
+export function stripSeqSuffix(title: string): string {
+  return title.replace(SEQ_SUFFIX, "").trimEnd();
+}
+
+/** The title a branch at `position` of `total` should have. Idempotent. */
+export function numberedTitle(title: string, position: number, total: number): string {
+  const base = stripSeqSuffix(title);
+  return total >= 2 ? `${base} (${position}/${total})` : base;
+}
+
+export interface TitleResult {
+  updated: number; // PR titles we edited on GitHub
+  dirty: boolean; // metadata mutated (cached prTitle changed) — caller persists
+}
+
+/**
+ * Reconcile every PR title in the stack to carry its `(N/M)` stack position.
+ * Backfills any missing cached titles first (so we never clobber a real GitHub
+ * title with a branch-name guess), renders the desired title from the cached
+ * one, and only calls `gh pr edit --title` when it actually changed — a no-op
+ * re-submit makes zero edits, while adding/reordering a branch renumbers the
+ * whole stack. Run this BEFORE refreshStackViz so the viz shows numbered titles.
+ */
+export async function reconcilePrTitles(stack: Stack, ordered: string[]): Promise<TitleResult> {
+  const dirtyBackfill = await backfillTitles(stack, ordered);
+  const total = ordered.length;
+
+  const plans: { pr: number; desired: string; bm: Branch }[] = [];
+  for (let i = 0; i < ordered.length; i++) {
+    const bm = stack.branches[ordered[i]!]!;
+    // Need a known base title — never guess from the branch name for an
+    // existing PR (backfill couldn't fetch it → skip rather than clobber).
+    if (bm.pr == null || !bm.prTitle) continue;
+    const desired = numberedTitle(bm.prTitle, i + 1, total);
+    if (desired !== bm.prTitle) plans.push({ pr: bm.pr, desired, bm });
+  }
+
+  const oks = await mapLimit(plans, 8, async (plan) => {
+    const ok = await updatePrTitle(plan.pr, plan.desired);
+    if (ok) plan.bm.prTitle = plan.desired;
+    return ok;
+  });
+
+  const updated = oks.filter(Boolean).length;
+  return { updated, dirty: dirtyBackfill || updated > 0 };
+}
+
 export interface VizResult {
   updated: number; // PRs whose description we PATCHed
   unchanged: number; // PRs skipped because their rendered block was identical
@@ -192,16 +259,17 @@ PRs whose rendered block is unchanged are skipped; --force rewrites all.
   console.log();
 
   const s = p.spinner();
-  s.start("Updating PR descriptions...");
+  s.start("Updating PR titles & descriptions...");
+  const titles = await reconcilePrTitles(stack, ordered);
   const result = await refreshStackViz(meta, stack, ordered, { force });
   s.stop("Done");
 
-  if (result.dirty) await writeMetadata(meta);
+  if (titles.dirty || result.dirty) await writeMetadata(meta);
 
   console.log();
   p.outro(
     pc.green(
-      `Updated ${result.updated} PR(s)` +
+      `Updated ${result.updated} description(s), ${titles.updated} title(s)` +
         (result.unchanged > 0 ? `, ${result.unchanged} unchanged` : "") +
         (result.skipped > 0 ? `, ${result.skipped} without PRs` : ""),
     ),
@@ -249,9 +317,9 @@ export function buildStackViz(
     // Tree character
     const tree = isLast ? "┗━" : "┣━";
 
-    // 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}`);
+    // No leading `N.` — the stack position now lives in the PR title itself as
+    // a `(N/M)` suffix (see reconcilePrTitles), so the tree just shows titles.
+    lines.push(`${tree} ${prLink} ${info.prTitle}${marker}`);
 
     if (!isLast) {
       lines.push("┃");

package/src/lib/github.ts

@@ -136,6 +136,18 @@ export async function updatePrBody(prNumber: number, body: string): Promise<bool
   }
 }
 
+/**
+ * Update a PR's title.
+ */
+export async function updatePrTitle(prNumber: number, title: string): Promise<boolean> {
+  try {
+    await $`gh pr edit ${prNumber} --title ${title}`.quiet();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Get PR body text.
  */