@joshuafolkken/kit 1.872.0

package/scripts/propagate/propagate-git.ts

@@ -0,0 +1,224 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { git_location_environment } from '#scripts/git/git-location-environment'
+import { ls_remote_branch_arguments } from '#scripts/git/git-ls-remote'
+import { execaSync } from 'execa'
+
+// The git probes propagation needs before it writes anything into a working tree.
+//
+// Propagation commits and pushes. A consumer with uncommitted work would have that work swept into
+// the upgrade commit — `josh git` stages the whole tree — and a supplier repository that is behind
+// its remote would propagate the *previous* release, which is already published and would report
+// success (joshuafolkken/kit#863).
+
+const GIT_TIMEOUT_MS = 10_000
+// The probes that talk to the remote get their own budget. Ten seconds is generous for a local
+// `rev-parse` and tight for an ssh handshake, and a probe that times out answers "no" — which for
+// the two below would report a push that never reached origin as a push nobody attempted.
+const REMOTE_TIMEOUT_MS = 60_000
+const SUCCESS_EXIT_CODE = 0
+const DEFAULT_BRANCH_REF = 'refs/remotes/origin/HEAD'
+const FALLBACK_DEFAULT_BRANCH = 'main'
+const ORIGIN_PREFIX = 'refs/remotes/origin/'
+const PRE_PUSH_HOOK = 'pre-push'
+
+// What a repository has to be for propagation to write into it, or the reason it is not.
+interface TreeState {
+	is_ready: boolean
+	reason?: string
+}
+
+// **`cwd` alone does not say which repository this is about** (joshuafolkken/kit#1515). `GIT_DIR` and
+// `GIT_WORK_TREE` beat it outright, and git exports both to every hook it runs — so under
+// `pnpm josh git`'s pre-push hook every probe below silently answered about the checkout the hook was
+// firing in rather than the path it was handed. The visible cost was in the unit suite, where
+// `propagate-guard.test.ts` builds directories that are deliberately *not* repositories and expects
+// the tree check to refuse them: with `GIT_DIR` inherited they resolved to the real checkout instead,
+// `current_branch` succeeded, and `is_up_to_date` went out to `origin` for real — two live fetches, 4
+// seconds each against a 10-second test timeout, on the one code path that only ever runs inside a
+// hook. That is the intermittent `propagate-guard` failure listed on the issue, and it is why it never
+// reproduced outside a push.
+//
+// Clearing them is what makes `cwd` mean what it says. `-C` would work as well and is not used here,
+// because every call below already passes the path this way and a second spelling of the same intent
+// is one more thing to keep in step.
+//
+// **The list itself moved to `#scripts/git/git-location-environment`** when joshuafolkken/kit#1530
+// found the same defect in a second file: three consumers now clear the same names, and a list kept
+// in one of them is a list the other two drift away from. It widened there past `GIT_DIR` /
+// `GIT_WORK_TREE` to the index and object-store variables, which redirect a *write* rather than a
+// lookup — inert for the read-only probes below, and required by the fixture that commits.
+
+function run_git(
+	repository_path: string,
+	args: ReadonlyArray<string>,
+	timeout_ms: number = GIT_TIMEOUT_MS,
+): string | undefined {
+	const result = execaSync('git', args, {
+		cwd: repository_path,
+		reject: false,
+		timeout: timeout_ms,
+		env: { LC_ALL: 'C', LANGUAGE: 'C', ...git_location_environment.location_free_environment() },
+		extendEnv: true,
+	})
+
+	return result.exitCode === SUCCESS_EXIT_CODE ? result.stdout.trim() : undefined
+}
+
+// The repository's default branch, from the remote's own HEAD. Falls back to `main` when the ref is
+// missing, which is the case in a fresh clone that never ran `git remote set-head`.
+function default_branch(repository_path: string): string {
+	const reference = run_git(repository_path, ['symbolic-ref', DEFAULT_BRANCH_REF])
+	if (reference?.startsWith(ORIGIN_PREFIX) !== true) return FALLBACK_DEFAULT_BRANCH
+
+	return reference.slice(ORIGIN_PREFIX.length)
+}
+
+function current_branch(repository_path: string): string | undefined {
+	return run_git(repository_path, ['rev-parse', '--abbrev-ref', 'HEAD'])
+}
+
+// Whether the working tree has no changes at all — tracked or untracked. Untracked files count
+// because `josh git` stages them too, so leaving them out would let a consumer's scratch files ride
+// into the pull request.
+function is_clean(repository_path: string): boolean {
+	return run_git(repository_path, ['status', '--porcelain']) === ''
+}
+
+// Refresh the remote-tracking ref. Without this the comparison below is between two pre-merge refs
+// and passes in exactly the situation the check exists for: the seconds after a pull request merged
+// on GitHub, when the local checkout has not seen the merge commit yet.
+function fetch_branch(repository_path: string, branch: string): void {
+	run_git(repository_path, ['fetch', '--quiet', 'origin', branch])
+}
+
+// Whether the branch's tip matches its remote. Fetched first, and an unknown answer reads as *not*
+// up to date: a repository whose remote ref cannot be resolved is one this command should not start
+// committing in, and passing on the unknown is what let a stale checkout
+// propagate the previous release.
+function is_up_to_date(repository_path: string, branch: string): boolean {
+	fetch_branch(repository_path, branch)
+	const local = run_git(repository_path, ['rev-parse', branch])
+	const remote = run_git(repository_path, ['rev-parse', `origin/${branch}`])
+	if (local === undefined || remote === undefined) return false
+
+	return local === remote
+}
+
+// The commit a feature branch carries beyond the default branch, or nothing when it carries none.
+// A branch that was created but never committed to still sits on the default branch's own tip, and
+// reading that tip as a commit would report a refused push for a push nobody attempted.
+function commit_ahead(repository_path: string, default_name: string): string | undefined {
+	const head = run_git(repository_path, ['rev-parse', 'HEAD'])
+	const base = run_git(repository_path, ['rev-parse', default_name])
+
+	if (head === undefined || head === base) return undefined
+
+	return run_git(repository_path, ['rev-parse', '--short', 'HEAD'])
+}
+
+// Whether origin already carries the branch. Asked of the remote itself rather than of a
+// remote-tracking ref: a push that was refused leaves no such ref behind, and neither does a branch
+// that was never pushed at all, so the ref cannot tell the two apart.
+//
+// **The arguments come from `git-ls-remote.ts`, which anchors the pattern at `refs/heads/`**
+// (joshuafolkken/kit#1732). Built here from the bare name, the query answered for any branch whose
+// ref ends in it — so a lane pushed as `wip/1641-lane` reported `1641-lane` as already on origin,
+// and propagation classified an unpushed branch as pushed.
+function has_remote_branch(repository_path: string, branch: string): boolean {
+	const heads = run_git(repository_path, ls_remote_branch_arguments(branch), REMOTE_TIMEOUT_MS)
+
+	return heads !== undefined && heads !== ''
+}
+
+// Whether the consumer has a pre-push hook at all, honouring `core.hooksPath` — which `rev-parse
+// --git-path` does not. Without this the classification would name a hook on the strength of a dry
+// run alone, and **any** push failure that has cleared by the time the probe runs satisfies that: a
+// dropped ssh connection, a refreshed token, one 500 from GitHub. Naming a hook that does not exist
+// is the same misattribution joshuafolkken/kit#1417 was filed for, pointed the other way.
+function hooks_directory(repository_path: string): string | undefined {
+	const configured = run_git(repository_path, ['config', '--get', 'core.hooksPath'])
+	if (configured !== undefined && configured !== '') return configured
+
+	return run_git(repository_path, ['rev-parse', '--git-path', 'hooks'])
+}
+
+function has_pre_push_hook(repository_path: string): boolean {
+	const directory = hooks_directory(repository_path)
+	if (directory === undefined || directory === '') return false
+
+	return existsSync(path.resolve(repository_path, directory, PRE_PUSH_HOOK))
+}
+
+// Whether the push would go through with the consumer's own hooks out of the way. Asked *after* a
+// real push has failed, this is what separates a pre-push hook's refusal from a transport failure:
+// both leave the commit local and origin without the branch, and only this says which of the two
+// happened. `--dry-run` writes nothing, so asking costs a round trip and no more — and `--no-verify`
+// is scoped to this probe, which never pushes anything: the consumer's gate stays exactly as strong
+// as it was, and a push it refused stays refused.
+function can_push_without_hooks(repository_path: string, branch: string): boolean {
+	const args = ['push', '--dry-run', '--no-verify', 'origin', branch]
+
+	return run_git(repository_path, args, REMOTE_TIMEOUT_MS) !== undefined
+}
+
+// Decide from already-gathered facts, so the decision is testable without a repository.
+function decide_tree_state(
+	branch: string,
+	default_name: string,
+	is_tree_clean: boolean,
+	is_current: boolean,
+): TreeState {
+	if (!is_tree_clean) return { is_ready: false, reason: 'working tree has uncommitted changes' }
+
+	if (branch !== default_name) {
+		return { is_ready: false, reason: `on branch ${branch}, not ${default_name}` }
+	}
+
+	return is_current
+		? { is_ready: true }
+		: { is_ready: false, reason: `${branch} is not up to date` }
+}
+
+// Whether a repository is safe to propagate into (or from). Everything unknown reads as not ready:
+// a repository git could not describe is not one to start committing in.
+function tree_state(repository_path: string): TreeState {
+	const branch = current_branch(repository_path)
+	if (branch === undefined) return { is_ready: false, reason: 'not a readable git repository' }
+	const default_name = default_branch(repository_path)
+
+	return decide_tree_state(
+		branch,
+		default_name,
+		is_clean(repository_path),
+		is_up_to_date(repository_path, branch),
+	)
+}
+
+// Return a checkout to its default branch and pull. Run after a consumer's pull request is opened:
+// `josh git` leaves the checkout on the feature branch, and the next propagation's pre-check would
+// refuse it for exactly that — so the consumer would silently stop receiving releases.
+function return_to_default_branch(repository_path: string): boolean {
+	const branch = default_branch(repository_path)
+	if (run_git(repository_path, ['checkout', branch]) === undefined) return false
+
+	return run_git(repository_path, ['pull', '--ff-only', 'origin', branch]) !== undefined
+}
+
+const propagate_git = {
+	default_branch,
+	fetch_branch,
+	return_to_default_branch,
+	current_branch,
+	commit_ahead,
+	has_remote_branch,
+	has_pre_push_hook,
+	can_push_without_hooks,
+	is_clean,
+	is_up_to_date,
+	decide_tree_state,
+	tree_state,
+}
+
+export type { TreeState }
+export { propagate_git }

