@joshuafolkken/kit 1.872.0

package/scripts/build/build-hooks.ts

@@ -0,0 +1,79 @@
+#!/usr/bin/env tsx
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { build } from 'esbuild'
+
+const PACKAGE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+const OUT_DIR = path.join(PACKAGE_DIR, 'dist', 'hooks')
+
+// Each Claude Code hook is bundled to its own `dist/hooks/<name>.js`, so a consumer (and kit itself)
+// invokes `node dist/hooks/<name>.js` directly — no `pnpm` launch and no `tsx` re-spawn from the
+// `dist/josh.js` dispatcher (joshuafolkken/kit#2023).
+//
+// **`splitting: true` is load-bearing, not an optimization.** Every hook module decides whether to
+// run its main from `process.argv[1] === fileURLToPath(import.meta.url)`. A single-file bundle would
+// collapse every imported module's `import.meta.url` to the one output path, so a call to
+// `node dist/hooks/pretool-guard.js` would fire the self-invoke of `batch-guard` and
+// `investigation-guard` too — each reads stdin, and the second read gets an empty payload. Code
+// splitting keeps every entry in its own file with its own `import.meta.url`, so an imported guard's
+// `import.meta.url` never equals `argv[1]` and only the file actually launched runs its main.
+//
+// `packages: 'external'` keeps bare dependencies as runtime imports the consumer resolves from kit's
+// node_modules, exactly as the library bundles do, while kit's internal `#scripts/*` graph is inlined.
+// No shebang banner is added: unlike `dist/josh.js` (the `bin.josh` entry, executed directly), a hook
+// bundle is always launched as `node <path>`.
+interface HookBundle {
+	source: string
+	out: string
+}
+
+// The three settings.json hooks, the Codex input adapter, and the three guards `pretool-guard`
+// composes: `batch-guard`, `investigation-guard` and `duplicate-read-guard` each self-invoke, so they
+// must be their own entries to keep their `import.meta.url` out of `pretool-guard`'s file.
+// `delivered-rules` (the fourth guard) has no self-invoke, so it stays inlined.
+const HOOK_BUNDLES: ReadonlyArray<HookBundle> = [
+	{ source: 'scripts/hooks/codex-hook-adapter.ts', out: 'codex-hook-adapter' },
+	{ source: 'scripts/hooks/pretool-guard.ts', out: 'pretool-guard' },
+	{ source: 'scripts/hooks/stop-guard.ts', out: 'stop-guard' },
+	{ source: 'scripts/hooks/format-edited-file.ts', out: 'format-edited' },
+	{ source: 'scripts/josh/session-language-cli.ts', out: 'session-lang' },
+	{ source: 'scripts/hooks/batch-guard.ts', out: 'batch-guard' },
+	{ source: 'scripts/delegation/investigation-guard.ts', out: 'investigation-guard' },
+	{ source: 'scripts/delegation/duplicate-read-guard.ts', out: 'duplicate-read-guard' },
+]
+
+function entry_point(bundle: HookBundle): { in: string; out: string } {
+	return { in: path.join(PACKAGE_DIR, bundle.source), out: bundle.out }
+}
+
+function outfile_for(bundle: HookBundle): string {
+	return path.join(OUT_DIR, `${bundle.out}.js`)
+}
+
+async function build_hooks(): Promise<void> {
+	await build({
+		entryPoints: HOOK_BUNDLES.map((bundle) => entry_point(bundle)),
+		outdir: OUT_DIR,
+		bundle: true,
+		splitting: true,
+		platform: 'node',
+		format: 'esm',
+		target: 'node22',
+		packages: 'external',
+	})
+}
+
+async function main(): Promise<void> {
+	try {
+		await build_hooks()
+		for (const bundle of HOOK_BUNDLES) console.info(`  ✔ ${outfile_for(bundle)} built`)
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error))
+		process.exit(1)
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export type { HookBundle }
+export { build_hooks, HOOK_BUNDLES, OUT_DIR, outfile_for }

