@joshuafolkken/kit 1.1010.0 → 1.1050.0

package/scripts/run/run-ship-steps.ts

@@ -0,0 +1,105 @@
+import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+import { run_ship } from './run-ship'
+import { run_ship_preflight } from './run-ship-preflight'
+import { run_ship_review_steps } from './run-ship-review-steps'
+import { run_ship_scoped } from './run-ship-scoped'
+import { run_ship_stage, type ShipState, type Stage } from './run-ship-stage'
+
+// The stages `josh ship` runs, in the order a change ships (joshuafolkken/kit#2398), kept apart from the
+// chaining CLI so the order is read in one place.
+
+const should_forward_stderr = true
+
+interface ShipArguments {
+	title: string
+	number: string
+	notify: ReadonlyArray<string>
+	body: ReadonlyArray<string>
+	body_path: string | undefined
+	cites: ReadonlyArray<string>
+	is_review: boolean
+	is_detach: boolean
+}
+
+interface Step {
+	stage: Stage
+	header: string
+	run: (args: ShipArguments, state: ShipState) => Promise<JoshResult>
+}
+
+const { STAGE } = run_ship_stage
+
+async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
+	return await josh_command.josh_run(argv, should_forward_stderr)
+}
+
+// joshuafolkken/kit#2946: the pull request's preconditions and the scoped pair are asked first, so a
+// stop they would cause lands before the review and the gate rather than after them.
+const PREFLIGHT_STEP: Step = {
+	stage: STAGE.PREFLIGHT,
+	header: run_ship.PREFLIGHT_HEADER,
+	run: async (args) =>
+		await run_ship_preflight.stage({ title: args.title, body_path: args.body_path }),
+}
+
+// The gate before the commit, the commit/push/PR before the merge. The gate meets the scoped pair
+// first: a round-1 reviewer may have edited the tree since the preflight, and `josh gate` refuses a tree
+// with no green record (joshuafolkken/kit#2946). The commit step carries the `--skip-*` flags a resumed
+// ship needs, so an existing commit or push is never made twice.
+const COMMIT_STEPS: ReadonlyArray<Step> = [
+	{
+		stage: STAGE.GATE,
+		header: run_ship.GATE_HEADER,
+		run: async () =>
+			await run_ship_scoped.run_phases([
+				run_ship_scoped.scoped_pair,
+				async () => await josh(['gate']),
+			]),
+	},
+	{
+		stage: STAGE.COMMIT,
+		header: run_ship.COMMIT_HEADER,
+		run: async (args, state) =>
+			await josh(['git', '-y', ...run_ship_stage.commit_flags(state), ...args.body, args.title]),
+	},
+]
+
+// The merge before the report bookkeeping.
+const MERGE_STEPS: ReadonlyArray<Step> = [
+	{
+		stage: STAGE.FOLLOWUP,
+		header: run_ship.FOLLOWUP_HEADER,
+		run: async (args) => await josh(['followup', args.title, ...args.notify]),
+	},
+	{
+		stage: STAGE.REPORT,
+		header: run_ship.REPORT_HEADER,
+		run: async (args) => await josh(['run:tail', args.number, ...args.cites]),
+	},
+]
+
+// `--review` (joshuafolkken/kit#2427) puts the supervised round-1 review in front of the gate: it
+// launches the gate itself, so the gate stage that follows reuses that tree's green record. It also
+// puts the round-2 pass between the commit and the followup (joshuafolkken/kit#2489), so the PR opens
+// between the rounds and round 2 runs beside CI — a no-op when round 1 left no fix delta.
+const REVIEW_STEP: Step = {
+	stage: STAGE.REVIEW,
+	header: run_ship.REVIEW_HEADER,
+	run: async (args) => await run_ship_review_steps.review_stage(args.number),
+}
+const ROUND_TWO_STEP: Step = {
+	stage: STAGE.ROUND_TWO,
+	header: run_ship.ROUND_TWO_HEADER,
+	run: async (args) => await run_ship_review_steps.round_two_stage(args.number),
+}
+
+function steps(args: ShipArguments): ReadonlyArray<Step> {
+	if (!args.is_review) return [PREFLIGHT_STEP, ...COMMIT_STEPS, ...MERGE_STEPS]
+
+	return [PREFLIGHT_STEP, REVIEW_STEP, ...COMMIT_STEPS, ROUND_TWO_STEP, ...MERGE_STEPS]
+}
+
+const run_ship_steps = { steps }
+
+export type { ShipArguments, Step }
+export { run_ship_steps }

