@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/lane/process-directories.ts

@@ -0,0 +1,70 @@
+import { spawnSync } from 'node:child_process'
+import path from 'node:path'
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { lane_paths } from './lane-paths'
+
+// Each process's working directory, read with `lsof` — the one place its output is parsed.
+//
+// **A process belongs to a lane by its working directory first, its ancestry only after.** A process
+// detached from a lane (`josh ship --detach`, a diagnostic started under `script`) is re-parented to
+// pid 1, so no parent chain reaches it, while its working directory still sits under `.kit-lanes/<N>`.
+// `run:board` draws such a process as a lane's or a leftover, and `lane:close` ends it
+// (joshuafolkken/kit#4304); the board falls back to the ancestry where the directory names no lane
+// (`run-board-usage-lanes.ts`).
+// **macOS alone**, as the board reads it: elsewhere nothing is listed.
+
+const LSOF_COMMAND = 'lsof'
+// `-a` joins the conditions: the `cwd` descriptor only, in `-F` fields. The board appends `-p <pids>`.
+const CWD_ARGUMENTS = ['-a', '-d', 'cwd', '-Fn']
+// `lsof -F`'s field lines: `p<pid>` opens a process, `n<path>` names its directory.
+const LSOF_PROCESS = /^(?=p)/mu
+const LSOF_NAME = 'n'
+const LISTING_PLATFORMS: ReadonlySet<NodeJS.Platform> = new Set(['darwin'])
+
+function lsof_block(block: string): [number, string] | undefined {
+	const [process_line = '', ...rest] = block.trim().split('\n')
+	const name = rest.find((line) => line.startsWith(LSOF_NAME))
+
+	return name === undefined ? undefined : [Number(process_line.slice(1)), name.slice(1)]
+}
+
+/** Each process's working directory from `lsof -F`'s output. */
+function parse(output: string): Map<number, string> {
+	const blocks = output.split(LSOF_PROCESS).map((block) => lsof_block(block))
+
+	return new Map(blocks.filter((block) => block !== undefined))
+}
+
+/**
+ * Every process's working directory, `undefined` where `lsof` could not be run or timed out — never
+ * read as "nothing there". `lsof` exits non-zero when one process cannot be read and still lists the
+ * rest, so its output is read whatever the exit status.
+ */
+function list_all(platform: NodeJS.Platform = process.platform): Map<number, string> | undefined {
+	if (!LISTING_PLATFORMS.has(platform)) return new Map()
+
+	const result = spawnSync(LSOF_COMMAND, CWD_ARGUMENTS, {
+		encoding: 'utf8',
+		timeout: PROBE_TIMEOUT_MS,
+		stdio: ['ignore', 'pipe', 'ignore'],
+	})
+
+	return result.error === undefined ? parse(result.stdout) : undefined
+}
+
+/**
+ * The lane of `root` a directory sits under — itself or a directory above it, the outermost first.
+ * The one lane-membership reading: the board draws a leftover by it, and the close ends by it
+ * (joshuafolkken/kit#4300).
+ */
+function lane_of(directory: string, root: string): string | undefined {
+	const parts = directory.split(path.sep)
+	const ancestors = parts.map((_, index) => parts.slice(0, index + 1).join(path.sep)).slice(1)
+	const environment = { [lane_paths.LANE_ROOT_KEY]: root }
+
+	return ancestors.map((ancestor) => lane_paths.lane_issue_of(ancestor, environment)).find(Boolean)
+}
+
+const process_directories = { CWD_ARGUMENTS, lane_of, list_all, parse }
+
+export { process_directories }

package/scripts/lane/process-lane-marks.ts

