@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/time-runtime/time-shell.ts

@@ -53,10 +53,26 @@ const CHAIN_PATTERN = /&&|\|\||;|\n/u
 // body is not shell syntax at all — an `it's` there is prose — so it is removed before the quotes are
 // paired, keeping the rest of its marker line (`cat <<EOF > f && git add f`) where the shell reads it.
 // Without both, a stray quote paired with one much later and erased every command between them.
-const QUOTED_SPAN_PATTERN = /\\[\s\S]|'[^']*'|"(?:\\[\s\S]|[^"\\])*"/gu
+//
+// **A `$(…)` inside double quotes is one atom of the span** (joshuafolkken/kit#4525): the quotes in
+// `"$(gh issue create --title "x")"` belong to the substitution, so the span closes at the outer `"`
+// rather than at the first inner one, which left the substitution cut in half. A `$` is read one way
+// only — the atom where one follows, a character where none does — because a `$` either could take
+// made an unclosed `"` followed by many `$(…)` try every split of them before failing.
+const SUBSTITUTION_ATOM = /\$\([^()]*\)/u
+const LONE_DOLLAR = /\$(?!\([^()]*\))/u
+const QUOTED_SPAN_PATTERN = new RegExp(
+	String.raw`\\[\s\S]|'[^']*'|"(?:\\[\s\S]|${SUBSTITUTION_ATOM.source}|${LONE_DOLLAR.source}|[^"\\$])*"`,
+	'gu',
+)
 const HEREDOC_MARKER = /(?<!<)<<-?\s*(['"]?)(\w+)\1/u
 const HEREDOC_DELIMITER_GROUP = 2
 const LINE_BREAK = '\n'
+const DOUBLE_QUOTE = '"'
+// A command substitution with no nested parenthesis — the shape a quoted `"$(cmd …)"` is written in —
+// or its backtick spelling. An escaped `\$(` or `` \` `` is literal text inside double quotes, so it
+// runs nothing.
+const SUBSTITUTION_PATTERN = /(?<!\\)\$\((?<dollar>[^()]*)\)|(?<!\\)`(?<tick>[^`]*)`/gu
 // `set -o pipefail` tells the shell to report the pipeline with the first failing command's status,
 // so nothing in it is discarded. The flag letters are loose because `set -eo pipefail` and
 // `set -euo pipefail` are the same instruction, and the `set` word is required so that a path or a
@@ -77,14 +93,36 @@ const FLAG_PREFIX = '-'
 // Two kinds of prefix, and they are not interchangeable. A wrapper runs the command that follows it,
 // so the walk continues past it; a navigation builtin runs nothing, so its segment yields no command
 // at all and the walk moves to the next segment.
-const WRAPPER_COMMANDS = new Set(['time', 'env', 'sudo'])
+//
+// **A wrapper is skipped with the flag values and operands it takes, and named by its basename**
+// (joshuafolkken/kit#4525). `/usr/bin/time -f %e pnpm josh gate` left the walk on `%e`, and
+// `timeout 600 pnpm josh gate` stopped at `timeout`, so a refusal keyed on the command was escaped by
+// wrapping it. Every reader that asks which command a segment runs goes through this one walk.
+interface WrapperShape {
+	readonly valued: ReadonlySet<string>
+	readonly operands: number
+}
+
+const WRAPPER_COMMANDS: ReadonlyMap<string, WrapperShape> = new Map([
+	['time', { valued: new Set(['-f', '-o', '--format', '--output']), operands: 0 }],
+	['env', { valued: new Set(['-u', '-C', '-S', '--unset', '--chdir']), operands: 0 }],
+	['sudo', { valued: new Set(['-u', '-g', '-C', '-D']), operands: 0 }],
+	['timeout', { valued: new Set(['-s', '-k', '--signal', '--kill-after']), operands: 1 }],
+	['nohup', { valued: new Set(), operands: 0 }],
+	['nice', { valued: new Set(['-n', '--adjustment']), operands: 0 }],
+	['command', { valued: new Set(), operands: 0 }],
+	['exec', { valued: new Set(['-a']), operands: 0 }],
+	['stdbuf', { valued: new Set(['-i', '-o', '-e']), operands: 0 }],
+])
 const NAVIGATION_COMMANDS = new Set(['cd', 'pushd', 'popd', 'export', 'source', 'set', '.'])
+const PATH_SEPARATOR = '/'
+const FLAG_AND_VALUE = 2
 
 // Anchored at a segment's command position, not searched anywhere in the string. A loose search
 // charged `git commit -m "ran pnpm josh gate"` to `josh gate`, and this repository's own commit
 // messages and issue comments name josh subcommands constantly. Only the first match counts: a
 // compound command naming two would otherwise charge its whole duration to each.
-const JOSH_PATTERN = /^(?:pnpm\s+(?:exec\s+)?)?josh\s+([a-z][\w:-]*)/u
+const JOSH_PATTERN = /^(?:(?:pnpm|npx)\s+(?:exec\s+)?)?josh\s+([a-z][\w:-]*)/u
 const JOSH_PREFIX = 'josh '
 const COMMAND_KEY = 'command'
 
@@ -99,19 +137,45 @@ function bash_command(input: unknown): string {
 // A wrapper's own flags are skipped with it. Skipping only the wrapper word left the walk on a flag,
 // which is not command-shaped, so `env -i pnpm test` yielded no command at all and its duration left
 // the per-command table entirely.
-function is_skippable(word: string): boolean {
-	if (word.startsWith(FLAG_PREFIX)) return true
+function after_flags(
+	words: ReadonlyArray<string>,
+	start: number,
+	valued: ReadonlySet<string>,
+): number {
+	let index = start
+
+	while (words[index]?.startsWith(FLAG_PREFIX) === true) {
+		index += valued.has(words[index] ?? '') ? FLAG_AND_VALUE : 1
+	}
+
+	return index
+}
+
+// The index past the prefix word at `index`, or `index` itself when that word is the command.
+function after_prefix_word(words: ReadonlyArray<string>, index: number): number {
+	const word = words[index] ?? ''
+
+	if (word.startsWith(FLAG_PREFIX) || ASSIGNMENT_PATTERN.test(word)) return index + 1
+
+	const wrapper = WRAPPER_COMMANDS.get(word.slice(word.lastIndexOf(PATH_SEPARATOR) + 1))
 
-	return ASSIGNMENT_PATTERN.test(word) || WRAPPER_COMMANDS.has(word)
+	if (wrapper === undefined) return index
+
+	return after_flags(words, index + 1, wrapper.valued) + wrapper.operands
 }
 
 // One segment with its leading assignments and wrappers dropped, so the first entry is the command
 // position. Shared by both readers below: what counts as the command is one rule, not two.
 function command_words(segment: string): Array<string> {
 	const words = segment.replaceAll(SUBSHELL_OPENER, ' ').trim().split(WHITESPACE_PATTERN)
-	const start = words.findIndex((word) => !is_skippable(word))
+	let start = 0
+
+	for (let next = after_prefix_word(words, start); next !== start;) {
+		start = next
+		next = after_prefix_word(words, start)
+	}
 
-	return start === -1 ? [] : words.slice(start)
+	return words.slice(start)
 }
 
 // The command this segment runs, or nothing. Nothing has two causes and both are deliberate: a
@@ -186,15 +250,35 @@ function without_heredoc_bodies(command: string): string {
 // removal for a different reason — a quoted `sed` script holds `|` and slashes that read as a
 // pipeline and as paths — and two spellings of "remove the quotes" would disagree the first time one
 // of them learned about a quoting form the other did not.
+//
+// **A `$(…)` inside double quotes runs, so it is kept as a command of its own** (joshuafolkken/kit#4525):
+// `out="$(pnpm josh gate)"` runs the gate, and removing the span with its quotes hid it. A single-quoted
+// span expands nothing and goes whole. The substitution's own quoted arguments go as any other.
+function spoken_substitutions(span: string): string {
+	if (!span.startsWith(DOUBLE_QUOTE)) return ' '
+
+	const inner = [...span.matchAll(SUBSTITUTION_PATTERN)].map((match) =>
+		(match.groups?.['dollar'] ?? match.groups?.['tick'] ?? '').replaceAll(QUOTED_SPAN_PATTERN, ' '),
+	)
+
+	return inner.length === 0 ? ' ' : ` ; ${inner.join(' ; ')} ; `
+}
+
 function unquoted(command: string): string {
-	return without_heredoc_bodies(command).replaceAll(QUOTED_SPAN_PATTERN, ' ')
+	return without_heredoc_bodies(command).replaceAll(QUOTED_SPAN_PATTERN, (span) =>
+		spoken_substitutions(span),
+	)
 }
 
 // Quoted text replaced by spaces of its own length, so an offset found here is the same offset in the
 // command — what a caller cutting the command where the unquoted reading says to needs. `undefined`
 // for a line carrying a heredoc, whose body lines a cut would read as commands of their own.
+function has_heredoc(command: string): boolean {
+	return HEREDOC_MARKER.test(command)
+}
+
 function blanked(command: string): string | undefined {
-	if (HEREDOC_MARKER.test(command)) return undefined
+	if (has_heredoc(command)) return undefined
 
 	return command.replaceAll(QUOTED_SPAN_PATTERN, (span) => ' '.repeat(span.length))
 }
@@ -344,12 +428,15 @@ const time_shell = {
 	blanked,
 	command_segment,
 	discarded_commands,
+	has_heredoc,
 	josh_arguments,
 	josh_command_of,
+	josh_command_of_segment,
 	josh_commands_of,
 	josh_signatures_of,
 	leading_word,
 	unquoted,
+	without_heredoc_bodies,
 }
 
 export { time_shell }

package/scripts/time-runtime/time-transcript-line.ts

@@ -1,6 +1,12 @@
 import type { FollowupStage } from '#scripts/followup/git-followup-stages'
 import { json_value } from '#scripts/lib/json-value'
-import { z } from 'zod'
+import {
+	transcript_record,
+	type TranscriptBlock,
+	type TranscriptContent,
+	type TranscriptMessage,
+	type TranscriptRecord,
+} from '#scripts/lib/transcript-record'
 import { time_background } from './time-background'
 import { time_followup_stage } from './time-followup-stage'
 import { time_instant } from './time-instant'
@@ -10,56 +16,20 @@ import { time_reported_failure } from './time-reported-failure'
 //
 // It moved out of `time-spans.ts` when that file passed its length limit — the seam that file is
 // already cut along elsewhere (`time-shell.ts`, `time-single-check.ts`), where the *reading* of a
-// field lives beside the field and the arithmetic stays next door. What is here is the JSONL shape
-// and nothing about time: schemas, the two records a line yields, and the parse that turns a string
-// into one.
+// field lives beside the field and the arithmetic stays next door. What is here is nothing about
+// time: the two records a line yields, and the read that turns a parsed line into one.
 //
 // **The block reader is not `cost-blocks.ts` and could not have been.** That module flattens every
 // line into one list of blocks for a token estimate, dropping the `id` / `tool_use_id` pair a call is
 // matched to its result by and the line boundary a timestamp belongs to. Both are the whole input
 // here.
-
-const BLOCK_SCHEMA = z.object({
-	type: 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 this result back as a failure. Present on a
-	// `tool_result` block and on nothing else, and absent even there for the tools that never report
-	// one — which is why it is read as three answers rather than as a boolean with a default.
-	is_error: z.boolean().nullish(),
-	// What the call printed. Read only to recover the outcome a pipeline threw away:
-	// it is kept as flattened text rather than as blocks, because that is
-	// the whole of what `time-reported-failure.ts` asks of it.
-	content: z.unknown().nullish(),
-})
-
-const CONTENT_SCHEMA = z.union([z.string(), z.array(BLOCK_SCHEMA)])
-// `id` is the assistant *message* the line belongs to, and Claude Code writes one line per content
-// block — a turn that thought and then issued two calls is three lines carrying one id.
-// Anything asking "how many calls did that turn make" therefore has to
-// group by this field; counting one line's blocks answers one, whatever the turn actually did. The
-// same field is what says how many *turns* a run had.
-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(),
-	// The branch the line was written on, which is where the issue number lives — `josh git` names a
-	// branch `<N>-<slug>`. Read here rather than re-parsed by a second reader so `josh time --issue`
-	// and `josh cost --issue` answer from the same field.
-	gitBranch: z.string().nullish(),
-	// The two fields outside `message` that the harness writes an end-of-task notice on.
-	// **Both are read as `unknown` rather than as strings**: a schema
-	// insisting on a string here would reject every line whose `content` is a list of blocks — which is
-	// most of them — and a rejected line is dropped from the timeline entirely, so the shares would stop
-	// reconstructing the elapsed time. The shape is checked at the read below instead.
-	content: z.unknown().nullish(),
-	attachment: z.unknown().nullish(),
-	message: MESSAGE_SCHEMA.nullish(),
-})
+//
+// The line's schema is `transcript-record.ts`'s, shared with every other reader of these lines. A
+// message `id` groups the lines of one assistant turn — Claude Code writes one line per content block
+// — so "how many calls did that turn make" groups by it. `gitBranch` is where the issue number lives
+// (`josh git` names a branch `<N>-<slug>`), read here so `josh time --issue` and `josh cost --issue`
+// answer from the same field. A `tool_result`'s `is_error` is read as three answers — absent for the
+// tools that never report one — and its `content` only to recover the outcome a pipeline threw away.
 
 const UNKNOWN_BRANCH = ''
 // The field an attachment line carries the notice in, named rather than written as a literal.
@@ -137,8 +107,8 @@ interface TranscriptLine {
 	type: string
 	timestamp_ms: number
 	branch: string
-	// The background run this line is the harness's end-of-task notice for, and `''` for every other
-	// line. It is read here rather than downstream for the reason every
+	// The background run this line is the harness's end-of-task notice for — or the `TaskStop` result
+	// that stopped it, which gets no notice — and `''` for every other line. It is read here rather than downstream for the reason every
 	// derived field above is: the notice is the line's whole content, which a span does not keep, and
 	// it is the only thing in a transcript that says a command had *finished* rather than merely been
 	// looked at.
@@ -156,9 +126,7 @@ interface TranscriptLine {
 // The four string fields, defaulted together and apart from the two that are not strings. Split out
 // so neither half carries every `??` in the block: read as one function the defaulting alone reached
 // the complexity limit, and the next field added would have had to be squeezed in beside them.
-function block_names(
-	raw: z.infer<typeof BLOCK_SCHEMA>,
-): Pick<Block, 'type' | 'name' | 'id' | 'result_id'> {
+function block_names(raw: TranscriptBlock): Pick<Block, 'type' | 'name' | 'id' | 'result_id'> {
 	return {
 		type: raw.type ?? '',
 		name: raw.name ?? '',
@@ -190,7 +158,7 @@ function guard_from_refusal(text: string): string {
 // **Only the harness's own feedback line counts.** It writes a Stop block back as a user turn whose
 // whole body is `Stop hook feedback:` and the reason, so a prompt that merely quotes one never opens
 // with the label and reads `''`.
-function stop_guard_of(data: z.infer<typeof LINE_SCHEMA>): string {
+function stop_guard_of(data: TranscriptRecord): string {
 	const content = data.message?.content
 	if (typeof content !== 'string' || !STOP_FEEDBACK_LABEL.test(content)) return ''
 
@@ -209,7 +177,7 @@ function token_lines_of(text: string): Array<string> {
 // content field that may be a string or a list of blocks into one string, and it is idempotent on a
 // string — so passing its own output back to `has_failure_line` reads exactly as passing the raw
 // field did, at one flattening instead of two.
-function to_block(raw: z.infer<typeof BLOCK_SCHEMA>): Block {
+function to_block(raw: TranscriptBlock): Block {
 	const text = time_reported_failure.result_text(raw.content)
 	const is_error = raw.is_error ?? undefined
 
@@ -229,9 +197,7 @@ function to_block(raw: z.infer<typeof BLOCK_SCHEMA>): Block {
 
 // A user turn written as a bare string carries no blocks, which is exactly right: it is a prompt,
 // and a prompt has no tool result to match.
-function to_blocks(
-	content: string | Array<z.infer<typeof BLOCK_SCHEMA>> | null | undefined,
-): Array<Block> {
+function to_blocks(content: TranscriptContent | null | undefined): Array<Block> {
 	return typeof content === 'string' || content === null || content === undefined
 		? []
 		: content.map((block) => to_block(block))
@@ -241,7 +207,7 @@ function to_blocks(
 // is written as one line per content block with the message's id repeated on each, so the id is what
 // says which blocks belonged to the same turn.
 function message_fields(
-	message: z.infer<typeof MESSAGE_SCHEMA> | null | undefined,
+	message: TranscriptMessage | null | undefined,
 ): Pick<TranscriptLine, 'message_id' | 'blocks'> {
 	return { message_id: message?.id ?? NO_MESSAGE_ID, blocks: to_blocks(message?.content) }
 }
@@ -253,16 +219,37 @@ function message_fields(
 // session happened to hold a different one. All three are read, and `time_background.finished_at`
 // keeps the earliest instant per id, so what is paired with the launch is when the task *ended* rather
 // than when the run was told about it.
-function notice_text(data: z.infer<typeof LINE_SCHEMA>): string {
+function notice_text(data: TranscriptRecord): string {
 	const attachment = json_value.is_record(data.attachment) ? data.attachment[PROMPT_KEY] : undefined
 	const carried = [data.message?.content, data.content, attachment]
 
 	return carried.find((one): one is string => typeof one === 'string') ?? ''
 }
 
+// The task a `TaskStop` result on this line stopped, which is an end the harness writes no notice for.
+// Its result body is a plain string, so only string contents are read and nothing is flattened again.
+function stopped_background(content: TranscriptContent | null | undefined): string {
+	if (!Array.isArray(content)) return time_background.NO_BACKGROUND
+
+	const ids = content.map((block) =>
+		typeof block.content === 'string' ? time_background.stopped_id(block.content) : '',
+	)
+
+	return ids.find((id) => id !== time_background.NO_BACKGROUND) ?? time_background.NO_BACKGROUND
+}
+
+// The task this line reports the end of: the harness's notice, or else a `TaskStop` result.
+function finished_background(data: TranscriptRecord): string {
+	const notice = time_background.finished_id(notice_text(data))
+
+	return notice === time_background.NO_BACKGROUND
+		? stopped_background(data.message?.content)
+		: notice
+}
+
 // A line without a parseable timestamp is dropped rather than dated: it has no place on a timeline,
 // and inventing one would move every span around it.
-function to_line(data: z.infer<typeof LINE_SCHEMA>): TranscriptLine | undefined {
+function to_line(data: TranscriptRecord): TranscriptLine | undefined {
 	const timestamp_ms = time_instant.parse_instant(data.timestamp)
 
 	if (timestamp_ms === undefined) return undefined
@@ -271,16 +258,16 @@ function to_line(data: z.infer<typeof LINE_SCHEMA>): TranscriptLine | undefined
 		type: data.type ?? '',
 		timestamp_ms,
 		branch: data.gitBranch ?? UNKNOWN_BRANCH,
-		finished_background: time_background.finished_id(notice_text(data)),
+		finished_background: finished_background(data),
 		stop_guard: stop_guard_of(data),
 		...message_fields(data.message),
 	}
 }
 
 function parse_line(line: string): TranscriptLine | undefined {
-	const parsed = LINE_SCHEMA.safeParse(json_value.parse_or_undefined(line))
+	const record = transcript_record.parse(line)
 
-	return parsed.success ? to_line(parsed.data) : undefined
+	return record === undefined ? undefined : to_line(record)
 }
 
 // A whole transcript's text read as its parsed lines, the unparseable ones dropped.

package/scripts/uninstall/uninstall.ts

@@ -11,6 +11,7 @@ import { init_logic_sonar } from '#scripts/init/init-logic-sonar'
 import { PACKAGE_DIR, PROJECT_ROOT } from '#scripts/init/init-paths'
 import { project_profile, type ProjectProfile } from '#scripts/init/project-profile'
 import { error_text } from '#scripts/lib/error-message'
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { file_reader } from '#scripts/lib/read-file'
 import { PROJECT_CONFIG_FILE } from '#scripts/safe-chain/project-config'
 import { did_refuse_self_run } from '#scripts/self-sync-guard/self-sync-refusal'
@@ -20,7 +21,6 @@ import { distributed_files } from './distributed-files'
 import { IGNORE_FILE, uninstall_plan, type FilePlan } from './uninstall-plan'
 import { uninstall_report, type UninstallPlan } from './uninstall-report'
 
-const PACKAGE_JSON = 'package.json'
 const LEFTHOOK_BIN = 'lefthook'
 const ARGUMENT_START_INDEX = 2
 const YES_FLAG = '--yes'

package/scripts/version/bump-version-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { run_bump_version } from './bump-version'
+
+// The `josh bump` entry, kept apart from `bump-version.ts` because `release-publish.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).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = run_bump_version(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/version/bump-version.ts

@@ -1,15 +1,16 @@
-#!/usr/bin/env tsx
-import { readFileSync, writeFileSync } from 'node:fs'
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { writeFileSync } from 'node:fs'
 import { error_text } from '#scripts/lib/error-message'
+import { package_manifest } from '#scripts/lib/package-manifest'
 import { json_object_schema, package_with_version_schema } from '#scripts/lib/schemas'
 import semver from 'semver'
 
 const VALID_BUMP_TYPES = ['major', 'minor', 'patch'] as const
 type BumpType = (typeof VALID_BUMP_TYPES)[number]
 
+const BUMP_TYPE_NAMES: ReadonlySet<string> = new Set(VALID_BUMP_TYPES)
 const PACKAGE_JSON_INDENT = '\t'
+const USAGE = 'Usage: josh bump [major|minor|patch]'
+const FAILURE_EXIT_CODE = 1
 
 function compute_new_version(version: string, bump_type: BumpType): string {
 	const new_version = semver.inc(version, bump_type)
@@ -19,28 +20,21 @@ function compute_new_version(version: string, bump_type: BumpType): string {
 	return new_version
 }
 
-function package_json_path(): string {
-	return path.join(process.cwd(), 'package.json')
-}
-
 // **Set the version to an already-decided number.** `bump_version` below is this plus the decision;
 // `pnpm josh release` supplies its own, because a release raises the version by as many minors as
 // main has taken merges rather than by one. Written once so the two agree
 // on the file's shape and indentation.
 function write_version(new_version: string): void {
-	const package_path = package_json_path()
-	const package_json = json_object_schema.parse(JSON.parse(readFileSync(package_path, 'utf8')))
+	const package_json = package_manifest.read_manifest(process.cwd(), json_object_schema)
 
 	writeFileSync(
-		package_path,
+		package_manifest.manifest_path(process.cwd()),
 		`${JSON.stringify({ ...package_json, version: new_version }, undefined, PACKAGE_JSON_INDENT)}\n`,
 	)
 }
 
 function read_current_version(): string {
-	const file_content = readFileSync(package_json_path(), 'utf8')
-
-	return package_with_version_schema.parse(JSON.parse(file_content)).version
+	return package_manifest.read_manifest(process.cwd(), package_with_version_schema).version
 }
 
 function bump_version(bump_type: BumpType): void {
@@ -50,23 +44,29 @@ function bump_version(bump_type: BumpType): void {
 	console.info(new_version)
 }
 
-function main(): void {
-	const ARGV_INDEX = 2
-	const bump_type = process.argv[ARGV_INDEX] ?? 'minor'
+function is_bump_type(value: string): value is BumpType {
+	return BUMP_TYPE_NAMES.has(value)
+}
+
+// `josh bump`'s body, answering its exit code to `bump-version-main.ts`.
+function run_bump_version(args: ReadonlyArray<string>): number {
+	const [bump_type = 'minor'] = args
 
-	if (!VALID_BUMP_TYPES.includes(bump_type as BumpType)) {
-		console.error(`Usage: tsx scripts/version/bump-version.ts [major|minor|patch]`)
-		process.exit(1)
+	if (!is_bump_type(bump_type)) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
 	}
 
 	try {
-		bump_version(bump_type as BumpType)
+		bump_version(bump_type)
 	} catch (error) {
 		console.error(error_text.message_of(error))
-		process.exit(1)
+
+		return FAILURE_EXIT_CODE
 	}
-}
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+	return 0
+}
 
-export { bump_version, compute_new_version, write_version }
+export { bump_version, compute_new_version, run_bump_version, USAGE, write_version }

package/scripts/version/effective-upstream.ts

@@ -1,12 +1,9 @@
-import { existsSync, readFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import path from 'node:path'
 import { ancestor_directories } from '#scripts/lib/ancestor-directories'
-import { json_value } from '#scripts/lib/json-value'
+import { package_manifest } from '#scripts/lib/package-manifest'
 import { package_named_version_schema } from '#scripts/lib/schemas'
 
-const PACKAGE_JSON = 'package.json'
-
 // Options for `resolve_effective_upstream_version`. `resolve_marker` is a subpath specifier used for
 // `createRequire().resolve()` when the package root itself is not directly resolvable — e.g. kit does
 // not list `package.json` (nor a `.` entry) in `exports`, so a subpath like
@@ -18,21 +15,18 @@ interface EffectiveUpstreamOptions {
 // Read the `version` from a package.json only when its `name` matches the target package — undefined
 // when the file is missing, malformed, or belongs to a different (e.g. nested) package. Matching by
 // name is what lets the walk-up skip intermediate package.json files and land on the true root.
-function read_matching_version(manifest_path: string, package_name: string): string | undefined {
-	if (!existsSync(manifest_path)) return undefined
-	const parsed = package_named_version_schema.safeParse(
-		json_value.parse_or_undefined(readFileSync(manifest_path, 'utf8')),
-	)
-	if (!parsed.success || parsed.data.name !== package_name) return undefined
+function read_matching_version(directory: string, package_name: string): string | undefined {
+	const manifest = package_manifest.read_manifest_if_valid(directory, package_named_version_schema)
+	if (manifest?.name !== package_name) return undefined
 
-	return parsed.data.version
+	return manifest.version
 }
 
 // Walk up from a resolved file's directory to the package root, returning the version of the first
 // ancestor package.json whose `name` matches the target — or undefined when no matching root exists.
 function walk_up_for_version(start_directory: string, package_name: string): string | undefined {
 	for (const directory of ancestor_directories.list(start_directory)) {
-		const version = read_matching_version(path.join(directory, PACKAGE_JSON), package_name)
+		const version = read_matching_version(directory, package_name)
 		if (version !== undefined) return version
 	}
 

package/scripts/version/latest-corepack.ts

@@ -42,14 +42,14 @@
 import { readFileSync, writeFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { json_value } from '#scripts/lib/json-value'
-import { COMMAND_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { execaSync } from 'execa'
 import semver from 'semver'
 import { z } from 'zod'
+import { npm_registry } from './npm-registry'
 import { package_manager_version } from './package-manager-version'
 import { release_age } from './release-age'
 
-const PACKAGE_JSON_PATH = 'package.json'
 const PACKAGE_MANAGER_RE = /"packageManager"\s*:\s*"pnpm@(\d+)(?:[^\d]|$)/u
 const PINNED_VERSION_RE = /"packageManager"\s*:\s*"pnpm@([^"+]+)/u
 const TARGET_PREFIX = 'pnpm@'
@@ -133,13 +133,10 @@ function extract_times_json(stdout: string): Record<string, string> | undefined
 // The registry's publish timestamps for every pnpm release (version → ISO date, plus the
 // created/modified bookkeeping keys the selector ignores).
 function query_release_times(): Record<string, string> | undefined {
-	const result = execaSync('pnpm', ['view', 'pnpm', 'time', '--json'], {
-		reject: false,
-		timeout: COMMAND_TIMEOUT_MS,
-	})
-	if ((result.exitCode ?? FAILURE_EXIT_CODE) !== 0) return undefined
+	const answer = npm_registry.view('pnpm', 'time', 'json')
+	if (answer.exit_code !== 0) return undefined
 
-	return extract_times_json(result.stdout)
+	return extract_times_json(answer.stdout)
 }
 
 function to_resolution(
@@ -179,13 +176,10 @@ function parse_latest_version(stdout: string): string | undefined {
 }
 
 function query_latest_version(): string | undefined {
-	const result = execaSync('pnpm', ['view', 'pnpm', 'version', '--json'], {
-		reject: false,
-		timeout: COMMAND_TIMEOUT_MS,
-	})
-	if ((result.exitCode ?? FAILURE_EXIT_CODE) !== 0) return undefined
+	const answer = npm_registry.view('pnpm', 'version', 'json')
+	if (answer.exit_code !== 0) return undefined
 
-	return parse_latest_version(result.stdout)
+	return parse_latest_version(answer.stdout)
 }
 
 // The target handed to pnpm self-update: an exact registry-resolved version on the pinned major, or
@@ -239,7 +233,7 @@ function run_pnpm_update(target: string): number {
 // match). Runs on every path, not just after a successful bump: a repository that arrives
 // with the two fields already out of step sits in the no-bump steady state forever, so an
 // alignment gated on a bump would never repair it.
-function sync_development_engines(package_json_path: string = PACKAGE_JSON_PATH): void {
+function sync_development_engines(package_json_path: string = PACKAGE_JSON): void {
 	const content = readFileSync(package_json_path, 'utf8')
 	const aligned = package_manager_version.align_development_engines_version(content)
 	if (aligned === content) return
@@ -249,10 +243,7 @@ function sync_development_engines(package_json_path: string = PACKAGE_JSON_PATH)
 }
 
 // Restore the pre-run manifest if self-update fails after changing it.
-function restore_package_json(
-	content: string,
-	package_json_path: string = PACKAGE_JSON_PATH,
-): void {
+function restore_package_json(content: string, package_json_path: string = PACKAGE_JSON): void {
 	writeFileSync(package_json_path, content)
 	console.info('✔ Restored package.json pin (pnpm bump failed)')
 }
@@ -274,20 +265,17 @@ function extract_encoded_integrity(stdout: string): string | undefined {
 }
 
 function query_integrity(target: string): string | undefined {
-	const result = execaSync('pnpm', ['view', target, 'dist.integrity', '--json'], {
-		reject: false,
-		timeout: COMMAND_TIMEOUT_MS,
-	})
-	if ((result.exitCode ?? FAILURE_EXIT_CODE) !== 0) return undefined
+	const answer = npm_registry.view(target, 'dist.integrity', 'json')
+	if (answer.exit_code !== 0) return undefined
 
-	const encoded = extract_encoded_integrity(result.stdout)
+	const encoded = extract_encoded_integrity(answer.stdout)
 	if (encoded === undefined) return undefined
 
 	return decode_integrity(encoded)
 }
 
 function restore_integrity(target: string, integrity: string): void {
-	const content = readFileSync(PACKAGE_JSON_PATH, 'utf8')
+	const content = readFileSync(PACKAGE_JSON, 'utf8')
 	const version = target.slice(TARGET_PREFIX.length)
 	const expected = `pnpm@${version}`
 	const current = PACKAGE_MANAGER_VALUE_RE.exec(content)?.[0]
@@ -303,10 +291,7 @@ function restore_integrity(target: string, integrity: string): void {
 		},
 	)
 
-	writeFileSync(
-		PACKAGE_JSON_PATH,
-		package_manager_version.align_development_engines_version(pinned),
-	)
+	writeFileSync(PACKAGE_JSON, package_manager_version.align_development_engines_version(pinned))
 }
 
 // The equal case is the steady state of every up-to-date run, so it logs as success; only
@@ -342,7 +327,7 @@ function pin_unpinned_manifest(original: string, target: string, integrity: stri
 	)
 
 	writeFileSync(
-		PACKAGE_JSON_PATH,
+		PACKAGE_JSON,
 		package_manager_version.align_development_engines_version(`${pinned}\n`),
 	)
 
@@ -403,7 +388,7 @@ function bump_to_registry_target(original: string, major: string | undefined): n
 }
 
 function main(): number {
-	const original = readFileSync(PACKAGE_JSON_PATH, 'utf8')
+	const original = readFileSync(PACKAGE_JSON, 'utf8')
 	const status = bump_to_registry_target(original, extract_pnpm_major(original))
 
 	sync_development_engines()