@joshuafolkken/kit 1.872.0

package/scripts/hooks/batch-guard.ts

@@ -0,0 +1,144 @@
+#!/usr/bin/env tsx
+import { text } from 'node:stream/consumers'
+import { fileURLToPath } from 'node:url'
+import { hook_decision } from '#scripts/josh/hook-decision'
+import { lane_guard_policy, type LaneGuardMode } from '#scripts/lane/lane-guard-policy'
+import { time_batch_guard, type GuardedCall } from '#scripts/time-runtime/time-batch-guard'
+
+// The disk half of the batching guard (joshuafolkken/kit#1390): find the transcript, read enough of
+// its end, remember when a call was last refused, and write the refusal Claude Code understands.
+//
+// **It is a `PreToolUse` hook, and that is the point of the Issue.** The live density line rides
+// `PostToolUse`, where the round trip has already been spent and all that is left is to describe it.
+// Three runs measured after that line shipped came in at 1.10–1.12 calls per round trip, unchanged —
+// so what is added here intervenes in the decision instead of reporting on it.
+//
+// **What the transcript holds is the turns already closed, and nothing usable about the one in hand.**
+// Claude Code writes one line per content block and starts the first tool as soon as that block parses,
+// so a turn's later `tool_use` lines do not exist yet — measured on a live session, they arrive 1.4 to
+// 15 seconds afterwards. The decision is therefore made from closed history alone;
+// `time-batch-guard.ts` → "What it cannot know" carries the measurement and what it costs.
+//
+// **The shell is `hook-decision.ts`, shared with the investigation guard** (joshuafolkken/kit#1460):
+// the payload schema, the deny envelope, the switch, the `.env` load, the stamp that makes a refusal
+// unrepeatable, and the six steps every refusing hook takes in the same order. What stays here is this
+// guard's own rule and its own two names, and the seven exports below are unchanged so nothing that
+// reads them had to move.
+
+// The escape hatch. **On by default**: this is a distributed convention, and a guard nobody enables
+// would leave the Issue exactly where it started. What the variable buys is a way to switch a
+// refusing hook off without editing the settings
+// file — a machine debugging the guard itself, or a session where a run of genuinely dependent single
+// calls is expected.
+const SWITCH_ENV_KEY = 'JOSH_BATCH_GUARD'
+
+// **The judgement is `time-batch-guard.ts`'s, not a second one.** Whether a call is one this guard may
+// refuse and whether the run has stopped batching are both its, so a refusal here can never disagree
+// with the report the Issue's own verification step reads.
+// The transcript is read for a call the guard could act on either way: one it may refuse, or the one
+// whole-file write it may only notify about (joshuafolkken/kit#1848). The read is skipped for the rest
+// exactly as before — most of a run's calls are neither.
+function is_batch_candidate(call: GuardedCall): boolean {
+	return time_batch_guard.is_guarded_call(call) || time_batch_guard.is_notice_call(call)
+}
+
+// **How the batching guard behaves for the session in hand, decided from the one-place enumeration**
+// (joshuafolkken/kit#2138, joshuafolkken/kit#2164, joshuafolkken/kit#2178, joshuafolkken/kit#2276).
+// Outside a lane child the mode is `refuse` and the guard is exactly what it always was; in a dispatched
+// lane child it is `notice` — kit#2178 took it to `off` after kit#2164's generic notice did not move the
+// density, and kit#2276 restores it as a notice that names the concrete recent calls and recurs every
+// single-call turn, the two things #2164's notice lacked, so the density can be re-measured with the
+// notice actually firing where it is measured. The wrappers below are three-valued so this needs no
+// change beyond the enumeration. The enumeration reads `is_child_of` — the dispatch mark against this
+// checkout's own issue — only for a guard whose mode it would actually change, so a person working in a
+// lane sees the guard unchanged.
+function batching_mode(): LaneGuardMode {
+	return lane_guard_policy.mode_here('batching')
+}
+
+// A guard the enumeration turns fully `off` says nothing at all. Batching is `notice` in a lane child
+// since kit#2276, so a candidate call is reached there; only a guard some future enumeration sets to
+// `off` is skipped. On the main line the mode is `refuse`.
+function is_candidate(call: GuardedCall): boolean {
+	return is_batch_candidate(call) && batching_mode() !== 'off'
+}
+
+// A refusable call is refused only where the mode is `refuse`. A lane child is `notice` (kit#2276), so
+// it reaches here and is withheld the refusal — the notice branch below carries the guidance instead,
+// because a refusal ends a headless child's turn (kit#2138).
+function should_block_here(tail: string, call: GuardedCall, refused_at_ms: number): boolean {
+	if (batching_mode() !== 'refuse') return false
+
+	return time_batch_guard.should_block(tail, call, refused_at_ms)
+}
+
+// The whole-file write earns a notice on every run (joshuafolkken/kit#1848). The second branch turns a
+// refusable call into a notice under a `notice`-mode guard, which is the mode batching takes in a lane
+// child again since kit#2276. Both read the notice's own record, so a notice never spends the refusal's
+// stamp and re-fires on the notice's own `NOTICE_REFIRE_EVERY` cadence.
+function should_notify_here(tail: string, call: GuardedCall, notified_at_ms: number): boolean {
+	if (time_batch_guard.should_notify(tail, call, notified_at_ms)) return true
+	if (batching_mode() !== 'notice') return false
+
+	return time_batch_guard.should_block(
+		tail,
+		call,
+		notified_at_ms,
+		time_batch_guard.NOTICE_REFIRE_EVERY,
+	)
+}
+
+// The wording each notice carries, with the concrete calls the run just issued one-per-turn appended
+// (joshuafolkken/kit#2276). The whole-file write keeps its own base text; the lane notice is reached
+// under the `notice`-mode guard batching takes in a lane child again since kit#2276, so a headless
+// child is shown *which* recent calls it could have batched rather than only told to batch.
+function notice_text(call: GuardedCall, tail: string): string {
+	const base = time_batch_guard.is_notice_call(call)
+		? time_batch_guard.NOTICE
+		: time_batch_guard.LANE_NOTICE
+
+	return `${base}${time_batch_guard.recent_candidates(tail)}`
+}
+
+const GUARD = hook_decision.create_transcript_guard({
+	prefix: time_batch_guard.STAMP_PREFIX,
+	switch_key: SWITCH_ENV_KEY,
+	is_candidate,
+	should_block: should_block_here,
+	reason: time_batch_guard.REASON,
+	// The whole-file write is notified rather than refused, on a record of its own so it never spends
+	// the refusal's stamp (joshuafolkken/kit#1848); the lane-child refusable-call notice kit#2164 added
+	// here fires again since kit#2276 restored batching to `notice` in a lane child.
+	notify: {
+		prefix: time_batch_guard.NOTICE_STAMP_PREFIX,
+		should_notify: should_notify_here,
+		text: notice_text,
+	},
+})
+
+const batch_refusal = GUARD.refusal
+const batch_outcome = GUARD.outcome
+const { is_enabled, refusal_path } = GUARD
+// The notice's stamp path, exposed the way `refusal_path` is so a test can clean it apart from the
+// refusal's record (joshuafolkken/kit#1848).
+const notice_refusal_path = hook_decision.create_refusal_stamp(
+	time_batch_guard.NOTICE_STAMP_PREFIX,
+).path
+const { deny_envelope, load_environment_file, DISABLED_VALUES } = hook_decision
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	if (process.stdin.isTTY) hook_decision.report_no_payload('batch:guard')
+	else hook_decision.write_outcome(await text(process.stdin), batch_outcome)
+}
+
+export {
+	batch_outcome,
+	batch_refusal,
+	deny_envelope,
+	is_enabled,
+	load_environment_file,
+	notice_refusal_path,
+	refusal_path,
+	DISABLED_VALUES,
+	SWITCH_ENV_KEY,
+}

