@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,253 @@
+import type { FollowupStage } from '#scripts/git/git-followup-stages'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+import { time_background } from './time-background'
+import { time_followup_stage } from './time-followup-stage'
+import { time_instant } from './time-instant'
+import { time_reported_failure } from './time-reported-failure'
+
+// One line of a session transcript, read into the shape the span walk works on
+// (joshuafolkken/kit#1406).
+//
+// 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.
+//
+// **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 (joshuafolkken/kit#1309). 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
+	// (joshuafolkken/kit#1361): 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
+// (joshuafolkken/kit#1329). 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. Since
+// joshuafolkken/kit#1406 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 (joshuafolkken/kit#1268).
+	gitBranch: z.string().nullish(),
+	// The two fields outside `message` that the harness writes an end-of-task notice on
+	// (joshuafolkken/kit#1696). **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(),
+})
+
+const UNKNOWN_BRANCH = ''
+// The field an attachment line carries the notice in. Named rather than written as a literal for the
+// reason `time-background.ts`'s `BASH_ID_KEY` is: `dot-notation` rewrote `record['prompt']` into
+// `record.prompt`, which a value read as an index-signature record does not have — until
+// joshuafolkken/kit#1783 switched that fix off. The name is kept for its own sake.
+const PROMPT_KEY = 'prompt'
+const NO_MESSAGE_ID = ''
+// How much of an errored body is kept (joshuafolkken/kit#1642). A refusal's body *is* the reason the
+// harness wrote back, from its first character, so an opening this long identifies the speaker
+// without retaining the output of every failed command a session ran.
+const ERROR_TEXT_LIMIT = 256
+// The icon every guard refusal opens with (joshuafolkken/kit#1913). It is not `status_icons.FAIL_ICON`
+// — that one (`✗`) marks a josh check's failing item, which `has_failure_line` scans for; this one
+// marks a PreToolUse hook's *deny* reason, which is a different body carried in a different result. No
+// shared constant exists because each guard writes the literal in its own reason, so the one place a
+// refusal is *detected* names it here.
+const REFUSAL_MARKER = '⛔'
+
+interface Block {
+	type: string
+	name: string
+	id: string
+	result_id: string
+	input: unknown
+	// `undefined` where the block carried no `is_error` field, which is a different fact from
+	// `false`: one is a tool that reports no outcome, the other a call that succeeded.
+	is_error: boolean | undefined
+	// Whether the body carried a line opening with josh's failure icon — the one bit of it anything
+	// reads (joshuafolkken/kit#1361). The text itself is deliberately not kept: a field holding it
+	// would retain every byte the session's tools printed for the length of the parse.
+	has_failure_line: boolean
+	// The stage rows a `pnpm josh followup` call printed into its own output
+	// (joshuafolkken/kit#1445). Read here for the same reason the bit above is, and it obeys the same
+	// prohibition: what is kept is the ten-odd parsed laps, never the body they were read from. Empty
+	// for every other tool result, which is nearly all of them.
+	followup_stages: ReadonlyArray<FollowupStage>
+	// The opening of the body of a result the harness wrote back as a failure, and `''` for every
+	// other block (joshuafolkken/kit#1642). It obeys the same prohibition as the two fields above —
+	// what is kept is a bounded opening, never the whole body — and it exists so a reader asking
+	// which refusal a line carried can be answered from the parsed block rather than by matching
+	// `"is_error":true` against the raw line, a test one whitespace in the serializer defeats and
+	// which cannot tell one errored block from another on the same line.
+	error_text: string
+	// Which guard refused this call, read off the opening of an errored result and `''` for every other
+	// block (joshuafolkken/kit#1913). It obeys the same prohibition as `error_text` — what is kept is a
+	// short label, never the body — and it exists so the per-guard refusal breakdown can be answered from
+	// the parsed block rather than by re-scanning the body downstream. `''` where the result was not a
+	// `⛔` refusal, so a reader tells "no guard spoke" from "this guard spoke" without a second parse.
+	refusal_guard: string
+	// The id the harness assigned to a command it took into the background, and `''` for every other
+	// block (joshuafolkken/kit#1662). It is the fourth field read off the body under the same
+	// prohibition as the three above — what is kept is the id, never the text it was read from — and
+	// it is what pairs a launch with the call that later reads its output, so the minutes the command
+	// actually ran can be placed on the timeline instead of only the seconds its launch call took.
+	background_id: string
+}
+
+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 (joshuafolkken/kit#1696). 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.
+	finished_background: string
+	// The assistant message this line is one block of, or `''` where the line carries none — a user
+	// line, or an assistant line written without an id. The empty string is never treated as a group:
+	// every line lacking an id would otherwise fall into one bucket spanning the whole file.
+	message_id: string
+	blocks: Array<Block>
+}
+
+// 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'> {
+	return {
+		type: raw.type ?? '',
+		name: raw.name ?? '',
+		id: raw.id ?? '',
+		result_id: raw.tool_use_id ?? '',
+	}
+}
+
+// **A refusal is identified by what its body opens with, never by what it carries inside**
+// (joshuafolkken/kit#1913). 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
+// before the first `:` — `⛔ pre-gate cut: …` is `pre-gate cut`. A reason with no colon (a headline
+// like `⛔ scoped checks not green on this tree`) is taken whole. Reading the opening rather than
+// searching the body is what stops a result that merely quoted a reason being read as a refusal.
+function guard_from_refusal(text: string): string {
+	const trimmed = text.trimStart()
+	if (!trimmed.startsWith(REFUSAL_MARKER)) return ''
+
+	const headline = trimmed.slice(REFUSAL_MARKER.length).split('\n', 1)[0]?.trimStart() ?? ''
+	const colon = headline.indexOf(':')
+
+	return (colon === -1 ? headline : headline.slice(0, colon)).trim()
+}
+
+// **The body is flattened once and both readers are handed the text.** `result_text` is what turns a
+// 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 (joshuafolkken/kit#1445).
+function to_block(raw: z.infer<typeof BLOCK_SCHEMA>): Block {
+	const text = time_reported_failure.result_text(raw.content)
+	const is_error = raw.is_error ?? undefined
+
+	return {
+		...block_names(raw),
+		input: raw.input,
+		is_error,
+		has_failure_line: time_reported_failure.has_failure_line(text),
+		followup_stages: time_followup_stage.read_stages(text),
+		error_text: is_error === true ? text.slice(0, ERROR_TEXT_LIMIT) : '',
+		refusal_guard: is_error === true ? guard_from_refusal(text) : '',
+		background_id: time_background.launch_id(text),
+	}
+}
+
+// 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> {
+	return typeof content === 'string' || content === null || content === undefined
+		? []
+		: content.map((block) => to_block(block))
+}
+
+// The two fields read off `message`, taken together because they are one reading: an assistant turn
+// 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,
+): Pick<TranscriptLine, 'message_id' | 'blocks'> {
+	return { message_id: message?.id ?? NO_MESSAGE_ID, blocks: to_blocks(message?.content) }
+}
+
+// **One notice reaches the transcript on any of three line kinds, and which of them a session holds
+// varies** (joshuafolkken/kit#1696). The harness writes it on a `queue-operation` line when the notice
+// is generated, on an `attachment` line when it is delivered, and on a `user` line where it enters the
+// conversation — and a run measured against one carrier alone came back unmeasured whenever the
+// 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 {
+	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') ?? ''
+}
+
+// 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 {
+	const timestamp_ms = time_instant.parse_instant(data.timestamp)
+
+	if (timestamp_ms === undefined) return undefined
+
+	return {
+		type: data.type ?? '',
+		timestamp_ms,
+		branch: data.gitBranch ?? UNKNOWN_BRANCH,
+		finished_background: time_background.finished_id(notice_text(data)),
+		...message_fields(data.message),
+	}
+}
+
+function parse_line(line: string): TranscriptLine | undefined {
+	const parsed = LINE_SCHEMA.safeParse(json_value.parse_or_undefined(line))
+
+	return parsed.success ? to_line(parsed.data) : undefined
+}
+
+const time_transcript_line = {
+	ERROR_TEXT_LIMIT,
+	REFUSAL_MARKER,
+	NO_MESSAGE_ID,
+	guard_from_refusal,
+	parse_line,
+}
+
+export type { Block, TranscriptLine }
+export { time_transcript_line }

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

