@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/git/stash/stash-pop-cli.ts

@@ -1,7 +1,6 @@
-import { fileURLToPath } from 'node:url'
 import { error_text } from '#scripts/lib/error-message'
 import { git_stash } from './git-stash'
-import { stash_pop_args, type Request } from './stash-pop-args'
+import { stash_args, type Request } from './stash-args'
 
 // `josh stash:pop "<message>"` — pop the stash whose message matches, and no other.
 // The stash stack is shared by every working tree of the repository, so a
@@ -9,6 +8,8 @@ import { stash_pop_args, type Request } from './stash-pop-args'
 // selector from the message and pops that entry alone; no match and more than one match are both
 // refusals rather than a guess at which was meant.
 
+const COMMAND = 'stash:pop'
+
 const POPPED_VERDICT = 'popped'
 const CONFLICTED_VERDICT = 'conflicted'
 const NO_MATCH_VERDICT = 'no-match'
@@ -16,7 +17,6 @@ const AMBIGUOUS_VERDICT = 'ambiguous'
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 
 function report(verdict: string, detail: string, code: number): number {
 	console.info(verdict)
@@ -26,7 +26,7 @@ function report(verdict: string, detail: string, code: number): number {
 }
 
 function refuse(): number {
-	console.error(stash_pop_args.USAGE)
+	console.error(stash_args.usage(COMMAND))
 
 	return FAILURE_EXIT_CODE
 }
@@ -73,11 +73,11 @@ function report_unknown(error: unknown): number {
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
-	const parsed = stash_pop_args.read_arguments(argv)
+	const parsed = stash_args.read_arguments(argv)
 
 	if (parsed === undefined) return refuse()
 
-	const request = stash_pop_args.to_request(parsed)
+	const request = stash_args.to_request(parsed)
 
 	if (request === undefined) return refuse()
 
@@ -88,10 +88,6 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	}
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const stash_pop_cli = {
 	AMBIGUOUS_VERDICT,
 	CONFLICTED_VERDICT,
@@ -100,6 +96,4 @@ const stash_pop_cli = {
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export { stash_pop_cli }

package/scripts/git/stash/stash-pop-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { stash_pop_cli } from './stash-pop-cli'
+
+// The `josh stash:pop` entry, kept apart from `stash-pop-cli.ts` because `latest-if-required-cli.ts`
+// imports that one: a bundle is one file, so a main guard there would fire for every command that
+// carries it (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await stash_pop_cli.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/git/stash/stash-push-cli.ts

@@ -0,0 +1,76 @@
+import { error_text } from '#scripts/lib/error-message'
+import { git_stash } from './git-stash'
+import { stash_args, type Request } from './stash-args'
+
+// `josh stash:push "<message>"` — the one way a workflow sets its working tree aside, paired with
+// `josh stash:pop "<message>"` that brings it back. Two rules fix what it takes:
+//
+// - **Untracked files go with it (`-u`).** Work in progress almost always includes a new, untracked
+//   `*.test.ts`; a stash that leaves it behind leaves it for the next `pnpm josh ms` to refuse.
+// - **The observation ledger stays** — every path `observation_ledger.is_ledger_path` names, legacy
+//   ones included (`git_stash.STASHABLE_PATHSPEC`). A run appends its own lines to `.josh/observations/` and they
+//   ride on that run's commit; a stash would take them off the tree before the commit or the
+//   batch-end flush could see them.
+//
+// A tree with nothing outside the ledger to set aside pushes nothing and says `clean`, so a procedure
+// can call it unconditionally and pop only after `stashed`.
+
+const COMMAND = 'stash:push'
+
+const STASHED_VERDICT = 'stashed'
+const CLEAN_VERDICT = 'clean'
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+
+function report(verdict: string, detail: string): number {
+	console.info(verdict)
+	console.error(detail)
+
+	return SUCCESS_EXIT_CODE
+}
+
+function refuse(): number {
+	console.error(stash_args.usage(COMMAND))
+
+	return FAILURE_EXIT_CODE
+}
+
+type PushVerdict = typeof STASHED_VERDICT | typeof CLEAN_VERDICT
+
+// The decision and the push without the printing, so a caller that chains a pop on `stashed`
+// (`josh latest:if-required`) reads the verdict instead of parsing stdout.
+async function set_aside(request: Request): Promise<PushVerdict> {
+	if (!(await git_stash.has_stashable_changes(request.dir))) return CLEAN_VERDICT
+
+	await git_stash.push(request.message, request.dir, git_stash.STASHABLE_PATHSPEC)
+
+	return STASHED_VERDICT
+}
+
+async function answer(request: Request): Promise<number> {
+	if ((await set_aside(request)) === CLEAN_VERDICT) {
+		return report(CLEAN_VERDICT, 'Nothing to stash.')
+	}
+
+	return report(STASHED_VERDICT, `Stashed as "${request.message}".`)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const parsed = stash_args.read_arguments(argv)
+	const request = parsed === undefined ? undefined : stash_args.to_request(parsed)
+
+	if (request === undefined) return refuse()
+
+	try {
+		return await answer(request)
+	} catch (error) {
+		console.error(error_text.message_of(error))
+
+		return FAILURE_EXIT_CODE
+	}
+}
+
+const stash_push_cli = { CLEAN_VERDICT, STASHED_VERDICT, run, set_aside }
+
+export { stash_push_cli }

package/scripts/git/stash/stash-push-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { stash_push_cli } from './stash-push-cli'
+
+// The `josh stash:push` entry, kept apart from `stash-push-cli.ts` because `run-pause.ts` and
+// `latest-if-required-cli.ts` import that one: a bundle is one file, so a main guard there would fire
+// for every command that carries it (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await stash_push_cli.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/hooks/batch-guard.ts

@@ -1,6 +1,3 @@
-#!/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'
@@ -54,16 +51,14 @@ 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`.
+// A guard the enumeration turns fully `off` says nothing at all. The lane-child mode and its reason
+// live in `lane-guard-policy.ts`; 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).
+// A refusable call is refused only where the mode is `refuse`. Under any other mode it is withheld the
+// refusal; why a lane child takes that mode is its `because` in `lane-guard-policy.ts`.
 function should_block_here(tail: string, call: GuardedCall, refused_at_ms: number): boolean {
 	if (batching_mode() !== 'refuse') return false
 
@@ -71,8 +66,7 @@ function should_block_here(tail: string, call: GuardedCall, refused_at_ms: numbe
 }
 
 // The whole-file write earns a notice on every run. 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
+// refusable call into a notice under a `notice`-mode guard. 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
@@ -124,11 +118,6 @@ const notice_refusal_path = hook_decision.create_refusal_stamp(
 ).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,

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

@@ -0,0 +1,8 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { run_check } from './check-commit-message'
+
+// The `josh check-commit-message` entry, kept apart from `check-commit-message.ts` because
+// `main-merge.ts` imports that one: a bundle is one file, so a main guard there would fire for every
+// command that carries it (joshuafolkken/kit#4186). The message file is read from `process.argv`.
+if (process.argv[1] === fileURLToPath(import.meta.url)) process.exitCode = await run_check()

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

@@ -1,8 +1,6 @@
-#!/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'
 import { issue_cite } from '#scripts/issue/issue-cite'
 
@@ -122,16 +120,15 @@ async function check_commit_message(): Promise<CheckResult> {
 	}
 }
 
-async function main(): Promise<void> {
+// The `commit-msg` hook's run: the check's message, and a failure exit when it refused.
+async function run_check(): Promise<number> {
 	const result = await check_commit_message()
 
 	console.info(result.message)
 
-	if (!result.success) process.exit(1)
+	return result.success ? 0 : 1
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
-
-export { check_commit_message, extract_issue_number, is_safe_commit_message_path }
+export { check_commit_message, extract_issue_number, is_safe_commit_message_path, run_check }
 
 export type { CheckResult }

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

@@ -1,11 +1,11 @@
 #!/usr/bin/env tsx
 import { existsSync } 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 { resolve_local_bin } from '#scripts/build/local-bin'
 import { ESLINT_EDIT_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
 import { json_value } from '#scripts/lib/json-value'
 import { HOOK_PROCESS_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { eslint_daemon } from '#scripts/lint/eslint-daemon'
 import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
 import { execa } from 'execa'
 import { z } from 'zod'
@@ -83,12 +83,8 @@ const ESLINT_ARGUMENTS: ReadonlyArray<string> = [
 // identical rather than merely similar. The config entry file is re-read per request; the modules it
 // imports are not, which `plan_daemon_restart` below is the answer to. The daemon exits after 15
 // minutes of inactivity.
-const ESLINT_DAEMON = 'eslint_d'
+const { ESLINT_DAEMON } = eslint_daemon
 const DAEMON_RESTART = 'restart'
-// The two shapes a flat config is built from here and in every consumer of this kit: the root
-// `eslint.config.*` entry, and the rule modules under `eslint/` that it imports.
-const ESLINT_CONFIG_DIR = 'eslint'
-const ESLINT_CONFIG_ENTRY = /^eslint\.config\.[cm]?[jt]s$/u
 
 // The problems eslint could not auto-fix are handed to the model verbatim from eslint's own stdout —
 // its default formatter already prints the file, the `line:col`, and the rule name. A header names what the block is, since additionalContext arrives
@@ -104,11 +100,6 @@ const DIAGNOSTIC_TRUNCATION_NOTICE = '\n…(diagnostics truncated)'
 // present.
 const SECTION_SEPARATOR = '\n\n'
 
-// Where this file sits inside the kit package. `eslint_d` is kit's dependency rather than the
-// consumer's, and pnpm writes a `node_modules/.bin` shim only for a project's *direct* dependencies,
-// so a consumer's project root cannot see it and this directory can.
-const MODULE_DIRECTORY = path.dirname(fileURLToPath(import.meta.url))
-
 interface FormatCommand {
 	bin: string
 	command_arguments: ReadonlyArray<string>
@@ -226,10 +217,7 @@ const DAEMON_BINS: ReadonlySet<string> = new Set([ESLINT_BIN, ESLINT_DAEMON])
 function resolve_daemon_cli(bin: string, project_root: string): string | undefined {
 	if (!DAEMON_BINS.has(bin)) return undefined
 
-	return (
-		resolve_package_bin(MODULE_DIRECTORY, ESLINT_DAEMON, ESLINT_DAEMON) ??
-		resolve_package_bin(project_root, ESLINT_DAEMON, ESLINT_DAEMON)
-	)
+	return eslint_daemon.resolve_daemon_cli(project_root)
 }
 
 // Only the config *entry file* is re-read per request: ESLint cache-busts `eslint.config.js` by
@@ -238,13 +226,6 @@ function resolve_daemon_cli(bin: string, project_root: string): string | undefin
 // and then any source file, and it would be auto-fixed against the pre-edit rules for as long as the
 // daemon lives — an author testing a rule change would read that as the rule being broken. Restarting
 // after an edit to a config input is what makes the whole config current, not just its first file.
-function is_eslint_config_input(relative_path: string): boolean {
-	return (
-		relative_path.split(path.sep)[0] === ESLINT_CONFIG_DIR ||
-		ESLINT_CONFIG_ENTRY.test(relative_path)
-	)
-}
-
 function plan_daemon_restart(
 	file_path: string,
 	project_root: string,
@@ -253,7 +234,7 @@ function plan_daemon_restart(
 
 	if (
 		relative === undefined ||
-		!is_eslint_config_input(relative) ||
+		!eslint_daemon.is_config_input(relative) ||
 		resolve_daemon_cli(ESLINT_DAEMON, project_root) === undefined
 	) {
 		return []
@@ -392,8 +373,11 @@ async function format_edited_file(
 		...plan_commands(file_path, project_root),
 		...plan_daemon_restart(file_path, project_root),
 	]
+	const daemon_before = eslint_daemon.read_record(project_root)
 	const unfixed = await collect_unfixed(plan, runner, project_root)
 
+	eslint_daemon.remember_started(project_root, daemon_before)
+
 	return format_diagnostics(unfixed === '' ? undefined : unfixed)
 }
 

package/scripts/hooks/pre-commit-lint.ts

@@ -0,0 +1,118 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { core_budget } from '#scripts/gate/core-budget'
+import {
+	CSPELL_COMMIT_CACHE_FLAGS,
+	ESLINT_COMMIT_CACHE_FILE,
+	ESLINT_COMMIT_CACHE_FLAGS,
+	PRETTIER_CACHE_FLAGS,
+} from '#scripts/josh/josh-command-types'
+import { FAIL_EXIT_CODE } from '#scripts/lib/buffered-process'
+import { resolve_spawn_exit } from '#scripts/lib/spawn-exit'
+import { eslint_cache_dependencies } from '#scripts/lint/eslint-cache-dependencies'
+import { eslint_daemon } from '#scripts/lint/eslint-daemon'
+import { execa } from 'execa'
+
+// The pre-commit hook's cspell, prettier and eslint runs over the staged files. They go through here
+// rather than a bare `pnpm exec` in `lefthook/base.yml` so each cache location comes from the
+// constant its ignore rules are asserted against (joshuafolkken/kit#3948) — a YAML copy would keep
+// writing the old file the day that constant moves.
+//
+// cspell and eslint write the hook's own files: a staged-files cspell run prunes every entry it did
+// not visit, and `--quiet` stores eslint reports without their warnings. Prettier does neither, so
+// it shares the gate's file and a commit right after a green gate checks nothing twice.
+
+const ARGV_OFFSET = 2
+const USAGE_ERROR_EXIT_CODE = 2
+const PNPM = 'pnpm'
+const ESLINT = 'eslint'
+
+const TOOL_ARGUMENTS: Readonly<Record<string, ReadonlyArray<string>>> = {
+	cspell: [
+		'exec',
+		'cspell',
+		'lint',
+		'--no-must-find-files',
+		'--no-progress',
+		...CSPELL_COMMIT_CACHE_FLAGS,
+	],
+	prettier: ['exec', 'prettier', '--check', '--ignore-unknown', ...PRETTIER_CACHE_FLAGS],
+	eslint: ['exec', 'eslint', '--quiet', ...ESLINT_COMMIT_CACHE_FLAGS],
+}
+
+// **Each tool claims its place in the core budget** (joshuafolkken/kit#3944): lefthook starts the three
+// in parallel, and off the ledger every other lane's admission saw them only as foreign load. Each is
+// one process over the staged files — eslint over 40 of them took 16.9s of CPU over 14.0s of wall at
+// 1,225 MB, the one-process shape the whole-tree scan's weight already names.
+// The key is the one `CORE_WEIGHTS` and `MEMORY_MB` both declare the tool under.
+const TOOL_BUDGETS: Readonly<Record<string, 'spell_check' | 'format' | 'eslint_scan'>> = {
+	cspell: 'spell_check',
+	prettier: 'format',
+	eslint: 'eslint_scan',
+}
+
+const USAGE = `Usage: josh pre-commit-lint <${Object.keys(TOOL_ARGUMENTS).join('|')}> [files...]`
+
+function build_arguments(
+	tool: string,
+	staged_files: ReadonlyArray<string>,
+): ReadonlyArray<string> | undefined {
+	const tool_arguments = TOOL_ARGUMENTS[tool]
+	if (tool_arguments === undefined) return undefined
+
+	return [...tool_arguments, ...staged_files]
+}
+
+// eslint goes through the lane's warm daemon when one is reachable (joshuafolkken/kit#4358): the same
+// argument list and the same cache file, without paying the config and plugin load per commit. It
+// runs inside the tool's core-budget reservation like the cold route does.
+//
+// A merge or checkout can change only the files a staged file imports, and the content cache keeps
+// the staged file's verdict: its entry is dropped first when they changed (joshuafolkken/kit#4415).
+async function run_eslint(command_arguments: ReadonlyArray<string>): Promise<number> {
+	const result = await eslint_cache_dependencies.guard(
+		ESLINT_COMMIT_CACHE_FILE,
+		async () => await eslint_daemon.run_or_cold(command_arguments),
+	)
+	if (result.output !== '') process.stdout.write(result.output)
+
+	return result.exit_code ?? FAIL_EXIT_CODE
+}
+
+async function run_tool(command_arguments: ReadonlyArray<string>): Promise<number> {
+	const result = await execa(PNPM, command_arguments, { stdio: 'inherit', reject: false })
+
+	return resolve_spawn_exit(PNPM, result)
+}
+
+async function run_reserved(tool: string, staged_files: ReadonlyArray<string>): Promise<number> {
+	const command_arguments = build_arguments(tool, staged_files) ?? []
+	if (tool === ESLINT) return await run_eslint(command_arguments)
+
+	return await run_tool(command_arguments)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const [tool = '', ...staged_files] = argv
+	const budget = TOOL_BUDGETS[tool]
+
+	if (budget === undefined) {
+		console.error(USAGE)
+
+		return USAGE_ERROR_EXIT_CODE
+	}
+
+	return await core_budget.with_command_reservation(
+		core_budget.CORE_WEIGHTS[budget],
+		async () => await run_reserved(tool, staged_files),
+		{ memory_mb: core_budget.MEMORY_MB[budget], command: `pre-commit ${tool}` },
+	)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run(process.argv.slice(ARGV_OFFSET))
+}
+
+const pre_commit_lint = { build_arguments, run, USAGE_ERROR_EXIT_CODE }
+
+export { pre_commit_lint }

package/scripts/hooks/pre-push-unit.ts

@@ -130,10 +130,12 @@ function format_miss(reason: string): string {
 // as foreign load (joshuafolkken/kit#3874). Only the miss reserves: a reused record runs nothing, and a
 // claim there could make a push wait out a full ledger for a suite it then skips.
 async function run_reserved_suite(vitest_arguments: ReadonlyArray<string>): Promise<number> {
+	const claim = gate_plan.DIRECT_UNIT_CLAIM
+
 	return await core_budget.with_command_reservation(
-		gate_plan.direct_unit_weight(),
+		claim.core_weight(),
 		async () => await test_unit_guard.run_guarded_unit(process.cwd(), vitest_arguments),
-		{ memory_mb: gate_plan.direct_unit_memory() },
+		{ memory_mb: claim.memory_mb(), command: 'pre-push test:unit', is_unit: claim.is_unit_claim },
 	)
 }
 

package/scripts/hooks/pretool-guard-cli.ts

@@ -1,5 +1,4 @@
 #!/usr/bin/env tsx
-import { text } from 'node:stream/consumers'
 import { fileURLToPath } from 'node:url'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { pretool_guard } from './pretool-guard'
@@ -11,11 +10,5 @@ import { pretool_guard } from './pretool-guard'
 // `dist/hooks/pretool-guard.js`, so the bundled hook ran no guard at all and every refusal failed open.
 // An entry nothing imports keeps the self-invoke in the file that is actually launched.
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	if (process.stdin.isTTY) hook_decision.report_no_payload('pretool:guard')
-	else {
-		const raw_payload = await text(process.stdin)
-
-		hook_decision.load_environment_file()
-		await pretool_guard.respond(raw_payload)
-	}
+	await hook_decision.respond_from_stdin('pretool:guard', pretool_guard.respond)
 }