package/scripts/build/build-library.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env tsx
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { build } from 'esbuild'
+import { rollup, type Plugin } from 'rollup'
+import { dts } from 'rollup-plugin-dts'
+
+const PACKAGE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+const SCRIPTS_IMPORT_PREFIX = '#scripts/'
+
+interface LibraryPaths {
+	entry_point: string
+	outfile: string
+	dts_file: string
+}
+
+// Resolve the source entry and compiled outputs for a public library named `<name>`: source at
+// `scripts/<name>/index.ts`, bundled to `dist/<name>/index.{js,d.ts}` (mirrors the `./<name>`
+// package.json export). Shared by every per-library build script so the layout is single-sourced.
+function library_paths(name: string): LibraryPaths {
+	const output_directory = path.join(PACKAGE_DIR, 'dist', name)
+
+	return {
+		entry_point: path.join(PACKAGE_DIR, 'scripts', name, 'index.ts'),
+		outfile: path.join(output_directory, 'index.js'),
+		dts_file: path.join(output_directory, 'index.d.ts'),
+	}
+}
+
+// Bundle a library to a single runtime `.js`. `packages: 'external'` keeps bare dependencies
+// (js-yaml, execa, zod, …) as runtime imports the consumer resolves from kit's own node_modules,
+// while kit's internal `#scripts/*` graph is inlined — so a consumer can keep the library external
+// and avoid bundling kit's whole transitive graph.
+async function build_library_js(entry_point: string, outfile: string): Promise<void> {
+	await build({
+		entryPoints: [entry_point],
+		outfile,
+		bundle: true,
+		platform: 'node',
+		format: 'esm',
+		target: 'node22',
+		packages: 'external',
+	})
+}
+
+// rollup resolves bare specifiers and relative paths, but not kit's `#scripts/*` subpath imports
+// (declared in package.json `imports`). Map them to absolute source so rollup-plugin-dts follows
+// and inlines their types instead of leaving an unresolvable `#scripts/*` import in the output.
+function resolve_scripts_imports(): Plugin {
+	return {
+		name: 'resolve-scripts-imports',
+		resolveId(source: string): string | undefined {
+			if (!source.startsWith(SCRIPTS_IMPORT_PREFIX)) return undefined
+			const relative = source.slice(SCRIPTS_IMPORT_PREFIX.length)
+
+			return path.join(PACKAGE_DIR, 'scripts', `${relative}.ts`)
+		},
+	}
+}
+
+// Emit a single self-contained `index.d.ts` with no `#scripts/*` references, so a NodeNext
+// consumer type-checks against the compiled output without bundling or extensionless-import errors.
+async function build_library_dts(entry_point: string, dts_file: string): Promise<void> {
+	const bundle = await rollup({
+		input: entry_point,
+		plugins: [resolve_scripts_imports(), dts()],
+	})
+
+	await bundle.write({ file: dts_file, format: 'es' })
+	await bundle.close()
+}
+
+async function build_library(name: string): Promise<LibraryPaths> {
+	const paths = library_paths(name)
+
+	await build_library_js(paths.entry_point, paths.outfile)
+	await build_library_dts(paths.entry_point, paths.dts_file)
+
+	return paths
+}
+
+export type { LibraryPaths }
+export { build_library, library_paths }

package/scripts/build/build-managed-marker.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { build_library, library_paths } from './build-library'
+
+const MANAGED_MARKER_LIBRARY = 'managed-marker'
+const { outfile: MANAGED_MARKER_OUTFILE, dts_file: MANAGED_MARKER_DTS_FILE } =
+	library_paths(MANAGED_MARKER_LIBRARY)
+
+async function build_managed_marker_library(): Promise<void> {
+	await build_library(MANAGED_MARKER_LIBRARY)
+}
+
+async function main(): Promise<void> {
+	try {
+		await build_managed_marker_library()
+		console.info(`  ✔ ${MANAGED_MARKER_OUTFILE} built`)
+		console.info(`  ✔ ${MANAGED_MARKER_DTS_FILE} built`)
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error))
+		process.exit(1)
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { build_managed_marker_library, MANAGED_MARKER_OUTFILE, MANAGED_MARKER_DTS_FILE }