package/scripts/run/run-ship.ts

@@ -9,6 +9,7 @@
 // `run:tail`, ship stops at the first failed step: a red gate must never reach the commit, so the
 // composite ends at the failure, and the report names the step that failed so the run reads only it.
 
+const PREFLIGHT_HEADER = '=== preflight ==='
 const REVIEW_HEADER = '=== review ==='
 const GATE_HEADER = '=== gate ==='
 const COMMIT_HEADER = '=== commit/push/PR ==='
@@ -63,6 +64,7 @@ const run_ship = {
 	COMMIT_HEADER,
 	FOLLOWUP_HEADER,
 	GATE_HEADER,
+	PREFLIGHT_HEADER,
 	REPORT_HEADER,
 	REVIEW_HEADER,
 	ROUND_TWO_HEADER,

package/scripts/run/run-tail-cli.ts

@@ -17,9 +17,9 @@ import { run_tail, type TailSection } from './run-tail'
 //
 // **A dispatched lane child skips the ledger step** (joshuafolkken/kit#2492). A flush opens a
 // ledger-only pull request and waits out its whole CI before it merges — minutes per issue, spent on a
-// file only the retrospective and the measurements read. The line stays appended in the primary
-// checkout, and the `backlogrun` parent flushes once at its end (`run:carry --end`, `run-carry-flush.ts`).
-// A single run outside a lane keeps the step: its one end is already the run's end.
+// file only the retrospective and the measurements read — and a lane has nothing for it: its lines
+// merged with its own pull request (joshuafolkken/kit#2919). A single run outside a lane keeps the
+// step for a line written on the default branch outside any issue's run.
 
 const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0

package/scripts/run/run-tidy-stashes.ts

@@ -1,4 +1,3 @@
-import { readFile } from 'node:fs/promises'
 import { git_stash, type StashEntry } from '#scripts/git/git-stash'
 import { stash_orphans } from '#scripts/git/stash-orphans'
 import { stash_sweep_lock } from '#scripts/git/stash-sweep-lock'
@@ -18,16 +17,8 @@ const READ_CONCURRENCY = 8
 const GONE_REASON = 'already dropped by another run'
 const BUSY_REASON = 'another run held the stash sweep lock'
 
-async function read_ledger(ledger_path: string): Promise<string> {
-	try {
-		return await readFile(ledger_path, 'utf8')
-	} catch {
-		return ''
-	}
-}
-
-// An entry cut before joshuafolkken/kit#2724 holds its lines at the ledger's old path, so the lines of
-// every ledger path it touches are carried to the current ledger.
+// An entry cut before joshuafolkken/kit#2919 holds its lines at an old single-file path, so the lines
+// of every ledger path it touches are carried to the current ledger.
 async function added_ledger_lines(
 	hash: string,
 	ledger_paths: ReadonlyArray<string>,
@@ -43,16 +34,18 @@ async function added_ledger_lines(
 	return added
 }
 
-// How many ledger lines went into the primary checkout's ledger before the drop.
+// How many ledger lines went into the running work tree's ledger before the drop. The duplicate check
+// reads every issue's file, and the lines land in the file this tree writes (joshuafolkken/kit#2919),
+// so the run's own commit takes them to the default branch.
 async function carry_ledger(hash: string): Promise<number> {
 	const changed = await git_stash.changed_paths(hash)
 	const ledger_paths = changed.filter((file_path) => observation_ledger.is_ledger_path(file_path))
 
 	if (ledger_paths.length === 0) return 0
 
-	const ledger_path = observation_ledger_home.ledger_path()
+	const ledger_path = await observation_ledger_home.writer_path(new Date())
 	const added = await added_ledger_lines(hash, ledger_paths)
-	const carried = run_tidy.ledger_carry(added, await read_ledger(ledger_path))
+	const carried = run_tidy.ledger_carry(added, (await observation_ledger_home.read()) ?? '')
 
 	await observation_ledger_home.append(ledger_path, carried)
 

package/scripts/run/run-wake-cli.ts

@@ -2,9 +2,9 @@
 import { randomUUID } from 'node:crypto'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import type { AgentProfile } from '#scripts/agent/agent-role-profile'
 import { telegram_notify } from '#scripts/git/telegram-notify'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { run_carry, type CarryRead } from './run-carry'
 import { run_event_stream } from './run-event-stream'
 import { run_headless } from './run-headless'
@@ -120,11 +120,7 @@ function note_to_stderr(note: string): void {
 }
 
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	try {
-		return parseArgs({ args: [...argv], options: OPTIONS, strict: true }).values
-	} catch {
-		return undefined
-	}
+	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS, strict: true })?.values
 }
 
 function text_of(value: string | boolean | undefined): string | undefined {
@@ -294,7 +290,7 @@ function start(context: WakeContext, interval: string | undefined): number {
 	const existing = run_wake.read_wake(context.wake_target)
 
 	if (existing !== undefined && run_wake.is_supervisor_live(existing)) {
-		console.error(run_wake_describe.describe_wake(existing, context))
+		console.error(run_wake_describe.describe_wake_cited(existing, context))
 
 		return report(RUNNING_VERDICT)
 	}
@@ -346,7 +342,7 @@ function list(context: WakeContext): number {
 
 	if (wake === undefined) return report(NONE_VERDICT)
 
-	console.error(run_wake_describe.describe_wake(wake, context))
+	console.error(run_wake_describe.describe_wake_cited(wake, context))
 
 	return report(run_wake.is_supervisor_live(wake) ? SUPERVISING_VERDICT : STALE_VERDICT)
 }

package/scripts/run/run-wake-describe.ts

@@ -1,4 +1,6 @@
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { gh_spawn } from '#scripts/gh/gh-spawn'
+import { issue_citation } from '#scripts/rules/issue-citation'
 import { run_carry, type CarryRead } from './run-carry'
 import { run_event_stream } from './run-event-stream'
 import { run_liveness } from './run-liveness'
@@ -9,6 +11,7 @@ import { run_wake, type RunWake } from './run-wake'
 // record reads back to a person lives here, one cohesive block.
 
 const UNKNOWN_CUTS = 'an unreadable number of'
+const REPO_LOOKUP_TIMEOUT_MS = 10_000
 const STOP_COMMAND = 'pnpm josh run:wake --stop'
 
 // The three paths every verb needs: the carry record it reads, its own record, and the work tree a
@@ -91,7 +94,22 @@ function describe_wake(wake: RunWake, context: WakeContext): string {
 		.join('\n')
 }
 
-const run_wake_describe = { STOP_COMMAND, describe_wake }
+// The description as a person reads it, every issue on it a number-link (joshuafolkken/kit#2943). The
+// invocation and the newest event both name issues (`backlogrun #1 #2`, `#1904 merged`), and a report
+// that copies them bare is what the Stop guard sends back. The repository is asked here, bounded, rather
+// than in the context every verb resolves: only the two describing verbs print it, and a lookup that
+// does not answer leaves the description as it was rather than withholding it.
+function cite_description(description: string, repo: string | undefined): string {
+	return repo === undefined ? description : issue_citation.linkify(description, repo)
+}
+
+function describe_wake_cited(wake: RunWake, context: WakeContext): string {
+	const repo = gh_spawn.get_repo_name_with_owner_within(REPO_LOOKUP_TIMEOUT_MS)
+
+	return cite_description(describe_wake(wake, context), repo)
+}
+
+const run_wake_describe = { STOP_COMMAND, cite_description, describe_wake, describe_wake_cited }
 
 export type { WakeContext }
 export { run_wake_describe }

package/scripts/run/run-wake-driver.ts

@@ -6,6 +6,8 @@ import type { DriveResult } from './run-wake-loop'
 const SUCCESS = 0
 const FIRST_LINE = 0
 const RESUME_PREFIX = 'resume: '
+const DETAILS_TAIL_LENGTH = 2048
+const TRUNCATION_MARK = '... '
 
 function driver_args(invocation: string): ReadonlyArray<string> | undefined {
 	const rebuilt = run_invocation.rebuild(invocation)
@@ -24,13 +26,24 @@ function is_final_stop(verdict: string | undefined, read: CarryRead): boolean {
 	return verdict?.startsWith('stop') === true && read.kind === 'none'
 }
 
+// **The details are the driver's whole stderr, so only their tail is handed on, and it goes last**
+// (joshuafolkken/kit#2931). The stderr carries every command the driver ran since it started, which
+// after a long run is tens of kilobytes — far past what `is_safe_value` lets into an argv element. Its
+// tail is where the reason for stopping is; placing it last means the cap `wake_argv` applies to the
+// whole prompt can only ever cut into the details, never the verdict, the resume line or the epic note.
+function details_tail(details: string): string {
+	return details.length > DETAILS_TAIL_LENGTH
+		? `${TRUNCATION_MARK}${details.slice(-DETAILS_TAIL_LENGTH)}`
+		: details
+}
+
 function handoff_material(verdict: string, resume: string, details: string): string {
-	const context = details === '' ? '' : `\nDetails: ${details}`
+	const context = details === '' ? '' : `\nDetails: ${details_tail(details)}`
 	const epic = verdict.startsWith('epic #')
 		? '\nThe named item is an epic. Follow backlogrun-steps.md named epic procedure; do not launch the epic root as a fullrun child. After all children merge or park, record the root with pnpm josh run:carry --done <epic-number> --owner "$PPID" before continuing to the next named item.'
 		: ''
 
-	return `Driver result: ${verdict}\n${resume}${context}${epic}`
+	return `Driver result: ${verdict}\n${resume}${epic}${context}`
 }
 
 function driver_result(out: string, read: CarryRead, details = ''): DriveResult {

package/scripts/run/run-wake-session.ts

@@ -37,6 +37,8 @@ const WAKE_FLAGS = claude_agent_argv.AGENT_FLAGS
 const LOOP_FLAG = '--loop'
 const INTERVAL_FLAG = '--interval'
 const SUPERVISOR_SESSION = 'run-wake-supervisor'
+// eslint-disable-next-line no-control-regex -- matching control characters is the point
+const CONTROL_CHARACTERS = /[\u{0}-\u{1F}\u{7F}]/gu
 
 function scheduler_profile(): AgentProfile | undefined {
 	const resolved = agent_role_profile.resolve(agent_role_profile.SCHEDULER)
@@ -96,6 +98,17 @@ function resolved_argv(invocation: string, cwd?: string): AgentArgvResult {
 		: agent_argv.resolve_in(invocation, agent_role_profile.SCHEDULER, cwd)
 }
 
+// **Handoff material is made safe to launch rather than refused** (joshuafolkken/kit#2931). It is the
+// driver's own output, not the record, so it is flattened — a newline becomes a separator, any other
+// control character a space — and the prompt is cut at the cap `is_safe_value` enforces. The driver puts
+// its verdict and resume line first, so the cut only ever shortens the details. The check itself is
+// untouched: the argv still passes `is_safe_argv` before anything is spawned.
+function handoff_prompt(matched: string, material: string): string {
+	const flattened = material.replaceAll('\n', ' | ').replaceAll(CONTROL_CHARACTERS, ' ')
+
+	return `${matched} | Driver handoff: ${flattened}`.slice(0, agent_role_profile.MAX_VALUE_LENGTH)
+}
+
 function wake_argv(
 	invocation: string,
 	profile?: AgentProfile,
@@ -104,10 +117,7 @@ function wake_argv(
 ): AgentArgvResult | undefined {
 	const matched = safe_invocation(invocation)
 	if (matched === undefined) return undefined
-	const prompt =
-		typeof session === 'object'
-			? `${matched} | Driver handoff: ${session.material.replaceAll('\n', ' | ')}`
-			: matched
+	const prompt = typeof session === 'object' ? handoff_prompt(matched, session.material) : matched
 	const session_id = typeof session === 'object' ? session.id : session
 
 	return profile === undefined

package/scripts/run/run-watcher-hook.ts

@@ -81,6 +81,6 @@ async function watcher_hook_reason(
 	return await stale_reason(transcript, now_ms)
 }
 
-const run_watcher_hook = { SWITCH_ENV_KEY, STAMP_PREFIX, watcher_hook_reason }
+const run_watcher_hook = { SWITCH_ENV_KEY, STAMP_PREFIX, transcript_of, watcher_hook_reason }
 
 export { run_watcher_hook }

package/scripts/safe-chain/project-config.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
+import { file_reader } from '#scripts/lib/read-file'
 import { release_age } from '#scripts/version/release-age'
 import { yaml_document } from '#scripts/yaml/yaml-document'
 import { dump } from 'js-yaml'
@@ -126,17 +127,13 @@ function merge_project_config(existing: string, workspace: string, npmrc = ''):
 	return replace_safe_chain_block(existing, merged)
 }
 
-function read_optional(file_path: string): string {
-	return existsSync(file_path) ? readFileSync(file_path, 'utf8') : ''
-}
-
 function sync_project_config(root: string): boolean {
 	const workspace_path = path.join(root, WORKSPACE_FILE)
 	if (!existsSync(workspace_path)) return false
 	const config_path = path.join(root, PROJECT_CONFIG_FILE)
-	const existing = read_optional(config_path)
+	const existing = file_reader.read_file_or_empty(config_path)
 	const workspace = readFileSync(workspace_path, 'utf8')
-	const npmrc = read_optional(path.join(root, NPMRC_FILE))
+	const npmrc = file_reader.read_file_or_empty(path.join(root, NPMRC_FILE))
 	const merged = merge_project_config(existing, workspace, npmrc)
 	if (merged === existing) return false
 	writeFileSync(config_path, merged)

package/scripts/security/security-audit-provision.ts

@@ -4,6 +4,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { error_text } from '#scripts/lib/error-message'
 import { security_audit } from './security-audit'
 import { security_audit_logic } from './security-audit-logic'
 import { security_audit_provision_logic, type ScannerAsset } from './security-audit-provision-logic'
@@ -14,10 +15,6 @@ const FORCE_FLAG = '--force'
 const PATH_LOCATION = 'on PATH'
 const { RETRY_INTERVAL_MS } = security_audit_provision_logic
 
-function describe_error(error: unknown): string {
-	return error instanceof Error ? error.message : String(error)
-}
-
 // `content` absent is the failure, and `reason` says which one. A 404 — what a bumped version whose
 // asset was renamed looks like, and the one failure that never fixes itself — would otherwise read
 // exactly like a transient 503, and a rejected request like neither.
@@ -41,7 +38,7 @@ async function download(url: string, timeout_ms: number): Promise<DownloadOutcom
 
 		return { content: Buffer.from(await response.arrayBuffer()), reason: '' }
 	} catch (error) {
-		return { reason: describe_error(error) }
+		return { reason: error_text.message_of(error) }
 	}
 }
 
@@ -128,7 +125,7 @@ async function attempt(
 	} catch (error) {
 		return record_failure(
 			target_path,
-			security_audit_provision_logic.format_provision_error(describe_error(error)),
+			security_audit_provision_logic.format_provision_error(error_text.message_of(error)),
 		)
 	}
 }
@@ -175,7 +172,9 @@ async function main(): Promise<void> {
 	try {
 		console.info(await report(PROJECT_ROOT, process.platform, process.arch, is_forced))
 	} catch (error) {
-		console.warn(security_audit_provision_logic.format_provision_error(describe_error(error)))
+		console.warn(
+			security_audit_provision_logic.format_provision_error(error_text.message_of(error)),
+		)
 	}
 }
 

package/scripts/sonar/sonar-hotspots-cli.ts

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { git_command } from '#scripts/git/git-command'
+import { error_text } from '#scripts/lib/error-message'
 import { managed_config_scope } from '#scripts/sync/managed-config-scope'
 import { z } from 'zod'
 import {
@@ -69,7 +70,7 @@ async function fetch_hotspots(url: string): Promise<HotspotFetch> {
 
 		return { hotspots: parsed.hotspots ?? [] }
 	} catch (error) {
-		return { error: error instanceof Error ? error.message : String(error) }
+		return { error: error_text.message_of(error) }
 	}
 }
 

package/scripts/sync/directory-copy-guard.ts

@@ -1,6 +1,7 @@
 import { cpSync, lstatSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { transform_copied_content } from '#scripts/init/init-copy-content'
+import { error_text } from '#scripts/lib/error-message'
 import { file_content } from './file-content'
 
 // `josh init` and `josh sync` both copy a distributed directory with `cpSync`, and both have to
@@ -143,7 +144,7 @@ function copy_directory(source_path: string, destination_path: string): boolean
 // throw here would end `josh init` or `josh sync` in the middle of their work. The message is
 // returned for the caller to report, the same way a blocker is.
 function failure_message(prefix: string, error: unknown): string {
-	return `${prefix} (${error instanceof Error ? error.message : String(error)})`
+	return `${prefix} (${error_text.message_of(error)})`
 }
 
 // The two failures are reported apart because they leave the destination in opposite states, and

package/scripts/sync/sync-ai-files.ts

@@ -5,6 +5,7 @@ import { transform_copied_content } from '#scripts/init/init-copy-content'
 import { init_logic } from '#scripts/init/init-logic'
 import { PACKAGE_DIR, PROJECT_ROOT } from '#scripts/init/init-paths'
 import type { ProjectShape } from '#scripts/init/project-profile'
+import { file_reader } from '#scripts/lib/read-file'
 import { copy_directory_failure, directory_copy_blocker } from './directory-copy-guard'
 import { file_content } from './file-content'
 import { REMOVED_SKILL_MANIFEST } from './removed-skill-manifest'
@@ -70,8 +71,7 @@ function sync_workspace_yaml(
 	is_force = false,
 ): boolean {
 	const template = readFileSync(template_path, 'utf8')
-	const existing =
-		!is_force && existsSync(destination_path) ? readFileSync(destination_path, 'utf8') : ''
+	const existing = is_force ? '' : file_reader.read_file_or_empty(destination_path)
 	const merged = init_logic.merge_workspace_yaml(existing, template)
 
 	return file_content.write_text_if_changed(destination_path, merged)
@@ -155,7 +155,7 @@ function ensured_claude_md(existing: string | undefined, shape?: ProjectShape):
 // without ever disturbing those additions — so this ignores --force, which would otherwise mean
 // discarding a consumer's content.
 function sync_claude_md(destination_path: string, shape?: ProjectShape): void {
-	const existing = existsSync(destination_path) ? readFileSync(destination_path, 'utf8') : undefined
+	const existing = file_reader.read_optional(destination_path)
 	const ensured = ensured_claude_md(existing, shape)
 
 	if (ensured === existing) {

package/scripts/sync/template-source-logic.ts

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto'
-import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { copyFileSync, readFileSync, writeFileSync } from 'node:fs'
 import { package_path } from '#scripts/init/init-paths'
+import { file_reader } from '#scripts/lib/read-file'
 import { z } from 'zod'
 
 interface TemplateSourcePair {
@@ -39,9 +40,7 @@ function read_file(relative_path: string): string {
 }
 
 function read_optional_file(relative_path: string): string {
-	const full_path = package_path(relative_path)
-
-	return existsSync(full_path) ? readFileSync(full_path, 'utf8') : ''
+	return file_reader.read_file_or_empty(package_path(relative_path))
 }
 
 function hash_text(text: string): string {

package/scripts/test/e2e-retry-check.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env tsx
-import { appendFileSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { appendFileSync, readdirSync, statSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { file_reader } from '#scripts/lib/read-file'
 
 // Whether the preview server process died during a failed E2E attempt.
 //
@@ -59,11 +60,7 @@ function has_crash_signature(log_text: string): boolean {
 }
 
 function read_file_safe(file_path: string): string {
-	try {
-		return readFileSync(file_path, 'utf8')
-	} catch {
-		return ''
-	}
+	return file_reader.read_if_readable(file_path) ?? ''
 }
 
 // Every file under the directory, because wrangler names the debug log after the run and a job that

package/scripts/time-runtime/time-bundle-call.ts

@@ -336,8 +336,8 @@ function josh_subcommand(command: string): string | undefined {
 }
 
 // Whether a shell line is one of the read-only `josh` bookkeeping commands, and nothing else. A chained
-// line falls through. An alias is resolved to its canonical name first — a run may type `josh ist` for
-// `issue:state` — so the allow-list holds canonical names alone. Everything not on the list falls
+// line falls through. An alias is resolved to its canonical name first, so the allow-list holds
+// canonical names alone. Everything not on the list falls
 // through to the read/mutation test, which is what keeps `josh gate` / `followup` / `git`
 // non-bundleable (joshuafolkken/kit#1875).
 function is_read_josh(command: string): boolean {

package/scripts/ui/ui-routes-cli.ts

@@ -1,9 +1,10 @@
 #!/usr/bin/env tsx
-import { readdirSync, readFileSync } from 'node:fs'
+import { readdirSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { changed_paths } from '#scripts/git/changed-paths'
 import { git_command } from '#scripts/git/git-command'
+import { file_reader } from '#scripts/lib/read-file'
 import { ui_routes } from './ui-routes'
 
 // `josh ui:routes [--staged]` — list the screenshot-target routes the current change touches
@@ -59,11 +60,7 @@ function route_files(root: string): Array<RouteFile> {
 }
 
 function read_text(file: string): string {
-	try {
-		return readFileSync(file, 'utf8')
-	} catch {
-		return ''
-	}
+	return file_reader.read_if_readable(file) ?? ''
 }
 
 // A route file imports the component when its source names the component's file — the import

package/scripts/version/bump-version.ts

@@ -2,6 +2,7 @@
 import { readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { error_text } from '#scripts/lib/error-message'
 import { json_object_schema, package_with_version_schema } from '#scripts/lib/schemas'
 import semver from 'semver'
 
@@ -61,7 +62,7 @@ function main(): void {
 	try {
 		bump_version(bump_type as BumpType)
 	} catch (error) {
-		console.error(error instanceof Error ? error.message : String(error))
+		console.error(error_text.message_of(error))
 		process.exit(1)
 	}
 }