@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/josh/hook-decision.ts

@@ -1,4 +1,6 @@
+import { text } from 'node:stream/consumers'
 import { json_value } from '#scripts/lib/json-value'
+import { file_reader } from '#scripts/lib/read-file'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
 import { time_hook_transcript } from '#scripts/time-runtime/time-hook-transcript'
@@ -43,7 +45,6 @@ const ALLOW_DECISION = 'allow'
 // No record means nothing has been refused yet, and every span began after instant zero — which is
 // the answer wanted: the first qualifying accumulation of a run is refused.
 const NEVER_MS = 0
-const MISSING_FILE = 'ENOENT'
 
 // More than one spelling, because the mistake on this side is silent: a value meant to disable a
 // guard that the list does not recognize leaves it on, and the person sees refusals they asked to
@@ -69,9 +70,7 @@ function is_switch_opt_in(key: string): boolean {
 }
 
 function parse_hook_payload(raw_payload: string): HookPayload | undefined {
-	const parsed = payload_schema.safeParse(JSON.parse(raw_payload))
-
-	return parsed.success ? parsed.data : undefined
+	return json_value.parse_with(raw_payload, payload_schema)
 }
 
 // The documented shape a `PreToolUse` hook answers with. Plain stdout is not it — only this envelope
@@ -137,25 +136,19 @@ function stamp_fault(switch_key: string): string {
 	)
 }
 
-// **A transcript that does not exist yet is not a fault.** A delegated unit's own file is named before
-// anything is written under it, so a fork's first guarded calls read a path with no file behind it —
-// `time-hook-transcript.ts` states that "no history" is the honest verdict there. Reported as a fault
-// it would print on every early call of every fork, which is the routine case drowning the signal this
-// exists to raise.
-function is_missing_file(error: unknown): boolean {
-	if (!(error instanceof Error) || !('code' in error)) return false
-
-	return typeof error.code === 'string' && error.code === MISSING_FILE
-}
-
 function error_text(error: unknown): string {
 	if (error instanceof Error) return error.message
 
 	return typeof error === 'string' ? error : 'a value that is not an error'
 }
 
+// **A transcript that does not exist yet is not a fault.** A delegated unit's own file is named before
+// anything is written under it, so a fork's first guarded calls read a path with no file behind it —
+// `time-hook-transcript.ts` states that "no history" is the honest verdict there. Reported as a fault
+// it would print on every early call of every fork, which is the routine case drowning the signal this
+// exists to raise.
 function fault_notice(switch_key: string, error: unknown): string | undefined {
-	if (is_missing_file(error)) return undefined
+	if (file_reader.is_absent(error)) return undefined
 
 	const detail = error_text(error)
 
@@ -416,10 +409,10 @@ function create_transcript_guard(spec: TranscriptGuardSpec): TranscriptGuard {
 		return stamp.path(transcript_path)
 	}
 
-	// **Every failure allows the call.** A missing transcript, a payload that is not JSON, a
-	// half-written tail, a temp directory that cannot be written — each ends as "no refusal", for the
-	// same reason `format-edited-file.ts` swallows a formatter it could not start: a hook that failed
-	// closed would stop a run over its own plumbing.
+	// **Every failure allows the call.** An unreadable transcript, a half-written tail, a temp directory
+	// that cannot be written — each ends as "no refusal", for the same reason `format-edited-file.ts`
+	// swallows a formatter it could not start: a hook that failed closed would stop a run over its own
+	// plumbing. A payload that is not JSON names no call to judge, so it ends with no outcome at all.
 	//
 	// **What changed is that it no longer does so in silence**. The call still
 	// goes through — failing open is the right call and is not being revisited — but the fault comes
@@ -481,6 +474,24 @@ function report_no_payload(command: string): void {
 	)
 }
 
