@joshuafolkken/kit 1.1784.0 → 1.2116.0

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

@@ -36,7 +36,8 @@ const SHIP_COMMANDS: Record<string, CommandEntry> = {
 				},
 				{
 					names: [OUTPUT],
-					description: 'the transcript the outage split reads; absent, it is off.',
+					description:
+						'the transcript the outage and usage-limit splits read; absent, they are off.',
 				},
 				{
 					names: ['--driver'],
@@ -49,16 +50,43 @@ const SHIP_COMMANDS: Record<string, CommandEntry> = {
 	'run:review': {
 		script: 'scripts/run/review/run-review-cli.ts',
 		description:
-			'Start the gate in the background and print the /code-review brief in one call so the two overlap (--join to join the gate and check its verdict)',
+			'Start test:pinned and the gate in the background and write the /code-review brief to a file, printing its path, in one call so they overlap (--join to join them; it stops on an unpinned change)',
 		category: 'AI tools',
-		reference: ['[--join]', 'automation', ['processes', 'files']],
+		reference: [
+			'[--code-only] [--unpinned-ok "<reason>"] | --join [--fixing] | --pinned | --push',
+			'automation',
+			['processes', 'files', 'git', 'network'],
+		],
 		usage: {
 			examples: [
 				{
 					arguments: '',
-					note: 'detach the gate, print the brief; then launch the /code-review subagent',
+					note: 'detach test:pinned and the gate, write the brief (the interaction brief after it where due) to a file and print its path, then launch a reviewer per brief',
+				},
+				{
+					arguments: '--code-only',
+					note: "josh ship's own open: code's brief alone, since the ship opens the interaction brief itself",
+				},
+				{
+					arguments: '--unpinned-ok "only logs"',
+					note: 'check beside the pair as ever; the join prints the list and the reason and carries on past unpinned places',
+				},
+				{
+					arguments: '--join',
+					note: 'after the review returns: join the gate and test:pinned; exit 3 on an unpinned change',
+				},
+				{
+					arguments: '--join --fixing',
+					note: 'the join when round 1 has fixes to make: no grace on test:pinned, left running; prints the unpinned places the cache already holds',
+				},
+				{
+					arguments: '--pinned',
+					note: "read test:pinned alone (the ship's pre-detach reads it anyway); a lane child returns at once",
+				},
+				{
+					arguments: '--push',
+					note: 'launched by a lane open: push and open the PR at a green gate',
 				},
-				{ arguments: '--join', note: 'after the review returns: join the gate, check its verdict' },
 			],
 		},
 	},
@@ -91,7 +119,7 @@ const SHIP_COMMANDS: Record<string, CommandEntry> = {
 			'Ship a change in one call: gate, commit/push/PR, the CI-wait merge and the report bookkeeping, stopping at the first failed step',
 		category: 'AI tools',
 		reference: [
-			'"<title> #<N>" [<follow-up-N> ...] [--cite <N>] [--review] [--detach] [--body-file <path>] [--notify-message <text> | --notify-message-file <path>] | --log <N>',
+			'"<title> #<N>" [<follow-up-N> ...] [--cite <N>] [--review [--unpinned-ok "<reason>"]] [--detach] [--body-file <path>] [--notify-message <text> | --notify-message-file <path>] | --log <N>',
 			'automation',
 			['git', 'network'],
 		],
@@ -112,12 +140,32 @@ const SHIP_COMMANDS: Record<string, CommandEntry> = {
 				{
 					names: ['--review'],
 					description:
-						'runs review round 1 beside the gate, and round 2 after the commit when `review:round2` requires it; a High or an unfixed Medium stops the ship.',
+						'runs review round 1 beside the gate, and round 2 after the commit when `review:round2` requires it; a High or an unfixed Medium stops the ship. A pre-detach `test:pinned` stop at the first unpinned hunk probes the rest in the background, for the next pre-detach.',
+				},
+				{
+					names: ['--unpinned-ok <reason>'],
+					description:
+						"forwarded to round 1's `run:review`, past `unpinned` places no test can pin.",
 				},
 				{
 					names: ['--detach'],
 					description:
-						'hands the ship to a supervisor (implied in a lane child); a stop emits `ship-stop` (`--log <N>`). The preflight, type check, unused exports, cspell and guard tests run before the hand-off, the checks even after a preflight refusal, so one stop reports every failure; a stop returns to the same session.',
+						'hands the ship to a supervisor (implied in a lane child); a stop emits `ship-stop` (`--log <N>`). The preflight, type check, unused exports, cspell, guard tests and (`--review`, under `--unpinned-ok`, given or recorded, only if round 1 is reused) `test:pinned` precede hand-off, the checks even after a preflight refusal, so one stop reports every failure.',
+				},
+			],
+		},
+	},
+	'ship:wait': {
+		script: 'scripts/run/ship/run-ship-wait-cli.ts',
+		description:
+			'Wait on a detached ship through its gate and review round 1, so a stop there returns to this session (returned | passed | ended | pending)',
+		category: 'AI tools',
+		reference: ['<N>', 'automation', ['files', 'processes']],
+		usage: {
+			examples: [
+				{
+					arguments: '<N>',
+					note: 're-issue it on `pending` while `cost --cut` is `under`; `returned` prints the stop to fix',
 				},
 			],
 		},

package/scripts/josh/josh-commands-test-check.ts

@@ -0,0 +1,80 @@
+import { gate_plan } from '#scripts/gate/gate-plan'
+import type { CommandEntry } from './josh-command-types'
+
+// The commands that check a change's tests rather than run them, split out of
+// `josh-commands-development.ts` when it reached its line cap (joshuafolkken/kit#5153). `DEV_COMMANDS`
+// spreads this in at the same place, so the map keeps its order.
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const TEST_CHECK_COMMANDS: Record<string, CommandEntry> = {
+	'test:declared': {
+		script: 'scripts/test/test-declared.ts',
+		description:
+			'Report whether the working-tree change needs a test (required/exempt/satisfied); --match checks Step 0 declarations on stdin',
+		category: 'Development',
+		reference: ['[--match]', 'developer', ['processes']],
+		usage: {
+			examples: [
+				{ arguments: '' },
+				{ arguments: '--match', note: 'check Step 0 declarations on stdin' },
+				{ arguments: '--help', note: 'print usage, including the --match stdin form' },
+			],
+		},
+	},
+	'test:red': {
+		script: 'scripts/test/test-red-main.ts',
+		description:
+			'Run the changed unit tests against the pre-fix tree (merge-base worktree) and report red/green/no-test/stopped/test-only',
+		category: 'Development',
+		reference: ['', 'developer', ['git', 'processes']],
+		usage: { examples: [{ arguments: '', note: 'red, green, no-test, stopped or test-only' }] },
+	},
+	'test:reach': {
+		script: 'scripts/test/test-reach-cli.ts',
+		description:
+			"Print how many test files each file's imports reach — the count test:related sizes its claim by — one '<count> <file>' line per file",
+		category: 'Development',
+		reference: ['<files...>', 'automation', ['none']],
+		usage: {
+			examples: [
+				{
+					arguments: 'scripts/lane/lane-ledger.ts',
+					note: 'a reach count to measure before and after a change',
+				},
+			],
+		},
+	},
+	'test:pinned': {
+		script: 'scripts/test/test-pinned-main.ts',
+		description:
+			"Revert each changed hunk outside tests and fixtures only they reach, and replace each added file's top-level function bodies with a throw, in a HEAD worktree, run the related tests, and list what no test went red on",
+		category: 'Development',
+		reference: [
+			'[--max <n>] [--record <token>] [--origin <run-review|pre-detach|manual>] [--first-unpinned]',
+			'developer',
+			['git', 'processes'],
+		],
+		...gate_plan.DIRECT_UNIT_CLAIM,
+		usage: {
+			examples: [
+				{ arguments: '', note: 'unpinned <file>:<line> lines; unchecked counted per reason' },
+				{ arguments: '--max 5', note: 'check at most 5 hunks; the rest count as unchecked' },
+				{
+					arguments: '--record <token>',
+					note: 'also leave the answer, under the launch token, for run:review --join',
+				},
+				{
+					arguments: '--origin pre-detach',
+					note: 'name what started the run on its lane ledger row (default manual)',
+				},
+				{
+					arguments: '--first-unpinned',
+					note: 'start no probe once one hunk is unpinned; the rest count as unchecked',
+				},
+			],
+		},
+	},
+}
+/* eslint-enable @typescript-eslint/naming-convention */
+
+export { TEST_CHECK_COMMANDS }

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

@@ -188,7 +188,7 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Record a review round’s findings, or check a round was recorded',
 		category: 'Workflow',
 		reference: [
-			'--issue <N> [--comment | --interaction] [<category>:<severity>:<file> ...] | --check [--interaction] --issue <N>',
+			'--issue <N> [--comment | --interaction] [<category>:<severity>:<file>[ — <reason>] ...] | --check [--interaction] --issue <N>',
 			'automation',
 			['files', 'network'],
 		],

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

@@ -1,4 +1,7 @@
+import { readFileSync } from 'node:fs'
+import { parseEnv } from 'node:util'
 import { ENV_FILE_NAME } from '#ports'
+import { OPTIONAL_ENV_FILE_FLAGS } from './josh-command-types'
 
 // Loading `.env` from inside a command, for the commands that must stay in-process.
 //
@@ -8,23 +11,60 @@ import { ENV_FILE_NAME } from '#ports'
 // 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
+// `parseEnv` is node's own `--env-file` parser, and the loader 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.
 //
+// **A switch that turns a guard or a gate off is never taken from the file** (kit #4660): the run
+// can write `.env`, so a switch read from it would let the run switch off the guards that bind it. It
+// counts only from the environment the session was launched with — `JOSH_RULE_GUARD=off claude`. The
+// flag form is loaded through the same filter (`apply_node_flags`), so a process kit starts never
+// inherits a switch from the file either.
+//
 // **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 {
+
+// Every `JOSH_*_GUARD` switch, the hooks' `JOSH_*_FORCE` skips and the gate's `JOSH_SCOPED_GREEN`.
+const LAUNCH_ONLY_KEY = /^JOSH_(?:\w+_GUARD|\w+_FORCE|SCOPED_GREEN)$/u
+
+function is_launch_only_key(key: string): boolean {
+	return LAUNCH_ONLY_KEY.test(key)
+}
+
+function read_environment_file(): string {
 	try {
-		process.loadEnvFile(ENV_FILE_NAME)
+		return readFileSync(ENV_FILE_NAME, 'utf8')
 	} 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.
+		return ''
+	}
+}
+
+function load_environment_file(): void {
+	const entries = Object.entries(parseEnv(read_environment_file()))
+
+	for (const [key, value] of entries) {
+		if (!is_launch_only_key(key) && process.env[key] === undefined) process.env[key] = value
 	}
 }
 
+// The node flags a spawned command is started with. The `.env` flag is loaded here, into the
+// environment the child inherits, rather than handed to node, whose own loader cannot leave the
+// launch-only keys out.
+function apply_node_flags(flags: ReadonlyArray<string>): ReadonlyArray<string> {
+	const [environment_flag] = OPTIONAL_ENV_FILE_FLAGS
+
+	if (!flags.includes(environment_flag ?? '')) return flags
+
+	load_environment_file()
+
+	return flags.filter((flag) => flag !== environment_flag)
+}
+
 const josh_environment_file = {
+	apply_node_flags,
 	load_environment_file,
 }
 

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

@@ -31,8 +31,8 @@ function bundled_script_path(package_directory: string, script: string): string
 
 // The file this dispatcher imports in its own process, or `undefined` to spawn tsx instead.
 // `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
+// them a form of `--env-file`, which the dispatcher loads into the child's environment just before
+// it spawns (`josh_environment_file.apply_node_flags`). 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. Under plain node, which cannot load a `.ts` script at all, only a
 // pre-built command runs in-process; every other one keeps spawning tsx.

package/scripts/josh/josh-logic.ts

@@ -8,14 +8,15 @@ 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 } from './josh-aliases'
 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_environment_file } from './josh-environment-file'
 import { josh_in_process } from './josh-in-process'
 import { kit_only } from './kit-only'
 import { find_package_directory } from './package-directory'