package/scripts/build/build-self-sync-guard.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { build_library, library_paths } from './build-library'
+
+const SELF_SYNC_GUARD_LIBRARY = 'self-sync-guard'
+const { outfile: SELF_SYNC_GUARD_OUTFILE, dts_file: SELF_SYNC_GUARD_DTS_FILE } =
+	library_paths(SELF_SYNC_GUARD_LIBRARY)
+
+async function build_self_sync_guard_library(): Promise<void> {
+	await build_library(SELF_SYNC_GUARD_LIBRARY)
+}
+
+async function main(): Promise<void> {
+	try {
+		await build_self_sync_guard_library()
+		console.info(`  ✔ ${SELF_SYNC_GUARD_OUTFILE} built`)
+		console.info(`  ✔ ${SELF_SYNC_GUARD_DTS_FILE} built`)
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error))
+		process.exit(1)
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { build_self_sync_guard_library, SELF_SYNC_GUARD_OUTFILE, SELF_SYNC_GUARD_DTS_FILE }

package/scripts/build/build-version.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { build_library, library_paths } from './build-library'
+
+const VERSION_LIBRARY = 'version'
+const { outfile: VERSION_OUTFILE, dts_file: VERSION_DTS_FILE } = library_paths(VERSION_LIBRARY)
+
+async function build_version_library(): Promise<void> {
+	await build_library(VERSION_LIBRARY)
+}
+
+async function main(): Promise<void> {
+	try {
+		await build_version_library()
+		console.info(`  ✔ ${VERSION_OUTFILE} built`)
+		console.info(`  ✔ ${VERSION_DTS_FILE} built`)
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error))
+		process.exit(1)
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { build_version_library, VERSION_OUTFILE, VERSION_DTS_FILE }

package/scripts/build/local-bin.ts

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { package_bin_schema } from '#scripts/lib/schemas'
+
+const NODE_MODULES = 'node_modules'
+const BIN_DIR = '.bin'
+const WINDOWS_PLATFORM = 'win32'
+const WINDOWS_SHIM_SUFFIX = '.cmd'
+const PACKAGE_JSON = 'package.json'
+
+// Every spawn site that reaches for a locally-installed CLI needs the same two details: pnpm
+// writes the shims under `node_modules/.bin`, and on Windows the executable one carries a
+// `.cmd` suffix (execa resolves and escapes that shim itself, so no `shell` option is needed).
+// Resolving it here keeps the spawn sites — josh's tsx runner, `josh init`'s lefthook install,
+// the secretlint pre-commit scan and the cspell distribution guard — from drifting apart. The
+// lefthook one had already lost the `.cmd` suffix, so it failed to spawn on Windows.
+function resolve_local_bin(project_root: string, bin_name: string): string {
+	const shim =
+		process.platform === WINDOWS_PLATFORM ? `${bin_name}${WINDOWS_SHIM_SUFFIX}` : bin_name
+
+	return path.join(project_root, NODE_MODULES, BIN_DIR, shim)
+}
+
+// pnpm finds a shim by walking up from the working directory, so a caller that resolved only the
+// directory it was invoked in would disagree with the very commands it spawns — `josh gate` typed
+// in `src/lib` would miss the toolkit its sibling checks resolve fine (joshuafolkken/kit#934).
+// Ascending for the shim itself, rather than for a `package.json` first, is what keeps the two in
+// step: a nested manifest that owns no `node_modules` is not where pnpm would stop either.
+function ancestor_directories(start_directory: string): ReadonlyArray<string> {
+	const directories: Array<string> = []
+	let current = start_directory
+
+	while (!directories.includes(current)) {
+		directories.push(current)
+		current = path.dirname(current)
+	}
+
+	return directories
+}
+
+function find_local_bin_upwards(start_directory: string, bin_name: string): string | undefined {
+	return ancestor_directories(start_directory)
+		.map((directory) => resolve_local_bin(directory, bin_name))
+		.find((candidate) => existsSync(candidate))
+}
+
+// The string form of `bin` names exactly one executable, and its name is the package's own — so it
+// answers only when that is the name being asked for. Reading it unconditionally would hand back
+// `tsc`'s entry for a request for `tsserver`, which is a wrong path rather than a missing one.
+// The name npm gives that executable is the *unscoped* one: `@scope/name` installs a `name` shim,
+// so the comparison is against the basename or a scoped package's string form would never answer.
+function read_bin_entry(
+	manifest_path: string,
+	package_name: string,
+	bin_name: string,
+): string | undefined {
+	const { bin } = package_bin_schema.parse(JSON.parse(readFileSync(manifest_path, 'utf8')))
+
+	if (typeof bin === 'string') return bin_name === path.basename(package_name) ? bin : undefined
+
+	return bin?.[bin_name]
+}
+
+// The other way to reach a dependency's CLI: node's own resolution rather than the generated
+// `node_modules/.bin` shim. Two failures make this the route that works where the shim does not.
+// pnpm writes a shim only for a project's *direct* dependencies, so a CLI this kit depends on has
+// none in a consumer's tree — resolving it from this package's own directory finds it anyway. And
+// pnpm's shim hardcodes the store path of the version present when it was written: after a bump the
+// old store entry is pruned but the shim is not regenerated, so spawning it dies with
+// MODULE_NOT_FOUND (joshuafolkken/kit#668). Returns the CLI entry to hand `process.execPath`, or
+// nothing when the package, its `bin` field or the entry on disk is missing — every caller has a
+// slower route to fall back to, so a failure here is never thrown.
+// One constraint worth knowing before adding a caller: this reads the target's manifest through
+// `<package>/package.json`, which a package whose `exports` map omits that subpath refuses with
+// ERR_PACKAGE_PATH_NOT_EXPORTED. That arrives here as `undefined` like any other miss, so the caller
+// degrades to its slower route silently rather than reporting why.
+function resolve_package_bin(
+	base_directory: string,
+	package_name: string,
+	bin_name: string,
+): string | undefined {
+	try {
+		const resolve_from = createRequire(path.join(base_directory, PACKAGE_JSON))
+		const manifest_path = resolve_from.resolve(`${package_name}/${PACKAGE_JSON}`)
+		const bin_entry = read_bin_entry(manifest_path, package_name, bin_name)
+		if (bin_entry === undefined) return undefined
+
+		const cli_entry = path.join(path.dirname(manifest_path), bin_entry)
+
+		return existsSync(cli_entry) ? cli_entry : undefined
+	} catch {
+		return undefined
+	}
+}
+
+export { find_local_bin_upwards, resolve_local_bin, resolve_package_bin }

