@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -0,0 +1,38 @@
+import { time_shell } from './time-shell'
+import type { ToolCall } from './time-tool-call'
+
+// Which calls are a search, the one answer the investigation guard and the batching guard both read.
+// A search carries no file text but costs a turn, so it is what a run issues one per turn while it
+// locates the next edit.
+
+const SEARCH_COMMANDS: ReadonlyArray<string> = ['fd', 'find', 'grep', 'rg']
+const SEARCH_LABELS: ReadonlySet<string> = new Set(
+	SEARCH_COMMANDS.map((command) => time_shell.bash_label(command)),
+)
+
+// A search chain also prints the lines a search found, so `sed` (read-only) joins it: `grep` → `sed`
+// was measured the second-largest single-call pair in lane children.
+const CHAIN_COMMANDS: ReadonlyArray<string> = [...SEARCH_COMMANDS, 'sed']
+const CHAIN_LABELS: ReadonlySet<string> = new Set(
+	CHAIN_COMMANDS.map((command) => time_shell.bash_label(command)),
+)
+
+type SearchFacts = Pick<ToolCall, 'label' | 'is_bundleable' | 'may_write' | 'is_writing'>
+
+// `may_write` over-calls, as the investigation guard's refusal test must.
+function is_read_only_search(call: SearchFacts): boolean {
+	return SEARCH_LABELS.has(call.label) && call.is_bundleable && !call.may_write
+}
+
+// `may_write` holds for every `sed`, so the chain asks `is_writing` — certain, and false for `sed -n`.
+function is_search_chain_call(call: SearchFacts): boolean {
+	return CHAIN_LABELS.has(call.label) && call.is_bundleable && !call.is_writing
+}
+
+const time_search_call = {
+	is_read_only_search,
+	is_search_chain_call,
+}
+
+export type { SearchFacts }
+export { time_search_call }

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

@@ -1,5 +1,5 @@
 import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
-import { canonical_command } from '#scripts/josh/josh-command-map'
+import { canonical_command } from '#scripts/josh/josh-aliases'
 import { json_value } from '#scripts/lib/json-value'
 
 // Reading a shell command well enough to name what it ran.
@@ -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.
@@ -148,6 +118,9 @@ interface TranscriptLine {
 	// every line lacking an id would otherwise fall into one bucket spanning the whole file.
 	message_id: string
 	blocks: Array<Block>
+	// The reason a Stop-hook block sent this turn back with, its label stripped, or `''` for every
+	// other line.
+	stop_feedback: string
 	// The guard whose Stop-hook block sent this turn back, or `''` for every other line
 	// — read the way `Block.refusal_guard` is, off the reason's opening.
 	stop_guard: string
@@ -156,9 +129,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 ?? '',
@@ -167,6 +138,11 @@ function block_names(
 	}
 }
 
+// The body a refusal opens with, the harness's own label stripped — shared with `rule-value.ts`.
+function refusal_body(text: string): string {
+	return text.trimStart().replace(HOOK_ERROR_LABEL, '')
+}
+
 // **A refusal is identified by what its body opens with, never by what it carries inside**.
 // The hook denies a call on behalf of the one guard whose trigger fired and
 // writes that guard's reason back as the whole result, so the speaker is the token after the `⛔` and
@@ -178,7 +154,7 @@ function block_names(
 // label is stripped before the opening is read. Without it no live refusal
 // carried a guard: the fixtures wrote the bare `⛔` body and passed while every recorded one read `''`.
 function guard_from_refusal(text: string): string {
-	const trimmed = text.trimStart().replace(HOOK_ERROR_LABEL, '')
+	const trimmed = refusal_body(text)
 	if (!trimmed.startsWith(REFUSAL_MARKER)) return ''
 
 	const headline = trimmed.slice(REFUSAL_MARKER.length).split('\n', 1)[0]?.trimStart() ?? ''
@@ -189,12 +165,12 @@ 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 {
+// with the label and reads `''`. The reason is kept whole, so `rule-value.ts` can match it to its row.
+function stop_feedback_of(data: TranscriptRecord): string {
 	const content = data.message?.content
 	if (typeof content !== 'string' || !STOP_FEEDBACK_LABEL.test(content)) return ''
 
-	return guard_from_refusal(content.replace(STOP_FEEDBACK_LABEL, ''))
+	return content.replace(STOP_FEEDBACK_LABEL, '').trim()
 }
 
 function token_lines_of(text: string): Array<string> {
@@ -209,7 +185,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 +205,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 +215,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,34 +227,58 @@ 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
 
+	const stop_feedback = stop_feedback_of(data)
+
 	return {
 		type: data.type ?? '',
 		timestamp_ms,
 		branch: data.gitBranch ?? UNKNOWN_BRANCH,
-		finished_background: time_background.finished_id(notice_text(data)),
-		stop_guard: stop_guard_of(data),
+		finished_background: finished_background(data),
+		stop_feedback,
+		stop_guard: guard_from_refusal(stop_feedback),
 		...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.
@@ -295,6 +293,7 @@ const time_transcript_line = {
 	guard_from_refusal,
 	parse_line,
 	parse_text,
+	refusal_body,
 }
 
 export type { Block, TranscriptLine }

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 }