@joshuafolkken/kit 1.1471.0 → 1.1784.0

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

@@ -1,5 +1,15 @@
 import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
 
+const PR_TITLE = '"PR title #N"'
+const BODY_FILE_NOTE =
+	'(`-` reads stdin); use this whenever the body carries a backtick or `$`. Passing both forms is refused.'
+const ISSUE_URL = '--issue-url "https://..."'
+const REVIEW_ISSUE = '--issue 2325'
+const CHECK = '--check'
+const YES = '-y'
+const SKIP_COMMIT = '--skip-commit'
+const SKIP_PUSH = '--skip-push'
+
 const GIT_WORKFLOW_SCRIPT = 'scripts/git/git-workflow.ts'
 const GIT_MESSAGE_ARGUMENTS = '[-y] <message>'
 
@@ -10,6 +20,28 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Git workflow helper',
 		category: 'Workflow',
 		reference: [GIT_MESSAGE_ARGUMENTS, 'developer', ['git', 'network']],
+		usage: {
+			examples: [
+				{ arguments: '', note: 'interactive' },
+				{ arguments: YES, note: 'unattended (no TTY required)' },
+				{ arguments: '-y "title"', note: 'set commit message prefix' },
+				{ arguments: '-y "<title> #<N>"', note: 'follow-up commit on the same branch' },
+				{
+					arguments: '-y --skip-commit --skip-push',
+					note: 'open the PR without committing/pushing',
+				},
+			],
+			flags: [
+				{
+					names: [YES, '--yes'],
+					description: 'run non-interactively; works without a TTY (agent or CI shell).',
+				},
+				{
+					names: [SKIP_COMMIT, SKIP_PUSH],
+					description: 'recover/open a PR without a new commit or push.',
+				},
+			],
+		},
 	},
 	pr: {
 		script: GIT_WORKFLOW_SCRIPT,
@@ -18,7 +50,8 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		// Not `GIT_MESSAGE_ARGUMENTS`: `-y` is already in the default arguments below, so advertising
 		// it would document a flag that cannot change what this command does.
 		reference: ['<message>', 'developer', ['network']],
-		default_script_arguments: ['-y', '--skip-commit', '--skip-push'],
+		default_script_arguments: [YES, SKIP_COMMIT, SKIP_PUSH],
+		usage: { examples: [{ arguments: '', note: 'open the PR for the current <N>-<slug> branch' }] },
 	},
 	// **The optional form, on both**. The mandatory `--env-file=.env` is resolved by node before the
 	// script's first line: on a machine with no `.env` it dies as `.env: not found` with exit code 9,
