bstack 1.1.3 → 1.1.4

package/README.md

@@ -94,3 +94,4 @@ command before it runs.
 
 - [ezyang/ghstack](https://github.com/ezyang/ghstack)
 - [github/gh-stack](https://github.com/github/gh-stack)
+- [stacking.dev](https://www.stacking.dev/)

package/dist/bstack.mjs

@@ -0,0 +1,898 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import * as v from "valibot";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+//#region package.json
+var version = "1.1.4";
+//#endregion
+//#region src/command.ts
+var CommandError = class extends Error {
+	command;
+	result;
+	constructor(command, result) {
+		const detail = result.stderr.trim() || result.stdout.trim();
+		super(`${command.join(" ")} failed with exit code ${result.exitCode}${detail ? `\n${detail}` : ""}`);
+		this.command = command;
+		this.result = result;
+	}
+};
+var NodeCommandRunner = class {
+	logger;
+	constructor(logger) {
+		this.logger = logger;
+	}
+	run(command, options) {
+		const [executable, ...args] = command;
+		if (!executable) throw new Error("Cannot run an empty command");
+		this.logger?.(command);
+		const result = spawnSync(executable, args, {
+			cwd: options.cwd,
+			input: options.stdin,
+			encoding: "utf8",
+			env: options.env === void 0 ? process.env : {
+				...process.env,
+				...options.env
+			}
+		});
+		const commandResult = {
+			stdout: result.stdout ?? "",
+			stderr: result.stderr ?? result.error?.message ?? "",
+			exitCode: result.status ?? 1
+		};
+		if (commandResult.exitCode !== 0 && !options.allowFailure) throw new CommandError(command, commandResult);
+		return commandResult;
+	}
+};
+function formatCommand(command) {
+	return command.map(formatArgument).join(" ");
+}
+function formatArgument(argument) {
+	if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(argument)) return argument;
+	return `'${argument.replaceAll("'", `'"'"'`)}'`;
+}
+//#endregion
+//#region src/checkout.ts
+function checkoutStack(dependencies, options) {
+	const { repository, github, reporter } = dependencies;
+	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;
+	let remoteBase;
+	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 sync updates");
+	return {
+		headRef,
+		delegated: false
+	};
+}
+//#endregion
+//#region src/commit.ts
+const CHANGE_ID_TRAILER = "bstack-id";
+const changeIdTrailerPattern = new RegExp(`^${CHANGE_ID_TRAILER}:\\s*(\\S+)\\s*$`, "gm");
+const changeIdTrailerLinePattern = new RegExp(`^${CHANGE_ID_TRAILER}:\\s*\\S+\\s*$`);
+function readChangeId(message) {
+	const matches = [...message.matchAll(changeIdTrailerPattern)];
+	if (matches.length > 1) throw new Error(`A commit contains more than one ${CHANGE_ID_TRAILER} trailer`);
+	return matches[0]?.[1];
+}
+function addChangeId(message, changeId) {
+	return `${message.trimEnd()}\n\n${CHANGE_ID_TRAILER}: ${changeId}\n`;
+}
+function generateChangeId() {
+	return randomUUID().replaceAll("-", "");
+}
+function parseRawCommit(oid, raw) {
+	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(5),
+		parent: parents[0].slice(7),
+		message,
+		headers,
+		changeId: readChangeId(message)
+	};
+}
+function rewriteCommit(commit, parent, message) {
+	const rewrittenHeaders = [];
+	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}`;
+}
+function splitCommitMessage(message) {
+	const [subject = "Untitled change", ...bodyLines] = message.split("\n").filter((line) => !changeIdTrailerLinePattern.test(line)).join("\n").trim().split("\n");
+	return {
+		subject,
+		body: bodyLines.join("\n").trim()
+	};
+}
+//#endregion
+//#region src/git.ts
+var GitCliRepository = class {
+	cwd;
+	runner;
+	constructor(cwd, runner) {
+		this.cwd = cwd;
+		this.runner = runner;
+	}
+	git(args, options = {}) {
+		return this.runner.run(["git", ...args], {
+			cwd: this.cwd,
+			...options
+		});
+	}
+	assertReady() {
+		this.git(["rev-parse", "--show-toplevel"]);
+		if (this.git(["status", "--porcelain"]).stdout.trim()) throw new Error("The working tree must be clean before bstack rewrites commits or pushes branches");
+	}
+	currentBranch() {
+		return this.git([
+			"symbolic-ref",
+			"--quiet",
+			"--short",
+			"HEAD"
+		], { allowFailure: true }).stdout.trim();
+	}
+	resolveRemote(requested) {
+		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, base) {
+		const destination = `refs/remotes/${remote}/${base}`;
+		this.git([
+			"fetch",
+			"--no-tags",
+			remote,
+			`refs/heads/${base}:${destination}`
+		]);
+		return destination;
+	}
+	fetchRemoteBranch(remote, branch) {
+		const destination = `refs/remotes/${remote}/${branch}`;
+		this.git([
+			"fetch",
+			"--no-tags",
+			remote,
+			`+refs/heads/${branch}:${destination}`
+		]);
+		return destination;
+	}
+	checkout(ref) {
+		this.git([
+			"checkout",
+			"--detach",
+			ref
+		]);
+	}
+	mergeBase(left, right) {
+		return this.git([
+			"merge-base",
+			left,
+			right
+		]).stdout.trim();
+	}
+	commitsSince(baseOid) {
+		return this.git([
+			"rev-list",
+			"--reverse",
+			"--first-parent",
+			`${baseOid}..HEAD`
+		]).stdout.split("\n").filter(Boolean).map((oid) => parseRawCommit(oid, this.git([
+			"cat-file",
+			"commit",
+			oid
+		]).stdout));
+	}
+	rewriteCommits(rewrites) {
+		if (rewrites.length === 0) return [];
+		let parent = rewrites[0].commit.parent;
+		const rewrittenOids = [];
+		for (const rewrite of rewrites) {
+			const raw = rewriteCommit(rewrite.commit, parent, rewrite.message);
+			const oid = this.git([
+				"hash-object",
+				"-t",
+				"commit",
+				"-w",
+				"--stdin"
+			], { stdin: raw }).stdout.trim();
+			rewrittenOids.push(oid);
+			parent = oid;
+		}
+		const oldHead = rewrites.at(-1).commit.oid;
+		const newHead = rewrittenOids.at(-1);
+		this.git([
+			"update-ref",
+			"HEAD",
+			newHead,
+			oldHead
+		]);
+		return rewrittenOids;
+	}
+	pushBranches(remote, branches) {
+		const existing = this.remoteBranchOids(remote, branches.map((branch) => branch.name));
+		const leases = [];
+		const refspecs = [];
+		for (const branch of branches) {
+			const expected = existing.get(branch.name) ?? "";
+			leases.push(`--force-with-lease=refs/heads/${branch.name}:${expected}`);
+			refspecs.push(`${branch.oid}:refs/heads/${branch.name}`);
+		}
+		this.git([
+			"push",
+			"--atomic",
+			...leases,
+			remote,
+			...refspecs
+		]);
+	}
+	statePath() {
+		return this.git([
+			"rev-parse",
+			"--path-format=absolute",
+			"--git-path",
+			"bstack/state.json"
+		]).stdout.trim();
+	}
+	remotes() {
+		return this.git(["remote"]).stdout.split("\n").filter(Boolean);
+	}
+	configuredPushRemote() {
+		const result = this.git([
+			"config",
+			"--get",
+			"remote.pushDefault"
+		], { allowFailure: true });
+		return result.exitCode === 0 ? result.stdout.trim() || void 0 : void 0;
+	}
+	remoteBranchOids(remote, branches) {
+		if (branches.length === 0) return /* @__PURE__ */ 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];
+		}));
+	}
+};
+//#endregion
+//#region src/github.ts
+const pullRequestSchema = v.object({
+	number: v.number(),
+	url: v.string(),
+	state: v.picklist([
+		"OPEN",
+		"CLOSED",
+		"MERGED"
+	]),
+	title: v.string(),
+	body: v.string(),
+	isDraft: v.boolean()
+});
+const stackSchema = v.object({ number: v.number() });
+var GitHubCliPlatform = class {
+	cwd;
+	runner;
+	constructor(cwd, runner) {
+		this.cwd = cwd;
+		this.runner = runner;
+	}
+	gh(args) {
+		return this.runner.run(["gh", ...args], { cwd: this.cwd });
+	}
+	assertReady() {
+		this.gh([
+			"auth",
+			"status",
+			"--active"
+		]);
+		this.gh(["stack", "--version"]);
+	}
+	currentUserLogin() {
+		const login = this.gh([
+			"api",
+			"user",
+			"--jq",
+			".login"
+		]).stdout.trim();
+		return v.parse(v.pipe(v.string(), v.minLength(1)), login);
+	}
+	defaultBranch() {
+		return this.gh([
+			"repo",
+			"view",
+			"--json",
+			"defaultBranchRef",
+			"--jq",
+			".defaultBranchRef.name"
+		]).stdout.trim();
+	}
+	pullRequestForBranch(branch) {
+		const raw = this.gh([
+			"pr",
+			"list",
+			"--head",
+			branch,
+			"--state",
+			"all",
+			"--limit",
+			"20",
+			"--json",
+			"number,url,state,title,body,isDraft"
+		]).stdout;
+		const candidates = v.parse(v.array(pullRequestSchema), JSON.parse(raw));
+		return candidates.find((pr) => pr.state === "OPEN") ?? candidates.find((pr) => pr.state === "MERGED");
+	}
+	pullRequest(number) {
+		const raw = this.gh([
+			"pr",
+			"view",
+			String(number),
+			"--json",
+			"number,url,state,title,body,isDraft"
+		]).stdout;
+		return v.parse(pullRequestSchema, JSON.parse(raw));
+	}
+	createPullRequest(change, base, draft) {
+		const args = [
+			"pr",
+			"create",
+			"--base",
+			base,
+			"--head",
+			change.remoteBranch,
+			"--title",
+			change.subject,
+			"--body",
+			change.body
+		];
+		if (draft) 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, base, remote, draft) {
+		const args = [
+			"stack",
+			"link",
+			"--base",
+			base,
+			"--remote",
+			remote
+		];
+		if (!draft) args.push("--open");
+		args.push(...branches);
+		this.gh(args);
+	}
+	appendToStack(stackNumber, branches, remote, draft) {
+		const args = [
+			"stack",
+			"link",
+			"--remote",
+			remote
+		];
+		if (!draft) args.push("--open");
+		args.push(String(stackNumber), ...branches);
+		this.gh(args);
+	}
+	unstack(stackNumber) {
+		this.gh([
+			"stack",
+			"unstack",
+			String(stackNumber)
+		]);
+	}
+	editPullRequestBase(pr, base) {
+		this.gh([
+			"pr",
+			"edit",
+			String(pr.number),
+			"--base",
+			base
+		]);
+	}
+	editPullRequest(pr, change) {
+		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) {
+		const raw = this.gh(["api", `repos/{owner}/{repo}/stacks?pull_request=${prNumber}`]).stdout;
+		return v.parse(v.array(stackSchema), JSON.parse(raw))[0]?.number;
+	}
+	pullRequestHead(reference) {
+		return this.gh([
+			"pr",
+			"view",
+			reference,
+			"--json",
+			"headRefName",
+			"--jq",
+			".headRefName"
+		]).stdout.trim();
+	}
+	checkoutPullRequest(reference) {
+		this.gh([
+			"pr",
+			"checkout",
+			reference
+		]);
+	}
+};
+//#endregion
+//#region src/reporter.ts
+var ConsoleReporter = class {
+	progress(message) {
+		process.stderr.write(`[bstack] ${message}\n`);
+	}
+	command(command) {
+		this.progress(`$ ${formatCommand(command)}`);
+	}
+};
+//#endregion
+//#region src/state.ts
+const emptyState = () => ({
+	schemaVersion: 1,
+	stacks: []
+});
+const storedChangeSchema = v.object({
+	id: v.string(),
+	remoteBranch: v.string(),
+	pullRequest: v.number(),
+	url: v.string()
+});
+const storedStackSchema = v.object({
+	remote: v.string(),
+	base: v.string(),
+	stackNumber: v.optional(v.number()),
+	changes: v.array(storedChangeSchema)
+});
+const stateSchema = v.object({
+	schemaVersion: v.literal(1),
+	stacks: v.array(storedStackSchema)
+});
+var FileStateStore = class {
+	path;
+	constructor(path) {
+		this.path = path;
+	}
+	read() {
+		try {
+			return {
+				schemaVersion: 1,
+				stacks: v.parse(stateSchema, JSON.parse(readFileSync(this.path, "utf8"))).stacks.map((stack) => {
+					const stored = {
+						remote: stack.remote,
+						base: stack.base,
+						changes: stack.changes
+					};
+					if (stack.stackNumber !== void 0) stored.stackNumber = stack.stackNumber;
+					return stored;
+				})
+			};
+		} catch (error) {
+			if (error instanceof Error && "code" in error && error.code === "ENOENT") return emptyState();
+			if (v.isValiError(error)) throw new Error(`Unsupported bstack state in ${this.path}`, { cause: error });
+			throw error;
+		}
+	}
+	write(state) {
+		mkdirSync(dirname(this.path), { recursive: true });
+		const temporary = `${this.path}.tmp`;
+		writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`);
+		renameSync(temporary, this.path);
+	}
+};
+//#endregion
+//#region src/stack.ts
+var Stack = class Stack {
+	changes;
+	rewritten;
+	rewrites;
+	constructor(changes, rewritten = false, rewrites = []) {
+		this.changes = changes;
+		this.rewritten = rewritten;
+		this.rewrites = rewrites;
+		if (changes.length === 0) throw new Error("A stack must contain at least one change");
+	}
+	static fromChanges(changes) {
+		return new Stack(changes);
+	}
+	static fromCommits(commits, userLogin) {
+		const ids = commits.map((commit) => commit.changeId ?? generateChangeId());
+		const rewritten = commits.some((commit) => commit.changeId === void 0);
+		const rewrites = rewritten ? commits.map((commit, index) => ({
+			commit,
+			message: commit.changeId ? commit.message : addChangeId(commit.message, ids[index])
+		})) : [];
+		const changes = commits.map((commit, index) => {
+			const id = ids[index];
+			const { subject, body } = splitCommitMessage(commit.message);
+			return {
+				id,
+				oid: commit.oid,
+				subject,
+				body,
+				remoteBranch: `bstack/${userLogin}/${id}`
+			};
+		});
+		return new Stack(changes, rewritten, rewrites);
+	}
+	writeChangeIds(repository) {
+		if (!this.rewritten) return this;
+		const rewrittenOids = repository.rewriteCommits(this.rewrites);
+		if (rewrittenOids.length !== this.changes.length) throw new Error(`Git rewrote ${rewrittenOids.length} commits for a stack with ${this.changes.length} changes`);
+		const changes = this.changes.map((change, index) => ({
+			...change,
+			oid: rewrittenOids[index]
+		}));
+		return new Stack(changes, true);
+	}
+	findPrevious(state) {
+		const ids = new Set(this.changes.map((change) => change.id));
+		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];
+	}
+	transitionFrom(previous, options) {
+		if (!previous) return { kind: "full" };
+		const previousIds = previous.changes.map((change) => change.id);
+		const currentIds = this.changes.map((change) => change.id);
+		const previousIdSet = new Set(previousIds);
+		const currentIdSet = new Set(currentIds);
+		if (!sameSequence(previousIds.filter((id) => currentIdSet.has(id)), currentIds.filter((id) => previousIdSet.has(id)))) throw new Error("Submitted commits cannot be reordered. Restore their original relative order before syncing");
+		const removed = previous.changes.filter((change) => !currentIdSet.has(change.id));
+		const added = this.changes.filter((change) => !previousIdSet.has(change.id));
+		if (removed.length === 0) {
+			if (previousIds.every((id, index) => currentIds[index] === id)) return { kind: "full" };
+			const stackNumber = previous.stackNumber ?? options.lookups.stackNumberForPullRequest(previous.changes[0].pullRequest);
+			return stackNumber === void 0 ? { kind: "full" } : {
+				kind: "rebuild",
+				stackNumber,
+				action: "insert"
+			};
+		}
+		const firstCurrentIndex = previousIds.indexOf(currentIds[0]);
+		const isPreviousSlice = firstCurrentIndex >= 0 && currentIds.every((id, index) => previousIds[firstCurrentIndex + index] === id);
+		if (options.preserveHigherChanges && added.length === 0 && isPreviousSlice && firstCurrentIndex + currentIds.length < previousIds.length) {
+			if (previous.changes.slice(0, firstCurrentIndex).every((change) => options.lookups.pullRequestState(change.pullRequest) === "MERGED")) return {
+				kind: "partial",
+				previousOffset: firstCurrentIndex
+			};
+		}
+		const removedPrefixWasMerged = removed.every((change, index) => previous.changes[index] === change) && removed.every((change) => options.lookups.pullRequestState(change.pullRequest) === "MERGED");
+		const survivingIds = previousIds.slice(removed.length);
+		const onlyAppendedAfterMergedPrefix = removedPrefixWasMerged && survivingIds.every((id, index) => currentIds[index] === id) && currentIds.slice(survivingIds.length).every((id) => !previousIdSet.has(id));
+		if (removedPrefixWasMerged && added.length === 0) return { kind: "skip" };
+		if (onlyAppendedAfterMergedPrefix) {
+			if (previous.stackNumber === void 0) 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: added.map((change) => change.remoteBranch)
+			};
+		}
+		const stackNumber = previous.stackNumber ?? options.lookups.stackNumberForPullRequest(previous.changes[0].pullRequest);
+		if (stackNumber === void 0) throw new Error("Cannot remove submitted commits because the native GitHub stack number is missing from local state");
+		if (this.changes.length === 1) return {
+			kind: "collapse",
+			stackNumber
+		};
+		return {
+			kind: "rebuild",
+			stackNumber,
+			action: added.length === 0 ? "remove" : "update"
+		};
+	}
+};
+function sameSequence(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+//#endregion
+//#region src/sync.ts
+function syncStack(dependencies, options) {
+	const { repository, github, stateStore, reporter } = dependencies;
+	reporter.progress("Checking the repository and GitHub prerequisites");
+	repository.assertReady();
+	github.assertReady();
+	const remote = repository.resolveRemote(options.remote);
+	const base = options.base ?? github.defaultBranch();
+	const userLogin = github.currentUserLogin();
+	reporter.progress(`Using ${remote} as the remote and ${base} as the stack base`);
+	reporter.progress(`Using ${userLogin} as the remote branch namespace`);
+	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 pendingStack = Stack.fromCommits(commits, userLogin);
+	if (pendingStack.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 stack = options.dryRun ? pendingStack : pendingStack.writeChangeIds(repository);
+	const { changes, rewritten } = stack;
+	if (options.dryRun) {
+		reporter.progress("Dry run complete; no commits or remote branches were changed");
+		return {
+			base,
+			remote,
+			rewritten,
+			changes: [...changes]
+		};
+	}
+	reporter.progress("Reading the previous stack state");
+	const state = stateStore.read();
+	const previous = stack.findPrevious(state);
+	const transition = stack.transitionFrom(previous, {
+		preserveHigherChanges: repository.currentBranch() === "",
+		lookups: {
+			pullRequestState: (pullRequest) => github.pullRequest(pullRequest).state,
+			stackNumberForPullRequest: (pullRequest) => github.stackNumberForPullRequest(pullRequest)
+		}
+	});
+	reporter.progress(`Pushing ${changes.length} remote branch${changes.length === 1 ? "" : "es"}`);
+	repository.pushBranches(remote, changes.map((change) => ({
+		name: change.remoteBranch,
+		oid: change.oid
+	})));
+	reporter.progress("Looking up existing pull requests");
+	const existing = changes.map((change) => github.pullRequestForBranch(change.remoteBranch));
+	let pullRequests;
+	if (changes.length === 1) {
+		if (transition.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");
+		const pullRequest = existing[0] ?? github.createPullRequest(changes[0], base, options.draft);
+		if (transition.kind === "collapse") {
+			reporter.progress(`Removing omitted pull requests from stack #${transition.stackNumber}`);
+			github.unstack(transition.stackNumber);
+			try {
+				github.editPullRequestBase(pullRequest, base);
+			} catch (error) {
+				restorePreviousStack(github, previous, base, remote, reporter, error);
+			}
+		}
+		pullRequests = [pullRequest];
+	} else {
+		if (transition.kind === "full") {
+			reporter.progress(`Linking ${changes.length} pull requests as a native GitHub stack`);
+			github.linkStack(changes.map((change) => change.remoteBranch), base, remote, options.draft);
+		} else if (transition.kind === "rebuild") {
+			reporter.progress(`Rebuilding stack #${transition.stackNumber} to ${transition.action} pull requests`);
+			github.unstack(transition.stackNumber);
+			try {
+				github.linkStack(changes.map((change) => change.remoteBranch), base, remote, options.draft);
+			} catch (error) {
+				restorePreviousStack(github, previous, base, remote, reporter, error);
+			}
+		} else if (transition.kind === "append") {
+			reporter.progress(`Appending ${transition.branches.length} pull request${transition.branches.length === 1 ? "" : "s"} to stack #${transition.stackNumber}`);
+			github.appendToStack(transition.stackNumber, transition.branches, remote, options.draft);
+		} else if (transition.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 = transition.kind === "rebuild" ? github.stackNumberForPullRequest(pullRequests[0].number) : transition.kind === "collapse" ? void 0 : previous?.stackNumber ?? (pullRequests.length > 1 ? github.stackNumberForPullRequest(pullRequests[0].number) : void 0);
+	const synchronizedChanges = changes.map((change, index) => ({
+		id: change.id,
+		remoteBranch: change.remoteBranch,
+		pullRequest: pullRequests[index].number,
+		url: pullRequests[index].url
+	}));
+	const updatedStack = {
+		remote,
+		base,
+		changes: transition.kind === "partial" && previous ? [...synchronizedChanges, ...previous.changes.slice(transition.previousOffset + changes.length)] : synchronizedChanges
+	};
+	if (stackNumber !== void 0) updatedStack.stackNumber = stackNumber;
+	writeUpdatedState(stateStore, state, previous, updatedStack);
+	reporter.progress("Saved the local stack state");
+	return {
+		base,
+		remote,
+		rewritten,
+		changes: changes.map((change, index) => ({
+			...change,
+			pullRequest: pullRequests[index]
+		}))
+	};
+}
+function restorePreviousStack(github, previous, base, remote, reporter, rebuildError) {
+	const rebuildMessage = rebuildError instanceof Error ? rebuildError.message : String(rebuildError);
+	reporter.progress("Rebuild failed; restoring the previous native GitHub stack");
+	try {
+		github.linkStack(previous.changes.map((change) => change.remoteBranch), base, remote, true);
+	} catch (rollbackError) {
+		const rollbackMessage = rollbackError instanceof Error ? rollbackError.message : String(rollbackError);
+		throw new Error(`Stack rebuild failed: ${rebuildMessage}\nRestoring the previous stack also failed: ${rollbackMessage}`);
+	}
+	throw rebuildError;
+}
+function writeUpdatedState(store, state, previous, updated) {
+	const stacks = previous ? state.stacks.map((stack) => stack === previous ? updated : stack) : [...state.stacks, updated];
+	store.write({
+		schemaVersion: 1,
+		stacks
+	});
+}
+//#endregion
+//#region src/cli.ts
+const help = `bstack - turn a linear commit series into a native GitHub stack of PRs
+
+Usage:
+  bstack [sync] [options]
+  bstack checkout <PR-number-or-URL> [options]
+
+Options:
+  --base <branch>    Stack base; defaults to the GitHub default branch
+  --remote <name>    Git remote; defaults to remote.pushDefault or origin
+  --draft            Create draft PRs instead of ready-for-review PRs
+  --dry-run          Inspect the stack without rewriting commits or pushing
+  --verbose          Show each git and gh command before it runs
+  --same-base        Refuse checkout if it would change the current merge base
+  -v, --version      Show the installed version
+  -h, --help         Show this help
+`;
+function main() {
+	const { values, positionals } = parseArgs({
+		args: process.argv.slice(2),
+		allowPositionals: true,
+		options: {
+			base: { type: "string" },
+			remote: { type: "string" },
+			draft: {
+				type: "boolean",
+				default: false
+			},
+			"dry-run": {
+				type: "boolean",
+				default: false
+			},
+			verbose: {
+				type: "boolean",
+				default: false
+			},
+			"same-base": {
+				type: "boolean",
+				default: false
+			},
+			version: {
+				type: "boolean",
+				short: "v",
+				default: false
+			},
+			help: {
+				type: "boolean",
+				short: "h",
+				default: false
+			}
+		}
+	});
+	if (values.help) {
+		process.stdout.write(help);
+		return;
+	}
+	if (values.version) {
+		console.log(version);
+		return;
+	}
+	const reporter = new ConsoleReporter();
+	const runner = new NodeCommandRunner(values.verbose ? (invocation) => reporter.command(invocation) : void 0);
+	const cwd = process.cwd();
+	const repository = new GitCliRepository(cwd, runner);
+	const github = new GitHubCliPlatform(cwd, runner);
+	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,
+			reporter
+		}, {
+			reference,
+			base: values.base,
+			remote: values.remote,
+			sameBase: values["same-base"]
+		});
+		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,
+		stateStore: new FileStateStore(repository.statePath()),
+		reporter
+	}, {
+		base: values.base,
+		remote: values.remote,
+		draft: values.draft,
+		dryRun: values["dry-run"]
+	});
+	console.log(`${values["dry-run"] ? "Would sync" : "Synced"} ${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;
+}
+//#endregion
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bstack",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "Create native GitHub stacked pull requests from a linear series of commits",
   "license": "MIT",
   "repository": {
@@ -8,10 +8,10 @@
     "url": "git+https://github.com/wsehl/bstack.git"
   },
   "bin": {
-    "bstack": "./dist/bstack.js"
+    "bstack": "./dist/bstack.mjs"
   },
   "files": [
-    "dist/bstack.js"
+    "dist/bstack.mjs"
   ],
   "type": "module",
   "publishConfig": {
@@ -24,7 +24,7 @@
     "lint": "oxlint .",
     "prepack": "pnpm run build",
     "prepublishOnly": "pnpm run type-check && pnpm test",
-    "start": "pnpm run build && node dist/bstack.js",
+    "start": "pnpm run build && node dist/bstack.mjs",
     "test": "vitest run",
     "type-check": "tsc --noEmit"
   },