bstack 0.0.0

package/README.md

@@ -0,0 +1,36 @@
+# bstack
+
+`bstack` turns a series of commits in local branch into native GitHub stacked separate pull requests.
+
+## Install
+
+Requirements: Bun, Git, an authenticated GitHub CLI, and the `github/gh-stack` extension.
+
+```bash
+gh extension install github/gh-stack
+bun install --global bstack
+```
+
+## Use
+
+Create one commit per reviewable change, then publish the stack:
+
+```bash
+git switch -c my-feature
+git commit -am "Add the model"
+git commit -am "Add the API"
+bstack
+```
+
+Run `bstack` again after amending or rebasing commits. New PRs are drafts unless you pass `--open`.
+
+Checkout a stack through one of its PRs:
+
+```bash
+bstack checkout 123
+bstack checkout https://github.com/owner/repo/pull/123
+```
+
+The first publish adds a stable `Bstack-Id` trailer to each commit and rewrites their hashes. The working tree must be clean. Merge commits and signed commits that need trailers are not supported.
+
+Use `--dry-run` to inspect without publishing and `--quiet` to hide progress logs.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "bstack",
+  "version": "0.0.0",
+  "description": "Create native GitHub stacked pull requests from a linear series of commits",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wsehl/bstack.git"
+  },
+  "files": [
+    "src"
+  ],
+  "bin": {
+    "bstack": "./src/cli.ts"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "bun build ./src/cli.ts --compile --outfile ./dist/bstack",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint .",
+    "start": "bun run src/cli.ts",
+    "test": "bun test",
+    "type-check": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.0",
+    "oxfmt": "^0.64.0",
+    "oxlint": "^1.79.0",
+    "typescript": "^7.0.2"
+  }
+}

package/src/checkout.ts

@@ -0,0 +1,67 @@
+import type { GitRepository } from "./git";
+import type { GitHubPlatform } from "./github";
+import type { Reporter } from "./reporter";
+
+export type CheckoutOptions = {
+  reference: string;
+  base: string | undefined;
+  remote: string | undefined;
+  sameBase: boolean;
+  reporter: Reporter;
+};
+
+export type CheckoutResult = {
+  headRef: string;
+  delegated: boolean;
+};
+
+export function checkoutStack(
+  repository: GitRepository,
+  github: GitHubPlatform,
+  options: CheckoutOptions,
+): CheckoutResult {
+  const { reporter } = options;
+  reporter.progress("Checking the repository and GitHub prerequisites");
+  repository.assertReady();
+  github.assertReady();
+
+  const remote = repository.resolveRemote(options.remote);
+  reporter.progress(`Looking up pull request ${options.reference}`);
+  const headRef = github.pullRequestHead(options.reference);
+  if (!headRef.startsWith("bstack/")) {
+    reporter.progress(
+      "This is not a bstack pull request; delegating to gh pr checkout",
+    );
+    github.checkoutPullRequest(options.reference);
+    return { headRef, delegated: true };
+  }
+
+  let currentBase: string | undefined;
+  let remoteBase: string | undefined;
+  if (options.sameBase) {
+    const base = options.base ?? github.defaultBranch();
+    reporter.progress(
+      `Checking that the merge base remains on ${remote}/${base}`,
+    );
+    remoteBase = repository.fetchBase(remote, base);
+    currentBase = repository.mergeBase("HEAD", remoteBase);
+  }
+
+  reporter.progress(`Fetching ${remote}/${headRef}`);
+  const target = repository.fetchRemoteBranch(remote, headRef);
+  if (currentBase && remoteBase) {
+    const targetBase = repository.mergeBase(target, remoteBase);
+    if (currentBase !== targetBase) {
+      throw new Error(
+        `Checkout would change the merge base from ${currentBase.slice(0, 8)} to ${targetBase.slice(0, 8)}`,
+      );
+    }
+  }
+
+  reporter.progress(`Checking out ${remote}/${headRef} in detached HEAD state`);
+  repository.checkout(target);
+  reporter.progress(
+    "Checkout complete; amend the commits and run bstack to publish updates",
+  );
+  return { headRef, delegated: false };
+}

package/src/cli.ts