package/scripts/hooks/check-commit-message.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env tsx
+import { readFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { git_command } from '#scripts/git/git-command'
+
+interface CheckResult {
+	success: boolean
+	message: string
+}
+
+const PARENT_SEGMENT = '..'
+const COMMIT_MESSAGE_FILE_NAME = 'COMMIT_EDITMSG'
+// Only for a checkout git could not answer for; every real invocation has git's own answer.
+const FALLBACK_GIT_DIRECTORY = '.git'
+
+// Containment, decided after resolving — not a prefix of the spelling handed in. `path.relative`
+// answers how to walk from the directory to the file, so a path that climbs back out of it starts
+// with `..`, and one that never entered it comes back absolute. A string prefix would accept
+// `<dir>/../../etc/passwd`, which is the whole file this guard refuses to read.
+function is_inside(directory: string, resolved_path: string): boolean {
+	const relative = path.relative(directory, resolved_path)
+
+	return relative !== '' && !relative.startsWith(PARENT_SEGMENT) && !path.isAbsolute(relative)
+}
+
+// joshuafolkken/kit#1106: the guard used to be a prefix test — the path had to *start* with `.git/`,
+// which is only the shape the main work tree produces. A linked work tree gets an absolute
+// `<repo>/.git/worktrees/<name>/COMMIT_EDITMSG`, which shares no prefix with it, so the guard threw
+// before the real check ran and no commit inside a work tree could succeed.
+//
+// The directories are asked of git rather than assumed to be named `.git`, because the name is not a
+// property of a repository: a bare repository's git directory is the repository, and
+// `--separate-git-dir` puts it anywhere at all. Matching a `.git` segment instead would refuse both,
+// reproducing this defect one case over — and it would accept any path that merely passes through
+// some `.git` directory, which is wider than what the guard is for.
+function is_safe_commit_message_path(
+	file_path: string,
+	git_directories: ReadonlyArray<string>,
+): boolean {
+	const resolved = path.resolve(file_path)
+
+	return (
+		git_directories.some((directory) => is_inside(directory, resolved)) ||
+		is_inside(os.tmpdir(), resolved)
+	)
+}
+
+// Where git would have written the message, for a run that was passed no path. The work tree's own
+// git directory rather than a literal `.git/`: in a linked work tree that name is a *file*, so the
+// relative spelling this used to hardcode ends the run at ENOTDIR — the same defect as the guard's,
+// on the branch the guard does not reach (joshuafolkken/kit#1106).
+function default_commit_message_path(git_directories: ReadonlyArray<string>): string {
+	return path.join(git_directories[0] ?? FALLBACK_GIT_DIRECTORY, COMMIT_MESSAGE_FILE_NAME)
+}
+
+async function get_commit_message(): Promise<string> {
+	const FILE_INDEX = 2
+	const commit_message_file = process.argv.at(FILE_INDEX)
+	const git_directories = await git_command.git_directories()
+	const message_path = commit_message_file ?? default_commit_message_path(git_directories)
+
+	if (
+		commit_message_file !== undefined &&
+		!is_safe_commit_message_path(commit_message_file, git_directories)
+	) {
+		throw new Error(
+			`Commit message file must be inside a git directory or the system temp dir: ${commit_message_file}`,
+		)
+	}
+
+	try {
+		return readFileSync(message_path, 'utf8').trim()
+	} catch (error) {
+		throw new Error(`Failed to read commit message file: ${message_path}`, { cause: error })
+	}
+}
+
+function extract_issue_number(branch_name: string): string | undefined {
+	const branch_pattern = /^(\d+)-[\da-z-]+$/u
+	const match = branch_pattern.exec(branch_name)
+
+	return match?.[1]
+}
+
+function create_error_message(issue_number: string, branch: string, message: string): string {
+	return (
+		`🚫 Error: Commit message must include #${issue_number}\n` +
+		`   Current branch: ${branch}\n` +
+		`   Commit message: ${message}\n` +
+		`   Please include #${issue_number} in your commit message\n`
+	)
+}
+
+async function check_commit_message(): Promise<CheckResult> {
+	const current_branch = await git_command.branch()
+	const issue_number = extract_issue_number(current_branch)
+
+	if (issue_number === undefined) {
+		return {
+			success: true,
+			message: `✅ Branch format check passed: '${current_branch}' (no issue number required)`,
+		}
+	}
+
+	const commit_message = await get_commit_message()
+
+	if (!commit_message.includes(`#${issue_number}`)) {
+		return {
+			success: false,
+			message: create_error_message(issue_number, current_branch, commit_message),
+		}
+	}
+
+	return {
+		success: true,
+		message: `✅ Commit message check passed: Found #${issue_number}`,
+	}
+}
+
+async function main(): Promise<void> {
+	const result = await check_commit_message()
+
+	console.info(result.message)
+
+	if (!result.success) process.exit(1)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { check_commit_message, extract_issue_number, is_safe_commit_message_path }
+
+export type { CheckResult }

package/scripts/hooks/codex-hook-adapter.ts

@@ -0,0 +1,155 @@
+#!/usr/bin/env tsx
+import { text } from 'node:stream/consumers'
+import { fileURLToPath } from 'node:url'
+import { hook_decision, type GuardOutcome } from '#scripts/josh/hook-decision'
+import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
+import { z } from 'zod'
+import { build_envelope, compose_context, format_edited_payload } from './format-edited-file'
+import { pretool_guard } from './pretool-guard'
+
+const APPLY_PATCH_TOOL = 'apply_patch'
+const EDIT_TOOL = 'Edit'
+const PRETOOL_MODE = 'pretool'
+const POSTTOOL_MODE = 'posttool'
+const MODE_ARGUMENT_INDEX = 2
+const PATCH_FILE_PATTERN = /^\*\*\* (?:Add|Delete|Update) File: (.+)$/gmu
+const PATCH_MOVE_PATTERN = /^\*\*\* Move to: (.+)$/gmu
+// One canonical formatter can spend at most 75 seconds across its bounded process fallbacks. Start
+// at most two together and no later work, so every formatter that starts retains the 15-second
+// margin inside the Codex hook's 90-second timeout. Remaining files are left to the verification gate.
+const MAX_PARALLEL_FORMATS = 2
+// One patch can touch several files, each returning its own unfixed-lint block; a blank line between
+// them keeps the blocks readable when they are joined into the single envelope below.
+const DIAGNOSTIC_SEPARATOR = '\n\n'
+
+// Codex deliberately reports its canonical tool name even when an Edit or Write matcher selected
+// the hook. Its apply_patch body is `tool_input.command`; the Claude-shaped handlers downstream
+// instead classify Edit/Write and read `tool_input.file_path`. This module is the only translation
+// boundary between those provider contracts.
+const codex_payload_schema = z.looseObject({
+	tool_name: z.string().min(1),
+	tool_input: z.unknown(),
+})
+const patch_input_schema = z.object({ command: z.string().min(1) })
+
+type PayloadFormatter = (raw_payload: string, project_root: string) => Promise<string | undefined>
+
+function parse_payload(raw_payload: string): z.infer<typeof codex_payload_schema> | undefined {
+	try {
+		const parsed = codex_payload_schema.safeParse(JSON.parse(raw_payload))
+
+		return parsed.success ? parsed.data : undefined
+	} catch {
+		return undefined
+	}
+}
+
+function paths_matching(command: string, pattern: RegExp): Array<string> {
+	return [...command.matchAll(pattern)].flatMap((match) => {
+		const file_path = match[1]?.trim()
+
+		return file_path === undefined || file_path === '' ? [] : [file_path]
+	})
+}
+
+function patch_paths(tool_input: unknown): Array<string> {
+	const parsed = patch_input_schema.safeParse(tool_input)
+	if (!parsed.success) return []
+	const paths = [
+		...paths_matching(parsed.data.command, PATCH_FILE_PATTERN),
+		...paths_matching(parsed.data.command, PATCH_MOVE_PATTERN),
+	]
+
+	return [...new Set(paths)]
+}
+
+function canonical_payload(
+	payload: z.infer<typeof codex_payload_schema>,
+	file_path: string,
+	file_paths: ReadonlyArray<string>,
+): string {
+	return JSON.stringify({ ...payload, tool_name: EDIT_TOOL, tool_input: { file_path, file_paths } })
+}
+
+function pretool_payload(raw_payload: string): string {
+	const payload = parse_payload(raw_payload)
+	if (payload?.tool_name !== APPLY_PATCH_TOOL) return raw_payload
+	const paths = patch_paths(payload.tool_input)
+	const [file_path] = paths
+	if (file_path === undefined) return raw_payload
+
+	return canonical_payload(payload, file_path, paths)
+}
+
+function posttool_payloads(raw_payload: string): Array<string> {
+	const payload = parse_payload(raw_payload)
+	if (payload?.tool_name !== APPLY_PATCH_TOOL) return [raw_payload]
+
+	return patch_paths(payload.tool_input).map((file_path) =>
+		canonical_payload(payload, file_path, [file_path]),
+	)
+}
+
+function pretool_outcome(raw_payload: string): GuardOutcome {
+	return pretool_guard.pretool_outcome(pretool_payload(raw_payload))
+}
+
+// The formatters apply what eslint could fix silently and return what it could not; each patched
+// file's unfixed block is joined so the whole patch's lint problems reach the model on one edit
+// (joshuafolkken/kit#2275). `undefined` when every file was clean, so the ordinary patch adds nothing.
+async function format_posttool_payloads(
+	raw_payload: string,
+	project_root: string,
+	formatter: PayloadFormatter = format_edited_payload,
+): Promise<string | undefined> {
+	const planned = posttool_payloads(raw_payload).slice(0, MAX_PARALLEL_FORMATS)
+	const results = await bounded_pool.bounded_map(planned, MAX_PARALLEL_FORMATS, async (payload) => {
+		return await formatter(payload, project_root)
+	})
+	const blocks = results.filter((block): block is string => block !== undefined)
+
+	return blocks.length === 0 ? undefined : blocks.join(DIAGNOSTIC_SEPARATOR)
+}
+
+// The density line and the unfixed-lint blocks reach the model the same way — as additionalContext on
+// this one hook — so they are joined into the single envelope a `PostToolUse` payload can carry rather
+// than written as two objects the harness could not parse.
+async function write_posttool_context(raw_payload: string): Promise<void> {
+	const notice = time_density_hook.density_notice(raw_payload)
+	const diagnostics = await format_posttool_payloads(raw_payload, process.cwd())
+	const context = compose_context(notice, diagnostics)
+
+	if (context !== undefined) process.stdout.write(`${build_envelope(context)}\n`)
+}
+
+async function run(raw_payload: string, mode: string): Promise<void> {
+	if (mode === PRETOOL_MODE) {
+		hook_decision.write_outcome(raw_payload, pretool_outcome)
+
+		return
+	}
+
+	if (mode === POSTTOOL_MODE) {
+		await write_posttool_context(raw_payload)
+
+		return
+	}
+
+	process.stderr.write(`codex-hook-adapter expects ${PRETOOL_MODE} or ${POSTTOOL_MODE}.\n`)
+	process.exitCode = 1
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	await run(await text(process.stdin), process.argv[MODE_ARGUMENT_INDEX] ?? '')
+}
+
+const codex_hook_adapter = {
+	format_posttool_payloads,
+	patch_paths,
+	posttool_payloads,
+	pretool_outcome,
+	pretool_payload,
+}
+
+export { codex_hook_adapter }

package/scripts/hooks/edited-cspell.ts

@@ -0,0 +1,128 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { execa } from 'execa'
+
+// The spell half of the edit hook (joshuafolkken/kit#2296). joshuafolkken/kit#2275 gave the hook a way
+// to hand the model an edit's lint problems on the spot rather than at the gate; the gate then still
+// ran two extra times on average, and an unregistered word was one of the two things that put it there
+// — a `cspell:dot` failure a run could only read one word at a time under the output cap. Checking the
+// one edited file for unknown words the moment it changes closes that the same way the lint half does:
+// a short `additionalContext` block, riding the same `PostToolUse` envelope, and no output at all when
+// there is nothing to say.
+
+// **The kinds worth spell-checking on an edit.** cspell will lint any path handed to it, so without a
+// filter an edit to a binary asset would be read as text and report its bytes as unknown words. This is
+// the text where a real unknown word can live; anything else is a no-op before a process starts. It is
+// a spell-check concern of its own, not the prettier/eslint extension lists in `format-edited-file.ts`.
+const CSPELL_EXTENSIONS: ReadonlySet<string> = new Set([
+	'.ts',
+	'.tsx',
+	'.js',
+	'.jsx',
+	'.mjs',
+	'.cjs',
+	'.svelte',
+	'.md',
+	'.mdx',
+	'.txt',
+	'.json',
+	'.jsonc',
+	'.yml',
+	'.yaml',
+	'.html',
+	'.css',
+])
+
+// `lint` so the sub-command is explicit, `--words-only --unique` so stdout is the unknown words and
+// nothing else, `--no-progress --no-summary` so neither the progress line nor the tally is on it. The
+// exit code is ignored: cspell exits non-zero precisely when it found words, which is the case this
+// exists for.
+const CSPELL_ARGS: ReadonlyArray<string> = [
+	'exec',
+	'cspell',
+	'lint',
+	'--words-only',
+	'--unique',
+	'--no-progress',
+	'--no-summary',
+]
+const PNPM = 'pnpm'
+// A spell check that hangs would hold the edit's turn open; the bound is generous because reaching it
+// means something is already wrong, exactly as the formatter spawns in `format-edited-file.ts`.
+const PROCESS_TIMEOUT_MS = 15_000
+
+const HEADER =
+	'The edit hook found words cspell does not know; fix them or add them to `cspell.config.yaml` now rather than at the gate:'
+// additionalContext rides back on the edit, so a runaway list is bounded the same way the lint half is.
+const MAX_DIAGNOSTIC_CHARS = 4000
+const TRUNCATION_NOTICE = '\n…(unknown words truncated)'
+
+type CspellRunner = (file_path: string, project_root: string) => Promise<string>
+
+// One question before a process starts: is this a file under the project that spell-checking has
+// anything to say about?
+function is_checkable(file_path: string, project_root: string): boolean {
+	if (!existsSync(file_path) || !CSPELL_EXTENSIONS.has(path.extname(file_path).toLowerCase())) {
+		return false
+	}
+
+	const relative = path.relative(path.resolve(project_root), path.resolve(file_path))
+
+	return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative)
+}
+
+// The live runner. `reject: false` because a non-zero exit is the ordinary way cspell reports words,
+// and stderr is ignored so a config note never reaches the model as if it were an unknown word.
+async function run_cspell(file_path: string, project_root: string): Promise<string> {
+	const result = await execa(PNPM, [...CSPELL_ARGS, file_path], {
+		reject: false,
+		cwd: project_root,
+		stdout: 'pipe',
+		stderr: 'ignore',
+		timeout: PROCESS_TIMEOUT_MS,
+	})
+
+	return result.stdout
+}
+
+// The block the model reads, or `undefined` when cspell knew every word — so an ordinary edit adds
+// nothing to additionalContext. The words are cut to the bound before the header is added, so the cap
+// covers the whole block.
+function format_unknown_words(stdout: string): string | undefined {
+	const words = stdout
+		.split('\n')
+		.map((word) => word.trim())
+		.filter((word) => word.length > 0)
+
+	if (words.length === 0) return undefined
+
+	const joined = words.join('\n')
+	const body =
+		joined.length > MAX_DIAGNOSTIC_CHARS
+			? `${joined.slice(0, MAX_DIAGNOSTIC_CHARS)}${TRUNCATION_NOTICE}`
+			: joined
+
+	return `${HEADER}\n${body}`
+}
+
+// Never turns a successful edit into a failure: a runner that throws — cspell missing, a timeout — is
+// swallowed and reported as nothing to say, exactly as the lint half swallows a formatter that could
+// not start.
+async function spelling_diagnostics(
+	file_path: string | undefined,
+	project_root: string,
+	runner: CspellRunner = run_cspell,
+): Promise<string | undefined> {
+	if (file_path === undefined || !is_checkable(file_path, project_root)) return undefined
+
+	try {
+		return format_unknown_words(await runner(file_path, project_root))
+	} catch {
+		return undefined
+	}
+}
+
+const edited_cspell = { format_unknown_words, is_checkable, spelling_diagnostics }
+
+export type { CspellRunner }
+export { edited_cspell, MAX_DIAGNOSTIC_CHARS }

package/scripts/hooks/format-edited-file-fixtures.ts

@@ -0,0 +1,109 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { plan_commands, type CommandRunner, type FormatCommand } from './format-edited-file'
+
+// Shared across the two `format-edited-file` suites so neither redefines the other's fixtures. The
+// per-suite temp directory stays in each test file — vitest isolates the files, so each evaluates
+// this module and its own `afterAll` teardown of its own `mkdtemp`.
+const PRETTIER = 'prettier'
+const ESLINT = 'eslint'
+
+// What a formatter that ran and had nothing to say returns, so a test runner reads as "this route
+// worked" and no fallback is attempted.
+const RAN_CLEANLY = { exit_code: 0, stdout: '' }
+
+function payload_for(file_path: string): string {
+	return JSON.stringify({
+		hook_event_name: 'PostToolUse',
+		tool_input: { file_path },
+		tool_name: 'Edit',
+	})
+}
+
+// What Claude Code hands this hook after a shell call, which the matcher covers since
+// joshuafolkken/kit#1337: a command, and no edited path anywhere in the payload. The command edits a
+// file on purpose — an agent working through `sed` is the mode the widening was measured against,
+// and nothing here may start formatting a path it had to guess at.
+function shell_payload(transcript_path?: string): string {
+	return JSON.stringify({
+		tool_name: 'Bash',
+		tool_input: { command: `sed -i '' s/a/b/ app.ts` },
+		transcript_path,
+	})
+}
+
+function eslint_failing_runner(runs: Array<string>): CommandRunner {
+	return async (command) => {
+		await Promise.resolve()
+
+		if (command.bin === ESLINT) throw new Error('spawn ENOENT')
+
+		runs.push(command.bin)
+
+		return RAN_CLEANLY
+	}
+}
+
+const failing_runner: CommandRunner = async () => {
+	await Promise.resolve()
+	throw new Error('the formatter failed to start')
+}
+
+function recording_runner(runs: Array<string>): CommandRunner {
+	return async (command) => {
+		runs.push(command.bin)
+
+		await Promise.resolve()
+
+		return RAN_CLEANLY
+	}
+}
+
+// eslint exits non-zero with its problems on stdout when a `--fix` pass leaves something it could
+// not fix; prettier runs cleanly. This is the shape the hook has to lift the diagnostics out of.
+function eslint_reporting_runner(stdout: string): CommandRunner {
+	return async (command) => {
+		await Promise.resolve()
+
+		if (command.bin === ESLINT) return { exit_code: 1, stdout }
+
+		return RAN_CLEANLY
+	}
+}
+
+interface DirectoryHelpers {
+	write_fixture: (...segments: ReadonlyArray<string>) => string
+	plan_commands_in: (file_path: string) => ReadonlyArray<FormatCommand>
+}
+
+// Bound to a suite's own temp directory so the call sites stay `write_fixture('app.ts')`. The nested
+// functions close over `directory`, so they cannot be hoisted to module scope.
+function make_directory_helpers(directory: string): DirectoryHelpers {
+	function write_fixture(...segments: ReadonlyArray<string>): string {
+		const file_path = path.join(directory, ...segments)
+
+		mkdirSync(path.dirname(file_path), { recursive: true })
+		writeFileSync(file_path, '\n', 'utf8')
+
+		return file_path
+	}
+
+	function plan_commands_in(file_path: string): ReadonlyArray<FormatCommand> {
+		return plan_commands(file_path, directory)
+	}
+
+	return { write_fixture, plan_commands_in }
+}
+
+export {
+	eslint_failing_runner,
+	eslint_reporting_runner,
+	failing_runner,
+	make_directory_helpers,
+	payload_for,
+	recording_runner,
+	shell_payload,
+	ESLINT,
+	PRETTIER,
+	RAN_CLEANLY,
+}