gh-stack 0.17.2 → 0.19.0

package/src/lib/git.ts

@@ -143,30 +143,92 @@ export async function isAncestor(ancestor: string, descendant: string): Promise<
   return exitCode === 0;
 }
 
-/**
- * Force-push a branch with lease protection.
- */
-export async function forcePushWithLease(branch?: string): Promise<boolean> {
-  try {
-    if (branch) {
-      await $`git push --force-with-lease origin ${branch}`;
-    } else {
-      await $`git push --force-with-lease`;
-    }
-    return true;
-  } catch {
-    return false;
+export type PushResult =
+  | { ok: true }
+  | {
+      ok: false;
+      /**
+       * `not-integrated`: origin's tip was fetched but isn't in the local
+       * branch's history (--force-if-includes refused). `stale-lease`: origin
+       * moved since the last fetch. `rejected`: anything else.
+       */
+      reason: "not-integrated" | "stale-lease" | "rejected";
+      stderr: string;
+    };
+
+/**
+ * The one way gh-stack force-pushes a branch (restack, sync, merge's advance,
+ * submit, join). Sets upstream, and works whether or not the branch exists on
+ * origin yet.
+ *
+ * By default it's `--force-with-lease --force-if-includes`: the lease refuses
+ * if origin moved since the last fetch, and --force-if-includes refuses if the
+ * fetched tip was never brought into the local branch. That second check is
+ * #28's root cause (a collapse's squash commit fetched, never pulled, then
+ * overwritten), covered here for every command.
+ *
+ * `expect` gives the lease an explicit remote sha instead. Use it only for a
+ * tip whose content was checked first (see lib/remote-guard.ts): git makes
+ * --force-if-includes a no-op then, and the push still fails if origin moved
+ * off that sha.
+ */
+export async function forcePushWithLease(
+  branch: string,
+  opts: { expect?: string } = {},
+): Promise<PushResult> {
+  const lease = opts.expect
+    ? `--force-with-lease=refs/heads/${branch}:${opts.expect}`
+    : "--force-with-lease";
+  const { exitCode, stderr } = await $`git push -u ${lease} --force-if-includes origin ${branch}`
+    .nothrow()
+    .quiet();
+  if (exitCode === 0) return { ok: true };
+  const text = stderr.toString();
+  const reason = text.includes("remote ref updated since checkout")
+    ? "not-integrated"
+    : text.includes("stale info")
+      ? "stale-lease"
+      : "rejected";
+  return { ok: false, reason, stderr: text };
+}
+
+/** Why a force-push was refused, and what to do, in gh-stack terms (plain lines). */
+export function pushFailureHint(branch: string, result: PushResult): string[] {
+  if (result.ok) return [];
+  switch (result.reason) {
+    case "not-integrated":
+      return [
+        `origin/${branch} has commits you fetched but never brought into local ${branch}, so git refused to overwrite them (--force-if-includes).`,
+        `That's how a collapsed PR's squash commit gets lost (#28). See them: git log ${branch}..origin/${branch}`,
+        `Bring them in (git pull --rebase origin ${branch}, or cherry-pick), then retry.`,
+        `To drop them on purpose: gh-stack restack --overwrite-remote`,
+      ];
+    case "stale-lease":
+      return [
+        `origin/${branch} moved since your last fetch, so the lease refused.`,
+        `Look at what's there first: git fetch origin ${branch} && git log ${branch}..origin/${branch}`,
+      ];
+    default:
+      return [
+        result.stderr
+          .trim()
+          .split("\n")
+          .find((l) => l.includes("rejected") || l.startsWith("error")) ?? result.stderr.trim(),
+      ];
   }
 }
 
 /**
- * Push a stacked branch's ref to origin, setting upstream and using
- * force-with-lease. Works whether or not the remote branch already exists
- * (creates it on first push) — so restack can reconcile every ref, including
- * a branch that was never pushed before.
+ * Fetch commits from origin without moving any ref: no remote-tracking ref
+ * update (`--refmap=`) and no FETCH_HEAD. The tracking refs are what
+ * `--force-with-lease` and `--force-if-includes` compare against, so a check
+ * that needs origin's objects must never advance them.
  */
-export async function pushStackedBranch(branch: string): Promise<boolean> {
-  const { exitCode } = await $`git push -u --force-with-lease origin ${branch}`.nothrow().quiet();
+export async function fetchObjectsOnly(refs: string[]): Promise<boolean> {
+  if (refs.length === 0) return true;
+  const { exitCode } = await $`git fetch --quiet --no-write-fetch-head --refmap= origin ${refs}`
+    .nothrow()
+    .quiet();
   return exitCode === 0;
 }
 
@@ -264,10 +326,10 @@ export async function deleteTagsMatching(pattern: string): Promise<void> {
 }
 
 /**
- * Check if a tag exists.
+ * Whether a ref (branch, tag, remote-tracking ref, or any revision) resolves.
  */
-export async function tagExists(name: string): Promise<boolean> {
-  const { exitCode } = await $`git rev-parse --verify ${name}`.nothrow().quiet();
+export async function refExists(ref: string): Promise<boolean> {
+  const { exitCode } = await $`git rev-parse --verify --quiet ${ref}`.nothrow().quiet();
   return exitCode === 0;
 }
 
@@ -346,6 +408,20 @@ export async function allLocalBranches(): Promise<string[]> {
   return result.trim().split("\n").filter(Boolean);
 }
 
+/**
+ * Map every local branch to its tip SHA, in one call.
+ */
+export async function localBranchTips(): Promise<Map<string, string>> {
+  const result =
+    await $`git for-each-ref --format=${"%(refname:short) %(objectname)"} refs/heads`.text();
+  const tips = new Map<string, string>();
+  for (const line of result.trim().split("\n").filter(Boolean)) {
+    const [name, sha] = line.split(" ");
+    if (name && sha) tips.set(name, sha);
+  }
+  return tips;
+}
+
 /**
  * Determine the trunk branch name. Prefers "main", falls back to "master"
  * if only that exists locally. Defaults to "main" when neither is present.

package/src/lib/github.ts

@@ -40,6 +40,26 @@ export async function getPrNumber(branch: string): Promise<number | null> {
   }
 }
 
+/**
+ * Find the open PR whose head is `branch`, for adopting a PR opened outside
+ * gh-stack. Unlike getPrNumber, returns null unless there is exactly one match
+ * — a fork with the same branch name must never be adopted by accident.
+ */
+export async function findOpenPrForBranch(branch: string): Promise<number | null> {
+  try {
+    const out =
+      await $`gh pr list --head ${branch} --state open --json number --jq '.[].number'`.text();
+    const nums = out
+      .trim()
+      .split(/\s+/)
+      .filter(Boolean)
+      .map((n) => parseInt(n, 10));
+    return nums.length === 1 && !isNaN(nums[0]!) ? nums[0]! : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Get PR info for a specific PR number.
  */
@@ -183,17 +203,75 @@ export async function getPrBody(prNumber: number): Promise<string | null> {
  * squash-merge lands on this branch. Compare `headRefOid` against the live ref
  * (`getBranchRefSha`) to detect that staleness — see `merge.ts`.
  */
-export async function getPrMergeState(prNumber: number): Promise<{
+/** A PR's merge state, plus what merging it left behind. */
+export interface PrMergeResult {
   state: string;
   mergeable: string;
   mergeStateStatus: string;
   headRefName: string;
+  /** The PR's head; for a merged PR, its head when it merged. */
   headRefOid: string;
-} | null> {
+  /** The branch it targets (or merged into). */
+  baseRefName: string;
+  /** The commit merging it created on its base (for a squash merge, the squash commit). */
+  mergeCommit: string | null;
+}
+
+export async function getPrMergeState(prNumber: number): Promise<PrMergeResult | null> {
   try {
-    const result =
-      await $`gh pr view ${prNumber} --json state,mergeable,mergeStateStatus,headRefName,headRefOid`.text();
-    return JSON.parse(result.trim());
+    const data = JSON.parse(
+      (
+        await $`gh pr view ${prNumber} --json state,mergeable,mergeStateStatus,headRefName,headRefOid,baseRefName,mergeCommit`.text()
+      ).trim(),
+    );
+    return { ...data, mergeCommit: data.mergeCommit?.oid ?? null };
+  } catch {
+    return null;
+  }
+}
+
+/** A commit as a patch (`git format-patch` style), from the GitHub API. Null if unavailable. */
+export async function getCommitPatch(sha: string): Promise<string | null> {
+  const nwo = await getRepoNwo();
+  if (!nwo) return null;
+  const { stdout, exitCode } =
+    await $`gh api -H ${"Accept: application/vnd.github.patch"} repos/${nwo}/commits/${sha}`
+      .nothrow()
+      .quiet();
+  const text = stdout.toString();
+  return exitCode === 0 && text.trim() ? text : null;
+}
+
+/**
+ * The files a commit changed (path, status, blob sha after the commit), from
+ * the GitHub API. Null if unavailable, or if GitHub truncated the list (it
+ * returns at most 300 files): a partial list can't prove anything.
+ */
+export async function getCommitFiles(
+  sha: string,
+): Promise<
+  { filename: string; status: string; sha: string | null; before?: string | null }[] | null
+> {
+  const nwo = await getRepoNwo();
+  if (!nwo) return null;
+  const { stdout, exitCode } =
+    await $`gh api repos/${nwo}/commits/${sha} --jq ${"[.files[] | {filename, status, sha}]"}`
+      .nothrow()
+      .quiet();
+  if (exitCode !== 0) return null;
+  try {
+    const files: { filename: string; status: string; sha: string | null }[] = JSON.parse(
+      stdout.toString(),
+    );
+    if (!Array.isArray(files) || files.length === 0 || files.length >= 300) return null;
+    // The API gives no blob from before the commit, except that an added
+    // file had none; a removed file has no blob after it.
+    return files.map((f) => ({
+      filename: f.filename,
+      status: f.status,
+      sha: f.status === "removed" ? null : f.sha,
+      before: f.status === "added" ? null : undefined,
+    }));
   } catch {
     return null;
   }

package/src/lib/metadata.ts

@@ -11,6 +11,7 @@
 //   • A stack can never silently vanish — on write, a stale stack file is moved
 //     to `deleted/` (a recoverable tombstone), never just unlinked.
 import type { StackMetadata, Stack, Branch, RestackState } from "../types.ts";
+import { RUN_STATE_VERSION } from "../types.ts";
 import { mkdir, readdir, rename, unlink, stat } from "node:fs/promises";
 import {
   ghStackDir,
@@ -605,7 +606,7 @@ export function getOrderedBranches(stack: Stack): string[] {
  */
 export function getChildren(stack: Stack, branchName: string): string[] {
   return Object.entries(stack.branches)
-    .filter(([_, b]) => b.parent === branchName)
+    .filter(([, b]) => b.parent === branchName)
     .map(([name]) => name);
 }
 
@@ -655,23 +656,49 @@ export async function updateLastBranch(
 // ── Restack state (for --resume) ──
 
 /**
- * Save restack state for resume.
+ * Save a run's state (resume point + action log). Written after every step, so
+ * it goes through a temp file and a rename: a kill mid-write leaves the
+ * previous state, never a truncated file.
  */
 export async function saveRestackState(state: RestackState): Promise<void> {
   await ensureDirs();
-  await Bun.write(await restackStateFile(), JSON.stringify(state, null, 2) + "\n");
+  const path = await restackStateFile();
+  const tmp = `${path}.tmp`;
+  await Bun.write(tmp, JSON.stringify(state, null, 2) + "\n");
+  await rename(tmp, path);
 }
 
 /**
- * Load restack state for resume.
- * Returns null if no state file exists.
+ * Load the saved run state. Returns null if there is none. A file that can't
+ * be parsed, or was written by another version of gh-stack, throws
+ * InvalidRunStateError: it is never guessed at or upgraded.
  */
 export async function loadRestackState(): Promise<RestackState | null> {
-  const file = Bun.file(await restackStateFile());
+  const path = await restackStateFile();
+  const file = Bun.file(path);
   if (!(await file.exists())) {
     return null;
   }
-  return file.json();
+  let raw: Partial<RestackState>;
+  try {
+    raw = await file.json();
+  } catch {
+    throw new InvalidRunStateError(path, "it isn't valid JSON");
+  }
+  if (raw?.version !== RUN_STATE_VERSION) {
+    throw new InvalidRunStateError(path, "it was written by an older gh-stack");
+  }
+  return raw as RestackState;
+}
+
+/** The saved run state exists but can't be used (unreadable, or another version's shape). */
+export class InvalidRunStateError extends Error {
+  constructor(
+    readonly path: string,
+    readonly reason: string,
+  ) {
+    super(`The saved run state at ${path} can't be used: ${reason}.`);
+  }
 }
 
 /**

package/src/lib/output.ts

@@ -7,17 +7,40 @@
 //   - no ANSI colors (picocolors auto-disables via NO_COLOR; we also strip
 //     any residual escapes defensively)
 //
-// Interactive prompts (text, confirm, select) are re-exported unchanged —
+// Interactive prompts (text, confirm, select) are unchanged by plain mode —
 // plain mode is about output, not interactivity. Agents already pair --plain
-// with --yes/GH_STACK_YES so the interactive paths aren't reached.
+// with --yes/GH_STACK_YES so the interactive paths aren't reached. If one IS
+// reached with no TTY on stdin, nothing can ever answer it, so we fail fast
+// instead of blocking forever (#33).
 import * as clack from "@clack/prompts";
 
 let _plain = false;
+let stderrOnly = false;
 
 export function setPlain(enabled: boolean): void {
   _plain = enabled;
 }
 
+/**
+ * `--json` mode: plain output, all of it on stderr, so stdout carries only the
+ * JSON document the command writes itself.
+ */
+export function setStderrOnly(): void {
+  _plain = true;
+  stderrOnly = true;
+}
+
+/** Plain-mode line: stdout normally, stderr in --json mode. */
+function say(line: string): void {
+  if (stderrOnly) console.error(line);
+  else console.log(line);
+}
+
+/** A raw line of output (tree drawings, spacing), routed like the log calls. */
+export function print(line = ""): void {
+  say(_plain ? strip(line) : line);
+}
+
 export function isPlain(): boolean {
   return _plain;
 }
@@ -27,16 +50,43 @@ function strip(s: string | undefined): string {
   return (s ?? "").replace(ANSI_RE, "");
 }
 
-// ── Interactive prompts (unchanged) ──
+// ── Interactive prompts ──
 export const isCancel = clack.isCancel;
-export const text = clack.text;
-export const confirm = clack.confirm;
-export const select = clack.select;
+
+/**
+ * Exit non-zero instead of prompting when stdin isn't a TTY. A prompt there
+ * can never be answered, and it would otherwise hang (holding the repo) past
+ * the caller's timeout. (#33)
+ */
+function ensureInteractive(message: string): void {
+  if (process.stdin.isTTY) return;
+  console.error(
+    `gh-stack: refusing to prompt — stdin is not a TTY.\n` +
+      `  Prompt: ${strip(message)}\n` +
+      `  Pass --yes (or set GH_STACK_YES=1) to confirm automatically.`,
+  );
+  process.exit(1);
+}
+
+export const text: typeof clack.text = (opts) => {
+  ensureInteractive(opts.message);
+  return clack.text(opts);
+};
+
+export const confirm: typeof clack.confirm = (opts) => {
+  ensureInteractive(opts.message);
+  return clack.confirm(opts);
+};
+
+export const select: typeof clack.select = (opts) => {
+  ensureInteractive(opts.message);
+  return clack.select(opts);
+};
 
 // ── Banner / error ──
 export function intro(message?: string): void {
   if (_plain) {
-    if (message) console.log(strip(message));
+    if (message) say(strip(message));
   } else {
     clack.intro(message);
   }
@@ -44,7 +94,7 @@ export function intro(message?: string): void {
 
 export function outro(message?: string): void {
   if (_plain) {
-    if (message) console.log(strip(message));
+    if (message) say(strip(message));
   } else {
     clack.outro(message);
   }
@@ -60,11 +110,11 @@ export function cancel(message?: string): void {
 
 // ── log.* ──
 export const log = {
-  info: (msg: string) => (_plain ? console.log(strip(msg)) : clack.log.info(msg)),
-  success: (msg: string) => (_plain ? console.log(strip(msg)) : clack.log.success(msg)),
+  info: (msg: string) => (_plain ? say(strip(msg)) : clack.log.info(msg)),
+  success: (msg: string) => (_plain ? say(strip(msg)) : clack.log.success(msg)),
   warn: (msg: string) => (_plain ? console.warn(strip(msg)) : clack.log.warn(msg)),
   error: (msg: string) => (_plain ? console.error(strip(msg)) : clack.log.error(msg)),
-  step: (msg: string) => (_plain ? console.log(strip(msg)) : clack.log.step(msg)),
+  step: (msg: string) => (_plain ? say(strip(msg)) : clack.log.step(msg)),
 };
 
 // ── Spinner ──
@@ -78,13 +128,13 @@ export function spinner(): Spinner {
   if (!_plain) return clack.spinner() as Spinner;
   return {
     start: (msg) => {
-      if (msg) console.log(strip(msg));
+      if (msg) say(strip(msg));
     },
     stop: (msg) => {
-      if (msg) console.log(strip(msg));
+      if (msg) say(strip(msg));
     },
     message: (msg) => {
-      if (msg) console.log(strip(msg));
+      if (msg) say(strip(msg));
     },
   };
 }

package/src/lib/paths.ts

@@ -6,7 +6,7 @@
 //     archived/<stack>.json        merged/closed stacks
 //     deleted/<stack>.json         tombstones (recoverable)
 //     snapshots/<ts>__<stack>.json append-only pre-operation branch tips
-//     restack-state.json           in-flight restack/sync resume state
+//     restack-state.json           last restack/sync/join run: resume point + action log
 //
 // Everything lives inside `.git/` and is never committed — gh-stack is a
 // single-developer tool, so there's no need to share metadata across clones.