gh-stack 0.7.1 → 0.10.0

package/src/lib/metadata.ts

@@ -1,83 +1,377 @@
-// Read/write/validate .git/gh-stack-metadata.json
-import type { StackMetadata, StackMetadataV1, Stack, Branch, RestackState } from "../types.ts";
-import { gitDir } from "./git.ts";
+// v3 metadata: assemble from / fan out to `.git/.gh-stack/`.
+//
+// The in-memory `StackMetadata` shape is unchanged from v2 — every command
+// still reads `meta.stacks[...]` / `meta.current_stack` and calls
+// `writeMetadata(meta)`. Only the on-disk representation changed: instead of
+// one monolithic JSON file, each stack is its own file and per-branch
+// membership additionally lives in git config (see ./branch-config.ts).
+//
+// Two structural guarantees fall out of per-stack files:
+//   • A bad write can't corrupt other stacks (no all-or-nothing blast radius).
+//   • 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 { mkdir, readdir, rename, unlink, stat } from "node:fs/promises";
+import {
+  ghStackDir,
+  activeDir,
+  archivedDir,
+  deletedDir,
+  snapshotsDir,
+  currentFile,
+  restackStateFile,
+  legacyMetadataPath,
+  stackFileName,
+  stackNameFromFile,
+} from "./paths.ts";
+import {
+  allBranchMemberships,
+  setBranchMembership,
+  clearBranchMembership,
+  type BranchMembership,
+} from "./branch-config.ts";
+import { loadSnapshots } from "./snapshot.ts";
+
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Create the `.gh-stack/` folder and its subdirectories if missing. */
+async function ensureDirs(): Promise<void> {
+  for (const dir of [
+    await activeDir(),
+    await archivedDir(),
+    await deletedDir(),
+    await snapshotsDir(),
+  ]) {
+    await mkdir(dir, { recursive: true });
+  }
+}
+
+/** True if the v3 store (`.git/.gh-stack/`) exists. */
+export async function v3Exists(): Promise<boolean> {
+  return pathExists(await ghStackDir());
+}
+
+/** True if the legacy v2 monolith exists and hasn't been migrated yet. */
+export async function legacyMetadataExists(): Promise<boolean> {
+  return Bun.file(await legacyMetadataPath()).exists();
+}
+
+/**
+ * Whether usable metadata exists. In v3 this means the `.gh-stack/` store is
+ * present. (A bare legacy file is intentionally NOT counted — it must be
+ * migrated via `gh-stack doctor` first; the gate in safety.ts surfaces that.)
+ */
+export async function metadataExists(): Promise<boolean> {
+  return v3Exists();
+}
 
-let cachedGitDir: string | null = null;
+export async function restackStatePath(): Promise<string> {
+  return restackStateFile();
+}
 