@@ -0,0 +1,94 @@
+import { spawnSync } from 'node:child_process'
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { lane_child_marker } from './lane-child-marker'
+
+// Each process's lane mark — the `JOSH_LANE_CHILD` it inherited — read from `ps -E`
+// (joshuafolkken/kit#4315).
+//
+// **A process belongs to a lane by its mark wherever it runs.** A lane child that measures something
+// from the main checkout or `/tmp` leaves processes whose working directory is not under the lane, and
+// one started under `script` or a new session has left the child's tree and group for pid 1. The
+// environment survives all of that, and `lane:dispatch` puts the issue number in it
+// (`lane-child-marker.ts`), so the mark names the lane a process was started from.
+//
+// **The mark is read from the environment, never from the arguments.** `ps -E` appends the environment
+// to the command line, so the plain command line is read too and only what follows it is searched: a
+// `grep JOSH_LANE_CHILD=42` carries the text without the mark.
+//
+// **An application bundle is never marked.** A lane that opened Docker Desktop passed its environment
+// to an application the whole machine uses; it is a person's, not the lane's.
+//
+// **macOS alone**, as `process-directories.ts` reads it: elsewhere nothing is listed.
+
+const PS_COMMAND = '/bin/ps'
+const LISTING_ARGUMENTS = ['-A', '-ww', '-o', 'pid=,command=']
+const ENVIRONMENT_FLAG = '-E'
+// `ps -E` over every process runs to hundreds of kilobytes; the default 1 MiB would cut it short.
+const LISTING_BUFFER_BYTES = 67_108_864
+const PID_LINE = /^\s*(?<pid>\d+) (?<command>.*)$/u
+const APPLICATION_BUNDLE = '.app/Contents/'
+const LISTING_PLATFORMS: ReadonlySet<NodeJS.Platform> = new Set(['darwin'])
+const MARK = new RegExp(String.raw`(?:^|\s)${lane_child_marker.KEY}=(?<issue>\d+)(?=\s|$)`, 'u')
+
+function command_lines(printed: string): Map<number, string> {
+	const groups = printed.split('\n').map((line) => PID_LINE.exec(line)?.groups)
+
+	return new Map(
+		groups
+			.filter((group) => group !== undefined)
+			.map((group) => [Number(group['pid']), group['command'] ?? '']),
+	)
+}
+
+// What `ps -E` printed after the plain command line; `undefined` for an application bundle and for a
+// process the two listings disagree on (it ended or exec'd between them).
+function environment_of(command: string | undefined, with_environment: string): string | undefined {
+	if (command === undefined || command.includes(APPLICATION_BUNDLE)) return undefined
+
+	return with_environment.startsWith(command) ? with_environment.slice(command.length) : undefined
+}
+
+function mark_of(command: string | undefined, with_environment: string): string | undefined {
+	const environment = environment_of(command, with_environment)
+
+	return environment === undefined ? undefined : MARK.exec(environment)?.groups?.['issue']
+}
+
+/** Each marked process's issue, from `ps`'s plain and `-E` listings. */
+function parse(plain: string, with_environment: string): Map<number, string> {
+	const commands = command_lines(plain)
+	const marks = [...command_lines(with_environment)].map(
+		([pid, line]) => [pid, mark_of(commands.get(pid), line)] as const,
+	)
+
+	return new Map(marks.filter((pair): pair is [number, string] => pair[1] !== undefined))
+}
+
+function listing(arguments_: ReadonlyArray<string>): string | undefined {
+	const result = spawnSync(PS_COMMAND, arguments_, {
+		encoding: 'utf8',
+		maxBuffer: LISTING_BUFFER_BYTES,
+		timeout: PROBE_TIMEOUT_MS,
+		stdio: ['ignore', 'pipe', 'ignore'],
+	})
+
+	return result.error === undefined ? result.stdout : undefined
+}
+
+/**
+ * Every marked process's issue, `undefined` where `ps` could not be run or timed out — never read as
+ * "nothing marked".
+ */
+function list_all(platform: NodeJS.Platform = process.platform): Map<number, string> | undefined {
+	if (!LISTING_PLATFORMS.has(platform)) return new Map()
+	const plain = listing(LISTING_ARGUMENTS)
+	const with_environment = listing([ENVIRONMENT_FLAG, ...LISTING_ARGUMENTS])
+
+	if (plain === undefined || with_environment === undefined) return undefined
+
+	return parse(plain, with_environment)
+}
+
+const process_lane_marks = { list_all, parse }
+
+export { process_lane_marks }

package/scripts/lib/atomic-write.ts