package/scripts/propagate/propagate-publish.ts

@@ -0,0 +1,181 @@
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
+import { poll } from '#scripts/lib/poll'
+import { with_page_size } from '#scripts/version/version-remote'
+import { execaSync } from 'execa'
+
+// Waiting for a specific version of this package to actually exist in the registry.
+//
+// A merge is not a publish: kit's auto-tag and publish workflows run after the merge commit lands,
+// so a consumer told to upgrade the instant the PR merged resolves the previous release. The wait is
+// implemented once here because joshuafolkken/kit#864 resolves a cross-repository child on the same
+// condition — two implementations would drift, and the looser one would decide
+// (joshuafolkken/kit#863).
+
+const VERSIONS_PAGE_SIZE = 100
+const NAMES_JQ = '[.[] | .name]'
+const DEFAULT_TIMEOUT_MS = 600_000
+const DEFAULT_INTERVAL_MS = 15_000
+const GH_TIMEOUT_MS = 20_000
+// How many probes in a row may fail before the registry is called unreadable. One failure is a rate
+// limit, a 5xx or a DNS hiccup — ending a ten-minute wait seconds in, on the first of those, is the
+// opposite of waiting. Only a registry that fails this many times running is a broken one.
+const UNREADABLE_THRESHOLD = 3
+
+// How a wait ended. `timed_out` is deliberately distinct from `published`: a publish workflow that
+// failed never produces the version, and reporting that as anything other than an anomaly would let
+// propagation continue against a release that does not exist.
+type PublishWaitState = 'published' | 'timed_out' | 'unreadable'
+
+interface PublishWaitResult {
+	state: PublishWaitState
+	version: string
+	attempts: number
+	detail?: string
+}
+
+// Whether the target version is among the versions the registry reports. Exact membership, never
+// "something newer exists": a consumer several releases behind would otherwise be satisfied by any
+// publish at all, including one that predates the change being propagated.
+function is_version_published(
+	published_versions: ReadonlyArray<string>,
+	target_version: string,
+): boolean {
+	return published_versions.includes(target_version)
+}
+
+// Whether the wait should keep going. Split out so the loop below stays a loop over a decision
+// rather than a decision spread across a loop.
+function should_keep_waiting(now_ms: number, deadline_ms: number): boolean {
+	return now_ms < deadline_ms
+}
+
+function finish(state: PublishWaitState, version: string, attempts: number): PublishWaitResult {
+	return { state, version, attempts }
+}
+
+// The versions the registry reports for this package, or nothing when it could not be read. An
+// unreadable registry is never treated as "not published yet" past the timeout — the two are
+// reported apart, because one means wait longer and the other means something is broken.
+function fetch_published_versions(versions_endpoint: string): Array<string> | undefined {
+	const endpoint = with_page_size(versions_endpoint, VERSIONS_PAGE_SIZE)
+	const result = execaSync('gh', ['api', endpoint, '--jq', NAMES_JQ], {
+		...git_gh_exec.direct_environment(),
+		reject: false,
+		timeout: GH_TIMEOUT_MS,
+	})
+	if (result.exitCode !== 0) return undefined
+
+	try {
+		const parsed: unknown = JSON.parse(result.stdout)
+
+		return Array.isArray(parsed) ? parsed.filter((name) => typeof name === 'string') : undefined
+	} catch {
+		return undefined
+	}
+}
+
+// The knobs the wait exposes. Every one of them is injectable so the unit suite can drive the loop
+// without a registry, a clock, or a real delay.
+interface WaitOptions {
+	timeout_ms?: number
+	interval_ms?: number
+	fetch_versions?: (endpoint: string) => Array<string> | undefined
+	sleep?: (milliseconds: number) => Promise<void>
+	now?: () => number
+}
+
+interface ResolvedWait {
+	timeout_ms: number
+	interval_ms: number
+	fetch_versions: (endpoint: string) => Array<string> | undefined
+	sleep: (milliseconds: number) => Promise<void>
+	now: () => number
+}
+
+const WAIT_DEFAULTS: ResolvedWait = {
+	timeout_ms: DEFAULT_TIMEOUT_MS,
+	interval_ms: DEFAULT_INTERVAL_MS,
+	fetch_versions: fetch_published_versions,
+	sleep: poll.sleep,
+	now: Date.now,
+}
+
+// Spread rather than a chain of `??`, so adding a knob does not add a branch to a function the
+// complexity limit already caps.
+function resolve_wait_options(options: WaitOptions): ResolvedWait {
+	return { ...WAIT_DEFAULTS, ...options }
+}
+
+// The outcome of one probe: found, still waiting, or the registry has now failed often enough in a
+// row to call it unreadable.
+function probe_state(
+	versions: ReadonlyArray<string> | undefined,
+	target_version: string,
+	consecutive_failures: number,
+): PublishWaitState | undefined {
+	if (versions === undefined) {
+		return consecutive_failures >= UNREADABLE_THRESHOLD ? 'unreadable' : undefined
+	}
+
+	return is_version_published(versions, target_version) ? 'published' : undefined
+}
+
+// Poll until the target version exists, the timeout elapses, or the registry proves unreadable.
+//
+// A registry that keeps failing ends the wait rather than being retried to the timeout: `gh` failing
+// is a different problem from a publish still running, and propagating on a guess is what must not
+// happen. A single failure is not that — see `UNREADABLE_THRESHOLD`. Either way the caller reports
+// it and touches no consumer.
+// What the loop carries between probes: how many it has made, and how many failed in a row.
+interface WaitProgress {
+	attempts: number
+	failures: number
+}
+
+// One probe, advancing the progress it was given. Mutating it here rather than returning a new one
+// keeps the loop above within its statement budget.
+function probe_once(
+	resolved: ResolvedWait,
+	versions_endpoint: string,
+	target_version: string,
+	progress: WaitProgress,
+): { state?: PublishWaitState } {
+	progress.attempts += 1
+	const versions = resolved.fetch_versions(versions_endpoint)
+
+	progress.failures = versions === undefined ? progress.failures + 1 : 0
+	const state = probe_state(versions, target_version, progress.failures)
+
+	return state === undefined ? {} : { state }
+}
+
+async function wait_for_publish(
+	versions_endpoint: string,
+	target_version: string,
+	options: WaitOptions = {},
+): Promise<PublishWaitResult> {
+	const resolved = resolve_wait_options(options)
+	const deadline = resolved.now() + resolved.timeout_ms
+	const progress: WaitProgress = { attempts: 0, failures: 0 }
+
+	while (should_keep_waiting(resolved.now(), deadline)) {
+		const { state } = probe_once(resolved, versions_endpoint, target_version, progress)
+
+		if (state !== undefined) return finish(state, target_version, progress.attempts)
+		await resolved.sleep(resolved.interval_ms)
+	}
+
+	return finish('timed_out', target_version, progress.attempts)
+}
+
+const propagate_publish = {
+	DEFAULT_TIMEOUT_MS,
+	DEFAULT_INTERVAL_MS,
+	UNREADABLE_THRESHOLD,
+	is_version_published,
+	should_keep_waiting,
+	fetch_published_versions,
+	wait_for_publish,
+}
+
+export { propagate_publish }

