@joshuafolkken/kit 1.1471.0 → 1.1784.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-command-map.ts

@@ -47,6 +47,7 @@ const ALIASES: Record<string, string> = {
 	tr: 'test:related',
 	td: 'test:declared',
 	trd: 'test:red',
+	tpn: 'test:pinned',
 	te: 'test:e2e',
 	c: 'check',
 	pt: 'port',
@@ -55,7 +56,6 @@ const ALIASES: Record<string, string> = {
 	st: 'start',
 	sy: 'sync',
 	un: 'uninstall',
-	rmi: 'registry:migrate',
 	g: 'git',
 	gp: 'pr',
 	ms: 'main:sync',
@@ -77,7 +77,9 @@ const ALIASES: Record<string, string> = {
 	tm: 'time',
 	tmd: 'time:density',
 	rtr: 'retrospective',
+	ca: 'cost:audit',
 	rvf: 'review:findings',
+	rvs: 'review:stops',
 	ruv: 'rule:value',
 	ev: 'eval',
 	fr: 'fresh:run',
@@ -86,6 +88,9 @@ const ALIASES: Record<string, string> = {
 	lst: 'lane:stats',
 	lli: 'lane:limit',
 	lrs: 'lane:restart',
+	lwd: 'lane:withdraw',
+	lps: 'lane:pause',
+	lru: 'lane:resume',
 	blr: 'backlogrun',
 }
 

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

@@ -43,12 +43,33 @@ type CommandReference = readonly [
 	side_effects: ReadonlyArray<CommandSideEffect>,
 ]
 
+// One `pnpm josh <command> <arguments>` line of a usage block, with the comment printed after it.
+interface CommandExample {
+	arguments: string
+	note?: string
+}
+
+// Spellings of one option — `-y` and `--yes` — rendered side by side.
+interface CommandFlag {
+	names: ReadonlyArray<string>
+	description: string
+}
+
+// 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). Each command's
+// entry carries its own, so a command cannot be registered without one (#4185).
+interface CommandUsage {
+	examples: ReadonlyArray<CommandExample>
+	flags?: ReadonlyArray<CommandFlag>
+}
+
 interface CommandEntry {
 	script?: string
 	shell?: ReadonlyArray<string>
 	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
@@ -74,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
@@ -109,6 +132,13 @@ const TS_BUILD_INFO_FILE = '.tsbuildinfo'
 const CSPELL_CACHE_FILE = '.cspellcache'
 const ESLINT_EDIT_CACHE_FILE = '.eslintcache.edit'
 const ESLINT_RELATED_CACHE_FILE = '.eslintcache.related'
+const PRETTIER_CACHE_FILE = '.prettiercache'
+const PRETTIER_RELATED_CACHE_FILE = '.prettiercache.related'
+// The pre-commit hook's own, because a staged-files run on the gate's file degrades it: cspell prunes
+// every entry the run did not visit (measured 892 KB down to 18 KB), and `eslint --quiet` stores a
+// report without its warnings under the same config hash the gate reads.
+const CSPELL_COMMIT_CACHE_FILE = '.cspellcache.commit'
+const ESLINT_COMMIT_CACHE_FILE = '.eslintcache.commit'
 
 type GateCachePortability = 'raw' | 'rooted-json'
 
@@ -139,6 +169,10 @@ const ESLINT_RELATED_CACHE_SPEC: GateCacheSpec = {
 	cache_file: ESLINT_RELATED_CACHE_FILE,
 	portability: ROOTED_JSON_PORTABILITY,
 }
+// **Prettier's caches are in neither list: they do not survive a move to another checkout.**
+// Prettier 3 hashes each file's resolved options, *its absolute `filepath` included*, into the entry,
+// so rebasing the keys as ESLint's are still leaves every entry a miss — two checkouts of one tree
+// were measured sharing none of their 3,526 option hashes. Each checkout keeps a warm cache of its own.
 const GATE_CACHE_SPECS: ReadonlyArray<GateCacheSpec> = [
 	ESLINT_CACHE_SPEC,
 	TS_CACHE_SPEC,
@@ -154,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.
@@ -163,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
@@ -174,15 +208,21 @@ 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.
+// `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 three, the edit hook's, and the scoped lint's — a cache file that is not
-// ignored is committed, or spell-checked, which is a red gate with nothing misspelled in the tree.
+// written from. The gate's, the edit hook's, the scoped lint's and the pre-commit hook's — a cache
+// file that is not ignored is committed, or spell-checked, which is a red gate with nothing
+// misspelled in the tree.
 const IGNORED_CACHE_FILES: ReadonlyArray<string> = [
 	...GATE_CACHE_FILES,
 	ESLINT_EDIT_CACHE_FILE,
 	ESLINT_RELATED_CACHE_FILE,
+	PRETTIER_CACHE_FILE,
+	PRETTIER_RELATED_CACHE_FILE,
+	CSPELL_COMMIT_CACHE_FILE,
+	ESLINT_COMMIT_CACHE_FILE,
 ]
 
 // `--cache --cache-strategy content` is one convention rather than two coincidences: cspell adopted
@@ -190,11 +230,11 @@ const IGNORED_CACHE_FILES: ReadonlyArray<string> = [
 const CONTENT_CACHE_FLAGS = ['--cache', '--cache-strategy', 'content'] as const
 const CACHE_LOCATION_FLAG = '--cache-location'
 
-// Four locations are written with these same four flags — the gate's eslint cache, the scoped lint's,
-// the edit hook's and the spell check's — so the sequence is built here once. Spelled out per
-// location, a fix to the order would have to be made four times and each copy fails silently: a flag
-// and its value are one unit, and a wrong order makes the tool read `--cache-strategy` as the file
-// name rather than erroring.
+// Every location is written with these same four flags — the eslint, prettier and spell-check caches
+// of the gate, the scoped lint, the edit hook and the pre-commit hook — so the sequence is built here
+// once. Spelled out per location, a fix to the order would have to be made once per location and
+// each copy fails silently: a flag and its value are one unit, and a wrong order makes the tool read
+// `--cache-strategy` as the file name rather than erroring.
 function content_cache_flags(cache_file: string): ReadonlyArray<string> {
 	return [...CONTENT_CACHE_FLAGS, CACHE_LOCATION_FLAG, cache_file]
 }
@@ -204,20 +244,28 @@ const ESLINT_EDIT_CACHE_FLAGS = content_cache_flags(ESLINT_EDIT_CACHE_FILE)
 const ESLINT_RELATED_CACHE_FLAGS = content_cache_flags(ESLINT_RELATED_CACHE_FILE)
 const TS_CACHE_FLAGS = ['--incremental', '--tsBuildInfoFile', TS_BUILD_INFO_FILE] as const
 const CSPELL_CACHE_FLAGS = content_cache_flags(CSPELL_CACHE_FILE)
+const PRETTIER_CACHE_FLAGS = content_cache_flags(PRETTIER_CACHE_FILE)
+const PRETTIER_RELATED_CACHE_FLAGS = content_cache_flags(PRETTIER_RELATED_CACHE_FILE)
+const CSPELL_COMMIT_CACHE_FLAGS = content_cache_flags(CSPELL_COMMIT_CACHE_FILE)
+const ESLINT_COMMIT_CACHE_FLAGS = content_cache_flags(ESLINT_COMMIT_CACHE_FILE)
 
-export type { CommandCategory, CommandEntry, GateCacheSpec }
+export type { CommandCategory, CommandEntry, CommandUsage, GateCacheSpec }
 // The three cache files are exported one by one as well as as a list, because `josh bench` clears
 // 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,
 	CSPELL_CACHE_FILE,
 	CSPELL_CACHE_FLAGS,
+	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,
 	ESLINT_RELATED_CACHE_FILE,
@@ -226,6 +274,10 @@ export {
 	GATE_COMMAND,
 	IGNORED_CACHE_FILES,
 	OPTIONAL_ENV_FILE_FLAGS,
+	PRETTIER_CACHE_FILE,
+	PRETTIER_CACHE_FLAGS,
+	PRETTIER_RELATED_CACHE_FILE,
+	PRETTIER_RELATED_CACHE_FLAGS,
 	SHARED_CACHE_SPECS,
 	TS_BUILD_INFO_FILE,
 	TS_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.** `JOSH_BATCH_GUARD` and the other guard switches are
+		// per-machine preferences kept in `.env`, which every other command reads through
+		// `OPTIONAL_ENV_FILE_FLAGS` — 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, release the hold and print the issue citations 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 calls `process.loadEnvFile` 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 }