-async function getGitDir(): Promise<string> {
-  if (!cachedGitDir) {
-    cachedGitDir = await gitDir();
+/**
+ * Read one directory of `<stack>.json` files into a name→Stack map. Files that
+ * fail to parse are skipped (doctor reports them) rather than aborting a read.
+ */
+async function readStackDir(dir: string): Promise<Record<string, Stack>> {
+  const out: Record<string, Stack> = {};
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return out;
+  }
+  for (const file of entries) {
+    if (!file.endsWith(".json")) continue;
+    try {
+      const stack = (await Bun.file(`${dir}/${file}`).json()) as Stack;
+      out[stackNameFromFile(file)] = stack;
+    } catch {
+      // Malformed stack file — skip; `doctor` will flag it.
+    }
+  }
+  return out;
+}
+
+async function readCurrent(): Promise<string | null> {
+  try {
+    const text = (await Bun.file(await currentFile()).text()).trim();
+    return text.length > 0 ? text : null;
+  } catch {
+    return null;
   }
-  return cachedGitDir;
 }
 
 /**
- * Get the path to the metadata file.
+ * Read and assemble metadata from `.git/.gh-stack/`.
+ * Returns null if the store doesn't exist.
  */
-export async function metadataPath(): Promise<string> {
-  const dir = await getGitDir();
-  return `${dir}/gh-stack-metadata.json`;
+export async function readMetadata(): Promise<StackMetadata | null> {
+  if (!(await v3Exists())) return null;
+  await ensureDirs();
+
+  const stacks = await readStackDir(await activeDir());
+  const archive = await readStackDir(await archivedDir());
+  const current = await readCurrent();
+  const snapshots = await loadSnapshots();
+
+  const meta: StackMetadata = {
+    version: 3,
+    current_stack: current,
+    stacks,
+  };
+  if (Object.keys(archive).length > 0) meta.archive = archive;
+  if (snapshots.length > 0) meta.snapshots = snapshots;
+
+  backfillStackBase(meta);
+  // Catch the name-keyed JSON up to any `git branch -m` since the last write.
+  // In-memory only — the fix persists the next time a command writes metadata
+  // (which also repoints renamed branches' child config). Keeping reads
+  // side-effect-free avoids surprising writes from `status`/`--dry-run`.
+  await reconcileRenames(meta);
+  return meta;
 }
 
 /**
- * Get the path to the restack state file.
+ * The ref a stack is rooted on. Defaults to "main" for stacks created before
+ * the `base` field existed.
  */
-export async function restackStatePath(): Promise<string> {
-  const dir = await getGitDir();
-  return `${dir}/.gh-stack-sync-state`;
+export function stackBase(stack: Stack): string {
+  return stack.base ?? "main";
+}
+
+/** Ensure every stack has an explicit `base` (in-memory only). */
+function backfillStackBase(meta: StackMetadata): void {
+  for (const stack of Object.values(meta.stacks)) {
+    if (stack.base == null) stack.base = "main";
+  }
+  for (const stack of Object.values(meta.archive ?? {})) {
+    if (stack.base == null) stack.base = "main";
+  }
+}
+
+function serializeStack(stack: Stack): string {
+  const out: Stack = {
+    description: stack.description,
+    last_branch: stack.last_branch,
+    base: stackBase(stack),
+    branches: stack.branches,
+  };
+  return JSON.stringify(out, null, 2) + "\n";
 }
 
 /**
- * Check if metadata file exists.
+ * Fan `meta` out to disk: write each active/archived stack to its own file,
+ * tombstone any stack file that's no longer present, and reconcile git branch
+ * config to match active membership.
  */
-export async function metadataExists(): Promise<boolean> {
-  const path = await metadataPath();
-  return Bun.file(path).exists();
+export async function writeMetadata(meta: StackMetadata): Promise<void> {
+  await ensureDirs();
+
+  // 0. stamp a stable id on any active branch that lacks one, so a later
+  //    `git branch -m` can be recognized even before the branch has a PR.
+  ensureBranchIds(meta);
+
+  // 1. current hint
+  await Bun.write(await currentFile(), (meta.current_stack ?? "") + "\n");
+
+  const aDir = await activeDir();
+  const arDir = await archivedDir();
+
+  // 2. write active + archived stack files (write desired state BEFORE
+  //    removing anything — that's what makes "can't vanish" hold).
+  for (const [name, stack] of Object.entries(meta.stacks)) {
+    await Bun.write(`${aDir}/${stackFileName(name)}`, serializeStack(stack));
+  }
+  for (const [name, stack] of Object.entries(meta.archive ?? {})) {
+    await Bun.write(`${arDir}/${stackFileName(name)}`, serializeStack(stack));
+  }
+
+  // 3. reconcile stale files. A name that moved to the other category (active
+  //    ↔ archived) is just unlinked here; one that left both is tombstoned.
+  const activeNames = new Set(Object.keys(meta.stacks));
+  const archivedNames = new Set(Object.keys(meta.archive ?? {}));
+  await reconcileStale(aDir, activeNames, (name) => archivedNames.has(name));
+  await reconcileStale(arDir, archivedNames, (name) => activeNames.has(name));
+
+  // 4. mirror active membership into git config
+  await syncBranchConfig(meta);
 }
 
 /**
- * Read and parse metadata, with auto-migration from v1.
- * Returns null if file doesn't exist.
+ * Remove stack files in `dir` whose names aren't in `keep`. A file whose name
+ * lives in the other lifecycle bucket (`movedElsewhere`) is unlinked; anything
+ * else is moved to `deleted/` as a recoverable tombstone.
  */
-export async function readMetadata(): Promise<StackMetadata | null> {
-  const path = await metadataPath();
-  const file = Bun.file(path);
+async function reconcileStale(
+  dir: string,
+  keep: Set<string>,
+  movedElsewhere: (name: string) => boolean,
+): Promise<void> {
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return;
+  }
+  for (const file of entries) {
+    if (!file.endsWith(".json")) continue;
+    const name = stackNameFromFile(file);
+    if (keep.has(name)) continue;
+
+    const from = `${dir}/${file}`;
+    if (movedElsewhere(name)) {
+      await unlink(from).catch(() => {});
+    } else {
+      // Tombstone rather than delete — a stack must never just disappear.
+      const to = `${await deletedDir()}/${file}`;
+      await rename(from, to).catch(() => unlink(from).catch(() => {}));
+    }
+  }
+}
 
-  if (!(await file.exists())) {
-    return null;
+/**
+ * Reconcile git branch config so it exactly mirrors active-stack membership.
+ * Only branches whose recorded membership differs are touched, to avoid
+ * shelling out to `git config` for every branch on every write.
+ */
+async function syncBranchConfig(meta: StackMetadata): Promise<void> {
+  const desired = new Map<string, BranchMembership>();
+  for (const [stackName, stack] of Object.entries(meta.stacks)) {
+    for (const [branchName, b] of Object.entries(stack.branches)) {
+      desired.set(branchName, { stack: stackName, parent: b.parent, pr: b.pr, id: b.id });
+    }
+  }
+
+  const existing = await allBranchMemberships();
+
+  for (const [branch, m] of desired) {
+    const cur = existing.get(branch);
+    if (
+      !cur ||
+      cur.stack !== m.stack ||
+      cur.parent !== m.parent ||
+      cur.pr !== m.pr ||
+      cur.id !== m.id
+    ) {
+      await setBranchMembership(branch, m);
+    }
+  }
+
+  // Branches that still carry gh-stack config but are no longer active members.
+  for (const branch of existing.keys()) {
+    if (!desired.has(branch)) await clearBranchMembership(branch);
+  }
+}
+
+/**
+ * Stamp a stable UUID on every active branch that lacks one. Mutates `meta`;
+ * the ids persist via the normal stack-file write and get mirrored into git
+ * config by `syncBranchConfig`. A branch's id is its rename anchor.
+ */
+function ensureBranchIds(meta: StackMetadata): void {
+  for (const stack of Object.values(meta.stacks)) {
+    for (const b of Object.values(stack.branches)) {
+      if (!b.id) b.id = crypto.randomUUID();
+    }
   }
+}
 
-  const raw = await file.json();
-
-  // Auto-migrate v1 -> v2
-  if (!raw.version) {
-    const v1 = raw as StackMetadataV1;
-    const v2: StackMetadata = {
-      version: 2,
-      current_stack: v1.current_stack,
-      stacks: v1.stacks,
-    };
-    await writeMetadata(v2);
-    return v2;
+/**
+ * Reconcile the name-keyed JSON after a branch was renamed with `git branch -m`.
+ *
+ * Git moves a branch's entire `branch.<name>` config section on rename, so the
+ * membership config is rename-proof and authoritative for identity; only the
+ * JSON (keyed by branch name) drifts. For each branch the config currently knows
+ * by name N, if the JSON has no entry under N but does have one — in the same
+ * stack — matching N's stable id (or, for legacy/pre-id branches, its PR
+ * number), that entry was renamed: re-key it to N and repoint anything that
+ * referenced the old name.
+ *
+ * Mutates `meta` in place; returns true if anything changed. The change persists
+ * on the next `writeMetadata`, which also repoints the renamed branch's child
+ * `ghstack-parent` config (git rewrites section names, not string values).
+ */
+async function reconcileRenames(meta: StackMetadata): Promise<boolean> {
+  const config = await allBranchMemberships();
+  if (config.size === 0) return false;
+
+  let changed = false;
+  for (const [currentName, m] of config) {
+    if (!m.stack) continue;
+    const stack = meta.stacks[m.stack];
+    if (!stack) continue;
+    if (stack.branches[currentName]) continue; // JSON already keyed correctly
+
+    const oldKey = findStaleKey(stack, m);
+    if (!oldKey || oldKey === currentName) continue;
+
+    renameBranchKey(meta, m.stack, oldKey, currentName);
+    changed = true;
   }
+  return changed;
+}
 
-  return raw as StackMetadata;
+/** Find a stack's branch entry by stable id (preferred) or PR number (fallback). */
+function findStaleKey(stack: Stack, m: BranchMembership): string | null {
+  if (m.id) {
+    for (const [name, b] of Object.entries(stack.branches)) {
+      if (b.id === m.id) return name;
+    }
+  }
+  if (m.pr != null) {
+    for (const [name, b] of Object.entries(stack.branches)) {
+      if (b.pr === m.pr) return name;
+    }
+  }
+  return null;
 }
 
 /**
- * Write metadata to disk.
+ * Re-key a branch from `oldKey` to `newKey` and repoint every reference to the
+ * old name: the stack's `last_branch`, and any branch's `parent` or stack's
+ * `base` (across active AND archived stacks — a split stack roots on a branch
+ * that belongs to its parent stack).
  */
-export async function writeMetadata(data: StackMetadata): Promise<void> {
-  const path = await metadataPath();
-  await Bun.write(path, JSON.stringify(data, null, 2) + "\n");
+function renameBranchKey(
+  meta: StackMetadata,
+  stackName: string,
+  oldKey: string,
+  newKey: string,
+): void {
+  const stack = meta.stacks[stackName];
+  if (!stack) return;
+  const entry = stack.branches[oldKey];
+  if (!entry) return;
+
+  stack.branches[newKey] = entry;
+  delete stack.branches[oldKey];
+  if (stack.last_branch === oldKey) stack.last_branch = newKey;
+
+  for (const group of [meta.stacks, meta.archive ?? {}]) {
+    for (const s of Object.values(group)) {
+      if (s.base === oldKey) s.base = newKey;
+      for (const b of Object.values(s.branches)) {
+        if (b.parent === oldKey) b.parent = newKey;
+      }
+    }
+  }
 }
 
 /**
- * Initialize an empty metadata file.
+ * Initialize an empty v3 store.
  */
 export async function initMetadata(): Promise<StackMetadata> {
+  await ensureDirs();
   const data: StackMetadata = {
-    version: 2,
+    version: 3,
     current_stack: null,
     stacks: {},
   };
@@ -123,11 +417,13 @@ export async function createStack(
   meta: StackMetadata,
   name: string,
   description: string,
+  base: string = "main",
 ): Promise<StackMetadata> {
   meta.stacks[name] = {
     description,
     last_branch: null,
     branches: {},
+    base,
   };
   meta.current_stack = name;
   await writeMetadata(meta);
@@ -184,6 +480,11 @@ export async function removeBranchFromStack(
   // Remove the branch
   delete stack.branches[branchName];
 
+  // The removed branch may still exist in git but is no longer a member —
+  // drop its membership config explicitly (syncBranchConfig also would, but
+  // be direct since the branch is gone from `meta`).
+  await clearBranchMembership(branchName);
+
   // Update last_branch if it was the removed one
   if (stack.last_branch === branchName) {
     const remaining = Object.keys(stack.branches);
@@ -212,7 +513,7 @@ export function getOrderedBranches(stack: Stack): string[] {
     }
   }
 
-  addChildrenOf("main");
+  addChildrenOf(stackBase(stack));
   return ordered;
 }
 
@@ -274,8 +575,8 @@ export async function updateLastBranch(
  * Save restack state for resume.
  */
 export async function saveRestackState(state: RestackState): Promise<void> {
-  const path = await restackStatePath();
-  await Bun.write(path, JSON.stringify(state, null, 2) + "\n");
+  await ensureDirs();
+  await Bun.write(await restackStateFile(), JSON.stringify(state, null, 2) + "\n");
 }
 
 /**
@@ -283,13 +584,10 @@ export async function saveRestackState(state: RestackState): Promise<void> {
  * Returns null if no state file exists.
  */
 export async function loadRestackState(): Promise<RestackState | null> {
-  const path = await restackStatePath();
-  const file = Bun.file(path);
-
+  const file = Bun.file(await restackStateFile());
   if (!(await file.exists())) {
     return null;
   }
-
   return file.json();
 }
 
@@ -297,11 +595,8 @@ export async function loadRestackState(): Promise<RestackState | null> {
  * Clear restack state file.
  */
 export async function clearRestackState(): Promise<void> {
-  const path = await restackStatePath();
-  const file = Bun.file(path);
-
-  if (await file.exists()) {
-    const { unlink } = await import("node:fs/promises");
-    await unlink(path);
+  const path = await restackStateFile();
+  if (await Bun.file(path).exists()) {
+    await unlink(path).catch(() => {});
   }
 }

package/src/lib/paths.ts

@@ -0,0 +1,69 @@
+// Filesystem layout for v3 metadata, all under `.git/.gh-stack/`.
+//
+//   .git/.gh-stack/
+//     current                      hint: last-active stack name (a cache, not truth)
+//     active/<stack>.json          topology of a live stack
+//     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
+//
+// 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.
+import { gitDir } from "./git.ts";
+
+let cachedGitDir: string | null = null;
+
+async function getGitDir(): Promise<string> {
+  if (!cachedGitDir) cachedGitDir = await gitDir();
+  return cachedGitDir;
+}
+
+/** Root of the v3 metadata folder. */
+export async function ghStackDir(): Promise<string> {
+  return `${await getGitDir()}/.gh-stack`;
+}
+
+export async function activeDir(): Promise<string> {
+  return `${await ghStackDir()}/active`;
+}
+export async function archivedDir(): Promise<string> {
+  return `${await ghStackDir()}/archived`;
+}
+export async function deletedDir(): Promise<string> {
+  return `${await ghStackDir()}/deleted`;
+}
+export async function snapshotsDir(): Promise<string> {
+  return `${await ghStackDir()}/snapshots`;
+}
+export async function currentFile(): Promise<string> {
+  return `${await ghStackDir()}/current`;
+}
+export async function restackStateFile(): Promise<string> {
+  return `${await ghStackDir()}/restack-state.json`;
+}
+
+/** Legacy v2 monolith path (pre-migration). */
+export async function legacyMetadataPath(): Promise<string> {
+  return `${await getGitDir()}/gh-stack-metadata.json`;
+}
+
+/** Legacy v2 restack-state path (pre-migration). */
+export async function legacyRestackStatePath(): Promise<string> {
+  return `${await getGitDir()}/.gh-stack-sync-state`;
+}
+
+// Stack names come from branch names, which can contain `/` and other chars
+// that aren't filesystem-safe. Encode to a flat, reversible filename.
+export function stackFileName(stack: string): string {
+  return `${encodeURIComponent(stack)}.json`;
+}
+
+export function stackNameFromFile(file: string): string {
+  return decodeURIComponent(file.replace(/\.json$/, ""));
+}
+
+// For test isolation: forget the memoized git dir.
+export function resetGitDirCache(): void {
+  cachedGitDir = null;
+}

package/src/lib/safety.ts

@@ -1,6 +1,12 @@
 // Pre-flight safety checks
 import * as git from "./git.ts";
-import { metadataExists, readMetadata, findStackForBranch } from "./metadata.ts";
+import {
+  metadataExists,
+  legacyMetadataExists,
+  readMetadata,
+  findStackForBranch,
+  stackBase,
+} from "./metadata.ts";
 import type { StackMetadata, Stack } from "../types.ts";
 import * as p from "./output.ts";
 import pc from "picocolors";
@@ -16,10 +22,26 @@ export async function ensureGitRepo(): Promise<void> {
 }
 
 /**
- * Ensure metadata file exists. Returns the metadata.
+ * If no v3 store exists but a legacy v2 monolith does, halt and point the user
+ * at `gh-stack doctor`. Call this from any command that checks for metadata
+ * directly (i.e. doesn't go through ensureMetadata) so the migration gate is
+ * uniform. No-op when there's no legacy file to migrate.
  */
+export async function gateLegacyMetadata(): Promise<void> {
+  if (await metadataExists()) return;
+  if (await legacyMetadataExists()) {
+    p.cancel(
+      `Stack metadata is in the old format and needs migrating.\n\n  Run:\n    ${pc.green("gh-stack doctor")}`,
+    );
+    process.exit(1);
+  }
+}
+
 export async function ensureMetadata(): Promise<StackMetadata> {
   if (!(await metadataExists())) {
+    // A v2 monolith still on disk means this repo predates v3 — gate behind an
+    // explicit one-time migration rather than silently reading the old format.
+    await gateLegacyMetadata();
     p.cancel(
       `No stack metadata found.\n\n  Create your first stack with:\n    ${pc.green("gh-stack init")}`,
     );
@@ -106,6 +128,7 @@ export async function validateStack(meta: StackMetadata, stackName: string): Pro
 
   const branchNames = Object.keys(stack.branches);
   const errors: string[] = [];
+  const base = stackBase(stack);
 
   for (const branchName of branchNames) {
     const branch = stack.branches[branchName]!;
@@ -118,7 +141,10 @@ export async function validateStack(meta: StackMetadata, stackName: string): Pro
       errors.push(`Branch "${branchName}" cannot be its own parent`);
     }
 
-    if (branch.parent !== "main" && branch.parent !== "master" && !stack.branches[branch.parent]) {
+    // A branch's parent must be either the stack's base (the root branch) or
+    // another branch in the stack. For a split stack the base is a branch in
+    // the parent stack, which legitimately lives outside `stack.branches`.
+    if (branch.parent !== base && !stack.branches[branch.parent]) {
       errors.push(`Branch "${branchName}" has unknown parent "${branch.parent}"`);
     }
   }
@@ -138,7 +164,7 @@ export async function ensureValidStack(meta: StackMetadata, stackName: string):
   }
   console.log();
   console.log(
-    pc.dim("Fix .git/gh-stack-metadata.json or repair the local branches before retrying."),
+    pc.dim(`Repair the local branches, or run ${pc.green("gh-stack doctor")}, before retrying.`),
   );
   process.exit(1);
 }
@@ -148,13 +174,13 @@ function validateStackGraph(stack: Stack): string[] {
   if (branchNames.length === 0) return [];
 
   const errors: string[] = [];
+  const base = stackBase(stack);
   const roots = branchNames.filter((branchName) => {
-    const parent = stack.branches[branchName]!.parent;
-    return parent === "main" || parent === "master";
+    return stack.branches[branchName]!.parent === base;
   });
 
   if (roots.length === 0) {
-    errors.push("Stack has no root branch with parent main/master");
+    errors.push(`Stack has no root branch with parent "${base}"`);
   }
   if (roots.length > 1) {
     errors.push(`Stack must have exactly one root branch; found ${roots.length}`);