package/scripts/build/shim-shell.ts

@@ -0,0 +1,25 @@
+// The two `sh` fragments both unit-suite shims are built from. Single-sourced because a guard's own
+// defects fail **open**: a path that lost its quoting leaves the shim a syntax error that records
+// nothing, and a `printf` that lost its `>>` truncates the record every call — in either case the
+// run is reported clean while the calls keep going out. One spelling, used by every generator, is
+// what keeps that impossible to get wrong in only one of them.
+
+const SINGLE_QUOTE = "'"
+
+// One `sh` word, quoted. A checkout under `/Users/o'brien` is not exotic, and an unquoted path there
+// would close the quote and leave the rest of the line as syntax.
+function quoted(value: string): string {
+	// `sh` has no escape inside single quotes, so an apostrophe is written by closing the quote,
+	// emitting an escaped one, and opening a new quote: `'\''`.
+	return SINGLE_QUOTE + value.replaceAll("'", String.raw`'\''`) + SINGLE_QUOTE
+}
+
+// Append one line of prose to the shared record. `>>` rather than `>`, because every worker of the
+// run writes to the same file and the last one must not erase what the others found.
+function record_line(log_file: string, recorded: string): string {
+	return String.raw`printf '%s\n' "${recorded}" >> ${quoted(log_file)}`
+}
+
+const shim_shell = { quoted, record_line }
+
+export { shim_shell }

package/scripts/bytes/bytes-command.ts

