@joshuafolkken/kit 1.1010.0 → 1.1050.0

package/scripts/observations/observation-ledger-prepare.ts

@@ -1,29 +1,19 @@
-import { readFile } from 'node:fs/promises'
-import path from 'node:path'
-import { OBSERVATION_LEDGER_PATH } from './observation-ledger'
+import { observation_ledger_home } from './observation-ledger-home'
 import { observation_ledger_line, type BrokenLine } from './observation-ledger-line'
-import { observation_ledger_migrate } from './observation-ledger-migrate'
 
-// **What has to hold before a ledger line is committed, asked by both of the paths that commit one**
-// (joshuafolkken/kit#2763): `pnpm josh observations:flush` and the run's own commit in
-// `scripts/git/git-staging.ts`. Lines still on the old path are moved first (joshuafolkken/kit#2724),
-// so the commit carries the move and the lines together, and every entry line is then parsed against
-// the grammar (joshuafolkken/kit#2123) — each caller decides what a broken line costs it.
+// **What has to hold before a ledger line is committed, asked by every path that commits one**
+// (joshuafolkken/kit#2763): `pnpm josh observations:flush`, the run's own commit in
+// `scripts/git/git-staging.ts` and `pnpm josh followup`'s pre-merge ledger commit. Lines still on an
+// old path are moved first (joshuafolkken/kit#2724, joshuafolkken/kit#2919), so the commit carries the
+// move and the lines together, and every entry line is then parsed against the grammar
+// (joshuafolkken/kit#2123) — each caller decides what a broken line costs it.
 //
 // **A ledger that is not there has no line to break** — the change a status saw is then its deletion,
 // and a commit carries that like any other change to it.
-async function read_ledger(root: string): Promise<string> {
-	try {
-		return await readFile(path.join(root, OBSERVATION_LEDGER_PATH), 'utf8')
-	} catch {
-		return ''
-	}
-}
-
 async function prepare(root: string): Promise<ReadonlyArray<BrokenLine>> {
-	observation_ledger_migrate.migrate(root)
-
-	return observation_ledger_line.broken_ledger_lines(await read_ledger(root))
+	return observation_ledger_line.broken_ledger_lines(
+		(await observation_ledger_home.read(root)) ?? '',
+	)
 }
 
 const observation_ledger_prepare = { prepare }

package/scripts/observations/observation-ledger.ts

@@ -1,22 +1,33 @@
-// The observation ledger's one path, named here rather than inside any of the places that act on it
-// (joshuafolkken/kit#1756). `git-staging.ts` stages it with the run's own commit when its grammar
+// The observation ledger's one location, named here rather than inside any of the places that act on
+// it (joshuafolkken/kit#1756). `git-staging.ts` stages it with the run's own commit when its grammar
 // holds (joshuafolkken/kit#2763), `hook-gate-reuse.ts` excludes it from what a hook calls a carried
 // tree, and `observations-flush.ts` commits what no run carried — so a literal in each would be three
 // answers to one question, and a rename reaching only some of them would silently split them.
 //
 // **It sits under `docs/maintainers/`, apart from the reader-facing documents** (joshuafolkken/kit#2724).
