@joshuafolkken/kit 1.872.0

package/scripts/josh/josh-run.ts

@@ -0,0 +1,53 @@
+import { execa } from 'execa'
+
+// One captured `pnpm josh` subprocess (joshuafolkken/kit#2162). A composite command that collapses a
+// sequence of `pnpm josh` calls into one — `run:merge`, `backlog:offer`, `lane:launch` — reads each
+// step's output back rather than inheriting it, so the step's own report logic is reused rather than
+// cloned and only the composite's own token reaches the caller's stdout. This is that read, single-
+// sourced so the three composites cannot drift on how a subprocess is run or how its exit code is read.
+//
+// **`reject: false`**: a non-zero exit is a value to branch on, not a throw. **`forward_stderr`**: a
+// step's explanation (a refusal, a candidate elsewhere, a reason) belongs on the caller's stderr where
+// a person sees it, so a composite streams it through; `run:merge` keeps it piped, because it composes
+// its own report from the captured values instead.
+//
+// **Forwarded stderr is captured as well** (joshuafolkken/kit#2462): a composite that writes a report
+// of its own — `run:tail` — puts a failed step's reason in that report, where a detached run's log
+// otherwise showed only pnpm's `ELIFECYCLE` line.
+//
+// **`timeout_ms` bounds a read made from inside a loop** (joshuafolkken/kit#2503): 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.
+
+const PNPM = 'pnpm'
+const JOSH = 'josh'
+const NONZERO_EXIT = 1
+const FORWARDED_STDERR = ['pipe', 'inherit'] as const
+
+interface JoshResult {
+	code: number
+	out: string
+	err?: string
+}
+
+async function josh_run(
+	args: ReadonlyArray<string>,
+	should_forward_stderr = false,
+	timeout_ms?: number,
+): Promise<JoshResult> {
+	const result = await execa(PNPM, [JOSH, ...args], {
+		reject: false,
+		stderr: should_forward_stderr ? FORWARDED_STDERR : 'pipe',
+		...(timeout_ms !== undefined && { timeout: timeout_ms }),
+	})
+
+	return {
+		code: result.exitCode ?? NONZERO_EXIT,
+		out: result.stdout.trim(),
+		err: result.stderr.trim(),
+	}
+}
+
+const josh_command = { josh_run }
+
+export type { JoshResult }
+export { josh_command }

package/scripts/josh/josh-script-reader.ts

@@ -0,0 +1,11 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const REPOSITORY_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+
+function read_script(script: string): string {
+	return readFileSync(path.join(REPOSITORY_ROOT, script), 'utf8')
+}
+
+export { read_script }

package/scripts/josh/josh-verdict.ts

