gh-stack 0.7.1 → 0.10.0

package/src/commands/stacks.ts

@@ -0,0 +1,136 @@
+// gh-stack stacks — List all stacks and their topology (network-free).
+//
+// This is the machine-readable interface to stack metadata: `--json` emits the
+// full topology (stacks, ordered branches, PR numbers, base) so external tools
+// never have to reach into `.git/.gh-stack/` and parse the storage format
+// themselves. It performs NO network calls and does NOT mutate metadata.
+import pc from "picocolors";
+import * as git from "../lib/git.ts";
+import {
+  readMetadata,
+  metadataExists,
+  legacyMetadataExists,
+  getOrderedBranches,
+  findStackForBranch,
+  stackBase,
+} from "../lib/metadata.ts";
+
+export default async function stacks(args: string[]): Promise<void> {
+  if (args.includes("--help")) {
+    console.log(`
+gh-stack stacks — List all stacks and their topology
+
+USAGE
+  gh-stack stacks [options]
+
+OPTIONS
+  --json       Output topology as JSON (for tools/scripts; no network calls)
+  --current    Only the stack containing the current branch
+
+Read-only and network-free — emits stack membership straight from local
+metadata. Use --json as a stable interface so scripts don't parse the
+.git/.gh-stack/ store directly.
+`);
+    return;
+  }
+
+  const jsonMode = args.includes("--json");
+  const currentOnly = args.includes("--current");
+
+  // Read-only: don't hard-block on unmigrated v2 metadata — just note it to
+  // stderr (keeps stdout/JSON clean) and emit an empty result.
+  if (!(await metadataExists())) {
+    if (await legacyMetadataExists()) {
+      process.stderr.write("Note: stack metadata is unmigrated (v2). Run `gh-stack doctor`.\n");
+    }
+    if (jsonMode) {
+      console.log(
+        JSON.stringify({ current_stack: null, current_branch: null, stacks: [] }, null, 2),
+      );
+    } else {
+      console.log("No stacks found.");
+    }
+    return;
+  }
+
+  const meta = await readMetadata();
+  if (!meta) {
+    if (jsonMode) {
+      console.log(
+        JSON.stringify({ current_stack: null, current_branch: null, stacks: [] }, null, 2),
+      );
+    } else {
+      console.log("No stacks found.");
+    }
+    return;
+  }
+
+  let currentBranch: string | null = null;
+  try {
+    currentBranch = await git.currentBranch();
+  } catch {
+    // Detached HEAD or not on a branch — fine, just no "current" context.
+  }
+
+  const currentStackName = currentBranch ? findStackForBranch(meta, currentBranch) : null;
+
+  const entries = Object.entries(meta.stacks)
+    .filter(([name]) => !currentOnly || name === currentStackName)
+    .map(([name, stack]) => {
+      const ordered = getOrderedBranches(stack);
+      return {
+        name,
+        description: stack.description || "",
+        base: stackBase(stack),
+        is_current: name === currentStackName,
+        branches: ordered.map((branchName) => {
+          const b = stack.branches[branchName]!;
+          return {
+            branch: branchName,
+            parent: b.parent,
+            pr: b.pr ?? null,
+            description: b.description ?? null,
+          };
+        }),
+      };
+    });
+
+  if (jsonMode) {
+    console.log(
+      JSON.stringify(
+        {
+          current_stack: currentStackName ?? meta.current_stack ?? null,
+          current_branch: currentBranch,
+          stacks: entries,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  // ── Human-readable ──
+  if (entries.length === 0) {
+    console.log(currentOnly ? "Current branch is not in a stack." : "No stacks found.");
+    return;
+  }
+
+  console.log();
+  for (const stack of entries) {
+    const marker = stack.is_current ? pc.yellow(" (current)") : "";
+    console.log(`${pc.blue("📚")} ${pc.yellow(stack.name)}${marker} ${pc.dim(`→ ${stack.base}`)}`);
+    if (stack.description) {
+      console.log(`   ${pc.dim(stack.description)}`);
+    }
+    for (let i = 0; i < stack.branches.length; i++) {
+      const b = stack.branches[i]!;
+      const isLast = i === stack.branches.length - 1;
+      const tree = isLast ? "┗━" : "┣━";
+      const prNum = b.pr ? pc.dim(`#${b.pr}`) : pc.dim("(no PR)");
+      const cur = currentBranch === b.branch ? pc.yellow(" 👈") : "";
+      console.log(`   ${tree} ${i + 1}. ${b.branch} ${prNum}${cur}`);
+    }
+    console.log();
+  }
+}

package/src/commands/status.ts

@@ -5,6 +5,7 @@ import * as git from "../lib/git.ts";
 import {
   readMetadata,
   metadataExists,
+  legacyMetadataExists,
   getOrderedBranches,
   findStackForBranch,
 } from "../lib/metadata.ts";
@@ -32,6 +33,12 @@ Progress/spinner output goes to stderr so stdout stays clean for piping.
   const jsonMode = args.includes("--json");
   const currentOnly = args.includes("--current");
 
+  // Read-only command, so don't hard-block — but if v2 metadata hasn't been
+  // migrated, stacks won't be grouped. Nudge to stderr (keeps stdout/JSON clean).
+  if (!(await metadataExists()) && (await legacyMetadataExists())) {
+    process.stderr.write("Note: stack metadata is unmigrated (v2). Run `gh-stack doctor`.\n");
+  }
+
   // Progress goes to stderr so stdout is clean for agents
   process.stderr.write("Fetching open PRs...\n");
 

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);
   }