@@ -0,0 +1,71 @@
+import { time_bundle_call } from './time-bundle-call'
+import { time_markers } from './time-markers'
+
+// Which files one tool call **wrote** (joshuafolkken/kit#1472).
+//
+// **A span keeps no tool input**, so anything read off the input has to be read while the input is
+// still in hand — the reason `marker`, `targets` and `check_key` are already carried on `ToolCall`
+// rather than re-derived later. What was missing is the other half of that pair: a span said what a
+// call *named*, and never what it *changed*.
+//
+// **Two writes were therefore invisible, and both made the unedited count too large.**
+// `investigation-reads.ts` subtracts an edit from the set of files a run has read and not edited, and
+// it could only subtract what a span could describe:
+//
+// - `sed -i` labels as `Bash: sed`, exactly as the `sed -n` that is this repository's main reading
+//   command does, so a file written in place was counted as read and never taken back out.
+//   `CLAUDE.md` allows a small `sed -i` explicitly, so this is daily rather than exceptional.
+// - `MultiEdit` and `NotebookEdit` are edit tools for `time-markers.ts` but not bundleable ones for
+//   `time-bundle-call.ts`, so their spans arrived carrying `EDIT_MARKER` and `targets: []` — a
+//   subtraction with nothing to subtract.
+//
+// **This module is the one place that answers the question**, so the two callers cannot come to
+// disagree about it, and it reuses the extraction `time-bundle-call.ts` already owns rather than
+// writing a second one: `tool_targets` for a tool's own path fields, `targets_in` for a shell line.
+// Nothing here widens `BUNDLEABLE_TOOLS` — that set is what the batching measurement of
+// joshuafolkken/kit#1390 is defined over, and a call that writes is deliberately not bundleable.
+
+// **Whether a line is an in-place `sed` is `time-bundle-call.ts`'s answer, not a second one here**
+// (joshuafolkken/kit#1509). That module needs the same test as a boolean for the batching sequences,
+// and while the two were written separately they disagreed in both directions at once — one read the
+// whole line, so a piped `grep -i` made a read into a write; the other missed a bundled `sed -ni`, so
+// one span could carry `writes: ['x.ts']` beside `is_writing: false`. The segment scoping and the
+// quote removal that keep both honest are stated at `write_segment` there.
+//
+// **This is still not `time-batch-guard.ts`'s `WRITING_WORDS`, which excludes `sed` outright rather
+// than testing for `-i`** (that file states the choice at its own constant). Those answer different
+// questions and must differ: refusing a call half-applies a turn, so that guard treats every `sed` as
+// a write and errs toward allowing. What this module adds is *which* files, which a boolean could
+// not — and this set is subtracted, so an over-claim would delete a genuine pending read.
+
+// What a `Bash` line wrote. Only an in-place `sed` is claimed: a `>` redirection and a heredoc write
+// too, but naming them here would also claim the file the same line *read*, and this set is
+// subtracted rather than added — an over-claim silently removes a genuine pending read.
+//
+// The targets are read from the same segment the predicate answered about, so a file named in a later
+// pipeline stage cannot be claimed as written by the first one.
+function bash_writes(command: string): ReadonlyArray<string> {
+	const segment = time_bundle_call.write_segment(command)
+
+	return time_bundle_call.is_in_place_sed(segment) ? time_bundle_call.targets_in(segment) : []
+}
+
+// What a non-`Bash` call wrote: its path fields, when the tool is one `time-markers.ts` already
+// recognizes as opening implementation. Asking that module rather than keeping a second edit-tool set
+// is what makes `MultiEdit` and `NotebookEdit` answer here without being added anywhere new.
+function tool_writes(name: string, input: unknown): ReadonlyArray<string> {
+	if (time_markers.tool_marker(name, input) !== time_markers.EDIT_MARKER) return []
+
+	return time_bundle_call.tool_targets(input)
+}
+
+// **No `call_writes` beside these two.** `time-bundle-call.ts` has a `call_facts` because a
+// `PreToolUse` payload asks it about a raw invocation; nothing asks this module that — the live guard
+// never refuses an in-place `sed` or a `MultiEdit` in the first place — and an unwrapping entry point
+// with no caller is a second place for `Bash` handling to drift.
+const time_writes = {
+	bash_writes,
+	tool_writes,
+}
+
+export { time_writes }

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