@@ -0,0 +1,111 @@
+import { status_icons } from '#scripts/lib/status-icons'
+
+// A josh command's own overall verdict, and the one place its line is written (joshuafolkken/kit#1374).
+//
+// `status-icons.ts` single-sourced the *character* a failure line opens with, which was enough while
+// the only thing reading it was `time-reported-failure.ts` asking "did this call print a failure?".
+// It is not enough for a command that **forwards another tool's output**. `josh gate` prints the body
+// of a step that passed with warnings or skipped (joshuafolkken/kit#1328), and that body is written by
+// eslint, svelte-check, vitest or cspell — this repository owns none of those formats. One of them
+// opening a line with the failure icon makes a *green* gate read as a failed call, and the re-run that
+// follows it is then charged as rework: the very figure joshuafolkken/kit#1361 exists to make honest.
+//
+// **The anchor is the command's own verdict, not the shape of every line it prints.** A command that
+// forwards other tools' output states its own result in one line, and that line outranks the body it
+// summarizes. **It outranks that body and nothing further**: one tool call's output is not one
+// command's — a chained `pnpm josh gate && pnpm josh health` carries both, and `josh propagate` runs
+// each consumer's gate with inherited stdio — so a `passed` verdict speaks for the lines in front of
+// it and the reading resumes after it (`time-reported-failure.ts` → `lines_after_last_pass`).
+//
+// **Why not enumerate every josh failure-line shape.** That is the candidate joshuafolkken/kit#1374
+// names as most likely, and rejects for the reason it names: the gate's step line is
+// `✗ <label> (pnpm <cmd>) <n>s`, `josh health`'s is `  ✗ <label>` and `josh propagate`'s is
+// `  ✗ <repo>  <reason>`, so a pattern list tight enough to exclude a third-party warning is a list of
+// per-command patterns — and the next josh command to print a failure line is silently not counted,
+// which is the detector going quiet without failing. Reading the verdict instead leaves every other
+// josh command exactly as it was: no verdict line, so nothing changes for them.
+//
+// **What it degrades to is today's behavior, not silence.** A body the harness truncated past the
+// verdict line falls back to the bare-icon reading, so the figure stays a floor. The gate's verdict is
+// its **last** line, which is what survives the `2>&1 | tail -40` agents actually type
+// (`prompts/collaboration-workflow/output-bounds.md`), so the fallback is the rare case rather than
+// the common one.
+//
+// **The opening line is here for the same reason the verdict is** (joshuafolkken/kit#1379). A verdict
+// says where the gate's output *ended*; nothing said where it began, so a green verdict silenced every
+// failure mark printed before it — including one written by a command that had already finished. The
+// gate's plan line is what says "the gate starts here", and it is single-sourced for the reason the
+// verdict is: the printer builds it and the detector matches it from one place.
+
+const { FAIL_ICON, PASS_ICON } = status_icons
+const GATE_SUBJECT = 'verification gate'
+
+// The prefixes are what the detector matches **and** what the printer builds its line from, so a
+// reworded verdict moves both ends at once — the property joshuafolkken/kit#1361 gave the icon,
+// applied to the line. Splitting them into a printed string and a matched string is exactly the drift
+// this module exists to prevent.
+const GATE_PASSED_PREFIX = `${PASS_ICON} ${GATE_SUBJECT} passed`
+const GATE_FAILED_PREFIX = `${FAIL_ICON} ${GATE_SUBJECT} failed`
+
+type JoshVerdict = 'passed' | 'failed'
+
+// Typed rather than left to inference: the namespace object widens a bare literal to `string`, and a
+// caller comparing `read_verdict(line)` against it would then be comparing two unrelated types.
+const PASSED_VERDICT: JoshVerdict = 'passed'
+const FAILED_VERDICT: JoshVerdict = 'failed'
+
+function format_gate_passed(step_count: string, total: string): string {
+	return `${GATE_PASSED_PREFIX} (${step_count} checks) in ${total}.`
+}
+
+function format_gate_failed(failed_labels: string, total: string): string {
+	return `${GATE_FAILED_PREFIX}: ${failed_labels} (${total})`
+}
+
+// The gate's opening line — `plan: 4 of 4 checks at once, unit at 7 workers (10 cores)` — split into
+// the two fragments the matcher tests for, so the printed line and the test for it move together the
+// way the verdict's prefixes already do. `gate-plan.ts` builds the line from these.
+//
+// **It is the opening line and not a step header, and the difference is the whole safety of the
+// bound.** A step header repeats once per check, so a body long enough to push the first header off
+// the top of a `tail -40` window leaves later headers behind it — and a forwarded `✗` would then sit
+// *before* a header and be read as printed before the gate started, which is #1374's false positive
+// returning. The plan line is printed once, before any check body exists, so nothing the gate forwards
+// can ever precede it.
+const GATE_OPENING_PREFIX = 'plan: '
+const GATE_OPENING_MARK = ' checks at once'
+
+// **Deliberately narrow, and wrong in the safe direction if it is wrong.** Both fragments are required
+// rather than either alone: a missed opening costs the pre-#1379 behavior — the whole prefix stays
+// silenced and the figure stays the floor it already was — while a false one would let a forwarded
+// line be read.
+function is_gate_opening(line: string): boolean {
+	const trimmed = line.trimStart()
+
+	return trimmed.startsWith(GATE_OPENING_PREFIX) && trimmed.includes(GATE_OPENING_MARK)
+}
+
+// Leading whitespace is trimmed for the same reason `time-reported-failure.ts` trims it: a caller that
+// quoted the body into an indented block still printed the verdict.
+function read_verdict(line: string): JoshVerdict | undefined {
+	const trimmed = line.trimStart()
+
+	if (trimmed.startsWith(GATE_FAILED_PREFIX)) return FAILED_VERDICT
+
+	if (trimmed.startsWith(GATE_PASSED_PREFIX)) return PASSED_VERDICT
+
+	return undefined
+}
+
+const josh_verdict = {
+	PASSED_VERDICT,
+	FAILED_VERDICT,
+	format_gate_passed,
+	format_gate_failed,
+	GATE_OPENING_MARK,
+	GATE_OPENING_PREFIX,
+	is_gate_opening,
+	read_verdict,
+}
+
+export { josh_verdict }