@@ -0,0 +1,100 @@
+#!/usr/bin/env bun
+
+import { parseArgs } from "node:util";
+import { BunCommandRunner } from "./command";
+import { checkoutStack } from "./checkout";
+import { GitRepository } from "./git";
+import { GhPlatform } from "./github";
+import { ConsoleReporter } from "./reporter";
+import { syncStack } from "./sync";
+
+const help = `bstack - turn a linear commit series into native GitHub stacked PRs
+
+Usage:
+  bstack [sync] [options]
+  bstack checkout <PR-number-or-URL> [options]
+
+Options:
+  --base <branch>    Stack trunk; defaults to the GitHub default branch
+  --remote <name>    Git remote; defaults to remote.pushDefault or origin
+  --open             Create PRs ready for review instead of drafts
+  --dry-run          Inspect the stack without rewriting commits or pushing
+  --quiet            Hide progress logs; the final summary is still printed
+  --same-base        Refuse checkout if it would change the current merge base
+  -h, --help         Show this help
+`;
+
+function main(): void {
+  const { values, positionals } = parseArgs({
+    args: Bun.argv.slice(2),
+    allowPositionals: true,
+    options: {
+      base: { type: "string" },
+      remote: { type: "string" },
+      open: { type: "boolean", default: false },
+      "dry-run": { type: "boolean", default: false },
+      quiet: { type: "boolean", default: false },
+      "same-base": { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+
+  if (values.help) {
+    process.stdout.write(help);
+    return;
+  }
+  const runner = new BunCommandRunner();
+  const cwd = process.cwd();
+  const repository = new GitRepository(cwd, runner);
+  const github = new GhPlatform(cwd, runner);
+  const reporter = new ConsoleReporter(!values.quiet);
+  const command = positionals[0] ?? "sync";
+
+  if (command === "checkout") {
+    const reference = positionals[1];
+    if (!reference || positionals.length > 2) {
+      throw new Error(`Usage: bstack checkout <PR-number-or-URL> [options]`);
+    }
+    const result = checkoutStack(repository, github, {
+      reference,
+      base: values.base,
+      remote: values.remote,
+      sameBase: values["same-base"],
+      reporter,
+    });
+    console.log(
+      result.delegated
+        ? `Checked out pull request ${reference}`
+        : `Checked out ${result.headRef} from pull request ${reference}`,
+    );
+    return;
+  }
+
+  if (command !== "sync" || positionals.length > 1) {
+    throw new Error(`Unknown command: ${positionals.join(" ")}\n\n${help}`);
+  }
+
+  const result = syncStack(repository, github, {
+    base: values.base,
+    remote: values.remote,
+    open: values.open,
+    dryRun: values["dry-run"],
+    reporter,
+  });
+
+  console.log(
+    `${values["dry-run"] ? "Would publish" : "Published"} ${result.changes.length} change${result.changes.length === 1 ? "" : "s"} against ${result.base}:`,
+  );
+  for (const change of result.changes) {
+    const destination = change.pullRequest ? ` ${change.pullRequest.url}` : "";
+    console.log(`  ${change.oid.slice(0, 8)}  ${change.subject}${destination}`);
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`bstack: ${message}`);
+  process.exitCode = 1;
+}

package/src/command.ts

@@ -0,0 +1,61 @@
+export type CommandOptions = {
+  cwd: string;
+  stdin?: string;
+  env?: Record<string, string>;
+  allowFailure?: boolean;
+};
+
+export type CommandResult = {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+};
+
+export class CommandError extends Error {
+  constructor(
+    readonly command: readonly string[],
+    readonly result: CommandResult,
+  ) {
+    const detail = result.stderr.trim() || result.stdout.trim();
+    super(
+      `${command.join(" ")} failed with exit code ${result.exitCode}${detail ? `\n${detail}` : ""}`,
+    );
+  }
+}
+
+export interface CommandRunner {
+  run(command: readonly string[], options: CommandOptions): CommandResult;
+}
+
+export class BunCommandRunner implements CommandRunner {
+  run(command: readonly string[], options: CommandOptions): CommandResult {
+    const [executable, ...args] = command;
+    if (!executable) {
+      throw new Error("Cannot run an empty command");
+    }
+
+    const result = Bun.spawnSync([executable, ...args], {
+      cwd: options.cwd,
+      stdin:
+        options.stdin === undefined ? undefined : Buffer.from(options.stdin),
+      stdout: "pipe",
+      stderr: "pipe",
+      env:
+        options.env === undefined
+          ? process.env
+          : { ...process.env, ...options.env },
+    });
+
+    const commandResult = {
+      stdout: result.stdout.toString(),
+      stderr: result.stderr.toString(),
+      exitCode: result.exitCode,
+    };
+
+    if (commandResult.exitCode !== 0 && !options.allowFailure) {
+      throw new CommandError(command, commandResult);
+    }
+
+    return commandResult;
+  }
+}

package/src/git.ts

@@ -0,0 +1,197 @@
+import type { CommandRunner } from "./command";
+import {
+  addChangeId,
+  newChangeId,
+  parseRawCommit,
+  rewriteCommit,
+  splitCommitMessage,
+} from "./identity";
+import type { Change, Commit } from "./model";
+
+export class GitRepository {
+  constructor(
+    readonly cwd: string,
+    private readonly runner: CommandRunner,
+  ) {}
+
+  private git(
+    args: readonly string[],
+    options: { stdin?: string; allowFailure?: boolean } = {},
+  ) {
+    return this.runner.run(["git", ...args], { cwd: this.cwd, ...options });
+  }
+
+  assertReady(): void {
+    this.git(["rev-parse", "--show-toplevel"]);
+    const status = this.git(["status", "--porcelain"]).stdout;
+    if (status.trim()) {
+      throw new Error(
+        "The working tree must be clean before bstack rewrites or publishes commits",
+      );
+    }
+  }
+
+  currentBranch(): string {
+    return this.git(["symbolic-ref", "--quiet", "--short", "HEAD"], {
+      allowFailure: true,
+    }).stdout.trim();
+  }
+
+  remotes(): string[] {
+    return this.git(["remote"]).stdout.split("\n").filter(Boolean);
+  }
+
+  configuredPushRemote(): string | undefined {
+    const result = this.git(["config", "--get", "remote.pushDefault"], {
+      allowFailure: true,
+    });
+    return result.exitCode === 0
+      ? result.stdout.trim() || undefined
+      : undefined;
+  }
+
+  resolveRemote(requested?: string): string {
+    if (requested) {
+      if (!this.remotes().includes(requested)) {
+        throw new Error(`Git remote ${requested} does not exist`);
+      }
+      return requested;
+    }
+
+    const configured = this.configuredPushRemote();
+    if (configured) return configured;
+    const remotes = this.remotes();
+    if (remotes.length === 1) return remotes[0]!;
+    if (remotes.includes("origin")) return "origin";
+    throw new Error(
+      "Cannot choose a Git remote. Pass --remote or configure remote.pushDefault",
+    );
+  }
+
+  fetchBase(remote: string, base: string): string {
+    const destination = `refs/remotes/${remote}/${base}`;
+    this.git([
+      "fetch",
+      "--no-tags",
+      remote,
+      `refs/heads/${base}:${destination}`,
+    ]);
+    return destination;
+  }
+
+  fetchRemoteBranch(remote: string, branch: string): string {
+    const destination = `refs/remotes/${remote}/${branch}`;
+    this.git([
+      "fetch",
+      "--no-tags",
+      remote,
+      `+refs/heads/${branch}:${destination}`,
+    ]);
+    return destination;
+  }
+
+  checkout(ref: string): void {
+    this.git(["checkout", "--detach", ref]);
+  }
+
+  mergeBase(left: string, right: string): string {
+    return this.git(["merge-base", left, right]).stdout.trim();
+  }
+
+  commitsSince(baseOid: string): Commit[] {
+    const oids = this.git([
+      "rev-list",
+      "--reverse",
+      "--first-parent",
+      `${baseOid}..HEAD`,
+    ])
+      .stdout.split("\n")
+      .filter(Boolean);
+    return oids.map((oid) =>
+      parseRawCommit(oid, this.git(["cat-file", "commit", oid]).stdout),
+    );
+  }
+
+  ensureChangeIds(commits: readonly Commit[], dryRun: boolean): Change[] {
+    const assigned = commits.map((commit) => commit.changeId ?? newChangeId());
+    const needsRewrite = commits.some(
+      (commit) => commit.changeId === undefined,
+    );
+    let parent = commits[0]?.parent;
+    const rewrittenOids: string[] = [];
+
+    if (needsRewrite && !dryRun) {
+      for (const [index, commit] of commits.entries()) {
+        const changeId = assigned[index]!;
+        const message = commit.changeId
+          ? commit.message
+          : addChangeId(commit.message, changeId);
+        const raw = rewriteCommit(commit, parent!, message);
+        const oid = this.git(["hash-object", "-t", "commit", "-w", "--stdin"], {
+          stdin: raw,
+        }).stdout.trim();
+        rewrittenOids.push(oid);
+        parent = oid;
+      }
+
+      const oldHead = commits.at(-1)!.oid;
+      const newHead = rewrittenOids.at(-1)!;
+      this.git(["update-ref", "HEAD", newHead, oldHead]);
+    }
+
+    return commits.map((commit, index) => {
+      const id = assigned[index]!;
+      const oid = needsRewrite && !dryRun ? rewrittenOids[index]! : commit.oid;
+      const { subject, body } = splitCommitMessage(commit.message);
+      return { id, oid, subject, body, remoteBranch: `bstack/${id}` };
+    });
+  }
+
+  remoteBranchOids(
+    remote: string,
+    branches: readonly string[],
+  ): Map<string, string> {
+    if (branches.length === 0) return new Map();
+    const result = this.git([
+      "ls-remote",
+      "--heads",
+      remote,
+      ...branches.map((branch) => `refs/heads/${branch}`),
+    ]);
+    return new Map(
+      result.stdout
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+          const [oid, ref] = line.split(/\s+/, 2);
+          return [ref!.replace("refs/heads/", ""), oid!] as const;
+        }),
+    );
+  }
+
+  pushChanges(remote: string, changes: readonly Change[]): void {
+    const existing = this.remoteBranchOids(
+      remote,
+      changes.map((change) => change.remoteBranch),
+    );
+    const leases: string[] = [];
+    const refspecs: string[] = [];
+    for (const change of changes) {
+      const expected = existing.get(change.remoteBranch) ?? "";
+      leases.push(
+        `--force-with-lease=refs/heads/${change.remoteBranch}:${expected}`,
+      );
+      refspecs.push(`${change.oid}:refs/heads/${change.remoteBranch}`);
+    }
+    this.git(["push", "--atomic", ...leases, remote, ...refspecs]);
+  }
+
+  statePath(): string {
+    return this.git([
+      "rev-parse",
+      "--path-format=absolute",
+      "--git-path",
+      "bstack/state.json",
+    ]).stdout.trim();
+  }
+}

package/src/github.ts

@@ -0,0 +1,187 @@
+import type { CommandRunner } from "./command";
+import type { Change, PullRequest } from "./model";
+
+type PullRequestJson = {
+  number: number;
+  url: string;
+  state: string;
+  title: string;
+  body: string;
+  isDraft: boolean;
+};
+
+type StackJson = { number: number };
+
+export interface GitHubPlatform {
+  assertReady(): void;
+  defaultBranch(): string;
+  pullRequestForBranch(branch: string): PullRequest | undefined;
+  pullRequest(number: number): PullRequest;
+  createPullRequest(change: Change, base: string, open: boolean): PullRequest;
+  linkStack(
+    branches: readonly string[],
+    base: string,
+    remote: string,
+    open: boolean,
+  ): void;
+  appendToStack(
+    stackNumber: number,
+    branches: readonly string[],
+    remote: string,
+    open: boolean,
+  ): void;
+  editPullRequest(pr: PullRequest, change: Change): void;
+  stackNumberForPullRequest(prNumber: number): number | undefined;
+  pullRequestHead(reference: string): string;
+  checkoutPullRequest(reference: string): void;
+}
+
+export class GhPlatform implements GitHubPlatform {
+  constructor(
+    private readonly cwd: string,
+    private readonly runner: CommandRunner,
+  ) {}
+
+  private gh(args: readonly string[]) {
+    return this.runner.run(["gh", ...args], { cwd: this.cwd });
+  }
+
+  assertReady(): void {
+    this.gh(["auth", "status", "--active"]);
+    this.gh(["stack", "--version"]);
+  }
+
+  defaultBranch(): string {
+    return this.gh([
+      "repo",
+      "view",
+      "--json",
+      "defaultBranchRef",
+      "--jq",
+      ".defaultBranchRef.name",
+    ]).stdout.trim();
+  }
+
+  pullRequestForBranch(branch: string): PullRequest | undefined {
+    const raw = this.gh([
+      "pr",
+      "list",
+      "--head",
+      branch,
+      "--state",
+      "all",
+      "--limit",
+      "20",
+      "--json",
+      "number,url,state,title,body,isDraft",
+    ]).stdout;
+    const candidates = JSON.parse(raw) as PullRequestJson[];
+    const selected =
+      candidates.find((pr) => pr.state === "OPEN") ??
+      candidates.find((pr) => pr.state === "MERGED");
+    return selected ? normalizePullRequest(selected) : undefined;
+  }
+
+  pullRequest(number: number): PullRequest {
+    const raw = this.gh([
+      "pr",
+      "view",
+      String(number),
+      "--json",
+      "number,url,state,title,body,isDraft",
+    ]).stdout;
+    return normalizePullRequest(JSON.parse(raw) as PullRequestJson);
+  }
+
+  createPullRequest(change: Change, base: string, open: boolean): PullRequest {
+    const args = [
+      "pr",
+      "create",
+      "--base",
+      base,
+      "--head",
+      change.remoteBranch,
+      "--title",
+      change.subject,
+      "--body",
+      change.body,
+    ];
+    if (!open) args.push("--draft");
+    this.gh(args);
+    const created = this.pullRequestForBranch(change.remoteBranch);
+    if (!created)
+      throw new Error(
+        `GitHub did not return the PR created for ${change.remoteBranch}`,
+      );
+    return created;
+  }
+
+  linkStack(
+    branches: readonly string[],
+    base: string,
+    remote: string,
+    open: boolean,
+  ): void {
+    const args = ["stack", "link", "--base", base, "--remote", remote];
+    if (open) args.push("--open");
+    args.push(...branches);
+    this.gh(args);
+  }
+
+  appendToStack(
+    stackNumber: number,
+    branches: readonly string[],
+    remote: string,
+    open: boolean,
+  ): void {
+    const args = ["stack", "link", "--remote", remote];
+    if (open) args.push("--open");
+    args.push(String(stackNumber), ...branches);
+    this.gh(args);
+  }
+
+  editPullRequest(pr: PullRequest, change: Change): void {
+    if (pr.title === change.subject && pr.body === change.body) return;
+    this.gh([
+      "pr",
+      "edit",
+      String(pr.number),
+      "--title",
+      change.subject,
+      "--body",
+      change.body,
+    ]);
+  }
+
+  stackNumberForPullRequest(prNumber: number): number | undefined {
+    const raw = this.gh([
+      "api",
+      `repos/{owner}/{repo}/stacks?pull_request=${prNumber}`,
+    ]).stdout;
+    const stacks = JSON.parse(raw) as StackJson[];
+    return stacks[0]?.number;
+  }
+
+  pullRequestHead(reference: string): string {
+    return this.gh([
+      "pr",
+      "view",
+      reference,
+      "--json",
+      "headRefName",
+      "--jq",
+      ".headRefName",
+    ]).stdout.trim();
+  }
+
+  checkoutPullRequest(reference: string): void {
+    this.gh(["pr", "checkout", reference]);
+  }
+}
+
+function normalizePullRequest(pr: PullRequestJson): PullRequest {
+  if (pr.state !== "OPEN" && pr.state !== "CLOSED" && pr.state !== "MERGED") {
+    throw new Error(`GitHub returned an unknown PR state: ${pr.state}`);
+  }
+  return { ...pr, state: pr.state };
+}

package/src/identity.ts

@@ -0,0 +1,88 @@
+import { randomUUID } from "node:crypto";
+import type { Commit } from "./model";
+
+const trailerPattern = /^Bstack-Id:\s*(\S+)\s*$/gim;
+
+export function readChangeId(message: string): string | undefined {
+  const matches = [...message.matchAll(trailerPattern)];
+  if (matches.length > 1) {
+    throw new Error("A commit contains more than one Bstack-Id trailer");
+  }
+  return matches[0]?.[1];
+}
+
+export function addChangeId(message: string, changeId: string): string {
+  const trimmed = message.trimEnd();
+  return `${trimmed}\n\nBstack-Id: ${changeId}\n`;
+}
+
+export function newChangeId(): string {
+  return randomUUID().replaceAll("-", "");
+}
+
+export function parseRawCommit(oid: string, raw: string): Commit {
+  const boundary = raw.indexOf("\n\n");
+  if (boundary === -1) {
+    throw new Error(`Commit ${oid} has an invalid object format`);
+  }
+
+  const headers = raw.slice(0, boundary).split("\n");
+  const treeLine = headers.find((line) => line.startsWith("tree "));
+  const parents = headers.filter((line) => line.startsWith("parent "));
+  if (!treeLine || parents.length !== 1) {
+    throw new Error(
+      `Commit ${oid} must have exactly one parent; merge and root commits are not supported`,
+    );
+  }
+  if (headers.some((line) => line.startsWith("gpgsig "))) {
+    throw new Error(
+      `Commit ${oid} is signed. bstack cannot add an identity trailer without replacing its signature`,
+    );
+  }
+
+  const message = raw.slice(boundary + 2);
+  return {
+    oid,
+    tree: treeLine.slice("tree ".length),
+    parent: parents[0]!.slice("parent ".length),
+    message,
+    headers,
+    changeId: readChangeId(message),
+  };
+}
+
+export function rewriteCommit(
+  commit: Commit,
+  parent: string,
+  message: string,
+): string {
+  const rewrittenHeaders: string[] = [];
+  let replacedParent = false;
+
+  for (const header of commit.headers) {
+    if (header.startsWith("parent ")) {
+      if (!replacedParent) {
+        rewrittenHeaders.push(`parent ${parent}`);
+        replacedParent = true;
+      }
+      continue;
+    }
+    rewrittenHeaders.push(header);
+  }
+
+  return `${rewrittenHeaders.join("\n")}\n\n${message}`;
+}
+
+export function splitCommitMessage(message: string): {
+  subject: string;
+  body: string;
+} {
+  const withoutIdentity = message
+    .split("\n")
+    .filter((line) => !/^Bstack-Id:\s*\S+\s*$/i.test(line))
+    .join("\n")
+    .trim();
+  const [subject = "Untitled change", ...bodyLines] =
+    withoutIdentity.split("\n");
+  return { subject, body: bodyLines.join("\n").trim() };
+}

package/src/model.ts

@@ -0,0 +1,44 @@
+export type Commit = {
+  oid: string;
+  tree: string;
+  parent: string;
+  message: string;
+  headers: readonly string[];
+  changeId: string | undefined;
+};
+
+export type Change = {
+  id: string;
+  oid: string;
+  subject: string;
+  body: string;
+  remoteBranch: string;
+};
+
+export type PullRequest = {
+  number: number;
+  url: string;
+  state: "OPEN" | "CLOSED" | "MERGED";
+  title: string;
+  body: string;
+  isDraft: boolean;
+};
+
+export type StoredChange = {
+  id: string;
+  remoteBranch: string;
+  pullRequest: number;
+  url: string;
+};
+
+export type StoredStack = {
+  remote: string;
+  base: string;
+  stackNumber?: number;
+  changes: StoredChange[];
+};
+
+export type BstackState = {
+  schemaVersion: 1;
+  stacks: StoredStack[];
+};

package/src/reporter.ts

@@ -0,0 +1,11 @@
+export interface Reporter {
+  progress(message: string): void;
+}
+
+export class ConsoleReporter implements Reporter {
+  constructor(private readonly enabled = true) {}
+
+  progress(message: string): void {
+    if (this.enabled) process.stderr.write(`[bstack] ${message}\n`);
+  }
+}

package/src/state.ts

@@ -0,0 +1,52 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { BstackState, StoredStack } from "./model";
+
+const emptyState = (): BstackState => ({ schemaVersion: 1, stacks: [] });
+
+export class StateStore {
+  constructor(private readonly path: string) {}
+
+  read(): BstackState {
+    try {
+      const parsed = JSON.parse(readFileSync(this.path, "utf8")) as unknown;
+      if (!isState(parsed))
+        throw new Error(`Unsupported bstack state in ${this.path}`);
+      return parsed;
+    } catch (error) {
+      if (isMissingFile(error)) return emptyState();
+      throw error;
+    }
+  }
+
+  write(state: BstackState): void {
+    mkdirSync(dirname(this.path), { recursive: true });
+    const temporary = `${this.path}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`);
+    renameSync(temporary, this.path);
+  }
+
+  findByChangeIds(
+    state: BstackState,
+    ids: ReadonlySet<string>,
+  ): StoredStack | undefined {
+    const matches = state.stacks.filter((stack) =>
+      stack.changes.some((change) => ids.has(change.id)),
+    );
+    if (matches.length > 1)
+      throw new Error(
+        "The current commits match more than one stored bstack stack",
+      );
+    return matches[0];
+  }
+}
+
+function isMissingFile(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+
+function isState(value: unknown): value is BstackState {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as { schemaVersion?: unknown; stacks?: unknown };
+  return candidate.schemaVersion === 1 && Array.isArray(candidate.stacks);
+}

package/src/sync.ts

@@ -0,0 +1,251 @@
+import type { GitRepository } from "./git";
+import type { GitHubPlatform } from "./github";
+import type { BstackState, Change, PullRequest, StoredStack } from "./model";
+import type { Reporter } from "./reporter";
+import { StateStore } from "./state";
+
+export type SyncOptions = {
+  base: string | undefined;
+  remote: string | undefined;
+  open: boolean;
+  dryRun: boolean;
+  reporter: Reporter;
+};
+
+export type SyncResult = {
+  base: string;
+  remote: string;
+  rewritten: boolean;
+  changes: Array<Change & { pullRequest?: PullRequest }>;
+};
+
+export function syncStack(
+  repository: GitRepository,
+  github: GitHubPlatform,
+  options: SyncOptions,
+): SyncResult {
+  const { reporter } = options;
+  reporter.progress("Checking the repository and GitHub prerequisites");
+  repository.assertReady();
+  github.assertReady();
+  const remote = repository.resolveRemote(options.remote);
+  const base = options.base ?? github.defaultBranch();
+  reporter.progress(
+    `Using ${remote} as the remote and ${base} as the stack base`,
+  );
+  reporter.progress(`Fetching ${remote}/${base}`);
+  const remoteBase = repository.fetchBase(remote, base);
+  const baseOid = repository.mergeBase("HEAD", remoteBase);
+  const commits = repository.commitsSince(baseOid);
+  if (commits.length === 0)
+    throw new Error(`No commits found between ${base} and HEAD`);
+  reporter.progress(
+    `Found ${commits.length} local change${commits.length === 1 ? "" : "s"}`,
+  );
+
+  const rewritten = commits.some((commit) => commit.changeId === undefined);
+  if (rewritten) {
+    reporter.progress(
+      options.dryRun
+        ? "Stable change IDs would be added to the commits"
+        : "Adding stable change IDs to the commits",
+    );
+  } else {
+    reporter.progress("All commits already have stable change IDs");
+  }
+  const changes = repository.ensureChangeIds(commits, options.dryRun);
+  if (options.dryRun) {
+    reporter.progress(
+      "Dry run complete; no commits or remote branches were changed",
+    );
+    return { base, remote, rewritten, changes };
+  }
+
+  reporter.progress("Reading the previous stack state");
+  const store = new StateStore(repository.statePath());
+  const state = store.read();
+  const previous = store.findByChangeIds(
+    state,
+    new Set(changes.map((change) => change.id)),
+  );
+  const evolution = analyzeEvolution(previous, changes, github);
+
+  reporter.progress(
+    `Publishing ${changes.length} protected remote ref${changes.length === 1 ? "" : "s"}`,
+  );
+  repository.pushChanges(remote, changes);
+
+  reporter.progress("Looking up existing pull requests");
+  const existing = changes.map((change) =>
+    github.pullRequestForBranch(change.remoteBranch),
+  );
+  let pullRequests: PullRequest[];
+  if (changes.length === 1) {
+    if (evolution.kind === "partial") {
+      reporter.progress(
+        "Updating this down-stack prefix while preserving higher pull requests",
+      );
+    }
+    reporter.progress(
+      existing[0]
+        ? "Using the existing pull request"
+        : "Creating a pull request",
+    );
+    pullRequests = [
+      existing[0] ?? github.createPullRequest(changes[0]!, base, options.open),
+    ];
+  } else {
+    if (evolution.kind === "full") {
+      reporter.progress(
+        `Linking ${changes.length} pull requests as a native GitHub stack`,
+      );
+      github.linkStack(
+        changes.map((change) => change.remoteBranch),
+        base,
+        remote,
+        options.open,
+      );
+    } else if (evolution.kind === "append") {
+      reporter.progress(
+        `Appending ${evolution.branches.length} pull request${evolution.branches.length === 1 ? "" : "s"} to stack #${evolution.stackNumber}`,
+      );
+      github.appendToStack(
+        evolution.stackNumber,
+        evolution.branches,
+        remote,
+        options.open,
+      );
+    } else if (evolution.kind === "partial") {
+      reporter.progress(
+        "Updating this down-stack prefix while preserving higher pull requests",
+      );
+    } else {
+      reporter.progress(
+        "The native GitHub stack already has the correct members",
+      );
+    }
+    pullRequests = changes.map((change, index) => {
+      const pr =
+        existing[index] ?? github.pullRequestForBranch(change.remoteBranch);
+      if (!pr)
+        throw new Error(
+          `GitHub did not return a PR for ${change.remoteBranch}`,
+        );
+      return pr;
+    });
+  }
+
+  reporter.progress("Synchronizing pull request titles and descriptions");
+  for (const [index, pr] of pullRequests.entries()) {
+    github.editPullRequest(pr, changes[index]!);
+    reporter.progress(`PR #${pr.number}: ${changes[index]!.subject}`);
+  }
+
+  const stackNumber =
+    previous?.stackNumber ??
+    (pullRequests.length > 1
+      ? github.stackNumberForPullRequest(pullRequests[0]!.number)
+      : undefined);
+  const synchronizedChanges = changes.map((change, index) => ({
+    id: change.id,
+    remoteBranch: change.remoteBranch,
+    pullRequest: pullRequests[index]!.number,
+    url: pullRequests[index]!.url,
+  }));
+  const storedChanges =
+    evolution.kind === "partial" && previous
+      ? [
+          ...synchronizedChanges,
+          ...previous.changes.slice(evolution.previousOffset + changes.length),
+        ]
+      : synchronizedChanges;
+  const stored: StoredStack = {
+    remote,
+    base,
+    ...(stackNumber === undefined ? {} : { stackNumber }),
+    changes: storedChanges,
+  };
+  writeUpdatedState(store, state, previous, stored);
+  reporter.progress("Saved the local stack state");
+
+  return {
+    base,
+    remote,
+    rewritten,
+    changes: changes.map((change, index) => ({
+      ...change,
+      pullRequest: pullRequests[index]!,
+    })),
+  };
+}
+
+type Evolution =
+  | { kind: "full" }
+  | { kind: "skip" }
+  | { kind: "partial"; previousOffset: number }
+  | { kind: "append"; stackNumber: number; branches: string[] };
+
+function analyzeEvolution(
+  previous: StoredStack | undefined,
+  changes: readonly Change[],
+  github: GitHubPlatform,
+): Evolution {
+  if (!previous) return { kind: "full" };
+  const previousIds = previous.changes.map((change) => change.id);
+  const currentIds = changes.map((change) => change.id);
+
+  const firstCurrentIndex = previousIds.indexOf(currentIds[0]!);
+  if (firstCurrentIndex === -1) {
+    throw new Error(
+      "The current commits do not continue the previously submitted stack",
+    );
+  }
+
+  const removedPrefix = previous.changes.slice(0, firstCurrentIndex);
+  for (const removed of removedPrefix) {
+    if (github.pullRequest(removed.pullRequest).state !== "MERGED") {
+      throw new Error(
+        "Submitted commits may only disappear from the bottom after their pull requests are merged",
+      );
+    }
+  }
+
+  const surviving = previousIds.slice(firstCurrentIndex);
+  const sharedLength = Math.min(surviving.length, currentIds.length);
+  for (let index = 0; index < sharedLength; index++) {
+    if (surviving[index] !== currentIds[index]) {
+      throw new Error(
+        "Reordering or removing submitted commits is not supported yet. Restore the original order before syncing",
+      );
+    }
+  }
+  if (currentIds.length < surviving.length) {
+    return { kind: "partial", previousOffset: firstCurrentIndex };
+  }
+
+  const appended = changes.slice(surviving.length);
+  if (removedPrefix.length === 0) return { kind: "full" };
+  if (appended.length === 0) return { kind: "skip" };
+  if (previous.stackNumber === undefined) {
+    throw new Error(
+      "Cannot append after a merge because the native GitHub stack number is missing from local state",
+    );
+  }
+  return {
+    kind: "append",
+    stackNumber: previous.stackNumber,
+    branches: appended.map((change) => change.remoteBranch),
+  };
+}
+
+function writeUpdatedState(
+  store: StateStore,
+  state: BstackState,
+  previous: StoredStack | undefined,
+  updated: StoredStack,
+): void {
+  const stacks = previous
+    ? state.stacks.map((stack) => (stack === previous ? updated : stack))
+    : [...state.stacks, updated];
+  store.write({ schemaVersion: 1, stacks });
+}