@@ -0,0 +1,62 @@
+import { randomUUID } from 'node:crypto'
+import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+// Replacing a file so a concurrent reader sees the old content or the new, never half of either.
+//
+// The content is written to a staging file and renamed over the target; `rename` swaps the path
+// itself, so a reader that opened the old file keeps reading it. **The staging name is unique per
+// write** — process id and a random UUID — because two writers sharing one name interleave their bytes
+// into the same staging file and both rename the mix into place. Create-exclusively refuses a name
+// someone else already holds rather than writing through it, and the `finally` removes the staging
+// file on every failing path. The `.tmp` ending keeps it out of a directory scan that matches the
+// target's own extension.
+
+const STAGING_EXTENSION = '.tmp'
+const CREATE_EXCLUSIVE_FLAG = 'wx'
+
+interface AtomicWriteOptions {
+	// Given to the create, so a private file is never readable at another mode in between, and
+	// applied again with `chmod`, so the umask cannot narrow it.
+	readonly mode?: number
+	// Where the staging file is written; the target's directory by default. It must sit on the
+	// target's filesystem for the rename to stay atomic.
+	readonly staging_directory?: string
+}
+
+function staging_path(target: string, staging_directory: string): string {
+	const name = `${path.basename(target)}.${String(process.pid)}.${randomUUID()}${STAGING_EXTENSION}`
+
+	return path.join(staging_directory, name)
+}
+
+function write_staged(staging: string, content: string | Uint8Array, mode?: number): void {
+	writeFileSync(staging, content, {
+		flag: CREATE_EXCLUSIVE_FLAG,
+		...(mode !== undefined && { mode }),
+	})
+	if (mode !== undefined) chmodSync(staging, mode)
+}
+
+function replace_file(
+	target: string,
+	content: string | Uint8Array,
+	options: AtomicWriteOptions = {},
+): void {
+	const directory = options.staging_directory ?? path.dirname(target)
+	const staging = staging_path(target, directory)
+
+	mkdirSync(directory, { recursive: true })
+
+	try {
+		write_staged(staging, content, options.mode)
+		renameSync(staging, target)
+	} finally {
+		rmSync(staging, { force: true })
+	}
+}
+
+const atomic_write = { replace_file }
+
+export { atomic_write }
+export type { AtomicWriteOptions }

package/scripts/lib/buffered-process.ts

@@ -69,6 +69,16 @@ function collect_output(all: string, reason: ReadonlyArray<string>): string {
 	return [all, ...reason].filter((part) => part !== '').join('\n')
 }
 