package/scripts/josh/josh.ts

@@ -0,0 +1,60 @@
+import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
+import { find_package_directory, josh_logic, UNKNOWN_COMMAND_EXIT_CODE } from './josh-logic'
+
+const ARGV_OFFSET = 2
+
+// `--help` and `-h` ask for the listing as plainly as the bare `help` does. They used to fall
+// through to `handle_unknown`, which reached stdout only because the listing was printed there;
+// routing that path to stderr for #825 would otherwise have left `josh --help` printing nothing a
+// pipe could read.
+const HELP_COMMANDS: ReadonlySet<string> = new Set(['help', '--help', '-h'])
+// `josh --all` (and `josh --help --all`) lists every command available in this checkout.
+// A bare `--all` in the command slot is a help request, not a command.
+const ALL_FLAG = '--all'
+
+function print_help(is_all: boolean, is_consumer: boolean): void {
+	console.info(josh_logic.format_help(is_all, is_consumer))
+}
+
+// Both halves go to stderr. The help listing is a diagnosis here, not the answer, and a shell
+// wiring `--port $(josh port dev)` reads stdout alone, so a command name this kit cannot resolve
+// has to leave that stream empty rather than substitute the whole toolkit index (#825).
+function handle_unknown(cmd: string): never {
+	console.error(josh_logic.format_unknown_command(cmd))
+	process.exit(1)
+}
+
+// `process.exit` truncates a piped stdout at its buffer size, and since joshuafolkken/kit#1342 the
+// output at risk is the script's own — `scripts/gate/verification-gate.ts` writes its per-check blocks
+// and its failure summary through this process, and sets `process.exitCode` rather than exiting for
+// exactly that reason. Recording the code and letting node exit when the loop drains keeps every
+// byte, and it leaves the last word with a script that finishes work after module evaluation
+// returns. It is a function of its own so the assignment does not sit after an `await` in `main`,
+// where `require-atomic-updates` reads any write to `process` as a possible race.
+function record_exit_code(exit_code: number): void {
+	if (exit_code !== 0) process.exitCode = exit_code
+}
+
+// `run_command` answers with a number for a shell command and a promise for a script it runs in
+// this same process (joshuafolkken/kit#1342); `await` covers both, and the argv slice is taken
+// before it because the in-process branch replaces `process.argv` with the script's own.
+async function main(): Promise<void> {
+	const cmd = process.argv[ARGV_OFFSET]
+	const is_all = process.argv.includes(ALL_FLAG)
+	const is_consumer = doctor_consumer.is_kit_consumer(find_package_directory(process.cwd()))
+
+	if (!cmd || cmd === ALL_FLAG || HELP_COMMANDS.has(cmd)) {
+		print_help(is_all, is_consumer)
+
+		return
+	}
+
+	const subcommand_arguments = process.argv.slice(ARGV_OFFSET + 1)
+	const exit_code = await josh_logic.run_command(cmd, subcommand_arguments, is_consumer)
+
+	if (exit_code === UNKNOWN_COMMAND_EXIT_CODE) handle_unknown(cmd)
+
+	record_exit_code(exit_code)
+}
+
+await main()

package/scripts/josh/kit-only.ts