@@ -0,0 +1,181 @@
+#!/usr/bin/env tsx
+import { existsSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { document_byte_budget } from '#scripts/document/document-byte-budget'
+import { entry_read_budget } from '#scripts/document/entry-read-budget'
+
+// The package root, resolved from this file rather than the caller's working directory.
+const REPO_ROOT = fileURLToPath(new URL('../../', import.meta.url))
+
+// `josh bytes` — the byte counterpart of `josh lines` (joshuafolkken/kit#2176). A mandated
+// documentation update that grows an agent-read document past its byte ceiling is invisible until
+// `pnpm josh gate` reports it 80–90 seconds in, and the raise that follows is rework. This answers
+// the same question before that: how many bytes each budgeted document already has, its ceiling, and
+// how many are left — the number to check right after an edit.
+//
+// **It reports and never fails**, exactly as `josh lines` does. The ceiling is the gate's to enforce
+// (and `josh lint:related` now enforces it early, sharing `document-byte-budget.ts`); a second
+// command exiting non-zero on the same condition would be a second enforcement point, which is how a
+// headroom report turns into a way to reinterpret the gate. A non-zero exit here means the arguments
+// were unusable, never that a document is large.
+
+const ARGV_START = 2
+const ROW_GAP = '  '
+// The no-argument scan's answer when nothing sits near its ceiling — a defined "none" rather than an
+// empty output that would read as a broken command.
+const NONE_NEAR = 'no document near its byte ceiling'
+// A path argument that names no agent-read document has no ceiling to be counted against — the budget
+// covers exactly those documents, and quoting a limit for anything else would answer a question
+// nobody asked.
+const NOT_BUDGETED = 'not counted: no byte budget for this path'
+// A path argument the tree does not hold: a typo, or a document that was removed.
+const NOT_A_FILE = 'not counted: no file at this path'
+
+interface DocumentStatus {
+	path: string
+	current: number
+	recorded: number
+	remaining: number
+}
+
+function status_of(
+	relative_path: string,
+	recorded: number,
+	root: string = REPO_ROOT,
+): DocumentStatus {
+	const current = statSync(path.join(root, relative_path)).size
+	const remaining = document_byte_budget.remaining_bytes(recorded, current)
+
+	return { path: relative_path, current, recorded, remaining }
+}
+
+// An over-budget row names the number to record — the next block multiple, the same value
+// `over_budget_message` states; an in-budget row names the headroom left, so a reader sees the margin
+// before spending it.
+function status_body(status: DocumentStatus): string {
+	const ceiling = status.recorded.toString()
+	const current = status.current.toString()
+	const next = document_byte_budget.block_ceiling(status.current).toString()
+
+	if (status.remaining < 0) {
+		return `${current}/${ceiling} bytes · over by ${(-status.remaining).toString()} — raise recorded to ${next}`
+	}
+
+	return `${current}/${ceiling} bytes · ${status.remaining.toString()} left`
+}
+
+function status_row(status: DocumentStatus): string {
+	return `${status.path}${ROW_GAP}${status_body(status)}`
+}
+
+// A leading `./` is stripped so a path typed the way it reads on screen matches the repository-root
+// spelling the budget records; anything else is compared as given.
+function normalized_path(argument: string): string {
+	return argument.startsWith('./') ? argument.slice('./'.length) : argument
+}
+
+function argument_row(argument: string, root: string = REPO_ROOT): string {
+	const relative_path = normalized_path(argument)
+	const recorded = document_byte_budget.recorded_bytes_for(relative_path)
+
+	if (recorded === undefined) return `${relative_path}${ROW_GAP}${NOT_BUDGETED}`
+	if (!existsSync(path.join(root, relative_path))) return `${relative_path}${ROW_GAP}${NOT_A_FILE}`
+
+	return status_row(status_of(relative_path, recorded, root))
+}
+
+// A document is "near its ceiling" once less than this is left before its recorded block ceiling —
+// the point where the next addition tips it over and forces a deterministic bump. Display-only, so it
+// is this command's own dial rather than the ratchet's block size.
+const NEAR_CEILING_BYTES = 512
+
+// The scan reports the documents nearing their ceiling — less than `NEAR_CEILING_BYTES` of headroom
+// left before the next block bump — least headroom first, so an over-budget document sorts ahead of
+// one that merely has little room left. A document freshly recorded to its block sits with the whole
+// block of headroom and is left out, so the scan surfaces what is moving toward its ceiling rather
+// than the whole budget.
+function near_ceiling_statuses(root: string = REPO_ROOT): ReadonlyArray<DocumentStatus> {
+	return document_byte_budget.DOCUMENT_BYTE_BUDGET.filter((entry) =>
+		existsSync(path.join(root, entry.path)),
+	)
+		.map((entry) => status_of(entry.path, entry.bytes, root))
+		.filter((status) => status.remaining < NEAR_CEILING_BYTES)
+		.toSorted((left, right) => left.remaining - right.remaining)
+}
+
+interface EntryStatus {
+	entry: string
+	current: number
+	recorded: number
+	remaining: number
+}
+
+function entry_status_of(entry: string, recorded: number): EntryStatus {
+	const current = entry_read_budget.entry_total_bytes(REPO_ROOT, entry)
+	const remaining = document_byte_budget.remaining_bytes(recorded, current)
+
+	return { entry, current, recorded, remaining }
+}
+
+function remaining_phrase(remaining: number): string {
+	return remaining < 0 ? `over by ${(-remaining).toString()}` : `${remaining.toString()} left`
+}
+
+// The primary budget, one row per entry: the total each workflow entry reads against its recorded
+// ceiling and the headroom left — printed on every scan, so the main budget is no longer a number the
+// gate reveals only when it fails (joshuafolkken/kit#2271).
+function entry_row(status: EntryStatus): string {
+	const counts = `${status.current.toString()}/${status.recorded.toString()} bytes`
+
+	return `entry ${status.entry}${ROW_GAP}${counts} · ${remaining_phrase(status.remaining)}`
+}
+
+function entry_rows(): ReadonlyArray<string> {
+	return entry_read_budget.ENTRY_READ_BUDGET.map((one) =>
+		entry_row(entry_status_of(one.entry, one.bytes)),
+	)
+}
+
+function scan_lines(): ReadonlyArray<string> {
+	const near = near_ceiling_statuses().map((status) => status_row(status))
+
+	return [near.length === 0 ? NONE_NEAR : near.join('\n'), ...entry_rows()]
+}
+
+function run_scan(): number {
+	process.stdout.write(`${scan_lines().join('\n')}\n`)
+
+	return 0
+}
+
+function run_arguments(command_arguments: ReadonlyArray<string>): number {
+	const rows = command_arguments.map((argument) => argument_row(argument))
+
+	process.stdout.write(`${rows.join('\n')}\n`)
+
+	return 0
+}
+
+function run_bytes(command_arguments: ReadonlyArray<string>): number {
+	return command_arguments.length === 0 ? run_scan() : run_arguments(command_arguments)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = run_bytes(process.argv.slice(ARGV_START))
+}
+
+const bytes_command = {
+	argument_row,
+	entry_row,
+	entry_rows,
+	near_ceiling_statuses,
+	run_bytes,
+	scan_lines,
+	status_row,
+	NONE_NEAR,
+	NOT_A_FILE,
+	NOT_BUDGETED,
+}
+
+export { bytes_command }

package/scripts/cases/cases-cli.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { cases, type Boundary } from './cases-logic'
+
+// `josh cases <path...>` — print the I/O boundaries the changed paths cross and the abnormal cases
+// each owes (joshuafolkken/kit#2246). The boundary tokens go on stdout so `$(pnpm josh cases …)` reads
+// them; the required cases go on stderr so a person sees them without a shell parsing around them.
+// The logic and the vocabulary live in `cases-logic.ts`; everything here is the invocation.
+
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh cases <path...>'
+const FAILURE_EXIT_CODE = 1
+
+function report_none(): number {
+	console.info(cases.NONE)
+	console.error('no network, process, filesystem or time boundary crossed')
+
+	return 0
+}
+
+function report_boundaries(boundaries: ReadonlyArray<Boundary>): number {
+	console.info(boundaries.join(' '))
+	console.error(`required abnormal cases: ${cases.cases_for(boundaries).join(' / ')}`)
+
+	return 0
+}
+
+function run(argv: ReadonlyArray<string>): number {
+	if (argv.length === 0) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const boundaries = cases.boundaries_in(argv)
+
+	return boundaries.length === 0 ? report_none() : report_boundaries(boundaries)
+}
+
+function main(argv: ReadonlyArray<string>): void {
+	process.exitCode = run(argv)
+}
+
+const cases_cli = { USAGE, main, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
+
+export { cases_cli }