@@ -41,9 +74,37 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 			['git', 'network', 'notifications'],
 		],
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		usage: {
+			examples: [
+				{ arguments: PR_TITLE, note: 'merges (default)' },
+				{ arguments: String.raw`${PR_TITLE} --notify-message "Implemented X:\n- change 1"` },
+				{ arguments: `${PR_TITLE} --notify-message-file completion.md` },
+				{ arguments: `${PR_TITLE} --ai-review-ignore-reason "false positive"` },
+				{ arguments: `${PR_TITLE} --no-merge`, note: 'do the work, leave the PR open' },
+			],
+			flags: [
+				{
+					names: ['--no-merge'],
+					description:
+						'do the follow-up work but do not merge; leaves the PR open (the only flag that stops the merge). `--merge` is a deprecated no-op. A PR already merged by hand skips the CI wait, the AI-review scan and the merge and runs only the post-merge tail; a completion report already on the Issue is not posted again.',
+				},
+				{
+					names: ['--notify-message'],
+					description: 'inline completion body; `\\n` expands to newlines.',
+				},
+				{
+					names: ['--notify-message-file'],
+					description: `read the completion body from a file ${BODY_FILE_NOTE}`,
+				},
+				{
+					names: ['--ai-review-ignore-reason'],
+					description: 'reason to dismiss an AI-review finding.',
+				},
+			],
+		},
 	},
 	notify: {
-		script: 'scripts/notify/telegram-test.ts',
+		script: 'scripts/notify/telegram-test-main.ts',
 		description: 'Send Telegram notification',
 		category: 'Workflow',
 		reference: [
@@ -52,6 +113,38 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 			['notifications'],
 		],
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		usage: {
+			examples: [
+				{
+					arguments: String.raw`--task-type planning ${ISSUE_URL} --body="- bullet 1\n- bullet 2"`,
+				},
+				{
+					arguments: `--task-type confirmation ${ISSUE_URL} --body-file r.md --recommended "Go" --alternative "Wait"`,
+				},
+			],
+			flags: [
+				{
+					names: ['--task-type'],
+					description:
+						'one of `planning` 📋, `completion` ✅, `failure` ❌, `warning` ⚠️, `kickoff_retry` 🔄, `confirmation` ⏸️. Do not send `completion` or `warning` by hand — `josh followup` sends them.',
+				},
+				{
+					names: ['--body', "--body=$'…'"],
+					description: "inline body; use `--body=$'…'` when it starts with `-`.",
+				},
+				{ names: ['--body-file'], description: `read the body from a file ${BODY_FILE_NOTE}` },
+				{
+					names: ['--repo-name', '--issue-url', '--pr-url'],
+					description:
+						'header repository, resolved in that order, then the working directory. The issue title is read from `--issue-url`.',
+				},
+				{
+					names: ['--recommended', '--alternative'],
+					description:
+						'the choices appended under `JOSH_SESSION_LANG` headings; `--recommended` is required for `confirmation`, `--alternative` is repeatable.',
+				},
+			],
+		},
 	},
 	// One observation-ledger sighting: the key's count, the append and the second-sighting verdict,
 	// which a run used to type as a `cat | grep -c` and judge by hand.
@@ -60,6 +153,21 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Record an observation sighting and answer whether it is now filed',
 		category: 'Workflow',
 		reference: ['<key> <depth> <where> <what> [--checkout <path>]', 'automation', ['files']],
+		usage: {
+			examples: [
+				{ arguments: "flaky-e2e d1 'tests/e2e/login.test.ts' 'times out on CI only'" },
+				{
+					arguments: "flaky-e2e d1 'src/app.ts' 'fails there too' --checkout ~/Development/app",
+					note: "another repository's ledger",
+				},
+			],
+			flags: [
+				{
+					names: ['--checkout <path>'],
+					description: "count and append in that repository's `.josh/observations/` instead.",
+				},
+			],
+		},
 	},
 	// The observation ledger's commit path for the lines no run's own commit carried:
 	// a lane's lines sit in the primary checkout, which
