@joshuafolkken/kit 1.1178.0 → 1.1240.0

package/scripts/notify/telegram-test.ts

@@ -6,13 +6,19 @@ import { git_gh_repo } from '#scripts/gh/git-gh-repo'
 import { github_issue_url, type IssueUrlTarget } from '#scripts/gh/github-issue-url'
 import { git_error } from '#scripts/git/git-error'
 import { josh_environment_file } from '#scripts/josh/josh-environment-file'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { telegram_notify } from './telegram-notify'
 import { telegram_test_logic, type CliValues, type ResolvedContext } from './telegram-test-logic'
 
 const REPO_NAME_SEPARATOR = '/'
+const ARGV_OFFSET = 2
+
+// The free-text values a caller writes, often opening with a Markdown `-` bullet.
+const FREE_TEXT_FLAGS = ['--body', '--issue-title']
 
 function parse_cli_arguments(): CliValues {
 	const { values } = parseArgs({
+		args: [...cli_flags.attach_values(process.argv.slice(ARGV_OFFSET), FREE_TEXT_FLAGS)],
 		options: {
 			'task-type': { type: 'string' },
 			'repo-name': { type: 'string' },

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

@@ -34,16 +34,16 @@ function slug_of(first_field: string): string {
 
 // The `?? ''` lives in these small helpers rather than in `field_reason`, so that function stays a
 // single lookup with no branching of its own.
-function is_present(field: string | undefined): boolean {
-	return (field ?? '').trim().length > 0
+function is_present(field: string | undefined = ''): boolean {
+	return field.trim().length > 0
 }
 
-function matches(pattern: RegExp, field: string | undefined): boolean {
-	return pattern.test(field ?? '')
+function matches(pattern: RegExp, field: string | undefined = ''): boolean {
+	return pattern.test(field)
 }
 
-function slug_ok(key_field: string | undefined): boolean {
-	return SLUG_PATTERN.test(slug_of(key_field ?? ''))
+function slug_ok(key_field: string | undefined = ''): boolean {
+	return SLUG_PATTERN.test(slug_of(key_field))
 }
 
 // Each field's check paired with the reason it fails, so `field_reason` is a single lookup for the

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

@@ -1,8 +1,18 @@
-import { appendFileSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync } from 'node:fs'
+import {
+	appendFileSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	rmdirSync,
+	rmSync,
+} from 'node:fs'
 import path from 'node:path'
 import { file_reader } from '#scripts/lib/read-file'
 import {
+	LEDGER_FILE_EXTENSION,
 	LEGACY_LEDGER_FILE,
+	LEGACY_OBSERVATION_LEDGER_DIRECTORY,
 	LEGACY_OBSERVATION_LEDGER_PATHS,
 	MIGRATION_CLAIM_SUFFIX,
 	OBSERVATION_LEDGER_DIRECTORY,
@@ -136,14 +146,55 @@ function migrate_one(legacy: string, target: string): boolean {
 	return true
 }
 
+// The ledger file a name in the old directory belongs to — a claim `<name>.md.<pid>.migrating` left by
+// a killed process included, whose `<name>.md` may already be gone.
+function source_name(name: string): string | undefined {
+	const end = name.indexOf(LEDGER_FILE_EXTENSION)
+
+	return end === -1 ? undefined : name.slice(0, end + LEDGER_FILE_EXTENSION.length)
+}
+
+function legacy_directory_names(directory: string): ReadonlyArray<string> {
+	try {
+		const names = readdirSync(directory).map((name) => source_name(name))
+
+		return [...new Set(names.filter((name) => name !== undefined))]
+	} catch {
+		return []
+	}
+}
+
+// **The old directory moves file by file into the same names** (joshuafolkken/kit#3341), so an
+// issue's lines stay in that issue's file; the emptied directory is removed when nothing else is left.
+function migrate_directory(root: string): boolean {
+	const legacy_directory = path.join(root, LEGACY_OBSERVATION_LEDGER_DIRECTORY)
+	const did_move = legacy_directory_names(legacy_directory)
+		.map((name) =>
+			migrate_one(
+				path.join(legacy_directory, name),
+				path.join(root, OBSERVATION_LEDGER_DIRECTORY, name),
+			),
+		)
+		.some(Boolean)
+
+	try {
+		rmdirSync(legacy_directory)
+	} catch {
+		// Absent, or still holding something that is not the ledger's — left where it is.
+	}
+
+	return did_move
+}
+
 // Returns whether anything was moved. `root` is the checkout the ledger lives in. Every old path is
 // tried — `map` before `some`, so one that moved does not leave the next one where it was.
 function migrate(root: string): boolean {
 	const target = path.join(root, OBSERVATION_LEDGER_DIRECTORY, LEGACY_LEDGER_FILE)
-
-	return LEGACY_OBSERVATION_LEDGER_PATHS.map((legacy) =>
+	const moved_files = LEGACY_OBSERVATION_LEDGER_PATHS.map((legacy) =>
 		migrate_one(path.join(root, legacy), target),
-	).some(Boolean)
+	)
+
+	return [...moved_files, migrate_directory(root)].some(Boolean)
 }
 
 const observation_ledger_migrate = { migrate }

package/scripts/observations/observation-ledger.ts

@@ -4,14 +4,24 @@
 // 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).
+// **It sits outside `docs/`** (joshuafolkken/kit#3341): its files are machine-written data lines, not
+// documents a person reads, and at about forty new files a day they were most of `docs/`.
 //
 // **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 OBSERVATION_LEDGER_DIRECTORY = '.josh/observations'
+
+// Where the directory lived until joshuafolkken/kit#3341, a migration source for the same reasons as
+// the single-file ledgers below: each `<name>.md` in it moves to the same name in the directory.
+const LEGACY_OBSERVATION_LEDGER_DIRECTORY = 'docs/maintainers/observations'
+
+const LEDGER_DIRECTORIES: ReadonlyArray<string> = [
+	OBSERVATION_LEDGER_DIRECTORY,
+	LEGACY_OBSERVATION_LEDGER_DIRECTORY,
+]
 
 const LEDGER_FILE_EXTENSION = '.md'
 
@@ -51,18 +61,25 @@ function is_ledger_file_name(name: string): boolean {
 // (`observation-ledger-migrate.ts`): `docs/observations.md.<pid>.migrating`.
 const MIGRATION_CLAIM_SUFFIX = '.migrating'
 
+function is_legacy_directory_file(file_path: string): boolean {
+	return file_path.startsWith(`${LEGACY_OBSERVATION_LEDGER_DIRECTORY}/`)
+}
+
 // 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 LEGACY_OBSERVATION_LEDGER_PATHS.some(
-		(legacy) => file_path.startsWith(`${legacy}.`) && file_path.endsWith(MIGRATION_CLAIM_SUFFIX),
+	if (!file_path.endsWith(MIGRATION_CLAIM_SUFFIX)) return false
+
+	return (
+		is_legacy_directory_file(file_path) ||
+		LEGACY_OBSERVATION_LEDGER_PATHS.some((legacy) => file_path.startsWith(`${legacy}.`))
 	)
 }
 
-// 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.
+// Porcelain status collapses an untracked directory to `.josh/observations/`, so the directory
+// itself, trailing slash and all, is the ledger as much as any file inside it — the old directory too.
 function is_in_directory(file_path: string): boolean {
-	return file_path.startsWith(`${OBSERVATION_LEDGER_DIRECTORY}/`)
+	return LEDGER_DIRECTORIES.some((directory) => file_path.startsWith(`${directory}/`))
 }
 
 function is_ledger_path(file_path: string): boolean {
@@ -107,8 +124,10 @@ const observation_ledger = {
 }
 
 export {
+	LEDGER_DIRECTORIES,
 	LEDGER_FILE_EXTENSION,
 	LEGACY_LEDGER_FILE,
+	LEGACY_OBSERVATION_LEDGER_DIRECTORY,
 	LEGACY_OBSERVATION_LEDGER_PATHS,
 	MIGRATION_CLAIM_SUFFIX,
 	OBSERVATION_LEDGER_DIRECTORY,

package/scripts/overrides/lockfile-overrides.ts

@@ -1,6 +1,6 @@
 import { yaml_document } from '#scripts/lib/yaml-document'
 import { overrides_check } from './overrides-logic'
-import { lockfile_importers_schema, type LockfileImporter } from './schemas'
+import { lockfile_importers_schema, type LockfileImporter } from './overrides-schemas'
 
 // The importer sections whose entries pnpm rewrites through `overrides` before resolving.
 const DEPENDENCY_GROUPS = ['dependencies', 'devDependencies', 'optionalDependencies'] as const

package/scripts/overrides/overrides-logic.ts

@@ -3,7 +3,7 @@ import {
 	package_pnpm_schema,
 	package_with_deps_schema,
 	workspace_overrides_schema,
-} from './schemas'
+} from './overrides-schemas'
 
 interface AddedEntry {
 	key: string

package/scripts/propagate/propagate-git.ts

@@ -3,6 +3,7 @@ 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 { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { GIT_TIMEOUT_MS } from '#scripts/lib/timeouts'
 
 // The git probes propagation needs before it writes anything into a working tree.
 //
@@ -11,7 +12,6 @@ import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
 // 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.

package/scripts/propagate/propagate-publish.ts

@@ -1,5 +1,6 @@
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { poll } from '#scripts/lib/poll'
+import { GH_API_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { with_page_size } from '#scripts/version/version-remote'
 
 // Waiting for a specific version of this package to actually exist in the registry.
@@ -14,7 +15,6 @@ 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.
@@ -60,7 +60,7 @@ function fetch_published_versions(versions_endpoint: string): Array<string> | un
 	const stdout = git_gh_exec.read_gh_api_sync({
 		path: endpoint,
 		jq_filter: NAMES_JQ,
-		timeout_ms: GH_TIMEOUT_MS,
+		timeout_ms: GH_API_TIMEOUT_MS,
 	})
 	if (stdout === undefined) return undefined
 

package/scripts/propagate/propagate-steps.ts

@@ -4,7 +4,8 @@ import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
 import { OTHER_CHANGE_LABEL } from '#scripts/issue/issue-labels'
 import { GATE_COMMAND } from '#scripts/josh/josh-command-types'
 import { error_text } from '#scripts/lib/error-message'
-import { build_upgrade_shell_command } from '#scripts/version/upgrade-shell-command'
+import { SUITE_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { build_upgrade_command } from '#scripts/version/upgrade-shell-command'
 import { create_version_command_config } from '#scripts/version/version-command-config'
 import { execaSync } from 'execa'
 import { propagate_git } from './propagate-git'
@@ -20,9 +21,6 @@ import type { PropagateTarget } from './propagate-targets'
 // and the sequencing stays testable (joshuafolkken/kit#863).
 
 const SUCCESS_EXIT_CODE = 0
-// Long enough for a consumer's full unit suite and a `pnpm add`, short enough that a hung step ends
-// the run instead of holding the whole propagation open.
-const STEP_TIMEOUT_MS = 1_800_000
 // The consumer-side gate. `josh gate` is the same command the AI documents require of a person
 // (joshuafolkken/kit#914) — running the four checks concurrently and reporting every failure in one
 // pass — so the chain is not repeated here. It resolves in the consumer's directory, which by this
@@ -54,11 +52,15 @@ function sync_command(bin_name: string): ReadonlyArray<string> {
 // which would defeat the exact-version wait: a release published while the run was in flight would
 // be the one every consumer received. `josh adopt` names `latest` deliberately, because it is pulling
 // whatever is newest inward rather than carrying one known release outward. Built through kit's own
-// upgrade-command builder either way, so the lockfile repair it chains stays single-sourced.
-function upgrade_command(package_name: string, version: string): ReadonlyArray<string> {
+// upgrade-command builder either way, so the lockfile repair it chains stays single-sourced — and
+// its steps are argument vectors, so the version never passes through a shell.
+function upgrade_command(
+	package_name: string,
+	version: string,
+): ReadonlyArray<ReadonlyArray<string>> {
 	const config = create_version_command_config({ package_name })
 
-	return ['sh', '-c', build_upgrade_shell_command(version, true, config)]
+	return build_upgrade_command(version, true, config).steps
 }
 
 const PROPAGATE_ORIGIN =
@@ -149,8 +151,8 @@ const NO_COMMAND = 'no command defined'
 // tail would throw on its first `replaceAll`, and nothing between here and the report catches it:
 // the throw escapes the whole run, so every consumer after this one goes unattempted and the
 // end-of-run block is never printed — "one consumer's failure never stops another", lost to a crash.
-function captured(text: string | undefined): string {
-	return text ?? ''
+function captured(text: string | undefined = ''): string {
+	return text
 }
 
 function step_result(step: string, exit_code: number | undefined): StepResult {
@@ -172,7 +174,7 @@ function spawn_step(
 		cwd: target.path,
 		reject: false,
 		stdio: 'inherit',
-		timeout: STEP_TIMEOUT_MS,
+		timeout: SUITE_TIMEOUT_MS,
 	})
 
 	return step_result(step, spawned.exitCode)
@@ -207,7 +209,7 @@ function spawn_captured(
 		stdin: 'inherit',
 		stdout: ['inherit', 'pipe'],
 		stderr: ['inherit', 'pipe'],
-		timeout: STEP_TIMEOUT_MS,
+		timeout: SUITE_TIMEOUT_MS,
 	})
 
 	return {
@@ -383,11 +385,14 @@ function run_each(
 	return { step, is_ok: true }
 }
 
+// One entry per step, so `run_each` stops a toolkit's lockfile repair after its failed install.
 function upgrade_commands(plan: ReleasePlan): ReadonlyArray<ToolkitCommand> {
-	return plan.releases.map((release) => ({
-		package_name: release.package_name,
-		command: upgrade_command(release.package_name, release.version),
-	}))
+	return plan.releases.flatMap((release) =>
+		upgrade_command(release.package_name, release.version).map((command) => ({
+			package_name: release.package_name,
+			command,
+		})),
+	)
 }
 
 function sync_commands(plan: ReleasePlan): ReadonlyArray<ToolkitCommand> {

package/scripts/propagate/propagate.ts

@@ -24,8 +24,7 @@ const SKIP_PUBLISH_FLAG = '--skip-publish-wait'
 const DRY_RUN_FLAG = '--dry-run'
 const TARGET_FLAG = '--target'
 const KNOWN_FLAGS: ReadonlyArray<string> = [SKIP_PUBLISH_FLAG, DRY_RUN_FLAG]
-// Shown in the usage line only. `--target` carries a value, so it is taken out of argv before the
-// flag-only refusal runs, and this entry never has to match an argument.
+// Shown in the usage line only: `--target` carries a value, so it is spelled with a placeholder.
 const TARGET_USAGE = `${TARGET_FLAG} <repo>`
 const DRY_RUN_REASON = 'would be propagated'
 const UNTOUCHED_NOTE = 'No consumer was touched.'
@@ -40,41 +39,51 @@ interface RunOptions {
 	usage?: string
 }
 
-interface TargetArgument {
-	rest: Array<string>
-	target?: string
-	usage?: string
+// `--target` is read as a list so a second one is seen and refused rather than letting one of the two
+// names win silently.
+const OPTIONS = {
+	'skip-publish-wait': { type: 'boolean' },
+	'dry-run': { type: 'boolean' },
+	target: { type: 'string', multiple: true },
+} as const
+const USAGE = `Usage: josh propagate [${[...KNOWN_FLAGS, TARGET_USAGE].join('] [')}]`
+const TARGET_MISSING = `${TARGET_FLAG} needs a repository name, e.g. ${TARGET_FLAG} app-kit`
+
+type ParsedValues = NonNullable<ReturnType<typeof cli_flags.values_of<typeof OPTIONS>>>
+
+function refused(usage: string): RunOptions {
+	return { is_dry_run: false, is_publish_wait_skipped: false, usage }
 }
 
-// Take `--target <repo>` out of argv. A second `--target` stays in `rest`, where the flag-only
-// refusal rejects it rather than letting one of the two names win silently.
-function split_target(argv: ReadonlyArray<string>): TargetArgument {
-	const index = argv.indexOf(TARGET_FLAG)
-	if (index === -1) return { rest: [...argv] }
-	const target = argv[index + 1]
-	const rest = argv.filter((_, position) => position !== index && position !== index + 1)
+function to_options(values: ParsedValues): RunOptions {
+	const [target] = values.target ?? []
 
-	if (target === undefined || target.startsWith('-')) {
-		return { rest, usage: `${TARGET_FLAG} needs a repository name, e.g. ${TARGET_FLAG} app-kit` }
+	return {
+		is_dry_run: values['dry-run'] ?? false,
+		is_publish_wait_skipped: values['skip-publish-wait'] ?? false,
+		...(target !== undefined && { target }),
 	}
-
-	return { rest, target }
 }
 
 // Reject anything not on the list rather than ignoring it. `--dryrun` silently falling through to
-// the real write path is the mistake this refusal exists to prevent.
+// the real write path is the mistake this refusal exists to prevent. A `--target` with no usable name
+// after it — last on the line, or followed by `--dry-run` — is named on its own, so the caller learns
+// which value is missing rather than reading the generic usage.
+function read_values(argv: ReadonlyArray<string>): ParsedValues | undefined {
+	const values = cli_flags.values_of(argv, OPTIONS)
+
+	return (values?.target?.length ?? 0) > 1 ? undefined : values
+}
+
 function parse_options(argv: ReadonlyArray<string>): RunOptions {
-	const { rest, target, usage: target_usage } = split_target(argv)
-	const options: RunOptions = {
-		is_dry_run: rest.includes(DRY_RUN_FLAG),
-		is_publish_wait_skipped: rest.includes(SKIP_PUBLISH_FLAG),
-		...(target !== undefined && { target }),
+	if (cli_flags.is_value_unusable(argv, TARGET_FLAG)) return refused(TARGET_MISSING)
+	const values = read_values(argv)
+
+	if (values === undefined) {
+		return refused(`Unknown argument(s) or a repeated ${TARGET_FLAG}: ${argv.join(' ')}\n${USAGE}`)
 	}
-	const usage =
-		target_usage ??
-		cli_flags.refuse_unknown_flags(rest, [...KNOWN_FLAGS, TARGET_USAGE], 'propagate')
 
-	return usage === undefined ? options : { ...options, usage }
+	return to_options(values)
 }
 
 // Propagation runs from the supplier's own repository, and only there — kit's, or a toolkit's built

package/scripts/refactor/import-graph.ts

@@ -28,7 +28,7 @@ type FileGraph = ReadonlyMap<string, ReadonlySet<string>>
 function specifiers_of(source: string, pattern: RegExp): ReadonlyArray<string> {
 	const matches = [...source.matchAll(pattern)]
 
-	return matches.flatMap((match) => (match[1] === undefined ? [] : [match[1]]))
+	return matches.flatMap((match) => match[1] ?? [])
 }
 
 function parse_imports(source: string): ReadonlyArray<string> {
@@ -157,6 +157,22 @@ function expand(
 	return included
 }
 
+// Every file `entry` reaches through its own imports, `entry` included, with no stage cap — the whole
+// transitive closure a running script loads, not the §4.3 neighborhood `expand` bounds.
+function reachable(entry: string, forward: FileGraph): ReadonlySet<string> {
+	const included = new Set<string>([entry])
+	const pending = [entry]
+
+	for (let file = pending.pop(); file !== undefined; file = pending.pop()) {
+		const fresh = [...(forward.get(file) ?? [])].filter((target) => !included.has(target))
+
+		for (const target of fresh) included.add(target)
+		pending.push(...fresh)
+	}
+
+	return included
+}
+
 // The whole §4.3 walk: build the graph over the universe, then expand the seed within it.
 function expand_scope(
 	seed: ReadonlyArray<string>,
@@ -174,6 +190,7 @@ const import_graph = {
 	expand_scope,
 	invert,
 	parse_imports,
+	reachable,
 	resolve_spec,
 	MAX_STAGES,
 }

package/scripts/refactor/refactor-lint.ts

@@ -1,5 +1,6 @@
 import path from 'node:path'
 import { find_local_bin_upwards } from '#scripts/build/local-bin'
+import { LINT_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 import { z } from 'zod'
 
@@ -20,7 +21,6 @@ const PNPM_EXEC = 'exec'
 // `--no-inline-config` so a `/* eslint-disable */` in a file cannot hide a candidate from the scan the
 // way it can from the gate; the scan reports what the rules say, not what a file asked to suppress.
 const FORMAT_FLAGS: ReadonlyArray<string> = ['--format', 'json', '--no-inline-config']
-const PROCESS_TIMEOUT_MS = 180_000
 
 type Priority = 'high' | 'medium' | 'low'
 const HIGH: Priority = 'high'
@@ -188,9 +188,9 @@ function eslint_command(root: string, files: ReadonlyArray<string>): ReadonlyArr
 // `undefined` means the run did not produce parseable eslint JSON — a failure, kept distinct from a
 // valid empty array (a clean scope), so a scan that could not run is never reported as `clear`
 // (joshuafolkken/kit#2180).
-function parse_results(raw: string | undefined): Array<LintResult> | undefined {
+function parse_results(raw: string | undefined = 'null'): Array<LintResult> | undefined {
 	try {
-		const parsed = results_schema.safeParse(JSON.parse(raw ?? 'null'))
+		const parsed = results_schema.safeParse(JSON.parse(raw))
 
 		return parsed.success ? parsed.data : undefined
 	} catch {
@@ -216,7 +216,7 @@ async function run_eslint_json(
 			reject: false,
 			stdout: 'pipe',
 			stderr: 'ignore',
-			timeout: PROCESS_TIMEOUT_MS,
+			timeout: LINT_TIMEOUT_MS,
 		})
 
 		return parse_results(result.stdout)

package/scripts/release/github-release-environment.ts

@@ -38,6 +38,7 @@ function read_release_input(environment: Environment): ReleaseInput {
 			workflow: optional(environment['RELEASE_WORKFLOW']),
 			jobs: job_names(environment['RELEASE_JOBS']),
 			await_publish: environment['RELEASE_AWAIT_PUBLISH'] === 'true',
+			release_run_workflow: optional(environment['RELEASE_RUN_WORKFLOW']),
 		},
 	}
 }

package/scripts/release/github-release-runs.ts

@@ -0,0 +1,115 @@
+import { z } from 'zod'
+
+// A job skipped by its `if:` (or neutral) belongs to a run that succeeded; counting it would skip a
+// lower tag whose release is still on its way.
+const FAILED_CONCLUSIONS = new Set(['failure', 'cancelled', 'timed_out', 'startup_failure'])
+const RELEASE_RUN_TITLE = 'GitHub Release '
+const RUN_SCHEMA = z.object({
+	id: z.number(),
+	display_title: z.string(),
+	status: z.string().optional(),
+	conclusion: z.string().nullable().optional(),
+})
+const JOB_SCHEMA = z.object({
+	name: z.string(),
+	status: z.string(),
+	conclusion: z.string().nullable(),
+})
+const RUNS_SCHEMA = z.object({ workflow_runs: z.array(RUN_SCHEMA) })
+const JOBS_SCHEMA = z.object({ jobs: z.array(JOB_SCHEMA) })
+
+type Run = z.infer<typeof RUN_SCHEMA>
+type PollState = 'ready' | 'failed' | 'pending'
+
+// `read` answers a GET on a repository API path. `workflow` is the publish workflow and `jobs` the
+// jobs in it whose failure counts (empty: every job). `release_run_workflow` is the workflow that
+// creates a tag's release — the publish workflow itself when its run creates the release.
+interface RunSource {
+	read: (path: string) => Promise<unknown>
+	workflow: string | undefined
+	jobs: ReadonlyArray<string>
+	release_run_workflow: string | undefined
+}
+
+function is_failed_job(job: z.infer<typeof JOB_SCHEMA>, names: ReadonlyArray<string>): boolean {
+	if (job.status !== 'completed' || !FAILED_CONCLUSIONS.has(job.conclusion ?? '')) return false
+	if (names.length === 0) return true
+
+	return names.some((name) => job.name === name || job.name.startsWith(`${name} /`))
+}
+
+async function list_runs(source: RunSource, workflow_name: string): Promise<ReadonlyArray<Run>> {
+	const workflow = encodeURIComponent(workflow_name)
+
+	return RUNS_SCHEMA.parse(await source.read(`/actions/workflows/${workflow}/runs?per_page=100`))
+		.workflow_runs
+}
+
+async function find_run(
+	source: RunSource,
+	workflow_name: string,
+	title: string,
+): Promise<Run | undefined> {
+	const runs = await list_runs(source, workflow_name)
+
+	return runs.find((item) => item.display_title === title)
+}
+
+async function has_failed_job(source: RunSource, run_id: number): Promise<boolean> {
+	const { jobs } = JOBS_SCHEMA.parse(
+		await source.read(`/actions/runs/${String(run_id)}/jobs?per_page=100`),
+	)
+
+	return jobs.some((job) => is_failed_job(job, source.jobs))
+}
+
+// A run started before its title named the tag may be at work on any tag.
+function may_release(run: Run, tag: string): boolean {
+	if (run.status === 'completed') return false
+
+	return (
+		run.display_title === `${RELEASE_RUN_TITLE}${tag}` ||
+		!run.display_title.startsWith(RELEASE_RUN_TITLE)
+	)
+}
+
+// Unset, nothing tells that a release is over, so the lower tag is waited for.
+async function is_release_over(source: RunSource, tag: string): Promise<boolean> {
+	const workflow = source.release_run_workflow
+	if (workflow === undefined) return false
+	if (workflow === source.workflow) return true
+
+	const runs = await list_runs(source, workflow)
+
+	return runs.every((run) => !may_release(run, tag))
+}
+
+// A lower tag whose publication failed, or finished while no release run is left at work on it,
+// never gains a release: a tag cut before joshuafolkken/kit#3138 was fixed would hold every later one.
+async function is_release_lost(source: RunSource, tag: string): Promise<boolean> {
+	if (source.workflow === undefined) return false
+
+	const run = await find_run(source, source.workflow, `Publish ${tag}`)
+	if (!run) return false
+	if (await has_failed_job(source, run.id)) return true
+
+	return run.status === 'completed' && (await is_release_over(source, tag))
+}
+
+// A run not listed yet is pending too: the announcement that starts this release also starts the
+// publication, so the release can ask before GitHub has queued that run.
+async function publication_state(
+	source: RunSource,
+	workflow: string,
+	tag: string,
+): Promise<PollState> {
+	const run = await find_run(source, workflow, `Publish ${tag}`)
+	if (run?.status !== 'completed') return 'pending'
+
+	return run.conclusion === 'success' ? 'ready' : 'failed'
+}
+
+const github_release_runs = { is_release_lost, publication_state }
+
+export type { PollState, RunSource }
+export { github_release_runs }