@joshuafolkken/kit 1.872.0

package/scripts/release/release-publish.ts

@@ -0,0 +1,152 @@
+import { git_command } from '#scripts/git/git-command'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_pr_checks } from '#scripts/git/git-pr-checks'
+import { git_remote_branch } from '#scripts/git/git-remote-branch'
+import { write_version } from '#scripts/version/bump-version'
+import { version_targets } from '#scripts/version/version-targets'
+import type { ReleasePlan } from './release-plan'
+import { release_tag } from './release-tag'
+import { release_worktree } from './release-worktree'
+
+// The write half of `pnpm josh release`: the branch, the commit, the pull request, the merge and the
+// wait for the tag (joshuafolkken/kit#1169).
+//
+// **The merge goes through the same gate every other pull request does.** `wait_for_pr_success` is
+// the merge gate `pnpm josh followup` waits on, and it is called here rather than reimplemented —
+// weakening it for a release commit would open exactly the "merge without green CI" path the issue's
+// closing note prohibits.
+
+const { PACKAGE_JSON } = version_targets
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+
+function branch_name_for(version: string): string {
+	return `release/v${version}`
+}
+
+function commit_message(version: string): string {
+	return `Release v${version}`
+}
+
+// **No `closes #N`.** A release carries whatever merged since the last one, so it closes no single
+// issue; the mapping from issue to release is recovered from the merge commits between two tags,
+// which is what `.github/release.yml` already classifies.
+function pull_request_body(plan: ReleasePlan): string {
+	return [
+		`${String(plan.pending)} merge(s) have landed on main since \`${plan.base}\`, the commit that last changed the version.`,
+		'',
+		`Raising the version by that many minors: \`${plan.current_version}\` → \`${plan.next_version}\`.`,
+		'',
+		'Opened by `pnpm josh release` (joshuafolkken/kit#1169).',
+	].join('\n')
+}
+
+// **A branch already there is a previous release attempt, not a name collision.** The wait for CI
+// can throw — a timeout, a red required check, a `gh` failure — and the branch and its pull request
+// survive it. Re-running then recomputes the same `pending`, so the branch name is identical and
+// `git checkout -b` fails with git's own opaque message. Saying what is actually there leaves the
+// person one decision rather than one diagnosis.
+function existing_branch_message(branch_name: string): string {
+	return `\`${branch_name}\` already exists — a previous release attempt got as far as opening it. Finish or delete that pull request and branch, then run \`pnpm josh release\` again.`
+}
+
+// **A remote that cannot be asked is refused, not read as "no branch there"** (joshuafolkken/kit#1641).
+// `pnpm josh release` pushes, opens a pull request, merges it and waits for a tag, so it cannot
+// finish without the remote in any case: refusing here is the failure the run was going to have
+// anyway, moved in front of the version write and the commit — which is the whole point of this
+// guard. Silently answering "not taken" instead would put the raw error back after two writes.
+function unreachable_remote_message(branch_name: string): string {
+	return `Could not ask origin whether \`${branch_name}\` already exists, so \`pnpm josh release\` stops before writing the version. It needs the remote to push, open the pull request and merge it. Restore the connection and run \`pnpm josh release\` again.`
+}
+
+// **The remote is asked as well as the local branch.** A previous attempt pushed before it opened
+// the pull request, so deleting the local branch — or retrying from a second checkout — leaves the
+// remote one standing on its own. Checking only locally there lets the run write the version, commit
+// it and reach `push`, which then fails with git's non-fast-forward message: the raw error this
+// guard exists to replace, and now after two writes rather than before them.
+//
+// **`git branch --list --remotes` could not answer it, which is why origin is asked directly.** Its
+// short names carry the remote — `origin/x`, never `x` — so the unprefixed pattern this used to pass
+// matched nothing and the remote arm reported "absent" for every branch that has ever existed. The
+// remote-tracking refs it reads are stale anyway, since nothing in this workflow prunes them, so
+// `git_remote_branch.ask` puts the question to origin itself.
+async function is_release_branch_taken(branch_name: string): Promise<boolean> {
+	if (await git_command.branch_exists(branch_name)) return true
+
+	const answer = await git_remote_branch.ask(branch_name)
+
+	if (answer === 'unreachable') throw new Error(unreachable_remote_message(branch_name))
+
+	return answer === 'present'
+}
+
+async function refuse_existing_branch(branch_name: string): Promise<void> {
+	if (!(await is_release_branch_taken(branch_name))) return
+
+	throw new Error(existing_branch_message(branch_name))
+}
+
+// **No `checkout -b` and no branch guard here** (joshuafolkken/kit#2411). The work tree is already
+// sitting on the release branch — `release_worktree.create` cut it that way — and the guard ran
+// before that creation, because `worktree_add` makes the branch local and `branch_exists` would then
+// report every release as already taken. This runs after `process.chdir` into the work tree, so the
+// version write and the git commands all act on it rather than on the root.
+async function commit_release(plan: ReleasePlan): Promise<void> {
+	write_version(plan.next_version)
+	await git_command.add_path(PACKAGE_JSON)
+	await git_command.commit(commit_message(plan.next_version))
+	await git_command.push()
+	console.info(
+		await git_gh_command.pr_create(commit_message(plan.next_version), pull_request_body(plan)),
+	)
+}
+
+async function merge_and_tag(plan: ReleasePlan, branch_name: string): Promise<number> {
+	await git_pr_checks.wait_for_pr_success(branch_name)
+	await git_gh_command.pr_merge(branch_name)
+
+	const is_tagged = await release_tag.wait_for_tag(plan.next_version)
+
+	console.info(release_tag.format_result(plan.next_version, is_tagged))
+
+	return is_tagged ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+// The whole release happens inside a work tree cut for it, so the root checkout is never touched: the
+// branch guard runs before the tree exists, `process.chdir` points the version write and the git
+// commands at the tree, and the `finally` returns to the root and removes the tree — whichever way
+// the wait ended, so a failed tag watch cleans up rather than leaving debris behind.
+async function publish(plan: ReleasePlan): Promise<number> {
+	const branch_name = branch_name_for(plan.next_version)
+
+	await refuse_existing_branch(branch_name)
+
+	const directory = await release_worktree.create(branch_name)
+	const previous_cwd = process.cwd()
+
+	try {
+		process.chdir(directory)
+		await commit_release(plan)
+
+		return await merge_and_tag(plan, branch_name)
+	} finally {
+		process.chdir(previous_cwd)
+		await release_worktree.remove(directory, branch_name)
+	}
+}
+
+const release_publish = {
+	branch_name_for,
+	commit_message,
+	existing_branch_message,
+	// Exported so the three answers the guard has to separate — here, on origin, on neither — are
+	// asserted directly rather than through `publish`, whose next step writes `package.json`.
+	is_release_branch_taken,
+	publish,
+	pull_request_body,
+	unreachable_remote_message,
+	FAILURE_EXIT_CODE,
+	SUCCESS_EXIT_CODE,
+}
+
+export { release_publish }

package/scripts/release/release-scope-cli.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_followup_pending } from '#scripts/git/git-followup-pending'
+import { path_decision } from '#scripts/josh/path-decision'
+import { release_plan } from './release-plan'
+
+// **Whether a release is owed is a command's answer, not a judgement** (joshuafolkken/kit#1582).
+//
+// joshuafolkken/kit#1169 took the version off the branch and put it behind one command a person
+// types, and nothing ever said *when* to type it. Nothing fails when nobody does — CI green, every
+// pull request merged, every Issue closed — so 53 merges reached main unreleased and no consumer of
+// this package saw one of them.
+//
+// **`pnpm josh release --dry-run` cannot be the check.** It refuses off the default branch and on a
+// dirty working tree, and it counts against `HEAD`; every position a run asks the question from is
+// a feature branch or a lane, which is exactly where it throws.
+//
+// **So this counts nothing of its own.** It reads the number `pnpm josh followup` already puts in
+// the completion notification — `git_followup_pending.read_pending`, which fetches the default
+// branch and counts `--first-parent` merges against `origin/<default>` — and turns it into a
+// verdict. One counting path, two readers.
+//
+// The flag parse and the printing come from `path_decision`, the contract every mechanically-decided
+// command here shares. Only its `parse_options` / `run_path_decision` are path-specific, and this
+// decision is not made from changed paths, so those two are the ones left alone.
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh release:scope [--json]'
+const JSON_KEY = 'scope'
+// Not `path_decision.KNOWN_FLAGS`: that set carries `--staged`, which means nothing here, and a
+// command that accepts a flag it ignores answers a question nobody asked.
+const KNOWN_FLAGS: ReadonlyArray<string> = [path_decision.JSON_FLAG]
+const REQUIRED_SCOPE = 'required'
+const SKIPPED_SCOPE = 'skip'
+const UNKNOWN_SCOPE = 'unknown'
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const NOTHING_PENDING_REASON = 'main has taken no merge since the version last changed'
+const RELEASE_HINT = 'run `pnpm josh release` on the default branch of the primary checkout'
+// **Not `skip`.** An unreadable version, a fetch that could not run or a base the search cannot
+// resolve is not "nothing is waiting to ship", and reporting it as one is how a release goes
+// missing quietly a second time.
+const UNKNOWN_REASON = 'the unreleased-merge count could not be read — report unknown, never skip'
+
+type ReleaseScope = typeof REQUIRED_SCOPE | typeof SKIPPED_SCOPE | typeof UNKNOWN_SCOPE
+
+interface Decision {
+	scope: ReleaseScope
+	reason: string
+}
+
+// **The threshold is one, and the position carries the rest.** A release per invocation is the
+// cadence joshuafolkken/kit#1582 asks for — its own complaint is that accumulating makes a single
+// version larger and its contents harder to trace afterwards — so anything above zero is owed. What
+// keeps this from firing per child of a batch is where the question is asked, which belongs to the
+// procedure rather than to this command.
+function decide(pending: number | undefined): Decision {
+	if (pending === undefined) return { scope: UNKNOWN_SCOPE, reason: UNKNOWN_REASON }
+
+	const line = release_plan.format_pending_line(pending)
+
+	if (pending === 0) return { scope: SKIPPED_SCOPE, reason: `${line} — ${NOTHING_PENDING_REASON}` }
+
+	return { scope: REQUIRED_SCOPE, reason: `${line} — ${RELEASE_HINT}` }
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	if (path_decision.has_unknown_flag(argv, KNOWN_FLAGS)) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const decision = decide(await git_followup_pending.read_pending({}))
+	const is_json = argv.includes(path_decision.JSON_FLAG)
+
+	path_decision.print_decision(JSON_KEY, decision.scope, decision.reason, is_json)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const release_scope_cli = {
+	decide,
+	main,
+	run,
+	JSON_KEY,
+	KNOWN_FLAGS,
+	NOTHING_PENDING_REASON,
+	RELEASE_HINT,
+	REQUIRED_SCOPE,
+	SKIPPED_SCOPE,
+	UNKNOWN_REASON,
+	UNKNOWN_SCOPE,
+	USAGE,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export type { Decision }
+export { release_scope_cli }

package/scripts/release/release-tag.ts

@@ -0,0 +1,93 @@
+import { git_gh_api_path } from '#scripts/git/git-gh-api-path'
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
+import { poll, type PollOptions } from '#scripts/lib/poll'
+
+// **The release is not finished when the pull request merges — it is finished when the tag exists.**
+//
+// Merging is what starts the distribution chain: `ci.yml`'s `notify-auto-tag` dispatches, `auto-tag.yml`
+// creates `v<version>`, and `publish.yml` / `production.yml` run off that tag. Every link after the
+// merge can fail silently, and one of them is known to (joshuafolkken/kit#1481: a later push to main
+// cancels the release commit's CI run, so nothing dispatches and nothing is tagged). An automatic
+// release would have been picked up by the next cycle; a release a person types has no next cycle, so
+// the person walks away believing something shipped when nothing did.
+//
+// So this waits for the tag and **reports its absence as a failure** (joshuafolkken/kit#1169 → §3).
+
+const HTTP_OK = 200
+const TAG_POLL_INTERVAL_MS = 15_000
+const MILLISECONDS_PER_SECOND = 1000
+
+// Long enough for main's full CI run plus the dispatch hop that follows it. A release that has not
+// been tagged after this has not been slow, it has been lost — which is the answer this reports.
+const DEFAULT_TIMEOUT_SECONDS = 1800
+const TIMEOUT_ENV = 'JOSH_RELEASE_TAG_TIMEOUT_SECONDS'
+
+function tag_name(version: string): string {
+	return `v${version}`
+}
+
+function configured_timeout_seconds(raw: string | undefined): number {
+	const parsed = Number(raw)
+
+	if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_TIMEOUT_SECONDS
+
+	return parsed
+}
+
+function attempts_for(timeout_seconds: number): number {
+	const budget_ms = timeout_seconds * MILLISECONDS_PER_SECOND
+
+	return Math.max(1, Math.ceil(budget_ms / TAG_POLL_INTERVAL_MS))
+}
+
+// REST answers 404 for a tag that does not exist, so the status code alone is the whole question.
+async function tag_exists(version: string): Promise<boolean> {
+	const status = await git_gh_exec.exec_gh_api_status(
+		git_gh_api_path.tag_ref_api_path(tag_name(version)),
+	)
+
+	return status === HTTP_OK
+}
+
+async function wait_for_tag(
+	version: string,
+	sleeper?: (duration_ms: number) => Promise<void>,
+): Promise<boolean> {
+	const timeout_seconds = configured_timeout_seconds(process.env[TIMEOUT_ENV])
+	// Spread rather than a conditional call: `exactOptionalPropertyTypes` refuses an explicit
+	// `sleeper: undefined`, and writing the call twice to satisfy it would duplicate the predicate.
+	const options: PollOptions = {
+		attempts: attempts_for(timeout_seconds),
+		interval_ms: TAG_POLL_INTERVAL_MS,
+		...(sleeper !== undefined && { sleeper }),
+	}
+
+	return await poll.poll_until(async () => await tag_exists(version), options)
+}
+
+// **The failure text says what did not happen rather than what went wrong**, because the command
+// cannot know which link broke — only that the tag it was waiting for is not there, and that nothing
+// downstream of the tag can have run.
+function format_result(version: string, is_tagged: boolean): string {
+	if (is_tagged) return `🏷 ${tag_name(version)} exists — the release is published.`
+
+	return [
+		`❌ ${tag_name(version)} never appeared.`,
+		`  The release pull request merged, but no tag was created, so nothing was published.`,
+		`  Check the CI run on main: a later push cancels the release commit's run, which skips the tag (joshuafolkken/kit#1481).`,
+	].join('\n')
+}
+
+const release_tag = {
+	attempts_for,
+	configured_timeout_seconds,
+	format_result,
+	tag_exists,
+	tag_name,
+	wait_for_tag,
+	DEFAULT_TIMEOUT_SECONDS,
+	TAG_POLL_INTERVAL_MS,
+	TIMEOUT_ENV,
+}
+
+export { release_tag }

package/scripts/release/release-worktree.ts

@@ -0,0 +1,71 @@
+import path from 'node:path'
+import { git_command } from '#scripts/git/git-command'
+import { git_worktree } from '#scripts/git/git-worktree'
+import { lane_install } from '#scripts/lane/lane-install'
+import { lane_paths } from '#scripts/lane/lane-paths'
+
+// The dedicated linked work tree `pnpm josh release` runs inside (joshuafolkken/kit#2411). The whole
+// point is that the release never touches the root checkout: it is cut fresh from
+// `origin/<default>` as the `release/v<version>` branch, the version bump / commit / push all happen
+// there, and it is removed whichever way the run ends. That lets a release run beside a `backlogrun`
+// — which keeps the root on the default branch — and lets a release start even when the root is dirty
+// or sitting on another branch.
+
+// The release work tree lives under the same sibling hidden directory the lanes do
+// (`.<repo>-lanes/`), so it inherits the same "not inside the repository" placement. Lanes are named
+// by their numeric issue number (`lane_paths` matches `^\d+$`) and their seat locks are named
+// separately, so a fixed non-numeric name collides with neither.
+const RELEASE_WORKTREE_NAME = 'release'
+
+function directory_for(repository_root: string): string {
+	return path.join(lane_paths.lane_root(repository_root), RELEASE_WORKTREE_NAME)
+}
+
+function install_failed_message(directory: string, output: string): string {
+	return `Could not install dependencies in the release work tree \`${directory}\`:\n${output}`
+}
+
+// The work tree and its local branch both go, in that order: a branch checked out in a work tree
+// cannot be deleted, so the tree is removed first. `branch_delete` uses `-D` because the release
+// branch is unmerged against the *local* default (the merge happened on GitHub), which `-d` refuses.
+async function remove(directory: string, branch_name: string): Promise<void> {
+	await git_worktree.worktree_remove(directory)
+	await git_worktree.branch_delete(branch_name)
+}
+
+// **The dependency install is not optional, and disabling the hook is not the way around it**
+// (joshuafolkken/kit#2411). The release commit goes through lefthook's pre-commit, which runs
+// `pnpm exec` / `pnpm josh`, and a sibling work tree has no `node_modules` above it — so the tree
+// needs its own, installed the same way a lane's is. A failed install cleans up the tree it created
+// rather than leaving debris, then reports what git printed.
+async function install_or_clean(directory: string, branch_name: string): Promise<void> {
+	const result = await lane_install.install_dependencies(directory)
+
+	if (result.is_installed) return
+
+	await remove(directory, branch_name)
+	throw new Error(install_failed_message(directory, result.output))
+}
+
+// **The tree is cut from `origin/<default>`, not from the root's HEAD.** git refuses a second work
+// tree on the default branch, so the tree is created directly on the release branch — `git worktree
+// add --no-track -b release/v<version> <dir> origin/<default>`, which `worktree_add` already spells
+// when it is given a start point.
+async function create(branch_name: string): Promise<string> {
+	const directory = directory_for(process.cwd())
+	const default_branch = await git_command.get_default_branch()
+
+	await git_worktree.worktree_add(directory, branch_name, `origin/${default_branch}`)
+	await install_or_clean(directory, branch_name)
+
+	return directory
+}
+
+const release_worktree = {
+	directory_for,
+	create,
+	remove,
+	RELEASE_WORKTREE_NAME,
+}
+
+export { release_worktree }

package/scripts/repo/auto-merge-setting-logic.ts

@@ -0,0 +1,100 @@
+import { repo_setting, type RepoSettingStatus } from './repo-setting'
+
+// GitHub's repository-level "Allow auto-merge" setting, as reported by the `allow_auto_merge` field
+// of `GET /repos/{owner}/{repo}`.
+//
+// joshuafolkken/kit#834 added `.github/workflows/dependabot-auto-merge.yml` to the distributed
+// files, so a synced consumer now runs `gh pr merge --auto` on every github-actions patch and minor
+// bump. That command needs this setting: without it the step fails with `Auto-merge is not allowed
+// for this repository`, and the pull request sits green and unmerged — which is the exact state
+// joshuafolkken/app-kit#184 was found in, and the same defect kit itself hit in
+// joshuafolkken/kit#802. The setting is off by default, so distributing the workflow without
+// reporting it would hand every consumer a workflow that never merges anything.
+type AutoMergeStatus = RepoSettingStatus
+
+const SETTING_LABEL = 'Repository auto-merge'
+const ALLOW_AUTO_MERGE_FIELD = 'allow_auto_merge'
+const ORIGIN_ISSUE = 'joshuafolkken/kit#834'
+const WORKFLOW_PATH = '.github/workflows/dependabot-auto-merge.yml'
+
+// The remediation for `disabled`, addressed at the repository the report actually resolved. kit
+// prints it and never runs it: changing a repository setting is outward-facing, needs admin scope,
+// and is the maintainer's call — the same line joshuafolkken/kit#805 drew for
+// `automated-security-fixes`, which is why `josh doctor --fix` does not enable this either.
+function enable_command(repo: string | undefined): string {
+	return `gh api -X PATCH repos/${repo_setting.command_target(repo)} -f ${ALLOW_AUTO_MERGE_FIELD}=true`
+}
+
+// Classify one `gh api` result. A failed call, unparseable output and a non-boolean field all land
+// on `unreadable`: a missing answer is not a negative answer, and reporting one as `disabled` would
+// tell a maintainer to change a setting that may already be correct.
+function classify_auto_merge(exit_code: number, stdout: string): AutoMergeStatus {
+	return repo_setting.classify_boolean_setting(
+		repo_setting.parse_payload(exit_code, stdout),
+		ALLOW_AUTO_MERGE_FIELD,
+	)
+}
+
+// What the reader loses while the setting is off, and how to get it back.
+function format_disabled_detail(repo: string | undefined): ReadonlyArray<string> {
+	return [
+		`    off, so ${WORKFLOW_PATH} fails with`,
+		'    `Auto-merge is not allowed for this repository` and Dependabot pull requests stay open.',
+		`    Enable: ${enable_command(repo)}`,
+		`    ${ORIGIN_ISSUE} distributes the workflow; kit never changes a repository setting.`,
+	]
+}
+
+// Why the setting could not be read. The two branches have different causes and must not share
+// wording: when the repository itself was never identified, admin access is beside the point and
+// naming a settings page names no page the reader can open.
+//
+// For an identified repository the causes are listed rather than asserted. `allow_auto_merge` is
+// absent from the response for a token without the right scope, and the same branch catches a 404,
+// a timeout, an offline run and an unparseable body — so naming any one of them as the cause would
+// be a false diagnosis. No enable command here either: it would be wrong whenever the setting is
+// actually on and merely unreadable.
+function format_unreadable_detail(repo: string | undefined): ReadonlyArray<string> {
+	if (repo === undefined) {
+		return [
+			'    The repository could not be identified — `gh` is missing, unauthenticated, or this is',
+			'    not a GitHub remote.',
+		]
+	}
+
+	return [
+		'    No admin access, or the request failed (offline, timed out, or an unexpected response).',
+		"    Check Settings → General → Pull Requests → Allow auto-merge on the repository's page.",
+	]
+}
+
+// The report block for one repository: a single status line, plus the consequence and its
+// remediation when the setting is off, or the possible causes when it could not be read.
+function format_auto_merge_report(
+	status: AutoMergeStatus,
+	repo: string | undefined,
+): ReadonlyArray<string> {
+	const target = repo_setting.report_target(repo)
+	if (status === 'enabled') return [`  ✔ ${SETTING_LABEL}: enabled (${target})`]
+
+	if (status === 'unreadable') {
+		return [
+			`  ⚠ ${SETTING_LABEL}: could not be read (${target}) — not checked, not necessarily off`,
+			...format_unreadable_detail(repo),
+		]
+	}
+
+	return [`  ⚠ ${SETTING_LABEL}: disabled (${target})`, ...format_disabled_detail(repo)]
+}
+
+const auto_merge_setting_logic = {
+	SETTING_LABEL,
+	ALLOW_AUTO_MERGE_FIELD,
+	WORKFLOW_PATH,
+	enable_command,
+	classify_auto_merge,
+	format_auto_merge_report,
+}
+
+export type { AutoMergeStatus }
+export { auto_merge_setting_logic }

package/scripts/repo/auto-merge-setting.ts

@@ -0,0 +1,37 @@
+import { auto_merge_setting_logic, type AutoMergeStatus } from './auto-merge-setting-logic'
+import { repo_setting } from './repo-setting'
+
+// Read the repository's "Allow auto-merge" setting. Never throws and never propagates a non-zero
+// exit: an unreadable answer is a reported status, not a command failure (joshuafolkken/kit#834).
+//
+// The whole repository object is requested rather than a `--jq` projection, because a projection
+// cannot distinguish a field that is `false` from a field the response never carried — and that
+// distinction is the entire point of the `unreadable` status.
+function read_auto_merge(repo: string): AutoMergeStatus {
+	const { exit_code, stdout } = repo_setting.query_repo_api(`repos/${repo}`)
+
+	return auto_merge_setting_logic.classify_auto_merge(exit_code, stdout)
+}
+
+// Report the repository's setting as a blank-line-separated block. A repository that cannot be
+// resolved (no `gh`, not a GitHub remote) reports `unreadable` rather than skipping the check
+// silently: an absent answer must not look like a clean one.
+//
+// `repo` is supplied by the caller rather than defaulted, for the same reason as the
+// security-updates report — a default parameter fires on an explicitly-passed `undefined` and would
+// re-spawn `gh repo view` in the very path where the caller's own lookup already failed.
+function report_auto_merge_section(repo: string | undefined): AutoMergeStatus {
+	const status = repo === undefined ? 'unreadable' : read_auto_merge(repo)
+
+	repo_setting.print_section(auto_merge_setting_logic.format_auto_merge_report(status, repo))
+
+	return status
+}
+
+const auto_merge_setting = {
+	GH_TIMEOUT_MS: repo_setting.GH_TIMEOUT_MS,
+	read_auto_merge,
+	report_auto_merge_section,
+}
+
+export { auto_merge_setting }

package/scripts/repo/repo-setting.ts

@@ -0,0 +1,112 @@
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { read_spawn_stdout } from '#scripts/lib/spawn-exit'
+import { execaSync } from 'execa'
+
+// The shared half of every "report a GitHub repository setting kit cannot write" check.
+//
+// Two such checks exist — `automated-security-fixes` (joshuafolkken/kit#805) and `allow_auto_merge`
+// (joshuafolkken/kit#834) — and they agree on everything that is not wording: the same bounded
+// `gh api` call, the same rule that an answer which cannot be read is never reported as a negative
+// answer, and the same blank-line-separated report block. That agreement is the contract, so it
+// lives here once rather than being re-derived per setting.
+type RepoSettingStatus = 'enabled' | 'disabled' | 'unreadable'
+
+// Bounded, unlike the repository lookup: these calls only decide what a report *says*, never what
+// gets written, so a timeout degrades to `could not be read` and costs nothing. `josh doctor` made
+// no network calls at all before joshuafolkken/kit#805, and this keeps it prompt.
+const GH_TIMEOUT_MS = 5000
+
+// A literal `<owner>/<repo>` would be unusable when pasted into a shell, where `<` redirects — but
+// it is still the honest rendering when the repository could not be resolved at all.
+const REPO_PLACEHOLDER = '<owner>/<repo>'
+const UNKNOWN_REPOSITORY = 'unknown repository'
+
+interface RepoApiResult {
+	exit_code: number
+	stdout: string
+}
+
+// One `gh api` call. Never throws and never propagates a non-zero exit: an unreadable answer is a
+// reported status, not a command failure.
+function query_repo_api(api_path: string): RepoApiResult {
+	const result = execaSync('gh', ['api', api_path], {
+		...git_gh_exec.direct_environment(),
+		cwd: PROJECT_ROOT,
+		reject: false,
+		timeout: GH_TIMEOUT_MS,
+	})
+
+	return { exit_code: result.exitCode ?? 1, stdout: read_spawn_stdout(result) }
+}
+
+// The response body as an object, or nothing. A non-zero exit covers every case where the answer
+// cannot be trusted — a 404 on a repository that never had the setting, a token without the scope,
+// no network — and they collapse together with unparseable output because none of them proves the
+// setting is off.
+function parse_payload(exit_code: number, stdout: string): object | undefined {
+	if (exit_code !== 0) return undefined
+
+	try {
+		const parsed: unknown = JSON.parse(stdout)
+
+		return typeof parsed === 'object' && parsed !== null ? parsed : undefined
+	} catch {
+		return undefined
+	}
+}
+
+// Read one field off a parsed body. `Reflect.get` rather than an index signature: the body is
+// external JSON, so declaring it as a record would need a type assertion to claim a shape the
+// response never promised.
+function read_field(payload: object | undefined, field: string): unknown {
+	return payload === undefined ? undefined : Reflect.get(payload, field)
+}
+
+// A missing payload, a missing field, or a field that is not a boolean are all unreadable: a
+// missing answer is not a negative answer, and reporting one as `disabled` would raise a false
+// alarm — the failure mode both settings exist to remove.
+function classify_boolean_setting(payload: object | undefined, field: string): RepoSettingStatus {
+	const value = read_field(payload, field)
+	if (typeof value !== 'boolean') return 'unreadable'
+
+	return value ? 'enabled' : 'disabled'
+}
+
+// The repository a remediation command should address. Falls back to the placeholder rather than to
+// prose, because this value is pasted into a shell.
+function command_target(repo: string | undefined): string {
+	return repo ?? REPO_PLACEHOLDER
+}
+
+// The repository a status line should name. Falls back to prose rather than to the placeholder,
+// because this value is read, not pasted.
+function report_target(repo: string | undefined): string {
+	return repo ?? UNKNOWN_REPOSITORY
+}
+
+// The blank-line-separated report block, shared by every caller so the separator and the ordering
+// contract live in one place.
+function print_section(lines: ReadonlyArray<string>): void {
+	console.info('')
+
+	for (const line of lines) {
+		console.info(line)
+	}
+}
+
+const repo_setting = {
+	GH_TIMEOUT_MS,
+	REPO_PLACEHOLDER,
+	UNKNOWN_REPOSITORY,
+	query_repo_api,
+	parse_payload,
+	read_field,
+	classify_boolean_setting,
+	command_target,
+	report_target,
+	print_section,
+}
+
+export type { RepoSettingStatus }
+export { repo_setting }