@@ -0,0 +1,33 @@
+import { COMMAND_MAP } from './josh-command-map'
+import type { CommandEntry } from './josh-command-types'
+
+// The commands marked `is_kit_only` in the map only make sense inside the kit repository itself, so a
+// consumer never sees them in `josh --help` and is refused with guidance when it runs one
+// (joshuafolkken/kit#1988). The flag lives on the entry; everything a reader needs to act on it is
+// here, so the help filter, the dispatch guard and the distributed-doc test read one definition.
+
+// Where a consumer is told to go. A script-emitted string, so it stays English (`CLAUDE.md` →
+// content rules) even when the session language is not.
+function kit_only_notice(cmd: string): string {
+	return `\`josh ${cmd}\` is a kit-only command — run it from the kit repository (joshuafolkken/kit), not from a consumer project.`
+}
+
+function is_kit_only(entry: CommandEntry): boolean {
+	return entry.is_kit_only === true
+}
+
+// Every kit-only command name, for the test that pins that no distributed procedure document names
+// one as an execution step.
+function kit_only_command_names(): ReadonlyArray<string> {
+	return Object.entries(COMMAND_MAP)
+		.filter(([, entry]) => is_kit_only(entry))
+		.map(([name]) => name)
+}
+
+const kit_only = {
+	is_kit_only,
+	command_names: kit_only_command_names,
+	notice: kit_only_notice,
+}
+
+export { kit_only }

package/scripts/josh/path-decision.ts