+// A hook entry's whole main: the hand-run notice from a terminal, else the payload on stdin handed to
+// `respond` once `.env` is loaded.
+async function respond_from_stdin(
+	command: string,
+	respond: (raw: string) => Promise<void> | void,
+): Promise<void> {
+	if (process.stdin.isTTY) {
+		report_no_payload(command)
+
+		return
+	}
+
+	const raw_payload = await text(process.stdin)
+
+	load_environment_file()
+	await respond(raw_payload)
+}
+
 const hook_decision = {
 	DISABLED_VALUES,
 	ENABLED_VALUES,
@@ -497,6 +508,7 @@ const hook_decision = {
 	notice_envelope,
 	parse_hook_payload,
 	report_no_payload,
+	respond_from_stdin,
 	rewrite_envelope,
 	stamp_fault,
 	write_decision,

package/scripts/josh/josh-aliases.ts

@@ -0,0 +1,95 @@
+// The `josh` subcommand aliases, in a leaf of their own (joshuafolkken/kit#5128).
+//
+// **A reader that only expands an alias imports no command table.** The table (`josh-command-map.ts`)
+// imports every command module, so a module that imported it for `canonical_command` alone — the shell
+// and bundle readers of `josh time` — carried every command module into each test that reached it, and
+// a one-line change to any command table re-ran hundreds of unrelated tests under `josh test:related`.
+
+const ALIASES: Record<string, string> = {
+	ga: 'gate',
+	l: 'lint',
+	lr: 'lint:related',
+	cr: 'check:related',
+	ln: 'lines',
+	by: 'bytes',
+	mt: 'metrics',
+	f: 'format',
+	sd: 'cspell:dot',
+	bh: 'behavior',
+	eu: 'exports:unused',
+	t: 'test',
+	tu: 'test:unit',
+	tr: 'test:related',
+	td: 'test:declared',
+	trd: 'test:red',
+	tpn: 'test:pinned',
+	te: 'test:e2e',
+	c: 'check',
+	pt: 'port',
+	i: 'init',
+	pf: 'profile',
+	st: 'start',
+	sy: 'sync',
+	un: 'uninstall',
+	g: 'git',
+	gp: 'pr',
+	ms: 'main:sync',
+	mm: 'main:merge',
+	bp: 'bump',
+	re: 'release',
+	v: 'version',
+	r: 'ranges',
+	dr: 'doctor',
+	rc: 'ruleset:check',
+	pg: 'propagate',
+	ad: 'adopt',
+	ov: 'overrides',
+	a: 'audit',
+	rt: 'reconcile-templates',
+	cdv: 'command:derive',
+	u: 'latest',
+	lc: 'latest:corepack',
+	lu: 'latest:update',
+	tm: 'time',
+	tmd: 'time:density',
+	rtr: 'retrospective',
+	ca: 'cost:audit',
+	rvf: 'review:findings',
+	rvs: 'review:stops',
+	ruv: 'rule:value',
+	ev: 'eval',
+	fr: 'fresh:run',
+	as: 'auth:setup',
+	lsm: 'lane:sample',
+	lst: 'lane:stats',
+	lva: 'lane:value',
+	lnt: 'lane:net',
+	lbd: 'lane:breakdown',
+	lli: 'lane:limit',
+	lrs: 'lane:restart',
+	lwd: 'lane:withdraw',
+	lps: 'lane:pause',
+	lru: 'lane:resume',
+	lad: 'lane:adopt',
+	blr: 'backlogrun',
+}
+
+// The canonical name of a `josh` subcommand: an alias expands, and anything else passes through
+// unchanged.
+//
+// **The expansion is one rule, so it lives beside the table it reads.** Two readers had each written
+// their own `ALIASES[name] ?? name` — the layer report and the gate-run count — and a third, the run
+// measurement's command key, had not, so `pnpm josh ga` and `pnpm josh gate` were measured as two
+// different commands. A lookup is small enough to copy and exactly the kind of copy that drifts: the
+// two that had it disagreed with the one that did not about whether a call was the gate.
+//
+// **`Object.hasOwn` rather than a bare lookup**, because a subcommand spelled like a member of
+// `Object.prototype` — `constructor`, `toString` — would otherwise come back as that member instead
+// of as itself, and the caller would key a call by something that is not a command name at all.
+function canonical_command(name: string): string {
+	if (!Object.hasOwn(ALIASES, name)) return name
+
+	return ALIASES[name] ?? name
+}
+
+export { ALIASES, canonical_command }

package/scripts/josh/josh-command-map.ts

@@ -31,83 +31,5 @@ const COMMAND_MAP: Record<string, CommandEntry> = {
 	...CLONE_COMMANDS,
 }
 
-const ALIASES: Record<string, string> = {
-	ga: 'gate',
-	l: 'lint',
-	lr: 'lint:related',
-	ln: 'lines',
-	by: 'bytes',
-	mt: 'metrics',
-	f: 'format',
-	sd: 'cspell:dot',
-	bh: 'behavior',
-	eu: 'exports:unused',
-	t: 'test',
-	tu: 'test:unit',
-	tr: 'test:related',
-	td: 'test:declared',
-	trd: 'test:red',
-	te: 'test:e2e',
-	c: 'check',
-	pt: 'port',
-	i: 'init',
-	pf: 'profile',
-	st: 'start',
-	sy: 'sync',
-	un: 'uninstall',
-	rmi: 'registry:migrate',
-	g: 'git',
-	gp: 'pr',
-	ms: 'main:sync',
-	mm: 'main:merge',
-	bp: 'bump',
-	re: 'release',
-	v: 'version',
-	r: 'ranges',
-	dr: 'doctor',
-	rc: 'ruleset:check',
-	pg: 'propagate',
-	ad: 'adopt',
-	ov: 'overrides',
-	a: 'audit',
-	rt: 'reconcile-templates',
-	u: 'latest',
-	lc: 'latest:corepack',
-	lu: 'latest:update',
-	tm: 'time',
-	tmd: 'time:density',
-	rtr: 'retrospective',
-	ca: 'cost:audit',
-	rvf: 'review:findings',
-	ruv: 'rule:value',
-	ev: 'eval',
-	fr: 'fresh:run',
-	as: 'auth:setup',
-	lsm: 'lane:sample',
-	lst: 'lane:stats',
-	lli: 'lane:limit',
-	lrs: 'lane:restart',
-	lwd: 'lane:withdraw',
-	blr: 'backlogrun',
-}
-
-// The canonical name of a `josh` subcommand: an alias expands, and anything else passes through
-// unchanged.
-//
-// **The expansion is one rule, so it lives beside the table it reads.** Two readers had each written
-// their own `ALIASES[name] ?? name` — the layer report and the gate-run count — and a third, the run
-// measurement's command key, had not, so `pnpm josh ga` and `pnpm josh gate` were measured as two
-// different commands. A lookup is small enough to copy and exactly the kind of copy that drifts: the
-// two that had it disagreed with the one that did not about whether a call was the gate.
-//
-// **`Object.hasOwn` rather than a bare lookup**, because a subcommand spelled like a member of
-// `Object.prototype` — `constructor`, `toString` — would otherwise come back as that member instead
-// of as itself, and the caller would key a call by something that is not a command name at all.
-function canonical_command(name: string): string {
-	if (!Object.hasOwn(ALIASES, name)) return name
-
-	return ALIASES[name] ?? name
-}
-
 export type { CommandCategory, CommandEntry } from './josh-command-types'
-export { ALIASES, CATEGORY_ORDER, COMMAND_MAP, canonical_command }
+export { CATEGORY_ORDER, COMMAND_MAP }

package/scripts/josh/josh-command-types.ts

@@ -56,7 +56,8 @@ interface CommandFlag {
 }
 
 // What `josh help <command>` prints and what the reference pages render between their usage
-// markers — one source for both, so the page and the terminal cannot disagree (#3932).
+// markers — one source for both, so the page and the terminal cannot disagree (#3932). Each command's
+// entry carries its own, so a command cannot be registered without one (#4185).
 interface CommandUsage {
 	examples: ReadonlyArray<CommandExample>
 	flags?: ReadonlyArray<CommandFlag>
@@ -68,6 +69,7 @@ interface CommandEntry {
 	description: string
 	category: CommandCategory
 	reference: CommandReference
+	usage: CommandUsage
 	tsx_arguments?: ReadonlyArray<string>
 	default_script_arguments?: ReadonlyArray<string>
 	// Composite (`sh -c`) commands reject extra CLI arguments instead of swallowing them; this
@@ -93,6 +95,8 @@ interface CommandEntry {
 	// The memory the command's tools hold, claimed with its cores; read like
 	// `core_weight`, and none declared is none waited for.
 	memory_mb?: number | (() => number)
+	// A unit suite's claim, whose weight is its worker count (`gate_plan.DIRECT_UNIT_CLAIM`).
+	is_unit_claim?: boolean
 }
 
 // The name `josh gate` registers under. It lives here rather than in `verification-gate.ts` so a
@@ -184,7 +188,7 @@ const GATE_CACHE_FILES: ReadonlyArray<string> = GATE_CACHE_SPECS.map((spec) => s
 // The `PostToolUse` edit hook runs eslint too, and ESLint *deletes* the file at `--cache-location`
 // whenever it is started without `--cache` — so a shared file would be wiped by every single edit,
 // leaving the gate a cold lint. The hook is given a location of its own rather than the
-// gate's because the two run at the same time: `josh gate` lints the whole tree beside the review
+// gate's because the two run at the same time: `josh gate` lints beside the review
 // while this hook fires on every edit, and each eslint run rewrites its cache file whole from the
 // copy it loaded at start-up — so two writers silently discard each other's entries. A file of its
 // own makes the hook structurally unable to degrade the cache this exists to protect.
@@ -193,7 +197,7 @@ const GATE_CACHE_FILES: ReadonlyArray<string> = GATE_CACHE_SPECS.map((spec) => s
 // true, and a single-file run against the gate's full cache was measured byte-identical, so a shared
 // file would keep the entries that run never visited.
 // The same reasoning for the scoped lint. `josh lint:related` is what an implementation loop calls
-// between edits, and `josh gate` lints the whole tree beside the review — so those two run at the
+// between edits, and `josh gate` lints beside the review — so those two run at the
 // same time as readily as the hook and the gate do. Whichever of a pair sharing one file wrote last
 // would replace it with "the copy I loaded at start-up plus what I visited", so a narrowed run
 // finishing during a whole-tree run would roll the cache back to its pre-gate state, and a
@@ -204,8 +208,8 @@ const GATE_CACHE_FILES: ReadonlyArray<string> = GATE_CACHE_SPECS.map((spec) => s
 // warm from its own second call onwards, and the gate's stays exactly as the gate left it.
 //
 // **The lint's target scope is untouched.** This is where a cache is written, not what is read:
-// `josh lint:related` narrows in front of the gate and `josh gate` still runs `josh lint` over the
-// whole tree before any commit. The scoped lint's prettier cache is its own for the same reason:
+// `josh lint:related` and the gate's `josh lint --changed` each narrow to the change, on caches of
+// their own. The scoped lint's prettier cache is its own for the same reason:
 // prettier rewrites its cache file whole as well.
 // What the ignore rules are asserted against: every cache file this package writes, wherever it is
 // written from. The gate's, the edit hook's, the scoped lint's and the pre-commit hook's — a cache
@@ -250,7 +254,8 @@ export type { CommandCategory, CommandEntry, CommandUsage, GateCacheSpec }
 // them per target: the lint step writes only the eslint one, so a target
 // that cleared the list would report a cold type check as the lint's own cost. The edit hook's cache
 // stays private; the scoped lint cache is exported because #2060 shares its completed file between
-// worktrees, but it still never overlaps the gate's distinct cache location.
+// worktrees, but it still never overlaps the gate's distinct cache location. The pre-commit hook's
+// eslint cache is exported because the hook re-reads a red report against it (#4407).
 export {
 	COMMAND_AUDIENCES,
 	COMMAND_SIDE_EFFECTS,
@@ -259,6 +264,7 @@ export {
 	CSPELL_COMMIT_CACHE_FLAGS,
 	ESLINT_CACHE_FILE,
 	ESLINT_CACHE_FLAGS,
+	ESLINT_COMMIT_CACHE_FILE,
 	ESLINT_COMMIT_CACHE_FLAGS,
 	ESLINT_EDIT_CACHE_FLAGS,
 	ESLINT_RELATED_CACHE_FLAGS,

package/scripts/josh/josh-commands-agent-hooks.ts

@@ -0,0 +1,83 @@
+import type { CommandEntry } from './josh-command-types'
+
+const PRE_TOOL_USE = 'run by the PreToolUse hook, the pending tool call as JSON on stdin'
+
+// The Claude Code and Codex hook commands, split out of `josh-commands-development.ts` when each
+// command's usage moved onto its entry (#4185). `DEV_COMMANDS` spreads this in at the same place, so
+// the map keeps its order.
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const AGENT_HOOK_COMMANDS: Record<string, CommandEntry> = {
+	'format:edited': {
+		script: 'scripts/hooks/format-edited-cli.ts',
+		description: 'Claude Code hook: format the file just edited (reads the tool call on stdin)',
+		category: 'Development',
+		reference: ['', 'automation', ['files', 'processes']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'run by the PostToolUse hook, the tool call as JSON on stdin' },
+			],
+		},
+	},
+	'pretool:guard': {
+		script: 'scripts/hooks/pretool-guard-cli.ts',
+		description:
+			'Claude Code hook: the batch, investigation and rule guards in one process (reads the tool call on stdin)',
+		category: 'Development',
+		reference: ['', 'automation', ['none']],
+		usage: { examples: [{ arguments: '', note: PRE_TOOL_USE }] },
+		// **No `tsx_arguments`, deliberately.** The guards read `.env` for their other values, as other
+		// commands do through `OPTIONAL_ENV_FILE_FLAGS`; the guard switches themselves come from the
+		// launch environment alone (`josh-environment-file.ts`). But declaring any `tsx_arguments`
+		// disqualifies a command from in-process dispatch (`josh-in-process.ts`), and this is the one PreToolUse hook consumers run
+		// before every guarded call, where a second ~0.16 s tsx start is not affordable. Each guard it
+		// composes loads `.env` through the shared loader instead.
+	},
+	'stop:guard': {
+		script: 'scripts/hooks/stop-guard.ts',
+		description:
+			'Claude Code Stop hook: send the hold notify and release the hold itself; block on the rules that need the model (reads the Stop payload on stdin)',
+		category: 'Development',
+		reference: ['', 'automation', ['none']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'run by the Stop hook, the stop payload as JSON on stdin' },
+			],
+		},
+		// **No `tsx_arguments`, deliberately**, the same as `pretool:guard` above: this runs at every
+		// turn end, so it must stay eligible for in-process dispatch rather than pay a second tsx start.
+		// It loads `.env` through the shared `hook-decision.ts` loader.
+	},
+	'session:lang': {
+		script: 'scripts/josh/session-language-main.ts',
+		description:
+			'Claude Code hook: print a non-default JOSH_SESSION_LANG for the session context, and the run:board reply rule while a backlogrun is live (otherwise nothing)',
+		category: 'Development',
+		reference: ['', 'automation', ['none']],
+		usage: {
+			examples: [{ arguments: '', note: 'run by the UserPromptSubmit hook; `ja` prints nothing' }],
+		},
+		// **No `tsx_arguments`, deliberately**, the same as `pretool:guard` above: this runs on every
+		// `UserPromptSubmit`, so it must stay eligible for in-process dispatch rather than pay a second
+		// tsx start each turn. It loads `.env` itself through the shared loader.
+	},
+	'codex:hook-adapter': {
+		script: 'scripts/hooks/codex-hook-adapter.ts',
+		description:
+			'Codex hook: run the pretool or posttool guard on a Codex payload (reads the tool call on stdin)',
+		category: 'Development',
+		reference: ['<pretool|posttool>', 'automation', ['none']],
+		usage: {
+			examples: [
+				{ arguments: 'pretool', note: 'a Codex PreToolUse payload on stdin' },
+				{ arguments: 'posttool', note: 'a Codex PostToolUse payload on stdin' },
+			],
+		},
+		// The live-source fallback `scripts/hooks/run-hook.sh` derives from the `codex-hook-adapter`
+		// bundle name. **No `tsx_arguments`**, the same as `pretool:guard`
+		// above: it runs before every guarded Codex call.
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { AGENT_HOOK_COMMANDS }