@@ -0,0 +1,122 @@
+#!/usr/bin/env tsx
+import { readdirSync, readFileSync } 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 { ui_routes } from './ui-routes'
+
+// `josh ui:routes [--staged]` — list the screenshot-target routes the current change touches
+// (joshuafolkken/kit#2182).
+//
+// The derivation lives in `ui-routes.ts`; this file is the I/O around it: read the changed paths
+// (the branch diff, or the staged diff with `--staged`), and resolve a shared component to the routes
+// that import it by scanning `src/routes`. A change that derives no route prints that plainly rather
+// than guessing, matching the `verify-ui` skill's "do not guess".
+
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh ui:routes [--staged]'
+const STAGED_FLAG = '--staged'
+const ROUTES_DIR = 'src/routes'
+const PATH_SEPARATOR = '/'
+const FAILURE_EXIT_CODE = 1
+const NO_ROUTES_MESSAGE =
+	'no route derived from this change — name the screen to capture, do not guess'
+
+interface RouteFile {
+	absolute: string
+	relative: string
+}
+
+type ImporterFinder = (component: string) => Array<string>
+
+// `undefined` on an unknown flag rather than a default: a misspelled flag makes the invocation
+// unreadable, and an unreadable invocation is refused, not answered.
+function parse_staged(argv: ReadonlyArray<string>): boolean | undefined {
+	if (argv.some((argument) => argument !== STAGED_FLAG)) return undefined
+
+	return argv.includes(STAGED_FLAG)
+}
+
+function base_name(file: string): string {
+	return file.slice(file.lastIndexOf(PATH_SEPARATOR) + 1)
+}
+
+function to_route_file(root: string, directory: string, name: string): RouteFile {
+	const absolute = path.join(directory, name)
+
+	return { absolute, relative: path.relative(root, absolute).split(path.sep).join(PATH_SEPARATOR) }
+}
+
+function route_files(root: string): Array<RouteFile> {
+	try {
+		return readdirSync(path.join(root, ROUTES_DIR), { recursive: true, withFileTypes: true })
+			.filter((entry) => entry.isFile())
+			.map((entry) => to_route_file(root, entry.parentPath, entry.name))
+	} catch {
+		return []
+	}
+}
+
+function read_text(file: string): string {
+	try {
+		return readFileSync(file, 'utf8')
+	} catch {
+		return ''
+	}
+}
+
+// A route file imports the component when its source names the component's file — the import
+// statement carries the `.svelte` path. Over-inclusion is the safe direction for a candidate list: a
+// spare route is dropped by the reader, a missing one is never captured.
+function build_find_importers(files: ReadonlyArray<RouteFile>): ImporterFinder {
+	return (component) =>
+		files
+			.filter((file) => read_text(file.absolute).includes(base_name(component)))
+			.map((file) => file.relative)
+}
+
+function print_routes(routes: ReadonlyArray<string>): void {
+	if (routes.length === 0) {
+		console.info(NO_ROUTES_MESSAGE)
+
+		return
+	}
+
+	for (const route of routes) console.info(route)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const is_staged = parse_staged(argv)
+
+	if (is_staged === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const changed = await changed_paths.read_changed_paths(is_staged)
+	const find_importers = build_find_importers(route_files(await git_command.repository_root()))
+
+	print_routes(ui_routes.derive_routes(changed, find_importers))
+
+	return 0
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const ui_routes_cli = {
+	build_find_importers,
+	main,
+	parse_staged,
+	print_routes,
+	route_files,
+	run,
+	USAGE,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { ui_routes_cli }

package/scripts/ui/ui-routes.ts

@@ -0,0 +1,102 @@
+// The screenshot-target routes a change touches, derived from the diff rather than chosen by eye
+// (joshuafolkken/kit#2182).
+//
+// The `verify-ui` skill's §1 asked the reader to read `git diff` and name the routes whose
+// components, styles or copy it touches — but in SvelteKit a file path maps to a route path
+// mechanically, so the candidate list is computed. What stays a judgement is the narrowing "pick the
+// ones a reader would notice"; this module produces the candidates that judgement chooses from.
+//
+// A changed route file (`+page`/`+layout`) contributes its own route; a changed shared component
+// contributes the routes that render it, found through an injected `find_importers` so the file-system
+// scan stays in the CLI and this derivation stays pure. The import scan is one level deep: a component
+// imported only by another component, never directly by a route, yields no candidate here.
+
+const ROUTES_PREFIX = 'src/routes/'
+const SVELTE_EXTENSION = '.svelte'
+const ROUTE_SEPARATOR = '/'
+// A route-defining file renders UI: `+page*` is the page, `+layout*` wraps it. `+server`/`+error` are
+// not screenshot targets, so they are treated as shared files (imported by nothing, they contribute
+// nothing).
+const ROUTE_FILE_PATTERN = /^\+(page|layout)\b/u
+
+function is_under_routes(file: string): boolean {
+	return file.startsWith(ROUTES_PREFIX)
+}
+
+function base_name(file: string): string {
+	return file.slice(file.lastIndexOf(ROUTE_SEPARATOR) + 1)
+}
+
+function is_route_file(file: string): boolean {
+	return is_under_routes(file) && ROUTE_FILE_PATTERN.test(base_name(file))
+}
+
+// A `.svelte` file that is not a route file — a `$lib` component, or a component that sits beside
+// routes. Its own path names no route, so its routes are its importers'.
+function is_shared_svelte(file: string): boolean {
+	return file.endsWith(SVELTE_EXTENSION) && !is_route_file(file)
+}
+
+// A route group directory — `(marketing)` — is organizational and contributes no URL segment, so it
+// is dropped from the path (SvelteKit routing).
+function is_group_segment(segment: string): boolean {
+	return segment.startsWith('(') && segment.endsWith(')')
+}
+
+function route_path_of(file: string): string | undefined {
+	if (!is_route_file(file)) return undefined
+
+	const segments = file
+		.slice(ROUTES_PREFIX.length)
+		.split(ROUTE_SEPARATOR)
+		.slice(0, -1)
+		.filter((segment) => !is_group_segment(segment))
+
+	return `${ROUTE_SEPARATOR}${segments.join(ROUTE_SEPARATOR)}`
+}
+
+function is_route(value: string | undefined): value is string {
+	return value !== undefined
+}
+
+function routes_via_component(
+	component: string,
+	find_importers: (component: string) => ReadonlyArray<string>,
+): Array<string> {
+	return find_importers(component)
+		.map((importer) => route_path_of(importer))
+		.filter(is_route)
+}
+
+function routes_of_path(
+	file: string,
+	find_importers: (component: string) => ReadonlyArray<string>,
+): Array<string> {
+	const direct = route_path_of(file)
+	if (direct !== undefined) return [direct]
+	if (!is_shared_svelte(file)) return []
+
+	return routes_via_component(file, find_importers)
+}
+
+// The screenshot-target candidates for a set of changed paths, deduplicated and ordered. An empty
+// result is the honest "no route derived" the CLI reports rather than guessing.
+function derive_routes(
+	changed: ReadonlyArray<string>,
+	find_importers: (component: string) => ReadonlyArray<string>,
+): Array<string> {
+	const routes = changed.flatMap((file) => routes_of_path(file, find_importers))
+
+	return [...new Set(routes)].toSorted((first, second) => first.localeCompare(second))
+}
+
+const ui_routes = {
+	derive_routes,
+	is_route_file,
+	is_shared_svelte,
+	route_path_of,
+	ROUTES_PREFIX,
+	SVELTE_EXTENSION,
+}
+
+export { ui_routes }

package/scripts/version/bump-version.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env tsx
+import { readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+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 PACKAGE_JSON_INDENT = '\t'
+
+function compute_new_version(version: string, bump_type: BumpType): string {
+	const new_version = semver.inc(version, bump_type)
+
+	if (new_version === null) throw new Error(`Invalid version format: ${version}`)
+
+	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 (joshuafolkken/kit#1169). 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')))
+
+	writeFileSync(
+		package_path,
+		`${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
+}
+
+function bump_version(bump_type: BumpType): void {
+	const new_version = compute_new_version(read_current_version(), bump_type)
+
+	write_version(new_version)
+	console.info(new_version)
+}
+
+function main(): void {
+	const ARGV_INDEX = 2
+	const bump_type = process.argv[ARGV_INDEX] ?? 'minor'
+
+	if (!VALID_BUMP_TYPES.includes(bump_type as BumpType)) {
+		console.error(`Usage: tsx scripts/version/bump-version.ts [major|minor|patch]`)
+		process.exit(1)
+	}
+
+	try {
+		bump_version(bump_type as BumpType)
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error))
+		process.exit(1)
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+
+export { bump_version, compute_new_version, write_version }