@@ -0,0 +1,104 @@
+import { changed_paths } from '#scripts/git/changed-paths'
+
+// The shape both path-decided commands share (joshuafolkken/kit#907).
+//
+// `josh review:level` and `josh review:round2` ask different questions of the same tree, and they answer
+// the same way: read the changed paths, decide from them alone, print the answer on stdout and the reason on
+// stderr. Only the question differs, so only the question is written twice — a second copy of the
+// reading, the flags and the printing would let two commands disagree about what "changed" means.
+
+const STAGED_FLAG = '--staged'
+const JSON_FLAG = '--json'
+const KNOWN_FLAGS: ReadonlyArray<string> = [STAGED_FLAG, JSON_FLAG]
+const FAILURE_EXIT_CODE = 1
+// Enough paths to recognize the change, and a count for the rest. A reason that printed every path
+// of a large diff would bury the answer it exists to explain.
+const MAX_LISTED_PATHS = 5
+
+interface DecisionOptions {
+	is_staged: boolean
+	is_json: boolean
+}
+
+// What a command has to supply: its usage line, the key its `--json` form has always used, the
+// decision, and the sentence explaining it.
+interface DecisionCommand<Answer extends string> {
+	usage: string
+	key: string
+	decide: (paths: ReadonlyArray<string>) => Answer
+	explain: (paths: ReadonlyArray<string>, answer: Answer) => string
+}
+
+// The flag contract every mechanically-decided command shares — the two here and `josh review:round2`
+// (joshuafolkken/kit#1433). An argument that is not a known flag makes the whole invocation
+// unreadable, and an unreadable invocation is never answered with a default. Shared because the
+// *direction* is the load-bearing part rather than the `some` call: a command that guessed would
+// hand the caller the answer they were reaching for instead of the one their tree supports, and two
+// copies of that judgement are two chances to write it the other way round.
+function has_unknown_flag(argv: ReadonlyArray<string>, known: ReadonlyArray<string>): boolean {
+	return argv.some((argument) => !known.includes(argument))
+}
+
+// `undefined` rather than a default on an unknown flag: a misspelled `--stage` that silently read
+// the branch diff would answer a question nobody asked, and answer it confidently.
+function parse_options(argv: ReadonlyArray<string>): DecisionOptions | undefined {
+	if (has_unknown_flag(argv, KNOWN_FLAGS)) return undefined
+
+	return { is_staged: argv.includes(STAGED_FLAG), is_json: argv.includes(JSON_FLAG) }
+}
+
+function format_path_list(paths: ReadonlyArray<string>): string {
+	const listed = paths.slice(0, MAX_LISTED_PATHS).join(', ')
+
+	if (paths.length <= MAX_LISTED_PATHS) return listed
+
+	return `${listed}, +${String(paths.length - MAX_LISTED_PATHS)} more`
+}
+
+// The answer alone on stdout so `$(pnpm josh <command>)` reads it, and the reason on stderr so a
+// person sees why without a shell having to parse around it. `--json` puts both in one object under
+// the key that command has always used — `level` for `review:level`.
+function print_decision(key: string, answer: string, reason: string, is_json: boolean): void {
+	if (is_json) {
+		console.info(JSON.stringify({ [key]: answer, reason }))
+
+		return
+	}
+
+	console.info(answer)
+	console.error(reason)
+}
+
+async function run_path_decision<Answer extends string>(
+	argv: ReadonlyArray<string>,
+	command: DecisionCommand<Answer>,
+): Promise<number> {
+	const options = parse_options(argv)
+
+	if (options === undefined) {
+		console.error(command.usage)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const paths = await changed_paths.read_changed_paths(options.is_staged)
+	const answer = command.decide(paths)
+
+	print_decision(command.key, answer, command.explain(paths, answer), options.is_json)
+
+	return 0
+}
+
+const path_decision = {
+	format_path_list,
+	has_unknown_flag,
+	JSON_FLAG,
+	KNOWN_FLAGS,
+	MAX_LISTED_PATHS,
+	parse_options,
+	print_decision,
+	run_path_decision,
+	STAGED_FLAG,
+}
+
+export { path_decision }

package/scripts/josh/platform-temporary.ts

@@ -0,0 +1,66 @@
+import { accessSync, constants } from 'node:fs'
+import { tmpdir } from 'node:os'
+
+// The temp directory in a spelling every process on one host resolves alike. **`os.tmpdir()` is not
+// "the temp directory"**: it honors `TMPDIR`, which on macOS names a per-user `/var/folders/…/T`, so
+// two processes with different `TMPDIR` values resolve two different places. A record one josh
+// command writes for another to read then lands where the reader never looks — the transcript a
+// harness wrote under `/tmp` that `os.tmpdir()` could not name (joshuafolkken/kit#1501), and the run
+// record a `backlogrun` handed off that the `run:wake`-launched session began again from nothing
+// (joshuafolkken/kit#1909). A cross-process handoff has to key on a root neither end's own `TMPDIR`
+// can move, and that is what this pins.
+//
+// **It is decided by platform rather than written as a bare `/tmp`, because a POSIX literal is not
+// inert on Windows.** There is no `/tmp` there, and `path.relative` would resolve the rooted path
+// against the current drive as `C:\tmp` — a root nobody declared. Windows therefore keeps
+// `os.tmpdir()` exactly as it was; it reads `TEMP` / `TMP` per process, so the split this pins on
+// POSIX is not ruled out there, only left unchanged.
+//
+// **A POSIX host whose `/tmp` cannot be written falls back to `os.tmpdir()`.** Some environments point
+// `TMPDIR` at the only writable scratch directory — a Nix build sandbox, an Android terminal, a locked-down
+// container — and pinning to `/tmp` there would turn every record write into an error. Those hosts get
+// the behavior they had before, which is a working record rather than a shared one.
+const POSIX_TEMP_ROOT = '/tmp'
+const WINDOWS_PLATFORM = 'win32'
+
+function is_writable_directory(directory: string): boolean {
+	try {
+		accessSync(directory, constants.W_OK)
+
+		return true
+	} catch {
+		return false
+	}
+}
+
+function resolve_temporary_root(
+	platform: string,
+	can_write: (directory: string) => boolean = is_writable_directory,
+): string {
+	if (platform === WINDOWS_PLATFORM) return tmpdir()
+
+	return can_write(POSIX_TEMP_ROOT) ? POSIX_TEMP_ROOT : tmpdir()
+}
+
+// **An explicit root wins, and the unit suite is who sets one** (joshuafolkken/kit#2494). Every
+// record keyed here is shared by the whole host, so a unit test that drove a writer for real wrote
+// into the live run's records — progress lines for issues the run never touched, relayed to the
+// session watching it. The network guard's `arm` points this at a directory of its own before any
+// worker forks, so every process of one test run shares a root no real run reads, and `disarm`
+// removes it with the rest of the guard.
+const TEMP_ROOT_KEY = 'JOSH_TEMP_ROOT'
+
+function temporary_root(override: string | undefined, platform: string): string {
+	return override === undefined || override === '' ? resolve_temporary_root(platform) : override
+}
+
+const PLATFORM_TEMP_ROOT = temporary_root(process.env[TEMP_ROOT_KEY], process.platform)
+
+const platform_temporary = {
+	TEMP_ROOT_KEY,
+	resolve_temporary_root,
+	is_writable_directory,
+	temporary_root,
+}
+
+export { platform_temporary, PLATFORM_TEMP_ROOT, POSIX_TEMP_ROOT }