package/scripts/propagate/propagate-run.ts

@@ -0,0 +1,201 @@
+import { status_icons } from '#scripts/lib/status-icons'
+import type { PropagateTarget } from './propagate-targets'
+
+// Running the per-consumer sequence, and reporting what happened to every consumer.
+//
+// One consumer's failure never stops another: the whole point of the command is to leave the run
+// knowing which consumers took the release and which did not, and a run that aborts on the first
+// failure answers that for a prefix of them (joshuafolkken/kit#863).
+
+// The steps, in order, that carry a release into one consumer. `josh` here is the consumer's own
+// installed CLI, run from the consumer's directory — which is what keeps kit's self-sync guard
+// (joshuafolkken/kit#868) out of the way: the sync runs in a consumer project, where it belongs.
+const STEP_PRECHECK = 'working tree check'
+const STEP_UPGRADE = 'josh vu'
+const STEP_SYNC = 'josh sync'
+const STEP_VERIFY = 'verification gate'
+const STEP_ISSUE = 'open issue'
+const STEP_PR = 'josh git'
+const STEP_RETURN = 'return to default branch'
+// The precheck is first for the reason it exists: everything after it writes. A consumer with
+// uncommitted work must be refused before `josh vu` touches its lockfile, not after.
+const STEP_ORDER: ReadonlyArray<string> = [
+	STEP_PRECHECK,
+	STEP_UPGRADE,
+	STEP_SYNC,
+	STEP_VERIFY,
+	STEP_ISSUE,
+	STEP_PR,
+	STEP_RETURN,
+]
+const PROPAGATED_REASON = 'opened a pull request'
+
+type RunOutcome = 'propagated' | 'failed' | 'skipped'
+
+interface StepResult {
+	step: string
+	is_ok: boolean
+	detail?: string
+	// Set when the step succeeded *and* there is nothing left to do — an upgrade that changed no
+	// file, for instance. The sequence ends here as a skip rather than opening an empty pull request.
+	is_complete?: boolean
+	// What this failure actually left in the consumer, as the failing step measured it. Only the
+	// steps that can probe set it; for the rest the standing note below is what they always leave
+	// (joshuafolkken/kit#1417).
+	leftover?: string
+}
+
+interface TargetResult {
+	repo: string
+	outcome: RunOutcome
+	reason: string
+	steps: ReadonlyArray<StepResult>
+}
+
+// One step's execution, injected so the sequencing is testable without spawning anything.
+type RunStep = (target: PropagateTarget, step: string) => StepResult
+
+const SKIP_REASONS: Readonly<Record<string, string>> = {
+	up_to_date: 'already carries this release',
+	not_downstream: 'does not depend on this package',
+	missing_checkout: 'no local checkout at the mapped path — reported, not cloned',
+	unreadable: 'package.json could not be read',
+}
+
+// The reason text for a candidate that is not going to be processed. A missing local checkout is
+// reported rather than cloned: propagation writes to a working tree, and creating one nobody asked
+// for is not a step this command may take on its own.
+function skip_reason(target: PropagateTarget): string {
+	return SKIP_REASONS[target.state] ?? 'not eligible'
+}
+
+const LEFTOVER_NOTE = 'upgrade/sync changes left uncommitted'
+
+// Whether the failure happened after a step that writes into the consumer. The pre-check writes
+// nothing, so a consumer refused there is untouched; everything later leaves changes behind, and a
+// run that does not say so leaves a working tree the *next* run will silently refuse.
+function has_leftover_changes(steps: ReadonlyArray<StepResult>): boolean {
+	return steps.some((result) => result.step === STEP_UPGRADE)
+}
+
+// What to say the failure left behind. A step that measured it wins; the note above stands in only
+// where none did, which is every step before the commit — and there it is accurate, since nothing
+// has committed yet. Before joshuafolkken/kit#1417 it was appended to *every* failure after the
+// upgrade, including one whose commit had already been made, so a push refused by the consumer's
+// pre-push hook was reported as changes that were never committed.
+function leftover_of(result: StepResult, steps: ReadonlyArray<StepResult>): string | undefined {
+	if (!has_leftover_changes(steps)) return undefined
+
+	return result.leftover ?? LEFTOVER_NOTE
+}
+
+function failure_reason(result: StepResult, steps: ReadonlyArray<StepResult>): string {
+	const base =
+		result.detail === undefined
+			? `${result.step} failed`
+			: `${result.step} failed: ${result.detail}`
+	const leftover = leftover_of(result, steps)
+
+	return leftover === undefined ? base : `${base} — ${leftover}`
+}
+
+// Run one consumer's sequence, stopping at its first failing step. Stopping is per consumer: a
+// failed verification gate must not go on to open a pull request for that consumer, and must not
+// affect any other.
+// The result a step ends the sequence with, or nothing when the sequence continues.
+function terminal_result(
+	repo: string,
+	result: StepResult,
+	steps: ReadonlyArray<StepResult>,
+): TargetResult | undefined {
+	if (!result.is_ok) {
+		return { repo, outcome: 'failed', reason: failure_reason(result, steps), steps }
+	}
+
+	if (result.is_complete === true) {
+		return { repo, outcome: 'skipped', reason: result.detail ?? 'nothing to do', steps }
+	}
+
+	return undefined
+}
+
+function run_target(
+	target: PropagateTarget,
+	run_step: RunStep,
+	success_reason: string = PROPAGATED_REASON,
+): TargetResult {
+	const steps: Array<StepResult> = []
+
+	for (const step of STEP_ORDER) {
+		const result = run_step(target, step)
+
+		steps.push(result)
+		const terminal = terminal_result(target.repo, result, steps)
+
+		if (terminal !== undefined) return terminal
+	}
+
+	return { repo: target.repo, outcome: 'propagated', reason: success_reason, steps }
+}
+
+// Every candidate's result, in the order the map produced them. Candidates that are not ready are
+// recorded as skips rather than dropped, so the report accounts for every repository considered.
+function run_targets(
+	targets: ReadonlyArray<PropagateTarget>,
+	run_step: RunStep,
+	success_reason: string = PROPAGATED_REASON,
+): Array<TargetResult> {
+	return targets.map((target) =>
+		target.state === 'ready'
+			? run_target(target, run_step, success_reason)
+			: { repo: target.repo, outcome: 'skipped' as const, reason: skip_reason(target), steps: [] },
+	)
+}
+
+// Whether the run as a whole failed. A skip is not a failure — a consumer that already carries the
+// release, or never depended on the package, is a correct outcome.
+function has_failure(results: ReadonlyArray<TargetResult>): boolean {
+	return results.some((result) => result.outcome === 'failed')
+}
+
+const OUTCOME_ICONS: Readonly<Record<RunOutcome, string>> = {
+	propagated: '✓',
+	failed: status_icons.FAIL_ICON,
+	skipped: '–',
+}
+
+function format_result(result: TargetResult): string {
+	return `  ${OUTCOME_ICONS[result.outcome]} ${result.repo}  ${result.reason}`
+}
+
+// The whole run, as one block. Printed together at the end rather than streamed, so the answer to
+// "which consumers took this release" is in one place instead of interleaved with four commands'
+// output per consumer.
+function format_report(results: ReadonlyArray<TargetResult>): string {
+	if (results.length === 0) return 'No repositories were considered.'
+
+	return results.map((result) => format_result(result)).join('\n')
+}
+
+const propagate_run = {
+	PROPAGATED_REASON,
+	LEFTOVER_NOTE,
+	has_leftover_changes,
+	leftover_of,
+	STEP_RETURN,
+	STEP_PRECHECK,
+	STEP_ISSUE,
+	STEP_UPGRADE,
+	STEP_SYNC,
+	STEP_VERIFY,
+	STEP_PR,
+	STEP_ORDER,
+	skip_reason,
+	run_target,
+	run_targets,
+	has_failure,
+	format_report,
+}
+
+export type { RunStep, StepResult, TargetResult }
+export { propagate_run }