@@ -193,7 +194,7 @@ function spawn_script_entry(
 
 	return spawn_script(runner.executable, [
 		...runner.leading_arguments,
-		...(entry.tsx_arguments ?? []),
+		...josh_environment_file.apply_node_flags(entry.tsx_arguments ?? []),
 		script_path,
 		...script_arguments,
 	])
@@ -309,7 +310,8 @@ const josh_logic = {
 }
 
 export type { CommandEntry } from './josh-command-map'
-export { ALIASES, COMMAND_MAP } from './josh-command-map'
+export { ALIASES } from './josh-aliases'
+export { 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 {

package/scripts/josh/josh-run.ts

@@ -17,6 +17,8 @@ import { execa } from 'execa'
 //
 // **`timeout_ms` bounds a read made from inside a loop**: the step is killed and
 // its exit reads as a failure, so a hung network call ends a pass instead of the loop around it.
+//
+// **`environment` adds to the inherited one** for that one step — a switch the step's hooks read.
 
 const PNPM = 'pnpm'
 const JOSH = 'josh'
@@ -29,15 +31,31 @@ interface JoshResult {
 	err?: string
 }
 
+interface ExtraOptions {
+	timeout?: number
+	env?: Readonly<Record<string, string>>
+}
+
+function extra_options(
+	timeout_ms: number | undefined,
+	environment: Readonly<Record<string, string>> | undefined,
+): ExtraOptions {
+	return {
+		...(timeout_ms !== undefined && { timeout: timeout_ms }),
+		...(environment !== undefined && { env: environment }),
+	}
+}
+
 async function josh_run(
 	args: ReadonlyArray<string>,
 	should_forward_stderr = false,
 	timeout_ms?: number,
+	environment?: Readonly<Record<string, string>>,
 ): Promise<JoshResult> {
 	const result = await execa(PNPM, [JOSH, ...args], {
 		reject: false,
 		stderr: should_forward_stderr ? FORWARDED_STDERR : 'pipe',
-		...(timeout_ms !== undefined && { timeout: timeout_ms }),
+		...extra_options(timeout_ms, environment),
 	})
 
 	return {

package/scripts/josh/run-record-path.ts

@@ -0,0 +1,15 @@
+// The run's own records — observations, accepted metrics — josh writes under the root `.josh/`
+// directory. `defect-report.ts`, `scoped-green.ts`, `test-read-map.ts`, `test-pinned-cache.ts` and
+// the background `josh test:pinned`'s tree key (`run-review-pinned-tree.ts`) read such a path as
+// bookkeeping, not as a change to the code — no test reads it.
+const RUN_RECORD_ROOT = '.josh/'
+
+function is_run_record(relative: string): boolean {
+	return relative.startsWith(RUN_RECORD_ROOT)
+}
+
+const run_record_path = {
+	is_run_record,
+}
+
+export { run_record_path }

package/scripts/josh/stamp-file.ts

@@ -69,14 +69,22 @@ function account_key(): string {
 // **`suffix` is what the file is, not decoration.** Every record here was JSON until `josh gate`
 // needed to keep another tool's output verbatim, and a log named `.json`
 // tells every reader — a person, an editor, a `less` — that it is something it is not.
-function stamp_path(
+function stamp_name(
 	prefix: string,
 	root: string = PACKAGE_DIR,
 	suffix: string = STAMP_SUFFIX,
 ): string {
 	const key = digest(`${account_key()}${ACCOUNT_KEY_SEPARATOR}${root}`).slice(0, STAMP_KEY_LENGTH)
 
-	return path.join(PLATFORM_TEMP_ROOT, `${prefix}${key}${suffix}`)
+	return `${prefix}${key}${suffix}`
+}
+
+function stamp_path(
+	prefix: string,
+	root: string = PACKAGE_DIR,
+	suffix: string = STAMP_SUFFIX,
+): string {
+	return path.join(PLATFORM_TEMP_ROOT, stamp_name(prefix, root, suffix))
 }
 
 // **The write unlinks first, then creates exclusively.** `rmSync` removes a symlink rather than
@@ -199,6 +207,7 @@ const stamp_file = {
 	replace_stamp,
 	replace_text_stamp,
 	remove_stamp,
+	stamp_name,
 	stamp_path,
 	write_stamp,
 	write_text_stamp,

package/scripts/lane/lane-adopt-cli.ts

@@ -0,0 +1,98 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { session_cite } from '#scripts/issue/session-cite'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { lane_adopt, type Adoption } from './lane-adopt'
+import { lane_registry, type LaneInfo } from './lane-registry'
+import { lane_state, type LaneRecords } from './lane-state'
+
+// `josh lane:adopt <issue> | --all` — write a state record for each open lane that lost its own
+// (`lane-adopt.ts`), one line per lane. A named lane left unknown exits non-zero; one already recorded
+// had nothing to adopt and exits zero. Under `--all` neither is a failure.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ALL_FLAG = '--all'
+const USAGE = 'Usage: josh lane:adopt <issue-number> | josh lane:adopt --all'
+
+async function named_lane(issue: string): Promise<Array<LaneInfo> | undefined> {
+	if (!issue_number_shape.is_issue_number(issue)) return undefined
+
+	const lane = await lane_registry.find_open_lane(issue)
+
+	return lane === undefined ? [] : [lane]
+}
+
+async function lanes_of(target: ReadonlyArray<string>): Promise<Array<LaneInfo> | undefined> {
+	const [issue, ...rest] = target
+
+	if (issue === undefined || rest.length > 0) return undefined
+
+	return issue === ALL_FLAG ? await lane_registry.list_lanes() : await named_lane(issue)
+}
+
+function outcome_text(adoption: Adoption): string {
+	if (adoption.kind === 'left') return `left unknown — ${adoption.reason}`
+	if (adoption.kind === 'kept') return `already recorded ${adoption.state}`
+
+	return `recorded open — ${lane_adopt.facts_text(adoption.facts)}`
+}
+
+// Adopt one lane, report it, and put an adoption on the run's event stream as a note, as
+// `backlog-drive-adopt.ts` does: a `lane-state` line would reset the once-per-episode paused-lanes
+// notice (`backlog-drive-paused.ts`) though no paused lane changed.
+async function settle(lane: LaneInfo, records: LaneRecords): Promise<Adoption> {
+	const adoption = await lane_adopt.adopt(lane, records)
+	const { ADOPT_COMMAND } = lane_adopt
+
+	console.info(`${ADOPT_COMMAND} ${session_cite.issue(lane.issue)}: ${outcome_text(adoption)}`)
+	if (adoption.kind !== 'adopted') return adoption
+
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.NOTE,
+		`${issue_cite.plain(lane.issue)} adopted by ${ADOPT_COMMAND}`,
+	)
+
+	return adoption
+}
+
+async function apply(lanes: ReadonlyArray<LaneInfo>, is_named: boolean): Promise<number> {
+	const records = await lane_state.read_states(lanes.map((lane) => lane.issue))
+	const adoptions = await Promise.all(lanes.map(async (lane) => await settle(lane, records)))
+
+	return is_named && adoptions.some((adoption) => adoption.kind === 'left')
+		? FAILURE_EXIT_CODE
+		: SUCCESS_EXIT_CODE
+}
+
+function report(message: string): number {
+	console.error(message)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const lanes = await lanes_of(argv)
+
+	if (lanes === undefined) return report(USAGE)
+
+	if (lanes.length === 0 && argv[0] !== ALL_FLAG) {
+		return report(`No open lane for ${session_cite.issue(argv[0] ?? '')}`)
+	}
+
+	return await apply(lanes, argv[0] !== ALL_FLAG)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const lane_adopt_cli = { run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { lane_adopt_cli }