+// A buffered child writes to a pipe, so it is told to keep its colors unless the caller opted out.
+// Exported for the eslint daemon route (`eslint-daemon.ts`), which buffers the same way.
+function child_environment(): NodeJS.ProcessEnv {
+	const environment = { ...process.env }
+	if (environment['NO_COLOR'] === undefined) environment['FORCE_COLOR'] = FORCE_COLOR
+	else delete environment['FORCE_COLOR']
+
+	return environment
+}
+
 async function run_buffered_process(
 	command_args: ReadonlyArray<string>,
 	options: BufferedProcessOptions = {},
@@ -76,14 +86,11 @@ async function run_buffered_process(
 	// `performance.now()` rather than `Date.now()`: it is monotonic, so a system clock adjusted
 	// mid-check cannot produce a negative or wildly inflated duration.
 	const started_at = performance.now()
-	const environment = { ...process.env }
-	if (environment['NO_COLOR'] === undefined) environment['FORCE_COLOR'] = FORCE_COLOR
-	else delete environment['FORCE_COLOR']
 	// `cwd` is spread in rather than assigned: `exactOptionalPropertyTypes` refuses an explicit
 	// `undefined` for an optional `string`, and passing one anyway breaks execa's overload
 	// resolution — which silently widens `result.all` back to `string | undefined`.
 	const result = await execa(PNPM, [...command_args], {
-		env: environment,
+		env: child_environment(),
 		extendEnv: false,
 		all: true,
 		reject: false,
@@ -104,7 +111,7 @@ function is_process_failed(result: Pick<BufferedProcessResult, 'exit_code'>): bo
 	return result.exit_code !== 0
 }
 
-const buffered_process = { is_process_failed, run_buffered_process }
+const buffered_process = { child_environment, is_process_failed, run_buffered_process }
 
 export type { BufferedProcessResult }
 export { buffered_process, FAIL_EXIT_CODE }

package/scripts/lib/cli-flags.ts

@@ -152,7 +152,59 @@ function attach_values(
 	return attached
 }
 
+// Digits and nothing else. `Number('')`, `Number(' ')` and `Number('0x10')` are all safe integers, so a
+// check that only asked `Number.isSafeInteger` would read an unset shell variable — `--max
+// "$max_issues"` — as zero. The magnitude check is separate because the pattern bounds nothing: a
+// number past the safe range would be read as a different number.
+const COUNT_PATTERN = /^\d+$/u
+// Whole and positive: `0`, a sign, a decimal point and anything not a digit are refused.
+const POSITIVE_PATTERN = /^[1-9]\d*$/u
+
+// The value a positive-integer setting answers, or why it could not be read. A problem rather than a
+// throw: the caller decides whether a bad setting ends the command or is reported and worked around.
+type PositiveSetting = { kind: 'limit'; limit: number } | { kind: 'problem'; problem: string }
+
+function to_integer(raw: string | undefined, pattern: RegExp): number | undefined {
+	if (raw === undefined || !pattern.test(raw)) return undefined
+
+	const parsed = Number(raw)
+
+	return Number.isSafeInteger(parsed) ? parsed : undefined
+}
+
+// A count flag's value — zero or more — or `undefined` when it is absent or not a count.
+function to_count(raw: string | undefined): number | undefined {
+	return to_integer(raw, COUNT_PATTERN)
+}
+
+// A value that must be one or more, or `undefined` when it is absent or not.
+function to_positive(raw: string | undefined): number | undefined {
+	return to_integer(raw, POSITIVE_PATTERN)
+}
+
+// A positive-integer setting read from the environment or an argument. Blank is unset, not invalid — an
+// `.env` line left as `KEY=` is a setting nobody configured — and answers `fallback`. Anything else that
+// is not a positive integer is a problem naming `name`, never a silent fall back to the default: a typo
+// that quietly became the default is a number nobody chose.
+function read_positive_setting(
+	raw: string | undefined,
+	name: string,
+	fallback: number,
+): PositiveSetting {
+	const trimmed = raw?.trim() ?? ''
+
+	if (trimmed === '') return { kind: 'limit', limit: fallback }
+
+	const limit = to_positive(trimmed)
+	if (limit !== undefined) return { kind: 'limit', limit }
+
+	return { kind: 'problem', problem: `${name} must be a positive integer, not "${trimmed}"` }
+}
+
 const cli_flags = {
+	to_count,
+	to_positive,
+	read_positive_setting,
 	attach_values,
 	usage_line,
 	refuse_unknown_flags,
@@ -167,3 +219,4 @@ const cli_flags = {
 }
 
 export { cli_flags }
+export type { PositiveSetting }

package/scripts/lib/figure-format.ts

@@ -0,0 +1,63 @@
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
+
+// The figures the reports print — a dollar amount, a token count, a percentage share, a duration in
+// minutes and a local wall clock — and the precision each uses. The cost reports, `josh time`'s
+// reports, `run:board` and the run event pane all render these, so each is written once here.
+
+const USD_DECIMALS = 4
+const PERCENT_SCALE = 100
+const PERCENT_DECIMALS = 1
+const MINUTE_DECIMALS = 1
+const CLOCK_WIDTH = 2
+const CLOCK_PAD = '0'
+
+// The caller names the decimals where its figure rounds to another place — a run total to the cent.
+function format_usd(usd: number, decimals: number = USD_DECIMALS): string {
+	return `$${usd.toFixed(decimals)}`
+}
+
+function format_tokens(count: number): string {
+	return count.toLocaleString('en-US')
+}
+
+function format_share(part: number, whole: number): string {
+	if (whole === 0) return 'n/a'
+
+	return `${((part / whole) * PERCENT_SCALE).toFixed(PERCENT_DECIMALS)}%`
+}
+
+function format_minutes(duration_ms: number): string {
+	return `${(duration_ms / MS_PER_MINUTE).toFixed(MINUTE_DECIMALS)} min`
+}
+
+function two_digits(value: number): string {
+	return String(value).padStart(CLOCK_WIDTH, CLOCK_PAD)
+}
+
+// The local wall-clock `HH:MM:SS` of a moment.
+function clock_of(ms: number): string {
+	const date = new Date(ms)
+
+	return [date.getHours(), date.getMinutes(), date.getSeconds()]
+		.map((value) => two_digits(value))
+		.join(':')
+}
+
+// The local wall-clock `HH:MM` of a moment, for one a person reads to the minute.
+function minute_of(ms: number): string {
+	const date = new Date(ms)
+
+	return [date.getHours(), date.getMinutes()].map((value) => two_digits(value)).join(':')
+}
+
+const figure_format = {
+	format_usd,
+	format_tokens,
+	format_share,
+	format_minutes,
+	two_digits,
+	clock_of,
+	minute_of,
+}
+
+export { figure_format }

package/scripts/lib/json-value.ts

@@ -28,12 +28,20 @@ function parse_with<T>(text: string, schema: z.ZodType<T>): T | undefined {
 	return parsed.success ? parsed.data : undefined
 }
 
+// The read a listing wants: text that is not JSON and JSON that is not an array both answer
+// `undefined`, so a caller can keep "unreadable" apart from an empty listing.
+function parse_array(text: string): Array<unknown> | undefined {
+	const value = parse_or_undefined(text)
+
+	return Array.isArray(value) ? value : undefined
+}
+
 // A plain object, as opposed to an array or a primitive. `typeof null` is `'object'`, and an array
 // answers `'object'` too, so both have to be excluded by hand before a key lookup means anything.
 function is_record(value: unknown): value is Record<string, unknown> {
 	return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
-const json_value = { parse_or_undefined, parse_with, is_record }
+const json_value = { parse_or_undefined, parse_with, parse_array, is_record }
 
 export { json_value }

package/scripts/lib/package-manifest.ts

@@ -0,0 +1,35 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import type { z } from 'zod'
+import { json_value } from './json-value'
+import { file_reader } from './read-file'
+
+// The one place a `package.json` is named and read. Readers across `scripts/` had each spelled the
+// file name and written their own read-then-parse; they now ask here, and choose only how a manifest
+// that cannot be read answers.
+const PACKAGE_JSON = 'package.json'
+
+function manifest_path(directory: string): string {
+	return path.join(directory, PACKAGE_JSON)
+}
+
+// For a manifest that must exist: a missing file, text that is not JSON and a shape the schema
+// rejects all throw, so the defect surfaces where it was met.
+function read_manifest<T>(directory: string, schema: z.ZodType<T>): T {
+	const text = readFileSync(manifest_path(directory), 'utf8')
+
+	return schema.parse(JSON.parse(text))
+}
+
+// For a manifest that may be absent or broken without that being this reader's failure: every one of
+// those answers `undefined`.
+function read_manifest_if_valid<T>(directory: string, schema: z.ZodType<T>): T | undefined {
+	const text = file_reader.read_if_readable(manifest_path(directory))
+	if (text === undefined) return undefined
+
+	return json_value.parse_with(text, schema)
+}
+
+const package_manifest = { manifest_path, read_manifest, read_manifest_if_valid }
+
+export { PACKAGE_JSON, package_manifest }

package/scripts/lib/read-file.ts

@@ -2,6 +2,8 @@ import { readFileSync } from 'node:fs'
 
 const ABSENT_CODE = 'ENOENT'
 
+// Whether a filesystem error says "there is nothing here" — ENOENT and nothing else. A permission
+// error or ENOTDIR says something is there, so neither reads as absent.
 function is_absent(error: unknown): boolean {
 	return error instanceof Error && 'code' in error && error.code === ABSENT_CODE
 }
@@ -35,6 +37,6 @@ function read_if_readable(path: string): string | undefined {
 	}
 }
 
-const file_reader = { read_optional, read_file_or_empty, read_if_readable }
+const file_reader = { is_absent, read_optional, read_file_or_empty, read_if_readable }
 
 export { file_reader }

package/scripts/lib/stamped-memo.ts

@@ -0,0 +1,63 @@
+import { lstatSync } from 'node:fs'
+
+// An answer remembered per key, recomputed only when the key's stamp changes (joshuafolkken/kit#4263).
+//
+// **`run:board` redraws every second, and most of what it reads has not changed since the last
+// redraw.** A process's app name, a ledger's parsed lines and a work tree's git config were computed
+// again on every pass, and on a saturated machine those passes stopped the spinner for 45–200ms. The
+// stamp is what says "this has changed": a file's `file_stamp`, or a constant where the key alone
+// decides the answer.
+
+const NO_STAMP = ''
+const STAMP_SEPARATOR = ':'
+
+interface Remembered<Value> {
+	stamp: string
+	value: Value
+}
+
+interface StampedMemo<Value> {
+	// `compute`'s answer for `key`, run only when `key` was never seen or its stamp moved since.
+	of: (key: string, stamp: string, compute: () => Value) => Value
+	// Forget every key outside `keys` — a process gone from the table, so the memo cannot grow unbounded.
+	keep: (keys: ReadonlySet<string>) => void
+}
+
+function create<Value>(): StampedMemo<Value> {
+	const answers = new Map<string, Remembered<Value>>()
+
+	return {
+		of(key, stamp, compute) {
+			const known = answers.get(key)
+
+			if (known?.stamp === stamp) return known.value
+
+			const value = compute()
+
+			answers.set(key, { stamp, value })
+
+			return value
+		},
+		keep(keys) {
+			for (const key of answers.keys()) if (!keys.has(key)) answers.delete(key)
+		},
+	}
+}
+
+// What changes when a file is rewritten, appended to, replaced or re-owned: its inode, its modification
+// and change times and its size. An absent or unreadable file is `NO_STAMP`, so it reads again once
+// it appears.
+function file_stamp(file: string): string {
+	try {
+		const status = lstatSync(file)
+
+		return [status.ino, status.mtimeMs, status.ctimeMs, status.size].join(STAMP_SEPARATOR)
+	} catch {
+		return NO_STAMP
+	}
+}
+
+const stamped_memo = { NO_STAMP, create, file_stamp }
+
+export { stamped_memo }
+export type { StampedMemo }

package/scripts/lib/stdout-on-stderr.ts

@@ -0,0 +1,24 @@
+// Runs work whose own reports go to stdout with stdout pointed at stderr, for a caller whose stdout is
+// a contract: the `Stop` hook's decision envelope, and `josh run:hold`'s single verdict token.
+
+type StreamWrite = typeof process.stdout.write
+
+function set_stdout_write(stream_write: StreamWrite): void {
+	process.stdout.write = stream_write
+}
+
+async function run<T>(work: () => Promise<T>): Promise<T> {
+	const saved = { write: process.stdout.write.bind(process.stdout) }
+
+	set_stdout_write(process.stderr.write.bind(process.stderr))
+
+	try {
+		return await work()
+	} finally {
+		set_stdout_write(saved.write)
+	}
+}
+
+const stdout_on_stderr = { run }
+
+export { stdout_on_stderr }

package/scripts/lib/timeouts.ts

@@ -3,6 +3,12 @@
 // limit stays stuck where it stopped and never comes back, so every such
 // call takes one of these, and a value used in more than one place is named once here.
 
+// The unit conversions every duration is read and printed through. They sit beside the limits because a
+// limit is the most common thing they convert; a second copy in a caller is a clone of these two lines.
+const MS_PER_SECOND = 1000
+const SECONDS_PER_MINUTE = 60
+const MS_PER_MINUTE = MS_PER_SECOND * SECONDS_PER_MINUTE
+
 // A probe that only asks the local machine (`ps`, `lsof`, `git config`) on a path something else is
 // waiting on. Failing answers "cannot tell", which every caller handles, so anything slower is a fault.
 const PROBE_TIMEOUT_MS = 2000
@@ -41,6 +47,9 @@ export {
 	HOOK_PROCESS_TIMEOUT_MS,
 	INSTALL_TIMEOUT_MS,
 	LINT_TIMEOUT_MS,
+	MS_PER_MINUTE,
+	MS_PER_SECOND,
 	PROBE_TIMEOUT_MS,
+	SECONDS_PER_MINUTE,
 	SUITE_TIMEOUT_MS,
 }

package/scripts/lib/transcript-record.ts

@@ -0,0 +1,91 @@
+import { z } from 'zod'
+import { json_value } from './json-value'
+
+// One line of a Claude Code JSONL log — a session transcript, or the `stream-json` output of
+// `claude -p`, which writes the same `{ type, message: { id, content } }` shape. Every reader of those
+// lines parses through these schemas and takes what it needs from the record; a fix to the shape
+// reaches all of them at once.
+//
+// **Every field is optional, including `type`.** A required field would make one unexpected block
+// fail the whole array it sits in, and with it every other block on that line — an entire assistant
+// turn dropped because one tool wrote a shape no reader had seen. A block that parses to nothing
+// contributes nothing.
+
+const TEXT_TYPE = 'text'
+const TOOL_USE_TYPE = 'tool_use'
+const TOOL_RESULT_TYPE = 'tool_result'
+
+const BLOCK_SCHEMA = z.object({
+	type: z.string().nullish(),
+	text: z.string().nullish(),
+	name: z.string().nullish(),
+	id: z.string().nullish(),
+	tool_use_id: z.string().nullish(),
+	input: z.unknown().nullish(),
+	// Whether the harness wrote a `tool_result` back as a failure — absent on every other block, and
+	// on the results of tools that never report one.
+	is_error: z.boolean().nullish(),
+	// A result's body: a string or a list of blocks. Read as `unknown` because each reader flattens it
+	// its own way, and a narrower type here would drop the whole line over one odd item.
+	content: z.unknown().nullish(),
+})
+
+const CONTENT_SCHEMA = z.union([z.string(), z.array(BLOCK_SCHEMA)])
+// `id` is the assistant *message* the line belongs to; Claude Code writes one line per content block,
+// so a turn that issued two calls is several lines carrying one id.
+const MESSAGE_SCHEMA = z.object({ id: z.string().nullish(), content: CONTENT_SCHEMA.nullish() })
+
+const LINE_SCHEMA = z.object({
+	type: z.string().nullish(),
+	timestamp: z.string().nullish(),
+	gitBranch: z.string().nullish(),
+	// The two fields outside `message` the harness writes an end-of-task notice on. `unknown`, since a
+	// string here would reject every line whose `content` is a list of blocks.
+	content: z.unknown().nullish(),
+	attachment: z.unknown().nullish(),
+	message: MESSAGE_SCHEMA.nullish(),
+})
+
+type TranscriptBlock = z.infer<typeof BLOCK_SCHEMA>
+type TranscriptContent = z.infer<typeof CONTENT_SCHEMA>
+type TranscriptMessage = z.infer<typeof MESSAGE_SCHEMA>
+type TranscriptRecord = z.infer<typeof LINE_SCHEMA>
+type ToolCallBlock = TranscriptBlock & { name: string }
+
+function read(value: unknown): TranscriptRecord | undefined {
+	return LINE_SCHEMA.safeParse(value).data
+}
+
+// A blank line, a line that is not JSON and a line of another shape are one answer: `undefined`.
+function parse(line: string): TranscriptRecord | undefined {
+	return read(json_value.parse_or_undefined(line))
+}
+
+// The line's blocks. A message written as a bare string — a prompt — carries none.
+function blocks_of(record: TranscriptRecord): ReadonlyArray<TranscriptBlock> {
+	const content = record.message?.content
+
+	return Array.isArray(content) ? content : []
+}
+
+function is_tool_call(block: TranscriptBlock): block is ToolCallBlock {
+	return block.type === TOOL_USE_TYPE && typeof block.name === 'string'
+}
+
+// The calls a line made, in order. A `tool_use` block without a name is not a call anything can name.
+function tool_calls_of(record: TranscriptRecord): Array<ToolCallBlock> {
+	return blocks_of(record).filter((block) => is_tool_call(block))
+}
+
+const transcript_record = {
+	TEXT_TYPE,
+	TOOL_USE_TYPE,
+	TOOL_RESULT_TYPE,
+	read,
+	parse,
+	blocks_of,
+	tool_calls_of,
+}
+
+export type { TranscriptBlock, TranscriptContent, TranscriptMessage, TranscriptRecord }
+export { transcript_record }