@joshuafolkken/kit 1.872.0

package/scripts/josh/josh-commands-split.ts

@@ -0,0 +1,20 @@
+import type { CommandEntry } from './josh-command-types'
+
+// The `split:assess` command registry, split out of `josh-commands-ai.ts` so that file stays under its
+// 300-code-line limit, exactly as `LANE_COMMANDS` was for the same reason (joshuafolkken/kit#2162,
+// joshuafolkken/kit#2218). It is spread into `AI_COMMANDS` so the command stays grouped with the other
+// decision oracles under the 'AI tools' category.
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const SPLIT_COMMANDS: Record<string, CommandEntry> = {
+	'split:assess': {
+		script: 'scripts/split/split-assess-cli.ts',
+		description:
+			'Measure the branch change size (tests excluded) and answer the split assessment size question: split | single',
+		category: 'AI tools',
+		reference: ['[--json]', 'automation', ['none']],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { SPLIT_COMMANDS }

package/scripts/josh/josh-commands-versioning.ts

@@ -0,0 +1,48 @@
+import type { CommandEntry } from './josh-command-types'
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const VERSIONING_COMMANDS: Record<string, CommandEntry> = {
+	bump: {
+		script: 'scripts/version/bump-version.ts',
+		description: 'Bump package version',
+		category: 'Versioning',
+		reference: ['[major|minor|patch]', 'maintainer', ['files']],
+	},
+	version: {
+		script: 'scripts/version/version-check.ts',
+		description: 'Show kit versions; --upgrade updates the global and project install',
+		category: 'Versioning',
+		reference: ['[--upgrade]', 'developer', ['files', 'network', 'processes']],
+	},
+	// A `script` entry, not a shell one: script paths resolve against the kit package root, so this
+	// keeps working from a consumer repo where the file lives under node_modules. The registry
+	// probes need NODE_AUTH_TOKEN for any `@joshuafolkken/*` dependency; `josh latest` exports it
+	// before chaining here, exactly as it already does for `latest:update`.
+	ranges: {
+		script: 'scripts/version/publishable-range-check.ts',
+		description: 'Check that every published dependency range still resolves for a consumer',
+		category: 'Versioning',
+		reference: ['', 'developer', ['network']],
+	},
+	// The one place that decides a version (joshuafolkken/kit#1169). A `script` entry for the same
+	// reason `ranges` is one: script paths resolve against the kit package root, so it keeps working
+	// from a consumer repository where the file lives under node_modules.
+	release: {
+		script: 'scripts/release/release-cli.ts',
+		description: 'Release the merges main has taken since the version last changed',
+		category: 'Versioning',
+		reference: ['[version]', 'maintainer', ['git', 'network', 'release']],
+	},
+	// The read-only half of the one above (joshuafolkken/kit#1582). `release --dry-run` cannot
+	// answer this question: it refuses off the default branch and on a dirty tree, which is every
+	// position a run asks it from. A `script` entry for the same reason `release` is one.
+	'release:scope': {
+		script: 'scripts/release/release-scope-cli.ts',
+		description: 'Say whether a release is owed, from the unreleased merges on main',
+		category: 'Versioning',
+		reference: ['[--json]', 'automation', ['none']],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { VERSIONING_COMMANDS }

package/scripts/josh/josh-commands-workflow.ts

@@ -0,0 +1,116 @@
+import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
+
+const GIT_WORKFLOW_SCRIPT = 'scripts-ai/git-workflow.ts'
+const GIT_MESSAGE_ARGUMENTS = '[-y] <message>'
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
+	git: {
+		script: GIT_WORKFLOW_SCRIPT,
+		description: 'Git workflow helper',
+		category: 'Workflow',
+		reference: [GIT_MESSAGE_ARGUMENTS, 'developer', ['git', 'network']],
+	},
+	pr: {
+		script: GIT_WORKFLOW_SCRIPT,
+		description: 'Create PR only (skip commit and push)',
+		category: 'Workflow',
+		// Not `GIT_MESSAGE_ARGUMENTS`: `-y` is already in the default arguments below, so advertising
+		// it would document a flag that cannot change what this command does.
+		reference: ['<message>', 'developer', ['network']],
+		default_script_arguments: ['-y', '--skip-commit', '--skip-push'],
+	},
+	// **The optional form, on both** (joshuafolkken/kit#1564). These two were the last commands
+	// passing the mandatory `--env-file=.env`, which node resolves before the script's first line: on
+	// a machine with no `.env` they died as `.env: not found` with exit code 9, even where
+	// `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` existed as real environment variables — a cloud
+	// session, and `followup` with them the merge step of every `fullrun` there. `doctor` was moved to
+	// this form for the same reason in joshuafolkken/kit#869.
+	//
+	// Nothing is lost by relaxing it: both scripts already call `load_optional_environment()`
+	// themselves, so the file is read either way and node's precedence — an existing environment
+	// variable wins over the file — is node's own in both spellings.
+	//
+	// **What the mandatory flag was accidentally providing was noise**, and that is replaced rather
+	// than dropped: `telegram_notify.send` now throws on missing credentials and on a failed send, so
+	// `josh notify` exits non-zero instead of warning and answering 0.
+	followup: {
+		script: 'scripts-ai/git-followup-workflow.ts',
+		description: 'Follow-up git workflow',
+		category: 'Workflow',
+		reference: [
+			'<title> [--notify-message <text>]',
+			'automation',
+			['git', 'network', 'notifications'],
+		],
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+	},
+	notify: {
+		script: 'scripts-ai/telegram-test.ts',
+		description: 'Send Telegram notification',
+		category: 'Workflow',
+		reference: ['--task-type <type> --body <text>', 'automation', ['notifications']],
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+	},
+	// The observation ledger's only commit path (joshuafolkken/kit#1756). `pnpm josh git` excludes the
+	// ledger from what it stages, so without this command a parent's appended line has no route to the
+	// default branch at all — and the recurrence count the promotion rule reads is a count of main.
+	'observations:flush': {
+		script: 'scripts/observations/observations-flush-cli.ts',
+		description: 'Commit the observation ledger as a pull request of its own, and merge it',
+		category: 'Workflow',
+		reference: ['', 'automation', ['git', 'network']],
+	},
+	// The one write path for a `/code-review` round's findings (joshuafolkken/kit#2325), plus the
+	// `--check` gate `followup` runs before it merges (joshuafolkken/kit#2343). It appends a `- rf:`
+	// line per finding — or one zero-finding line for a clean round — to the observation ledger, so
+	// `observations:flush` commits them and the recurrence count survives the run.
+	'review:record': {
+		script: 'scripts/review/review-record-cli.ts',
+		description: 'Record a review round’s findings, or check a round was recorded',
+		category: 'Workflow',
+		reference: [
+			'--issue <N> [<category>:<severity>:<file> ...] | --check --issue <N>',
+			'automation',
+			['files'],
+		],
+	},
+	// The reader over what `review:record` wrote (joshuafolkken/kit#2325): each recurring category’s
+	// count, and the number of zero-finding rounds that distinguishes a quiet category from an unwatched one.
+	'review:findings': {
+		script: 'scripts/review/review-findings-cli.ts',
+		description: 'Count review findings by category from the observation ledger',
+		category: 'Workflow',
+		reference: ['', 'developer', ['files']],
+	},
+	// After a behavior-change Issue merges, re-run its declared baseline and print before/after; a value
+	// that did not move appends a refuted-premise line to the observation ledger (joshuafolkken/kit#2212).
+	'measure:rerun': {
+		script: 'scripts/issue/measure-rerun-cli.ts',
+		description: 'Re-run a merged issue’s baseline command and print the before/after pair',
+		category: 'Workflow',
+		reference: ['<path>', 'automation', ['processes', 'files']],
+	},
+	// A script rather than an `sh -c` chain, because it has a precondition to enforce: run inside a
+	// linked work tree it would hijack the default branch from every other one (joshuafolkken/kit#1535).
+	'main:sync': {
+		script: 'scripts/git/main-sync.ts',
+		description:
+			'Checkout default branch, pull latest, and prune merged remote-gone branches (refuses inside a lane)',
+		category: 'Workflow',
+		reference: ['', 'developer', ['git', 'network']],
+	},
+	// A script rather than an `sh -c` chain, because the strategy has to be named rather than left to
+	// the caller's git configuration: the `git pull` this replaced aborted with `Need to specify how
+	// to reconcile divergent branches` on exactly the diverged branch the command exists for
+	// (joshuafolkken/kit#1659).
+	'main:merge': {
+		script: 'scripts/git/main-merge.ts',
+		description: 'Merge origin default branch into the current branch',
+		category: 'Workflow',
+		reference: ['', 'developer', ['git', 'network']],
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { WORKFLOW_COMMANDS }

package/scripts/josh/josh-composite-arguments.ts

@@ -0,0 +1,55 @@
+import type { CommandEntry } from './josh-command-types'
+
+const SHELL_INTERPRETERS: ReadonlySet<string> = new Set(['sh', 'bash', 'zsh', 'dash'])
+const SHELL_COMMAND_FLAG = '-c'
+const PATH_SEPARATOR = '/'
+const USAGE_ERROR_EXIT_CODE = 1
+
+// The interpreter is matched on its basename so an absolute path counts too: `/bin/sh -c` behaves
+// exactly like `sh -c`, and the repo already spells it both ways.
+function is_shell_interpreter(executable: string): boolean {
+	return SHELL_INTERPRETERS.has(executable.split(PATH_SEPARATOR).at(-1) ?? executable)
+}
+
+// `sh -c '<script>'` turns anything appended into the shell's positional parameters. The script
+// string never expands them, so the arguments vanish without a word — `josh test --workers=1`
+// reads as a serial run while the suite stays parallel, and a green or red result is attributed
+// to a configuration that was never applied. Detecting the shape instead of tagging each command
+// is what makes this permanent: a composite added later cannot reopen the hole by forgetting to
+// opt in. Non-composite entries (`pnpm exec prettier --check .`) append to the real tool and
+// forward correctly, so they keep doing so.
+function is_composite_shell(shell: ReadonlyArray<string> | undefined): boolean {
+	const [executable, flag] = shell ?? []
+	if (executable === undefined) return false
+
+	return is_shell_interpreter(executable) && flag === SHELL_COMMAND_FLAG
+}
+
+function format_targets(targets: ReadonlyArray<string>): string {
+	return targets.map((target) => `josh ${target}`).join(' or ')
+}
+
+function format_rejection(cmd: string, targets: ReadonlyArray<string>): string {
+	const hint =
+		targets.length > 0
+			? `pass them to ${format_targets(targets)} instead`
+			: 'it runs a fixed sequence and forwards nothing'
+
+	return `josh ${cmd} takes no extra arguments — ${hint}`
+}
+
+// Returns the message to print, or undefined when the invocation is fine. Keeping the decision
+// separate from the printing lets the rule be asserted without capturing console output.
+function reject_extra_arguments(
+	cmd: string,
+	entry: CommandEntry,
+	extra: ReadonlyArray<string>,
+): string | undefined {
+	if (extra.length === 0 || !is_composite_shell(entry.shell)) return undefined
+
+	return format_rejection(cmd, entry.argument_targets ?? [])
+}
+
+const composite_arguments = { format_rejection, is_composite_shell, reject_extra_arguments }
+
+export { composite_arguments, USAGE_ERROR_EXIT_CODE }

package/scripts/josh/josh-environment-file.ts

@@ -0,0 +1,31 @@
+import { ENV_FILE_NAME } from '#ports'
+
+// Loading `.env` from inside a command, for the commands that must stay in-process.
+//
+// **The flag form is what most commands use, and it is not free.** Declaring any `tsx_arguments`
+// disqualifies a command from in-process dispatch (`josh-in-process.ts`), which puts a second
+// ~0.16 s tsx start in front of every call — the hot path joshuafolkken/kit#1342 took it off. A
+// command a hook fires on every `Bash` call, or one an unattended `epicrun` polls every sixty
+// seconds, cannot pay that, so it reads the file itself instead.
+//
+// `process.loadEnvFile` is node's own `--env-file` parser and keeps node's precedence: a value
+// already in the environment wins over the file's. A missing or unreadable file is swallowed,
+// exactly as `--env-file-if-exists` does.
+//
+// **Call it only on the real command path** — inside the `import.meta.url` guard, or the hook's own
+// entry — never from a function a unit test calls, so a developer's own `.env` cannot decide what
+// the tests see.
+function load_environment_file(): void {
+	try {
+		process.loadEnvFile(ENV_FILE_NAME)
+	} catch {
+		// No `.env` beside this project, or one this process may not read. The caller then reads from
+		// the environment alone, which is what it did before any file existed.
+	}
+}
+
+const josh_environment_file = {
+	load_environment_file,
+}
+
+export { josh_environment_file }

package/scripts/josh/josh-in-process.ts

@@ -0,0 +1,80 @@
+import { realpathSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+import type { CommandEntry } from './josh-command-types'
+
+// `pnpm josh <script command>` started tsx twice — once for this dispatcher, once for the script it
+// spawned. Measured on 2026-09-04, the second start was about 0.16 s of the 0.55 s a
+// `pnpm josh format:edited` took, and the edit/Bash hook pays it 60–90 times in a single run
+// (joshuafolkken/kit#1342). The script is ordinary TypeScript and a TypeScript loader is already
+// installed by the time this file runs, so the dispatcher evaluates the script itself instead.
+const TYPESCRIPT_EXTENSION = '.ts'
+const FAILURE_EXIT_CODE = 1
+
+// The dispatcher may only load a `.ts` script in its own process when it was itself loaded as
+// TypeScript — which is exactly the condition under which a loader capable of it is present. A
+// consumer runs the bundled `dist/josh.js` under plain node, whose `import.meta.url` ends in `.js`,
+// so that install keeps the spawning path unchanged rather than failing on a module node cannot
+// load at all.
+function is_typescript_dispatcher(dispatcher_url: string): boolean {
+	return dispatcher_url.endsWith(TYPESCRIPT_EXTENSION)
+}
+
+// `tsx_arguments` are node flags the script needs *before* its own code runs — today every one of
+// them a form of `--env-file`, which has no in-process equivalent that reproduces node's own
+// parsing and precedence. Those commands (`doctor`, `latest:scope`, `followup`, `notify`) keep a
+// process of their own; each runs at most a few times per run, so none of them is where the cost
+// this saves accumulates.
+function can_run_in_process(entry: CommandEntry, dispatcher_url: string): boolean {
+	if (entry.script === undefined || entry.tsx_arguments !== undefined) return false
+
+	return is_typescript_dispatcher(dispatcher_url)
+}
+
+// `process.exitCode` is typed `number | string | undefined`. Only the numeric form is an exit code
+// this dispatcher can forward, and an unset one means the script finished without asking for one.
+function read_exit_code(): number {
+	const code = process.exitCode
+
+	return typeof code === 'number' ? code : 0
+}
+
+// ESM resolution follows symlinks, so the `import.meta.url` a script's guard compares against is
+// its real path. The argv this dispatcher builds has to be that same string: a checkout
+// reached through a symlink would otherwise import the script cleanly, run nothing and answer 0. A
+// path that cannot be resolved is left as it is, so the import below reports the failure.
+function resolve_real_path(script_path: string): string {
+	try {
+		return realpathSync(script_path)
+	} catch {
+		return script_path
+	}
+}
+
+// Every josh script decides whether to run its own main from
+// `process.argv[1] === fileURLToPath(import.meta.url)`, so the dispatcher's argv is replaced with
+// the one the spawned process would have had before the module is evaluated. It is deliberately not
+// restored afterwards: the script is the program from here on, and anything it deferred past module
+// evaluation would otherwise read the dispatcher's argv instead of its own.
+async function run_in_process(
+	script_path: string,
+	script_arguments: ReadonlyArray<string>,
+): Promise<number> {
+	const resolved_path = resolve_real_path(script_path)
+
+	process.argv = [process.execPath, resolved_path, ...script_arguments]
+
+	try {
+		await import(pathToFileURL(resolved_path).href)
+	} catch (error) {
+		// A spawned tsx printed the stack and exited 1; the same failure has to look the same here.
+		console.error(error)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return read_exit_code()
+}
+
+const josh_in_process = { can_run_in_process, run_in_process }
+
+export { FAILURE_EXIT_CODE, josh_in_process }

package/scripts/josh/josh-logic.ts

@@ -0,0 +1,308 @@
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { resolve_local_bin, resolve_package_bin } from '#scripts/build/local-bin'
+import { package_version_schema } from '#scripts/lib/schemas'
+import { resolve_spawn_exit } from '#scripts/lib/spawn-exit'
+import { execaSync } from 'execa'
+import { command_suggest } from './command-suggest'
+import {
+	ALIASES,
+	CATEGORY_ORDER,
+	COMMAND_MAP,
+	type CommandCategory,
+	type CommandEntry,
+} from './josh-command-map'
+import { composite_arguments, USAGE_ERROR_EXIT_CODE } from './josh-composite-arguments'
+import { josh_in_process } from './josh-in-process'
+import { kit_only } from './kit-only'
+
+const COLUMN_WIDTH = 26
+const ALIAS_PAD_WIDTH = 2
+const TSX_BIN = 'tsx'
+const TSX_PACKAGE = 'tsx'
+const PACKAGE_JSON = 'package.json'
+// Not an exit code the shell ever sees: `josh.ts` reads it as "no such command" and answers with
+// the listing on stderr. It is named because `run_command` now reports through a promise, where a
+// bare `-1` is one step further from the check that reads it.
+const UNKNOWN_COMMAND_EXIT_CODE = -1
+
+interface TsxRunner {
+	executable: string
+	leading_arguments: ReadonlyArray<string>
+}
+
+// Resolve the kit package root by ascending to the nearest package.json. This works both
+// from the bundled dist/josh.js (one level under the root) and from the tsx source at
+// scripts/josh/ (two levels), so this file's depth no longer has to be hard-coded.
+function find_package_directory(start_directory: string): string {
+	let current = start_directory
+
+	while (!existsSync(path.join(current, PACKAGE_JSON))) {
+		const parent = path.dirname(current)
+		if (parent === current) return start_directory
+		current = parent
+	}
+
+	return current
+}
+
+const PACKAGE_DIR = find_package_directory(path.dirname(fileURLToPath(import.meta.url)))
+
+function resolve_tsx_executable(): string {
+	const candidates = [
+		resolve_local_bin(PACKAGE_DIR, TSX_BIN),
+		resolve_local_bin(process.cwd(), TSX_BIN),
+	]
+
+	return candidates.find(existsSync) ?? TSX_BIN
+}
+
+// Locating the CLI entry through tsx's own manifest never consults pnpm's generated shim, which
+// hardcodes a store path a later bump prunes. The resolution itself is `resolve_package_bin` —
+// shared with the format hook's eslint route rather than written twice (joshuafolkken/kit#1259).
+function resolve_tsx_cli_entry(): string | undefined {
+	for (const base_directory of [PACKAGE_DIR, process.cwd()]) {
+		const cli_entry = resolve_package_bin(base_directory, TSX_PACKAGE, TSX_BIN)
+		if (cli_entry !== undefined) return cli_entry
+	}
+
+	return undefined
+}
+
+// Preferred: run the resolved CLI entry with the current node binary. The `.bin` shim lookup
+// stays as a fallback for layouts where tsx is not resolvable from either manifest.
+function resolve_tsx_runner(): TsxRunner {
+	const cli_entry = resolve_tsx_cli_entry()
+
+	if (cli_entry !== undefined) {
+		return { executable: process.execPath, leading_arguments: [cli_entry] }
+	}
+
+	return { executable: resolve_tsx_executable(), leading_arguments: [] }
+}
+
+function read_package_version(): string {
+	const raw = readFileSync(path.join(PACKAGE_DIR, PACKAGE_JSON), 'utf8')
+
+	return package_version_schema.parse(JSON.parse(raw)).version
+}
+
+const HEADER = `josh v${read_package_version()} — Joshua Folkken's dev toolkit`
+const USAGE = 'Usage: josh <command> [options]'
+const ALL_HINT = "Run 'josh --all' to list every available command."
+
+function build_alias_lookup(): Map<string, string> {
+	const lookup = new Map<string, string>()
+	for (const [alias, cmd] of Object.entries(ALIASES)) lookup.set(cmd, alias)
+
+	return lookup
+}
+
+function resolve_alias(cmd: string): string {
+	return Object.hasOwn(ALIASES, cmd) ? (ALIASES[cmd] ?? cmd) : cmd
+}
+
+function format_command_line(cmd: string, entry: CommandEntry, alias?: string): string {
+	const prefix = alias ? `${alias}, `.padEnd(ALIAS_PAD_WIDTH + ALIAS_PAD_WIDTH) : ''
+
+	return `  ${(prefix + cmd).padEnd(COLUMN_WIDTH)}${entry.description}`
+}
+
+function format_category_section(
+	category: CommandCategory,
+	entries: Array<[string, CommandEntry]>,
+	alias_lookup: Map<string, string>,
+): string {
+	const lines = entries.map(([cmd, entry]) =>
+		format_command_line(cmd, entry, alias_lookup.get(cmd)),
+	)
+
+	return [`${category}:`, ...lines].join('\n')
+}
+
+// The command reference owns the audience decision for both kit and consumer help.
+function is_visible_command(entry: CommandEntry, is_all: boolean, is_consumer: boolean): boolean {
+	if (is_consumer && kit_only.is_kit_only(entry)) return false
+
+	return is_all || entry.reference[1] === 'developer'
+}
+
+function collect_visible(
+	is_all: boolean,
+	is_consumer: boolean,
+): Map<CommandCategory, Array<[string, CommandEntry]>> {
+	const by_category = new Map<CommandCategory, Array<[string, CommandEntry]>>(
+		CATEGORY_ORDER.map((cat) => [cat, []]),
+	)
+
+	for (const [cmd, entry] of Object.entries(COMMAND_MAP)) {
+		if (is_visible_command(entry, is_all, is_consumer)) {
+			by_category.get(entry.category)?.push([cmd, entry])
+		}
+	}
+
+	return by_category
+}
+
+// A category left empty after audience filtering is dropped rather than printed as a bare heading.
+function format_help(is_all = false, is_consumer = false): string {
+	const by_category = collect_visible(is_all, is_consumer)
+	const alias_lookup = build_alias_lookup()
+	const sections = CATEGORY_ORDER.map((cat) => [cat, by_category.get(cat) ?? []] as const)
+		.filter(([, entries]) => entries.length > 0)
+		.map(([cat, entries]) => format_category_section(cat, entries, alias_lookup))
+	const footer = is_all ? USAGE : `${USAGE}\n${ALL_HINT}`
+
+	return [HEADER, '', sections.join('\n\n'), '', footer].join('\n')
+}
+
+// Every name a user could type — the canonical commands and their aliases — ranked by edit distance
+// so `josh gat` points at `gate` (joshuafolkken/kit#1928).
+function all_command_names(): Array<string> {
+	return [...Object.keys(COMMAND_MAP), ...Object.keys(ALIASES)]
+}
+
+// `josh <unknown>` answers on stderr with a short line rather than the whole listing. A shell
+// substituting `$(josh port dev)` captures stdout alone, so a name this kit cannot resolve — a typo,
+// a retired command — must leave that stream empty rather than dump the toolkit index there, how #825
+// surfaced. It used to print the full help here; #1928 cut that to one line plus a "did you mean"
+// when a close command exists, so the diagnosis is readable and the stdout contract is unchanged.
+// `josh` and `josh --help` still print the listing to stdout, because there it is the answer rather
+// than the diagnosis.
+function format_unknown_command(cmd: string): string {
+	const suggestion = command_suggest.closest_command(cmd, all_command_names())
+	const hint = suggestion === undefined ? '' : ` Did you mean '${suggestion}'?`
+
+	return `Unknown command: ${cmd}.${hint} Run 'josh --help' for common commands or 'josh --all' for the full list.`
+}
+
+// A `.cmd` shim needs the win32 shell to be executable, but the node binary does not — and
+// running it through the shell would break on the spaces in a typical Windows install path.
+function should_use_shell(executable: string): boolean {
+	return process.platform === 'win32' && executable !== process.execPath
+}
+
+function spawn_script(tsx_executable: string, script_arguments: Array<string>): number {
+	const result = execaSync(tsx_executable, script_arguments, {
+		stdio: 'inherit',
+		shell: should_use_shell(tsx_executable),
+		reject: false,
+	})
+
+	return resolve_spawn_exit(tsx_executable, result)
+}
+
+function run_shell_command(shell: ReadonlyArray<string>, extra: Array<string>): number {
+	const [executable = '', ...rest_arguments] = shell
+	const result = execaSync(executable, [...rest_arguments, ...extra], {
+		stdio: 'inherit',
+		reject: false,
+	})
+
+	return resolve_spawn_exit(executable, result)
+}
+
+function spawn_script_entry(
+	entry: CommandEntry,
+	script_path: string,
+	script_arguments: ReadonlyArray<string>,
+): number {
+	const runner = resolve_tsx_runner()
+
+	return spawn_script(runner.executable, [
+		...runner.leading_arguments,
+		...(entry.tsx_arguments ?? []),
+		script_path,
+		...script_arguments,
+	])
+}
+
+// Only the in-process branch is genuinely asynchronous; the spawning one answers the moment the
+// child exits. Both are reported as a promise so every caller has one shape to handle, and
+// `josh.ts` awaits it either way (joshuafolkken/kit#1342).
+async function run_script_entry(
+	entry: CommandEntry,
+	subcommand_arguments: Array<string>,
+): Promise<number> {
+	const script_path = path.join(PACKAGE_DIR, entry.script ?? '')
+	const script_arguments = [...(entry.default_script_arguments ?? []), ...subcommand_arguments]
+
+	if (josh_in_process.can_run_in_process(entry, import.meta.url)) {
+		return await josh_in_process.run_in_process(script_path, script_arguments)
+	}
+
+	return spawn_script_entry(entry, script_path, script_arguments)
+}
+
+// The exit a command answers with before it runs, or `undefined` to go ahead: a consumer is refused a
+// kit-only command with guidance, and a composite command rejects extra arguments
+// (joshuafolkken/kit#1988).
+function pre_dispatch_exit(
+	resolved: string,
+	entry: CommandEntry,
+	subcommand_arguments: Array<string>,
+	is_consumer: boolean,
+): number | undefined {
+	if (is_consumer && kit_only.is_kit_only(entry)) {
+		console.error(kit_only.notice(resolved))
+
+		return USAGE_ERROR_EXIT_CODE
+	}
+
+	const rejection = composite_arguments.reject_extra_arguments(
+		resolved,
+		entry,
+		subcommand_arguments,
+	)
+	if (rejection === undefined) return undefined
+	console.error(rejection)
+
+	return USAGE_ERROR_EXIT_CODE
+}
+
+async function dispatch_entry(
+	entry: CommandEntry,
+	subcommand_arguments: Array<string>,
+): Promise<number> {
+	if (entry.shell) return run_shell_command(entry.shell, subcommand_arguments)
+
+	return await run_script_entry(entry, subcommand_arguments)
+}
+
+async function run_command(
+	cmd: string,
+	subcommand_arguments: Array<string>,
+	is_consumer = false,
+): Promise<number> {
+	const resolved = resolve_alias(cmd)
+	const entry = Object.hasOwn(COMMAND_MAP, resolved) ? COMMAND_MAP[resolved] : undefined
+
+	if (!entry) return UNKNOWN_COMMAND_EXIT_CODE
+
+	const early_exit = pre_dispatch_exit(resolved, entry, subcommand_arguments, is_consumer)
+	if (early_exit !== undefined) return early_exit
+
+	return await dispatch_entry(entry, subcommand_arguments)
+}
+
+const josh_logic = {
+	format_help,
+	format_unknown_command,
+	run_command,
+	spawn_script,
+	run_shell_command,
+}
+
+export type { CommandEntry } from './josh-command-map'
+export { ALIASES, COMMAND_MAP } from './josh-command-map'
+export { SPAWN_ERROR_EXIT_CODE } from '#scripts/lib/spawn-exit'
+export { composite_arguments, USAGE_ERROR_EXIT_CODE } from './josh-composite-arguments'
+export {
+	find_package_directory,
+	josh_logic,
+	resolve_alias,
+	resolve_tsx_executable,
+	resolve_tsx_runner,
+	UNKNOWN_COMMAND_EXIT_CODE,
+}