@@ -69,20 +177,46 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Commit the observation ledger as a pull request of its own, and merge it',
 		category: 'Workflow',
 		reference: ['', 'automation', ['git', 'network']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 	// The one write path for a `/code-review` round's findings, plus the
 	// `--check` gate `followup` runs before it merges. It appends a `- rf:`
 	// line per finding — or one zero-finding line for a clean round — to the observation ledger, so
 	// `observations:flush` commits them and the recurrence count survives the run.
 	'review:record': {
-		script: 'scripts/review/review-record-cli.ts',
+		script: 'scripts/review/review-record-main.ts',
 		description: 'Record a review round’s findings, or check a round was recorded',
 		category: 'Workflow',
 		reference: [
-			'--issue <N> [--comment] [<category>:<severity>:<file> ...] | --check --issue <N>',
+			'--issue <N> [--comment | --interaction] [<category>:<severity>:<file> ...] | --check [--interaction] --issue <N>',
 			'automation',
 			['files', 'network'],
 		],
+		usage: {
+			examples: [
+				{ arguments: `${REVIEW_ISSUE} bug-risks:medium:src/foo.ts:42 tests:low:a.test.ts` },
+				{ arguments: REVIEW_ISSUE, note: 'a zero-finding round — records one `none` line' },
+				{
+					arguments: `${REVIEW_ISSUE} --comment`,
+					note: 'a round that passed after the PR opened — an Issue comment, no append',
+				},
+				{ arguments: `${CHECK} ${REVIEW_ISSUE}`, note: 'the merge gate: was it recorded?' },
+				{
+					arguments: `${REVIEW_ISSUE} --interaction`,
+					note: 'the interaction review’s pass — a `- ri:` line',
+				},
+			],
+		},
+	},
+	// The reader over the durable review stop log: each finding that stopped a ship, with its file:line
+	// and first sentence, so a period's stops are classified without reading ship logs.
+	'review:stops': {
+		script: 'scripts/review/review-stops-cli.ts',
+		description:
+			'List the review findings that stopped a josh ship over a period, by kind, file:line and first sentence',
+		category: 'Workflow',
+		reference: ['[--period <days>]', 'developer', ['none']],
+		usage: { examples: [{ arguments: '--period 30', note: 'the last 30 days (default 7)' }] },
 	},
 	// The reader over what `review:record` wrote: each recurring category’s
 	// count, and the number of zero-finding rounds that distinguishes a quiet category from an unwatched one.
@@ -91,6 +225,7 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Count review findings by category from the observation ledger',
 		category: 'Workflow',
 		reference: ['', 'developer', ['files']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 	// After a behavior-change Issue merges, re-run its declared baseline and print before/after; a value
 	// that did not move appends a refuted-premise line to the observation ledger.
@@ -99,24 +234,32 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Re-run a merged issue’s baseline command and print the before/after pair',
 		category: 'Workflow',
 		reference: ['<issue-number>', 'automation', ['network', 'processes', 'files']],
+		usage: { examples: [{ arguments: '2212' }] },
 	},
 	// A script rather than an `sh -c` chain, because it has a precondition to enforce: run inside a
 	// linked work tree it would hijack the default branch from every other one.
 	'main:sync': {
-		script: 'scripts/git/main-sync.ts',
+		script: 'scripts/git/main-sync-main.ts',
 		description:
 			'Checkout default branch, pull latest, and prune merged remote-gone branches (refuses inside a lane)',
 		category: 'Workflow',
 		reference: ['', 'developer', ['git', 'network']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 	// A script rather than an `sh -c` chain, because the strategy has to be named rather than left to
 	// the caller's git configuration: a bare `git pull` aborts with `Need to specify how to reconcile
 	// divergent branches` on exactly the diverged branch the command exists for.
+	//
+	// **It declares no core weight, by measurement** (joshuafolkken/kit#3944): its own work is git, and
+	// the catalog it may regenerate took 0.6s of CPU. The heavy processes seen beside it are commit
+	// hooks — its regenerated catalog's commit runs them — which reserve themselves, and a weight here
+	// would set the held mark they inherit, folding the parallel hook tools into this one place.
 	'main:merge': {
-		script: 'scripts/git/main-merge.ts',
+		script: 'scripts/git/main-merge-main.ts',
 		description: 'Merge origin default branch into the current branch',
 		category: 'Workflow',
 		reference: ['', 'developer', ['git', 'network']],
+		usage: { examples: [{ arguments: '' }] },
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

package/scripts/josh/josh-logic.ts

@@ -1,9 +1,9 @@
-import { existsSync, readFileSync } from 'node:fs'
+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 { core_budget } from '#scripts/gate/core-budget'
-import { ancestor_directories } from '#scripts/lib/ancestor-directories'
+import { package_manifest } from '#scripts/lib/package-manifest'
 import { package_version_schema } from '#scripts/lib/schemas'
 import { resolve_spawn_exit } from '#scripts/lib/spawn-exit'
 import { execaSync } from 'execa'
@@ -18,13 +18,13 @@ import {
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from './josh-composite-arguments'
 import { josh_in_process } from './josh-in-process'
 import { kit_only } from './kit-only'
+import { find_package_directory } from './package-directory'
 import { run_github_prerequisite } from './run-github-prerequisite'
 
 const COLUMN_WIDTH = 26
 const ALIAS_PAD_WIDTH = 2
 const TSX_BIN = 'tsx'
 const TSX_PACKAGE = 'tsx'
-const PACKAGE_JSON = 'package.json'
 // Not an exit code the shell ever sees: `josh.ts` reads it as "no such command" and answers with
 // the listing on stderr. It is named because `run_command` now reports through a promise, where a
 // bare `-1` is one step further from the check that reads it.
@@ -35,17 +35,6 @@ interface TsxRunner {
 	leading_arguments: ReadonlyArray<string>
 }
 
-// Resolve the kit package root by ascending to the nearest package.json. This works both
-// from the bundled dist/josh.js (one level under the root) and from the tsx source at
-// scripts/josh/ (two levels), so this file's depth no longer has to be hard-coded.
-function find_package_directory(start_directory: string): string {
-	return (
-		ancestor_directories.nearest(start_directory, (directory) =>
-			existsSync(path.join(directory, PACKAGE_JSON)),
-		) ?? start_directory
-	)
-}
-
 const PACKAGE_DIR = find_package_directory(path.dirname(fileURLToPath(import.meta.url)))
 
 function resolve_tsx_executable(): string {
@@ -82,9 +71,7 @@ function resolve_tsx_runner(): TsxRunner {
 }
 
 function read_package_version(): string {
-	const raw = readFileSync(path.join(PACKAGE_DIR, PACKAGE_JSON), 'utf8')
-
-	return package_version_schema.parse(JSON.parse(raw)).version
+	return package_manifest.read_manifest(PACKAGE_DIR, package_version_schema).version
 }
 
 const HEADER = `josh v${read_package_version()} — Joshua Folkken's dev toolkit`
@@ -176,16 +163,11 @@ function format_unknown_command(cmd: string): string {
 	return `Unknown command: ${cmd}.${hint} Run 'josh --help' for common commands or 'josh --all' for the full list.`
 }
 
-// A `.cmd` shim needs the win32 shell to be executable, but the node binary does not — and
-// running it through the shell would break on the spaces in a typical Windows install path.
-function should_use_shell(executable: string): boolean {
-	return process.platform === 'win32' && executable !== process.execPath
-}
-
+// No `shell` option on purpose: execa runs a Windows `.cmd` shim itself and escapes the arguments
+// for cmd.exe, which the shell would receive unescaped.
 function spawn_script(tsx_executable: string, script_arguments: Array<string>): number {
 	const result = execaSync(tsx_executable, script_arguments, {
 		stdio: 'inherit',
-		shell: should_use_shell(tsx_executable),
 		reject: false,
 	})
 
@@ -287,6 +269,7 @@ function declared(value: number | (() => number) | undefined): number | undefine
 // without claiming a place. A command under a parent that already holds its cores claims nothing:
 // `core_budget.with_command_reservation` reads the mark that parent set.
 async function dispatch_entry(
+	command: string,
 	entry: CommandEntry,
 	subcommand_arguments: Array<string>,
 ): Promise<number> {
@@ -297,7 +280,7 @@ async function dispatch_entry(
 	return await core_budget.with_command_reservation(
 		weight,
 		async () => await run_entry(entry, subcommand_arguments),
-		{ memory_mb: declared(entry.memory_mb) },
+		{ memory_mb: declared(entry.memory_mb), command, is_unit: entry.is_unit_claim },
 	)
 }
 
@@ -314,7 +297,7 @@ async function run_command(
 	const early_exit = pre_dispatch_exit(resolved, entry, subcommand_arguments, is_consumer)
 	if (early_exit !== undefined) return early_exit
 
-	return await dispatch_entry(entry, subcommand_arguments)
+	return await dispatch_entry(resolved, entry, subcommand_arguments)
 }
 
 const josh_logic = {
@@ -330,10 +313,11 @@ export { ALIASES, 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 {
-	find_package_directory,
 	josh_logic,
 	resolve_alias,
 	resolve_tsx_executable,
 	resolve_tsx_runner,
 	UNKNOWN_COMMAND_EXIT_CODE,
 }
+
+export { find_package_directory } from './package-directory'

package/scripts/josh/josh.ts

@@ -1,4 +1,5 @@
 import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
+import { command_usage } from './command-usage'
 import { find_package_directory, josh_logic, UNKNOWN_COMMAND_EXIT_CODE } from './josh-logic'
 
 const ARGV_OFFSET = 2
@@ -12,10 +13,6 @@ const HELP_COMMANDS: ReadonlySet<string> = new Set(['help', '--help', '-h'])
 // 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).
@@ -24,6 +21,18 @@ function handle_unknown(cmd: string): never {
 	process.exit(1)
 }
 
+// `josh help <command>` prints that one command's usage — the text its reference page renders
+// (#3932); a flag in the topic slot is still a listing request (`josh --help --all`).
+function print_help(is_all: boolean, is_consumer: boolean, topic: string | undefined): void {
+	if (topic === undefined || topic.startsWith('-')) {
+		console.info(josh_logic.format_help(is_all, is_consumer))
+
+		return
+	}
+
+	console.info(command_usage.format_command_help(topic) ?? handle_unknown(topic))
+}
+
 // `process.exit` truncates a piped stdout at its buffer size, and 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
@@ -44,7 +53,7 @@ async function main(): Promise<void> {
 	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)
+		print_help(is_all, is_consumer, process.argv[ARGV_OFFSET + 1])
 
 		return
 	}

package/scripts/josh/package-directory.ts

@@ -0,0 +1,18 @@
+import { existsSync } from 'node:fs'
+import { ancestor_directories } from '#scripts/lib/ancestor-directories'
+import { package_manifest } from '#scripts/lib/package-manifest'
+
+// Resolve the kit package root by ascending to the nearest package.json. This works both
+// from the bundled dist/josh.js (one level under the root) and from the tsx source at
+// scripts/josh/ (two levels), so this file's depth no longer has to be hard-coded.
+// A leaf apart from `josh-logic`, so a bundled command can import it without pulling the
+// dispatcher's main-guarded closure into its single-file bundle.
+function find_package_directory(start_directory: string): string {
+	return (
+		ancestor_directories.nearest(start_directory, (directory) =>
+			existsSync(package_manifest.manifest_path(directory)),
+		) ?? start_directory
+	)
+}
+
+export { find_package_directory }

package/scripts/josh/process-identity.ts

@@ -3,8 +3,8 @@ import { randomUUID } from 'node:crypto'
 import { readFileSync, rmSync } from 'node:fs'
 import { createServer, type Server } from 'node:net'
 import path from 'node:path'
+import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
 import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
-import { PLATFORM_TEMP_ROOT } from './platform-temporary'
 
 // Whether the process a record names is still the one that wrote it.
 //
@@ -30,7 +30,7 @@ import { PLATFORM_TEMP_ROOT } from './platform-temporary'
 // `Tue Sep  8 09:15:33 2026` in one shell and `Tue Sep  8 02:15:33 2026` in another that exported
 // `TZ=UTC` — and a writer and reader disagreeing about `TZ` would read a live process as a stranger.
 // That failure is worse than the one this module fixes, because it fires on a gate that really is
-// running: `unit-worker-share` would sweep the marker of a live run and put every suite back on the
+// running: `unit-run-marker` would sweep the marker of a live run and put every suite back on the
 // whole machine, and `bench-guard` would clear the caches out from under a running gate. The probe
 // therefore pins `TZ` and `LC_ALL` rather than inheriting them.
 
@@ -237,11 +237,16 @@ function beacon_target(token: string): string | undefined {
 }
 
 // No status is a probe killed by its timeout or a signal — unknown, the same as its own timeout.
-function run_socket_probe(target: string): number | undefined {
+// `kill_after_ms` is a parameter so a test can ask what the probe itself reports for a socket
+// without a loaded machine's slow start turning the answer into the timeout's.
+function run_socket_probe(
+	target: string,
+	kill_after_ms: number = PROBE_TIMEOUT_MS,
+): number | undefined {
 	return (
 		spawnSync(process.execPath, ['-e', SOCKET_PROBE_SOURCE, target], {
 			stdio: 'ignore',
-			timeout: PROBE_TIMEOUT_MS,
+			timeout: kill_after_ms,
 		}).status ?? undefined
 	)
 }
@@ -359,6 +364,9 @@ function is_own_process(pid: number | undefined, recorded_start: string | undefi
 }
 
 const process_identity = {
+	PROBE_ENVIRONMENT,
+	START_PROBES,
+	START_TIME_FORMAT,
 	close_beacon,
 	is_live_beacon,
 	is_live_pid,
@@ -371,6 +379,7 @@ const process_identity = {
 	own_start,
 	read_start,
 	resolve_own_start,
+	run_socket_probe,
 }
 
 export { process_identity }

package/scripts/josh/session-language-cli.ts

@@ -1,8 +1,5 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { backlogrun_launch } from '#scripts/backlog/backlogrun-launch'
 import { run_carry } from '#scripts/run/carry/run-carry'
-import { josh_environment_file } from './josh-environment-file'
 import { session_language, type Resolution } from './session-language'
 
 // `josh session:lang` — say, on stdout, which language this session writes in, so a
@@ -43,7 +40,8 @@ const LIVE_PORTS: LivePorts = {
 	is_running: backlogrun_launch.is_running,
 }
 
-// The file load happens in `main`, on the command path only; the resolver reads the environment.
+// The file load happens in `session-language-main.ts`, on the command path only; the resolver reads
+// the environment.
 // The line carries the value alone: what the language covers is `CLAUDE.md` → "Output language",
 // already in context every turn, so repeating it here only spent context on each prompt. The default
 // prints nothing — that resident line already names `ja`.
@@ -68,8 +66,7 @@ function prompt_lines(resolution: Resolution, is_live: boolean): Array<string> {
 	return [format_line(resolution), is_live ? BOARD_LINE : ''].filter((line) => line !== '')
 }
 
-async function main(): Promise<void> {
-	josh_environment_file.load_environment_file()
+async function print_prompt_lines(): Promise<void> {
 	const lines = prompt_lines(resolve_session_lang(), await is_run_live())
 
 	for (const line of lines) console.info(line)
@@ -81,11 +78,10 @@ const session_language_cli = {
 	ENV_KEY,
 	format_line,
 	is_run_live,
+	print_prompt_lines,
 	prompt_lines,
 	resolve_session_lang,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
-
 export type { LivePorts }
 export { session_language_cli }

package/scripts/josh/session-language-main.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { josh_environment_file } from './josh-environment-file'
+import { session_language_cli } from './session-language-cli'
+
+// The `josh session:lang` entry and the `session-lang` hook bundle, kept apart from
+// `session-language-cli.ts` because `metrics-logic.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). `.env` is
+// read here, inside the guard, so a developer's own `.env` cannot decide what the unit tests see.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	josh_environment_file.load_environment_file()
+	await session_language_cli.print_prompt_lines()
+}

package/scripts/josh/session-language.ts

@@ -24,7 +24,12 @@ function resolve_session_lang(): Resolution {
 	return { lang: DEFAULT_SESSION_LANG, is_default: true }
 }
 
-const session_language = { DEFAULT_SESSION_LANG, ENV_KEY, resolve_session_lang }
+// `ja` and any regional form of it (`ja-JP`) is Japanese; every other language is the English fallback.
+function is_japanese(lang: string): boolean {
+	return lang.toLowerCase().startsWith(DEFAULT_SESSION_LANG)
+}
+
+const session_language = { DEFAULT_SESSION_LANG, ENV_KEY, resolve_session_lang, is_japanese }
 
 export type { Resolution }
 export { session_language }

package/scripts/josh/shared-cache.ts

@@ -0,0 +1,90 @@
+import { git_common_directory } from '#scripts/git/git-common-directory'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+import { stamp_file } from './stamp-file'
+
+// An answer one josh process read from GitHub, kept for the next process to reuse while it is fresh
+// (joshuafolkken/kit#4550).
+//
+// **Keyed to the repository's common git directory, so every work tree shares one record.** A
+// backlogrun asks the same question from its drive, its arrival probe and every lane at once; keying on
+// `PROJECT_ROOT` would give each work tree its own copy and each would read GitHub again.
+//
+// One record per slot: a different `key` replaces it rather than accumulating beside it, so the temp
+// directory holds at most one file per slot however many keys a run walks through.
+
+interface CacheSlot {
+	prefix: string
+	ttl_ms: number
+}
+
+const record_schema = z.object({
+	key: z.string(),
+	saved_at: z.number(),
+	value: z.unknown(),
+})
+
+function slot_path(slot: CacheSlot): string {
+	return stamp_file.stamp_path(slot.prefix, git_common_directory.repository() ?? PROJECT_ROOT)
+}
+
+function is_fresh(saved_at: number, slot: CacheSlot, now_ms: number): boolean {
+	return saved_at <= now_ms && now_ms - saved_at < slot.ttl_ms
+}
+
+function read_value(slot: CacheSlot, key: string, now_ms: number): unknown {
+	const raw = stamp_file.read_stamp_text(slot_path(slot))
+	const record = raw === undefined ? undefined : json_value.parse_with(raw, record_schema)
+
+	return record?.key === key && is_fresh(record.saved_at, slot, now_ms) ? record.value : undefined
+}
+
+// `undefined` is a miss: no record, another key's record, a stale one, or one that does not parse.
+function read<T>(
+	slot: CacheSlot,
+	key: string,
+	schema: z.ZodType<T>,
+	now_ms: number,
+): T | undefined {
+	const parsed = schema.safeParse(read_value(slot, key, now_ms))
+
+	return parsed.success ? parsed.data : undefined
+}
+
+// A write that fails leaves the next process to read GitHub itself — the answer this process already
+// has is still right, so the failure is not its caller's to handle.
+function write(slot: CacheSlot, key: string, value: unknown, now_ms: number): void {
+	try {
+		stamp_file.replace_stamp(slot_path(slot), { key, saved_at: now_ms, value })
+	} catch {
+		// The record is an optimization; a missing one costs one read.
+	}
+}
+
+// The cached answer for `key`, or `compute`'s — stored only when it is defined, so a failed read is
+// asked again by the next process rather than remembered for the whole TTL.
+async function remember<T>(
+	request: { slot: CacheSlot; key: string; schema: z.ZodType<T> },
+	compute: () => Promise<T | undefined>,
+	now_ms: number = Date.now(),
+): Promise<T | undefined> {
+	const cached = read(request.slot, request.key, request.schema, now_ms)
+
+	if (cached !== undefined) return cached
+
+	const value = await compute()
+
+	if (value !== undefined) write(request.slot, request.key, value, now_ms)
+
+	return value
+}
+
+function clear(slot: CacheSlot): void {
+	stamp_file.remove_stamp(slot_path(slot))
+}
+
+const shared_cache = { clear, read, remember, write }
+
+export { shared_cache }
+export type { CacheSlot }