-const OBSERVATION_LEDGER_PATH = 'docs/maintainers/observations.md'
-
-// Where the ledger lived before joshuafolkken/kit#2724, kept as a migration source rather than
-// forgotten: a run still on the old code, a stash cut before the move and a consumer repository's
-// existing ledger all write here, and `observation-ledger-migrate.ts` moves what it finds to the path
-// above. Every place that recognizes the ledger recognizes both, so a line on either path is never
-// staged into an ordinary commit. Remove it once every repository holding a ledger has migrated.
-const LEGACY_OBSERVATION_LEDGER_PATH = 'docs/observations.md'
-
-const OBSERVATION_LEDGER_PATHS: ReadonlyArray<string> = [
-	OBSERVATION_LEDGER_PATH,
-	LEGACY_OBSERVATION_LEDGER_PATH,
+//
+// **It is a directory of one file per issue, not one file** (joshuafolkken/kit#2919). One file every
+// run appended to made two lanes' pull requests conflict at its tail, so lanes parked their lines in
+// the primary checkout for a batch-end flush — and another run's stash took them from there, and the
+// flush never saw them. A run now appends to `<issue>.md` in its own work tree and merges it with its
+// own pull request: parallel lanes write different files, so nothing conflicts and nothing waits.
+const OBSERVATION_LEDGER_DIRECTORY = 'docs/maintainers/observations'
+
+const LEDGER_FILE_EXTENSION = '.md'
+
+// What the single-file ledgers held is moved here (`observation-ledger-migrate.ts`), so no line is
+// lost to the split.
+const LEGACY_LEDGER_FILE = `legacy${LEDGER_FILE_EXTENSION}`
+
+// Where the ledger lived as one file — `docs/observations.md` before joshuafolkken/kit#2724 and
+// `docs/maintainers/observations.md` until joshuafolkken/kit#2919 — kept as migration sources rather
+// than forgotten: a run still on the old code, a stash cut before the move and a consumer repository's
+// existing ledger all write there, and `observation-ledger-migrate.ts` moves what it finds into the
+// directory. Every place that recognizes the ledger recognizes them, so a line on either path is never
+// staged into an ordinary commit. Remove them once every repository holding a ledger has migrated.
+const LEGACY_OBSERVATION_LEDGER_PATHS: ReadonlyArray<string> = [
+	'docs/maintainers/observations.md',
+	'docs/observations.md',
 ]
 
 // `git status --porcelain` prints `XY PATH`, so the path starts at the fourth character.
@@ -26,29 +37,48 @@ function status_path(line: string): string {
 	return line.slice(STATUS_PATH_INDEX).trim()
 }
 
-// The suffix of the file a migration renames the old ledger to while it copies it
+// The ledger file one writer appends to — an issue number, or a date for a line written outside any
+// issue's run (`observation-ledger-home.ts` decides which).
+function ledger_file(name: number | string): string {
+	return `${OBSERVATION_LEDGER_DIRECTORY}/${String(name)}${LEDGER_FILE_EXTENSION}`
+}
+
+function is_ledger_file_name(name: string): boolean {
+	return name.endsWith(LEDGER_FILE_EXTENSION)
+}
+
+// The suffix of the file a migration renames an old ledger to while it copies it
 // (`observation-ledger-migrate.ts`): `docs/observations.md.<pid>.migrating`.
 const MIGRATION_CLAIM_SUFFIX = '.migrating'
 
 // A claim left by a process killed mid-migration holds ledger lines, so it is the ledger too: never
 // staged by an ordinary commit, and absorbed by the next migration.
 function is_migration_claim(file_path: string): boolean {
-	return (
-		file_path.startsWith(`${LEGACY_OBSERVATION_LEDGER_PATH}.`) &&
-		file_path.endsWith(MIGRATION_CLAIM_SUFFIX)
+	return LEGACY_OBSERVATION_LEDGER_PATHS.some(
+		(legacy) => file_path.startsWith(`${legacy}.`) && file_path.endsWith(MIGRATION_CLAIM_SUFFIX),
 	)
 }
 
+// Porcelain status collapses an untracked directory to `docs/maintainers/observations/`, so the
+// directory itself, trailing slash and all, is the ledger as much as any file inside it.
+function is_in_directory(file_path: string): boolean {
+	return file_path.startsWith(`${OBSERVATION_LEDGER_DIRECTORY}/`)
+}
+
 function is_ledger_path(file_path: string): boolean {
-	return OBSERVATION_LEDGER_PATHS.includes(file_path) || is_migration_claim(file_path)
+	return (
+		is_in_directory(file_path) ||
+		LEGACY_OBSERVATION_LEDGER_PATHS.includes(file_path) ||
+		is_migration_claim(file_path)
+	)
 }
 
 function is_ledger_line(line: string): boolean {
 	return is_ledger_path(status_path(line))
 }
 
-// The ledger paths a porcelain status names — what a flush stages after a migration, which may be the
-// new file together with the old one's deletion.
+// The ledger paths a porcelain status names — what a commit of the ledger stages, which may be a new
+// file together with an old one's deletion.
 function ledger_paths(status_output: string): ReadonlyArray<string> {
 	return status_output
 		.split('\n')
@@ -57,7 +87,7 @@ function ledger_paths(status_output: string): ReadonlyArray<string> {
 }
 
 // **The one place that answers "does this working tree hold a pending observation append?"**
-// `observations-flush.ts`'s `has_ledger_change` and `pnpm josh followup`'s pre-flush short-circuit
+// `observations-flush.ts`'s `has_ledger_change` and `pnpm josh followup`'s pre-merge ledger commit
 // both ask it (joshuafolkken/kit#1810), so a literal in each would be the clone the header above
 // warns against. A blank porcelain line carries no ledger path, so `is_ledger_line` answers false for
 // it and no filtering is needed.
@@ -67,17 +97,20 @@ function has_pending_append(status_output: string): boolean {
 
 const observation_ledger = {
 	has_pending_append,
+	is_ledger_file_name,
 	is_ledger_line,
 	is_ledger_path,
 	is_migration_claim,
+	ledger_file,
 	ledger_paths,
 	status_path,
 }
 
 export {
-	LEGACY_OBSERVATION_LEDGER_PATH,
+	LEDGER_FILE_EXTENSION,
+	LEGACY_LEDGER_FILE,
+	LEGACY_OBSERVATION_LEDGER_PATHS,
 	MIGRATION_CLAIM_SUFFIX,
-	OBSERVATION_LEDGER_PATH,
-	OBSERVATION_LEDGER_PATHS,
+	OBSERVATION_LEDGER_DIRECTORY,
 	observation_ledger,
 }

package/scripts/observations/observations-flush-cli.ts

@@ -1,38 +1,21 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { observation_ledger_home } from './observation-ledger-home'
+import { error_text } from '#scripts/lib/error-message'
 import { observations_flush } from './observations-flush'
 
 const FAILURE_EXIT_CODE = 1
 
-function message_of(error: unknown): string {
-	return error instanceof Error ? error.message : String(error)
-}
-
-// **From a lane, the flush acts on the primary checkout** (joshuafolkken/kit#2419). That is where the
-// ledger lives (`observation-ledger-home.ts`), and a lane's own checkout is never the one a flush may
-// switch — so the process moves there first, and every refusal after it is about that checkout, which
-// the prefix names so a "run `pnpm josh ms` first" is read as advice for the primary checkout.
-function enter_ledger_home(): string {
-	if (!observation_ledger_home.is_lane()) return ''
-
-	const root = observation_ledger_home.ledger_root()
-
-	process.chdir(root)
-
-	return `The observation ledger lives in the primary checkout, so this flush acts on ${root}: `
-}
-
 // The refusals are the command's whole safety story, so they are printed as the message rather than
 // as a stack: "this checkout is on a feature branch" and "the tree holds somebody else's work" are
 // both things the person fixes in one step, and a trace hides the sentence that says which.
+//
+// **It acts on the checkout it runs in** (joshuafolkken/kit#2919). A lane's ledger lines merge with
+// the lane's own pull request, so a lane has nothing to flush and is refused like any feature branch.
 async function main(): Promise<void> {
-	const prefix = enter_ledger_home()
-
 	try {
-		console.info(`${prefix}${await observations_flush.flush(new Date())}`)
+		console.info(await observations_flush.flush(new Date()))
 	} catch (error) {
-		console.error(`${prefix}${message_of(error)}`)
+		console.error(error_text.message_of(error))
 		process.exit(FAILURE_EXIT_CODE)
 	}
 }

package/scripts/observations/observations-flush-landing.ts

@@ -1,6 +1,7 @@
 import { git_gh_command } from '#scripts/git/git-gh-command'
 import type { OpenPull } from '#scripts/git/git-gh-pr-auto-merge'
 import { git_pr_checks } from '#scripts/git/git-pr-checks'
+import { error_text } from '#scripts/lib/error-message'
 
 // **A flush pull request lands whether or not the flush that opened it is still alive**
 // (joshuafolkken/kit#2497). The merge used to happen only inside the flush's own wait, so a session
@@ -25,7 +26,7 @@ async function request_auto_merge(branch_name: string): Promise<boolean> {
 
 		return true
 	} catch (error) {
-		console.warn(AUTO_MERGE_WARNING, error instanceof Error ? error.message : String(error))
+		console.warn(AUTO_MERGE_WARNING, error_text.message_of(error))
 
 		return false
 	}

package/scripts/observations/observations-flush.ts

@@ -1,15 +1,17 @@
 import { git_command } from '#scripts/git/git-command'
 import { git_gh_command } from '#scripts/git/git-gh-command'
 import { main_sync } from '#scripts/git/main-sync'
-import { observation_ledger, OBSERVATION_LEDGER_PATH } from './observation-ledger'
+import { error_text } from '#scripts/lib/error-message'
+import { observation_ledger, OBSERVATION_LEDGER_DIRECTORY } from './observation-ledger'
 import type { BrokenLine } from './observation-ledger-line'
 import { observation_ledger_prepare } from './observation-ledger-prepare'
 import { observations_flush_landing } from './observations-flush-landing'
 
-// The commit path for the ledger lines no run's own commit carried (joshuafolkken/kit#1756). A run in
-// the primary checkout commits its appended lines with its own pull request (`scripts/git/
-// git-staging.ts`, joshuafolkken/kit#2763), so what is left here is a lane's lines — they sit in the
-// primary checkout, which a lane's commit cannot see — and whatever was appended after a commit.
+// The commit path for the ledger lines no run's own commit carried (joshuafolkken/kit#1756). Every run —
+// a lane's included — commits its appended lines with its own pull request (`scripts/git/
+// git-staging.ts`, joshuafolkken/kit#2763, joshuafolkken/kit#2919), and `pnpm josh followup` commits a
+// line appended after that commit before it merges, so what is left here is a line written on the
+// default branch outside any issue's run — the date-named file `observation-ledger-home.ts` resolves.
 //
 // **The shape is `scripts/release/release-publish.ts`'s, deliberately.** Both open a pull request of
 // their own over one path, wait on the same required checks every other pull request waits on, and
@@ -19,7 +21,7 @@ import { observations_flush_landing } from './observations-flush-landing'
 // below does not survive — `observations-flush-landing.ts` carries why.
 
 const COMMIT_MESSAGE = 'Record observation ledger entries'
-const CLEAN_MESSAGE = `clean — ${OBSERVATION_LEDGER_PATH} matches the commit it sits on, so there is nothing to flush`
+const CLEAN_MESSAGE = `clean — ${OBSERVATION_LEDGER_DIRECTORY} matches the commit it sits on, so there is nothing to flush`
 const BRANCH_PREFIX = 'observations/'
 const SUCCESS_EXIT_CODE = 0
 const RETURN_FAILURE_MESSAGE =
@@ -55,7 +57,7 @@ function branch_name_for(stamp: string): string {
 // single issue, and the ledger's own lines say where each one was seen.
 function pull_request_body(): string {
 	return [
-		`Appended observations from \`${OBSERVATION_LEDGER_PATH}\` that no run's own commit carried.`,
+		`Appended observations from \`${OBSERVATION_LEDGER_DIRECTORY}\` that no run's own commit carried.`,
 		'',
 		'The ledger is append-only, and a second line under one key is what promotes an observation to an issue — so this pull request adds lines and changes none.',
 		'',
@@ -82,10 +84,6 @@ function other_changed_paths(status_output: string): ReadonlyArray<string> {
 	)
 }
 
-function message_of(error: unknown): string {
-	return error instanceof Error ? error.message : String(error)
-}
-
 // **The branch a failed flush leaves behind holds the only copy of those lines**, because the working
 // tree no longer shows them once they are committed. Sending a person to `pnpm josh ms` here — which
 // is what the ordinary off-default refusal says — would abandon them without a word, so this branch
@@ -205,7 +203,9 @@ async function catch_up_default(default_branch: string): Promise<void> {
 	try {
 		await git_command.merge_fast_forward(default_branch)
 	} catch (error) {
-		throw new Error(behind_default_message(default_branch, message_of(error)), { cause: error })
+		throw new Error(behind_default_message(default_branch, error_text.message_of(error)), {
+			cause: error,
+		})
 	}
 }
 
@@ -242,7 +242,9 @@ async function return_to_default_branch(default_branch: string): Promise<void> {
 	try {
 		await git_command.fast_forward_local(default_branch)
 	} catch (error) {
-		throw new Error(`${FAST_FORWARD_FAILURE_MESSAGE} ${message_of(error)}`, { cause: error })
+		throw new Error(`${FAST_FORWARD_FAILURE_MESSAGE} ${error_text.message_of(error)}`, {
+			cause: error,
+		})
 	}
 
 	const exit_code = await main_sync.run([])
@@ -258,7 +260,9 @@ async function push_and_open(branch_name: string): Promise<string> {
 
 		return await git_gh_command.pr_create(COMMIT_MESSAGE, pull_request_body(), 'ignore-for-release')
 	} catch (error) {
-		throw new Error(stranded_branch_message(branch_name, message_of(error)), { cause: error })
+		throw new Error(stranded_branch_message(branch_name, error_text.message_of(error)), {
+			cause: error,
+		})
 	}
 }
 
@@ -279,7 +283,7 @@ async function roll_back(branch_name: string, default_branch: string): Promise<s
 
 		return undefined
 	} catch (error) {
-		return message_of(error)
+		return error_text.message_of(error)
 	}
 }
 
@@ -315,9 +319,12 @@ async function commit_ledger(branch_name: string, default_branch: string): Promi
 	} catch (error) {
 		const roll_back_reason = await roll_back(branch_name, default_branch)
 
-		throw new Error(rejection_message(branch_name, message_of(error), roll_back_reason), {
-			cause: error,
-		})
+		throw new Error(
+			rejection_message(branch_name, error_text.message_of(error), roll_back_reason),
+			{
+				cause: error,
+			},
+		)
 	}
 }
 
@@ -345,7 +352,9 @@ async function land(
 	try {
 		await observations_flush_landing.wait_for_landing(branch_name, is_auto_merge)
 	} catch (error) {
-		throw new Error(stranded_branch_message(branch_name, message_of(error)), { cause: error })
+		throw new Error(stranded_branch_message(branch_name, error_text.message_of(error)), {
+			cause: error,
+		})
 	}
 
 	await return_to_default_branch(default_branch)
@@ -366,7 +375,7 @@ function merged_message(branch_name: string): string {
 function broken_lines_message(broken: ReadonlyArray<BrokenLine>): string {
 	const rows = broken.map((entry) => `  ${entry.line}\n    ↳ ${entry.reason}`).join('\n')
 
-	return `\`${OBSERVATION_LEDGER_PATH}\` has ${String(broken.length)} line(s) that break the ledger grammar, so \`pnpm josh observations:flush\` stops rather than committing them:\n${rows}`
+	return `\`${OBSERVATION_LEDGER_DIRECTORY}\` has ${String(broken.length)} line(s) that break the ledger grammar, so the ledger commit stops rather than carrying them:\n${rows}`
 }
 
 // **A malformed line is refused before a branch is cut, not after.** The ledger path was collected

package/scripts/package/package-scout-cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { z } from 'zod'
 import {
 	package_scout,
@@ -120,27 +120,19 @@ function parse_size(raw: string | undefined): number {
 	return raw === undefined || !Number.isSafeInteger(parsed) || parsed <= 0 ? DEFAULT_SIZE : parsed
 }
 
-function parse_arguments(argv: ReadonlyArray<string>): ScoutArguments | undefined {
-	const { values, positionals } = parseArgs({
+// An unknown flag is `undefined` rather than a throw, so the answer is the usage line rather than a
+// stack trace, on a command whose output a workflow reads.
+function read_arguments(argv: ReadonlyArray<string>): ScoutArguments | undefined {
+	const parsed = cli_flags.parse_or_undefined({
 		args: [...argv],
 		options: { size: { type: 'string' } },
 		allowPositionals: true,
 	})
-	const keywords = positionals.join(' ').trim()
-
-	if (keywords === '') return undefined
+	const keywords = parsed?.positionals.join(' ').trim() ?? ''
 
-	return { keywords, size: parse_size(values.size) }
-}
+	if (parsed === undefined || keywords === '') return undefined
 
-// An unknown flag makes `parseArgs` throw. Caught so the answer is the usage line rather than a stack
-// trace, on a command whose output a workflow reads.
-function read_arguments(argv: ReadonlyArray<string>): ScoutArguments | undefined {
-	try {
-		return parse_arguments(argv)
-	} catch {
-		return undefined
-	}
+	return { keywords, size: parse_size(parsed.values.size) }
 }
 
 async function report(args: ScoutArguments): Promise<number> {

package/scripts/ports/port-command.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { ports, type PortEnvironment } from '#ports'
+import { error_text } from '#scripts/lib/error-message'
 
 const SUCCESS_EXIT_CODE = 0
 const USAGE_EXIT_CODE = 1
@@ -49,7 +50,7 @@ function run(argv: ReadonlyArray<string>, environment?: PortEnvironment): PortRe
 		return { text: String(RESOLVERS[name](environment)), exit_code: SUCCESS_EXIT_CODE }
 	} catch (error) {
 		return {
-			text: error instanceof Error ? error.message : String(error),
+			text: error_text.message_of(error),
 			exit_code: FAILURE_EXIT_CODE,
 		}
 	}

package/scripts/propagate/propagate-plan.ts

@@ -0,0 +1,185 @@
+import { adopt_toolkits } from '#scripts/adopt/adopt-toolkits'
+import { propagate_run, type RunStep, type StepResult } from './propagate-run'
+import { propagate_steps, type Release, type ReleasePlan } from './propagate-steps'
+import { propagate_targets, type Manifest, type PropagateTarget } from './propagate-targets'
+
+// What one `josh propagate` run carries, decided from the repository it runs in (joshuafolkken/kit#2879).
+//
+// The supplier is kit or any toolkit built on it — app-kit, game-kit — and a toolkit's propagation
+// carries the base packages under it too, at the versions that toolkit itself has installed and was
+// verified with rather than at the base's newest. Each consumer is delivered by the topmost toolkit
+// it installs: a lower supplier skips it, because syncing only the base would write the overlay's
+// paths back to the base's originals (`docs/sync.md` → base first, overlay after), and would hand the
+// consumer a base the toolkit above it never verified. Discovery, ordering and the CLI name are
+// `josh adopt`'s own reads (`scripts/adopt/adopt-toolkits.ts`), not a second copy of them.
+
+const REFUSAL_PREFIX = 'Refusing to propagate:'
+const SUPPLIER_REFUSAL = [
+	`${REFUSAL_PREFIX} this is not a ${adopt_toolkits.TOOLKIT_SCOPE} toolkit's own repository.`,
+	'Propagation carries a published release outward, so it runs from the toolkit that published it',
+	'— kit, or a toolkit built on it that ships a CLI. Run it from that checkout instead.',
+].join('\n')
+const UNRESOLVED_CAUSE =
+	'declared here but not installed with a runnable CLI, so the consumers would receive this toolkit without it. Run `pnpm install`.'
+const MISPLACED_CAUSE =
+	'declared under `dependencies`, which leaves it out of the plan. Move it to `devDependencies`.'
+const ARROW = ' → '
+const LIST_SEPARATOR = ', '
+
+interface Supplier {
+	package_name: string
+	bin_name: string
+}
+
+interface SupplierResolution {
+	supplier?: Supplier
+	refusal?: string
+}
+
+interface BaseResolution {
+	bases?: Array<Release>
+	cause?: string
+}
+
+interface PlanResolution {
+	plan?: ReleasePlan
+	refusal?: string
+}
+
+// A toolkit is a scoped package that ships a CLI — the same reading `josh adopt` applies to an
+// installed one, applied here to the repository's own manifest.
+function toolkit_name(manifest: Manifest): string | undefined {
+	const { name } = manifest
+
+	return name !== undefined && adopt_toolkits.is_toolkit_package(name) ? name : undefined
+}
+
+function supplier_of(manifest: Manifest | undefined): Supplier | undefined {
+	const package_name = manifest === undefined ? undefined : toolkit_name(manifest)
+	if (manifest === undefined || package_name === undefined) return undefined
+	const bin_name = adopt_toolkits.bin_name_of(package_name, manifest)
+
+	return bin_name === undefined ? undefined : { package_name, bin_name }
+}
+
+function resolve_supplier(project_root: string): SupplierResolution {
+	const supplier = supplier_of(propagate_targets.read_manifest(project_root))
+
+	return supplier === undefined ? { refusal: SUPPLIER_REFUSAL } : { supplier }
+}
+
+// A base toolkit pinned to the version installed in the supplier's own checkout — the one the
+// supplier's verification gate ran against.
+function pin_installed(project_root: string, release: Release): Release | undefined {
+	const version = propagate_targets.installed_version(project_root, release.package_name)
+
+	return version === undefined ? undefined : { ...release, version }
+}
+
+// Why a declared base toolkit would fall out of the plan, naming it — either way `josh adopt` refuses
+// one for (joshuafolkken/kit#1540). A base left out is not merely left behind: every consumer that
+// installs it would then read it as a toolkit above this one and be skipped.
+function incomplete_cause(project_root: string): string | undefined {
+	const misplaced = adopt_toolkits.misplaced_toolkits(project_root)
+	if (misplaced.length > 0) return `${misplaced.join(LIST_SEPARATOR)} — ${MISPLACED_CAUSE}`
+	const unresolved = adopt_toolkits.unresolved_toolkits(project_root)
+
+	return unresolved.length === 0
+		? undefined
+		: `${unresolved.join(LIST_SEPARATOR)} — ${UNRESOLVED_CAUSE}`
+}
+
+// The supplier's base toolkits, base first, or the names that cannot be carried.
+function base_releases(project_root: string, supplier: Supplier): BaseResolution {
+	const cause = incomplete_cause(project_root)
+	if (cause !== undefined) return { cause }
+
+	const bases = adopt_toolkits
+		.discover_toolkits(project_root)
+		.filter((release) => release.package_name !== supplier.package_name)
+		.map((release) => pin_installed(project_root, release))
+
+	return bases.every((release) => release !== undefined) ? { bases } : { cause: UNRESOLVED_CAUSE }
+}
+
+// The releases one run carries: the base toolkits first, then the supplier at its own version, so the
+// sync runs base first and the supplier's overlay is written last.
+function build_plan(project_root: string, version: string): PlanResolution {
+	const { supplier, refusal } = resolve_supplier(project_root)
+	if (supplier === undefined) return { refusal: refusal ?? SUPPLIER_REFUSAL }
+	const { bases, cause } = base_releases(project_root, supplier)
+	if (bases === undefined) return { refusal: `${REFUSAL_PREFIX} ${cause ?? UNRESOLVED_CAUSE}` }
+	const releases = [...bases, { ...supplier, version }]
+
+	return { plan: { releases, origin: propagate_steps.PROPAGATE_ORIGIN } }
+}
+
+// The package the run publishes and waits for — by construction the plan's last release.
+function supplier_name(plan: ReleasePlan): string {
+	return plan.releases.at(-1)?.package_name ?? ''
+}
+
+// A declared scoped package counts as a toolkit unless it is demonstrably a library: installed, and
+// shipping no CLI. One that is not installed yet cannot be told apart, and treating it as a toolkit
+// errs toward leaving the consumer to the propagation above rather than reverting its overlay.
+function may_be_toolkit(repository_path: string, package_name: string): boolean {
+	if (adopt_toolkits.read_bin_name(repository_path, package_name) !== undefined) return true
+
+	return adopt_toolkits.is_unreachable_toolkit(repository_path, package_name)
+}
+
+function carriers_of(target: PropagateTarget, plan: ReleasePlan): Array<string> {
+	const carried = new Set(plan.releases.map((release) => release.package_name))
+
+	return adopt_toolkits
+		.all_declared_toolkits(target.path)
+		.filter((name) => !carried.has(name) && may_be_toolkit(target.path, name))
+}
+
+// A consumer that installs a toolkit this run does not carry is left to that toolkit's propagation.
+// Only a candidate that would otherwise be processed or reported current is re-classified.
+function mark_carried(target: PropagateTarget, plan: ReleasePlan): PropagateTarget {
+	if (target.state !== 'ready' && target.state !== 'up_to_date') return target
+	const carriers = carriers_of(target, plan)
+
+	return carriers.length === 0 ? target : { ...target, state: 'carried_above', carriers }
+}
+
+// What the dry run prints for the two steps that repeat per release: the versions each package is
+// pinned to, and the sync order.
+function plan_details(plan: ReleasePlan): Readonly<Record<string, string>> {
+	return {
+		[propagate_run.STEP_UPGRADE]: plan.releases
+			.map((release) => `${release.package_name}@${release.version}`)
+			.join(LIST_SEPARATOR),
+		[propagate_run.STEP_SYNC]: propagate_steps
+			.sync_commands(plan)
+			.map(({ command }) => command.join(' '))
+			.join(ARROW),
+	}
+}
+
+// The dry-run runner: it reports what each step would do and touches nothing.
+function create_step_describer(plan: ReleasePlan): RunStep {
+	const details = plan_details(plan)
+
+	return (target: PropagateTarget, step: string): StepResult => {
+		const detail = details[step]
+		const suffix = detail === undefined ? '' : `: ${detail}`
+
+		console.info(`  ${target.repo}: would run ${step}${suffix}`)
+
+		return { step, is_ok: true }
+	}
+}
+
+const propagate_plan = {
+	resolve_supplier,
+	build_plan,
+	supplier_name,
+	mark_carried,
+	create_step_describer,
+}
+
+export type { Supplier }
+export { propagate_plan }

package/scripts/propagate/propagate-publish.ts

@@ -1,7 +1,6 @@
 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.
 //
@@ -58,15 +57,15 @@ function finish(state: PublishWaitState, version: string, attempts: number): Pub
 // 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,
+	const stdout = git_gh_exec.read_gh_api_sync({
+		path: endpoint,
+		jq_filter: NAMES_JQ,
+		timeout_ms: GH_TIMEOUT_MS,
 	})
-	if (result.exitCode !== 0) return undefined
+	if (stdout === undefined) return undefined
 
 	try {
-		const parsed: unknown = JSON.parse(result.stdout)
+		const parsed: unknown = JSON.parse(stdout)
 
 		return Array.isArray(parsed) ? parsed.filter((name) => typeof name === 'string') : undefined
 	} catch {