@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/issue/issue-watch-diff.ts

@@ -1,9 +1,11 @@
+import { gh_author_association } from '#scripts/gh/gh-author-association'
 import { read_json_listing } from '#scripts/git/parse-json-array'
 import { z } from 'zod'
 
-// What a person changed on an issue since a run last read it, as the one pure answer the hook, the
-// review attestation, `josh issue:ack` and `josh followup` all print. Kept free of I/O so the four
-// callers cannot each draw the line between "a person's update" and "noise" differently.
+// What a person changed on an issue since a run last read it, as the one answer the hook, the review
+// attestation, `josh issue:ack` and `josh followup` all print. Kept in one place so the four callers
+// cannot each draw the line between "a person's update" and "noise" differently; its only I/O is the
+// write-access lookup `gh_author_association` makes for a `MEMBER` / `COLLABORATOR`.
 //
 // **A person's update is a body edit or a comment nobody automated.** A bot's comment (`type: Bot`,
 // or a `[bot]` login) is not one. A run's own comment is posted under the person's own `gh` login,
@@ -12,6 +14,13 @@ import { z } from 'zod'
 // through a raw `gh api` counts as a person's — the direction that costs one `josh issue:ack`, never a
 // missed correction.
 //
+// **Only an author with write access is a person here** (`gh_author_association`). On a public
+// repository anyone can comment, so a comment from anyone else is never handed to a run as an update,
+// and its `RUN_MARKER` is not taken as josh's own. A `MEMBER` / `COLLABORATOR` whose lookup failed
+// (`is_trusted: undefined` — the hook's timeout fired) is neither: their comment is announced with its
+// body withheld, costing one `josh issue:ack` rather than a missed correction, and its marker is not
+// trusted.
+//
 // **Comment edits are out of scope.** A new comment carries an id above the baseline's; an edited
 // one keeps its id and is not seen. The body is compared whole, so its edits are.
 
@@ -21,6 +30,8 @@ const BOT_SUFFIX = '[bot]'
 const NO_COMMENT_ID = 0
 const UNKNOWN_AUTHOR = '(unknown)'
 const UNKNOWN_TIME = '(undated)'
+const UNVERIFIED_BODY =
+	"(body withheld — the author's write access could not be checked; read it with `josh issue:read`)"
 
 const BODY_HEADING = 'Body edited:'
 const REMOVED_PREFIX = '- '
@@ -36,11 +47,14 @@ const comment_schema = z.looseObject({
 	user: z.looseObject({ login: z.string(), type: z.string().optional() }).nullish(),
 	created_at: z.string().optional(),
 	body: z.string().nullish(),
+	author_association: z.string().nullish(),
 })
 
 interface WatchComment {
 	id: number
 	author: string
+	// `undefined` when the write-access lookup failed.
+	is_trusted: boolean | undefined
 	is_automated: boolean
 	created_at: string
 	body: string
@@ -60,26 +74,48 @@ function is_bot(user: z.infer<typeof comment_schema>['user']): boolean {
 	return user?.type === BOT_TYPE || (user?.login.endsWith(BOT_SUFFIX) ?? false)
 }
 
-function is_automated(user: z.infer<typeof comment_schema>['user'], body: string): boolean {
-	return is_bot(user) || body.includes(RUN_MARKER)
+function is_automated(
+	raw: z.infer<typeof comment_schema>,
+	is_trusted: boolean | undefined,
+): boolean {
+	return is_bot(raw.user) || (is_trusted === true && (raw.body?.includes(RUN_MARKER) ?? false))
 }
 
-function to_comment(raw: z.infer<typeof comment_schema>): WatchComment {
-	const body = raw.body ?? ''
-	const author = raw.user?.login ?? UNKNOWN_AUTHOR
-	const created_at = raw.created_at ?? UNKNOWN_TIME
+async function to_comment(
+	raw: z.infer<typeof comment_schema>,
+	timeout_ms?: number,
+): Promise<WatchComment> {
+	const login = raw.user?.login
+	const is_trusted = await gh_author_association.trust_of({
+		login,
+		association: raw.author_association,
+		timeout_ms,
+	})
 
-	return { id: raw.id, author, is_automated: is_automated(raw.user, body), created_at, body }
+	return {
+		id: raw.id,
+		author: login ?? UNKNOWN_AUTHOR,
+		is_trusted,
+		is_automated: is_automated(raw, is_trusted),
+		created_at: raw.created_at ?? UNKNOWN_TIME,
+		body: raw.body ?? '',
+	}
 }
 
 // `undefined` — never `[]` — for a listing that could not be read, so a failed read is never taken
-// for "nobody commented".
-function parse_comments(json: string | undefined): ReadonlyArray<WatchComment> | undefined {
+// for "nobody commented". `timeout_ms` bounds each write-access lookup, which run concurrently, so a
+// hook's read stays inside its own timeout.
+async function parse_comments(
+	json: string | undefined,
+	timeout_ms?: number,
+): Promise<ReadonlyArray<WatchComment> | undefined> {
 	if (json === undefined) return undefined
 
 	const listing = read_json_listing(json, comment_schema)
 
-	return listing.kind === 'read' ? listing.rows.map((row) => to_comment(row)) : undefined
+	if (listing.kind !== 'read') return undefined
+
+	return await Promise.all(listing.rows.map(async (row) => await to_comment(row, timeout_ms)))
 }
 
 function last_comment_id(comments: ReadonlyArray<WatchComment>): number {
@@ -118,7 +154,9 @@ function body_section(previous_raw: string, current_raw: string): string | undef
 }
 
 function comment_section(comment: WatchComment): string {
-	return `${COMMENT_HEADING}${comment.author}${AT}${comment.created_at}${LINE_SEPARATOR}${comment.body}`
+	const body = comment.is_trusted === true ? comment.body : UNVERIFIED_BODY
+
+	return `${COMMENT_HEADING}${comment.author}${AT}${comment.created_at}${LINE_SEPARATOR}${body}`
 }
 
 function new_person_comments(
@@ -126,7 +164,10 @@ function new_person_comments(
 	snapshot: WatchSnapshot,
 ): ReadonlyArray<WatchComment> {
 	return snapshot.comments.filter(
-		(comment) => comment.id > baseline.last_comment_id && !comment.is_automated,
+		(comment) =>
+			comment.id > baseline.last_comment_id &&
+			comment.is_trusted !== false &&
+			!comment.is_automated,
 	)
 }
 

package/scripts/issue/issue-watch.ts

@@ -76,8 +76,9 @@ async function read_snapshot(
 	body: string,
 	etag: string | undefined,
 ): Promise<Fetched> {
-	const comments = issue_watch_diff.parse_comments(
+	const comments = await issue_watch_diff.parse_comments(
 		await git_gh_issue_read.issue_list_comments(request.issue, request.timeout_ms),
+		request.timeout_ms,
 	)
 
 	return comments === undefined ? UNREADABLE : { kind: 'read', snapshot: { body, comments }, etag }

package/scripts/issue/issue-wip.ts

@@ -1,3 +1,4 @@
+import { json_value } from '#scripts/lib/json-value'
 import { INTERRUPT_ROUTE_LABEL, SPLIT_ROUTE_LABEL, TIER_A_ROUTE_LABEL } from './issue-labels'
 
 // The WIP cap at the call that files. `josh issue:file` reads the count and asks the exemption
@@ -55,13 +56,7 @@ function count_line(count: number, repo: string, verdict: WipVerdict): string {
 // The listing's JSON is an array of rows; anything else is unreadable rather than zero, because zero
 // would pass every filing as within the cap.
 function count_of(json: string): number | undefined {
-	try {
-		const parsed: unknown = JSON.parse(json)
-
-		return Array.isArray(parsed) ? parsed.length : undefined
-	} catch {
-		return undefined
-	}
+	return json_value.parse_array(json)?.length
 }
 
 const issue_wip = { WIP_CAP, HELD, HELD_MESSAGE, UNREAD_MESSAGE, verdict_of, count_line, count_of }

package/scripts/issue/measure-rerun-cli.ts

@@ -24,7 +24,7 @@ import { session_cite } from './session-cite'
 
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const ISSUE_FIELDS = 'body,author_association'
+const ISSUE_FIELDS = 'body,author_association,user'
 const UNKNOWN_ASSOCIATION = 'unknown'
 const USAGE = 'Usage: josh measure:rerun <issue-number>'
 const NO_BASELINE = 'no `command → value` baseline found in ## ベースライン — nothing to re-run'
@@ -36,6 +36,7 @@ const MEASURE_TIMEOUT_MS = 60_000
 const issue_schema = z.object({
 	body: z.string().nullish(),
 	author_association: z.string().nullish(),
+	user: z.looseObject({ login: z.string() }).nullish(),
 })
 
 type IssueFields = z.infer<typeof issue_schema>
@@ -88,6 +89,15 @@ async function read_issue(issue_number: string): Promise<IssueFields | undefined
 	return json === undefined ? undefined : parse_json_object_or_undefined(json, issue_schema)
 }
 
+function untrusted(issue_number: string, issue: IssueFields): BodyRead {
+	const association = issue.author_association ?? UNKNOWN_ASSOCIATION
+
+	return {
+		kind: 'refused',
+		reason: `refusing to run the baseline of ${session_cite.issue(issue_number)}: its author (${association}) is not ${gh_author_association.TRUSTED_LIST}`,
+	}
+}
+
 // The body, only when its author can write to the repository. A read that fails is refused as well:
 // an unknown author is not a trusted one.
 async function read_trusted_body(issue_number: string): Promise<BodyRead> {
@@ -97,14 +107,9 @@ async function read_trusted_body(issue_number: string): Promise<BodyRead> {
 		return { kind: 'refused', reason: `could not read issue ${session_cite.issue(issue_number)}` }
 	}
 
-	const association = issue.author_association ?? UNKNOWN_ASSOCIATION
+	const author = { login: issue.user?.login, association: issue.author_association }
 
-	if (!gh_author_association.is_trusted(association)) {
-		return {
-			kind: 'refused',
-			reason: `refusing to run the baseline of ${session_cite.issue(issue_number)}: its author is ${association}, not ${gh_author_association.TRUSTED_LIST}`,
-		}
-	}
+	if (!(await gh_author_association.is_trusted(author))) return untrusted(issue_number, issue)
 
 	return { kind: 'trusted', body: issue.body ?? '' }
 }

package/scripts/issue/plan-consumers-cli.ts

@@ -0,0 +1,39 @@
+import { plan_consumers } from '#scripts/issue/plan-consumers'
+
+// `josh plan:consumers <identifier...>` — prints each identifier's existing references and the draft
+// of a plan's existing-consumers section (`plan-consumers.ts`). A flag is refused rather than searched
+// for, since an identifier never starts with `-`.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const USAGE = 'Usage: josh plan:consumers <identifier...>'
+
+function identifiers_of(argv: ReadonlyArray<string>): Array<string> | undefined {
+	const identifiers = [...new Set(argv.map((argument) => argument.trim()))]
+
+	if (identifiers.length === 0) return undefined
+
+	return identifiers.some((identifier) => identifier === '' || identifier.startsWith('-'))
+		? undefined
+		: identifiers
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const identifiers = identifiers_of(argv)
+
+	if (identifiers === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const { text, has_failed } = await plan_consumers.report(identifiers)
+
+	console.info(text)
+
+	return has_failed ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+}
+
+const plan_consumers_cli = { USAGE, run }
+
+export { plan_consumers_cli }

package/scripts/issue/plan-consumers-main.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { plan_consumers_cli } from './plan-consumers-cli'
+
+// The `josh plan:consumers` entry, kept apart from `plan-consumers-cli.ts` so a bundle carrying that
+// module never fires this guard (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await plan_consumers_cli.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/issue/plan-consumers-section.ts

@@ -0,0 +1,55 @@
+import { markdown_section } from '#scripts/issue/markdown-section'
+
+// A plan's existing-consumers section (`HEADING`) — the existing code, prompts and documents that
+// read or write each state, command, label, file or process the plan adds or changes, and what this
+// issue does with each. A concept added without it shipped while its readers still assumed the old
+// world (joshuafolkken/kit#4270, #4265 after `lane:pause`), so `issue:plan` refuses a plan that omits
+// it.
+//
+// **"None" is an answer only with its reason** (`NONE_WITH_REASON`), since a bare "none" cannot be
+// told from a section filled in to get past the check.
+
+const HEADING = '### 影響を受ける既存の利用者'
+const ANY_HEADING = /^#{1,6}\s/u
+const LIST_MARKER = /^(?:[-*+]|\d+\.)\s+/u
+const NONE_WORD = 'なし'
+const NONE_WITH_REASON = /^なし\s*[（(]\s*\S.*[）)]$/u
+const MISSING = `The plan has no \`${HEADING}\` section: list, for each state, command, label, file or process it adds or changes, the existing places that read or write it and what this issue does with each (\`pnpm josh plan:consumers <identifier...>\` drafts it), or write \`なし（<reason>）\`.`
+const EMPTY = `The plan's \`${HEADING}\` section is empty: list the existing consumers, or write \`なし（<reason>）\`.`
+const BARE_NONE = `The plan's \`${HEADING}\` section says \`なし\` without a reason: write \`なし（<reason>）\`.`
+
+// The section runs to the next heading of any level, since the plan's own sections are `###`. Fenced
+// lines are blanked first, so a `# comment` in a code block neither ends the section nor is an entry.
+function section_entries(plan: string): ReadonlyArray<string> | undefined {
+	if (!markdown_section.has_line(plan, HEADING)) return undefined
+	const raw = markdown_section.section_lines(plan, HEADING).join('\n')
+	const lines = markdown_section.fence_free_lines(raw)
+	const end = lines.findIndex((line) => ANY_HEADING.test(line.trim()))
+	const body = end === -1 ? lines : lines.slice(0, end)
+
+	return body.map((line) => line.trim().replace(LIST_MARKER, '')).filter((line) => line !== '')
+}
+
+// "None" answers for the whole section, so only a section that opens with it is read as one — a "none"
+// nested under a consumer entry is that entry's note. A reason wrapped onto later lines is joined back.
+function is_bare_none(entries: ReadonlyArray<string>): boolean {
+	const [first = ''] = entries
+
+	if (!first.startsWith(NONE_WORD) || NONE_WITH_REASON.test(first)) return false
+
+	return !NONE_WITH_REASON.test(entries.join(' '))
+}
+
+// The refusal for a plan whose section is missing, empty or a reasonless "none"; `undefined` passes.
+function refusal_of(plan: string): string | undefined {
+	const entries = section_entries(plan)
+
+	if (entries === undefined) return MISSING
+	if (entries.length === 0) return EMPTY
+
+	return is_bare_none(entries) ? BARE_NONE : undefined
+}
+
+const plan_consumers_section = { HEADING, refusal_of }
+
+export { plan_consumers_section }

package/scripts/issue/plan-consumers.ts

@@ -0,0 +1,127 @@
+import { git_grep_hits, type Hit } from '#scripts/git/git-grep-hits'
+import { plan_consumers_section } from '#scripts/issue/plan-consumers-section'
+
+// `josh plan:consumers <identifier...>` — where each identifier a plan adds or changes is already
+// read or written, so its existing-consumers section names them rather than leaving them for the
+// next incident to find. Every reference in the tracked tree — a CI workflow or a settings file reads
+// a name as surely as code does — grouped by kind, then a draft of the section for the plan to finish.
+// `.josh/` is left out: its observations and metrics record past runs rather than read the name.
+//
+// **Unlike `run:prep`'s code locations it keeps every line and every kind** — a prompt that tells a
+// run to count a label is as much a consumer of it as the code that does — but caps each kind, so one
+// common name cannot bury the rest.
+
+type Kind = 'code' | 'config' | 'doc' | 'prompt' | 'test'
+
+interface Consumers {
+	identifier: string
+	hits: ReadonlyArray<Hit>
+	has_failed: boolean
+}
+
+const PATHSPECS = [':(exclude).josh']
+const KINDS: ReadonlyArray<readonly [Kind, string]> = [
+	['code', 'code'],
+	['config', 'config and workflows'],
+	['prompt', 'prompts and skills'],
+	['doc', 'docs'],
+	['test', 'tests'],
+]
+const TEST_PATH = /(?:\.test\.ts|\.e2e\.ts|\.snap)$/u
+const CODE_PATH = /\.(?:ts|js|mjs|cjs|svelte|sh)$/u
+const PROMPT_ROOTS = ['prompts/', '.claude/']
+const MAX_HITS_PER_KIND = 20
+const MAX_DRAFT_FILES = 8
+const INDENT = '  '
+const HIT_INDENT = `${INDENT}${INDENT}`
+const HIT_SEPARATOR = '  '
+const NO_REFERENCE = ' — no reference in the tracked tree'
+const SEARCH_FAILED = ' — git grep failed; not searched'
+const DRAFT_ACTION = '<直す | 影響なし | 別 Issue>'
+const DRAFT_NO_REFERENCE = 'no existing reference'
+
+// Markdown under `prompts/` or `.claude/` instructs a run and other Markdown is read by people; the
+// rest that is neither code nor a test — workflows, settings, JSON and YAML data — is configuration.
+function markdown_kind(path: string): Kind {
+	return PROMPT_ROOTS.some((root) => path.startsWith(root)) ? 'prompt' : 'doc'
+}
+
+function kind_of(path: string): Kind {
+	if (TEST_PATH.test(path)) return 'test'
+	if (CODE_PATH.test(path)) return 'code'
+
+	return path.endsWith('.md') ? markdown_kind(path) : 'config'
+}
+
+function more_line(count: number): Array<string> {
+	return count > MAX_HITS_PER_KIND
+		? [`${HIT_INDENT}… +${String(count - MAX_HITS_PER_KIND)} more`]
+		: []
+}
+
+function format_kind(hits: ReadonlyArray<Hit>, kind: Kind, label: string): Array<string> {
+	const of_kind = hits.filter((hit) => kind_of(hit.path) === kind)
+
+	if (of_kind.length === 0) return []
+	const lines = of_kind
+		.slice(0, MAX_HITS_PER_KIND)
+		.map((hit) => `${HIT_INDENT}${hit.path}:${hit.line}${HIT_SEPARATOR}${hit.excerpt}`)
+
+	return [`${INDENT}${label}`, ...lines, ...more_line(of_kind.length)]
+}
+
+function format_consumers(consumers: Consumers): string {
+	if (consumers.has_failed) return `${consumers.identifier}${SEARCH_FAILED}`
+	if (consumers.hits.length === 0) return `${consumers.identifier}${NO_REFERENCE}`
+	const kinds = KINDS.flatMap(([kind, label]) => format_kind(consumers.hits, kind, label))
+
+	return [consumers.identifier, ...kinds].join('\n')
+}
+
+// Tests are left out of the draft: a test follows the code it covers, so it is never the consumer a
+// plan has to decide about.
+function kind_rank(path: string): number {
+	return KINDS.findIndex(([kind]) => kind === kind_of(path))
+}
+
+// Code first, in `KINDS` order, so the cap drops docs before the code a plan most has to decide on.
+function draft_files(hits: ReadonlyArray<Hit>): Array<string> {
+	const paths = [...new Set(hits.map((hit) => hit.path))]
+		.filter((path) => kind_of(path) !== 'test')
+		.toSorted((left, right) => kind_rank(left) - kind_rank(right))
+	const shown = paths.slice(0, MAX_DRAFT_FILES).map((path) => `\`${path}\``)
+	const rest = paths.length - shown.length
+
+	return rest > 0 ? [...shown, `+${String(rest)} more`] : shown
+}
+
+function draft_entry(consumers: Consumers): string {
+	const files = draft_files(consumers.hits)
+
+	if (files.length === 0) return `- \`${consumers.identifier}\`: ${DRAFT_NO_REFERENCE}`
+
+	return `- \`${consumers.identifier}\`: ${files.join(', ')} — ${DRAFT_ACTION}`
+}
+
+function format_draft(all: ReadonlyArray<Consumers>): string {
+	const entries = all.map((consumers) => draft_entry(consumers))
+
+	return ['draft:', plan_consumers_section.HEADING, '', ...entries].join('\n')
+}
+
+async function find(identifier: string): Promise<Consumers> {
+	return { identifier, ...(await git_grep_hits.search(identifier, [], PATHSPECS)) }
+}
+
+async function report(
+	identifiers: ReadonlyArray<string>,
+): Promise<{ text: string; has_failed: boolean }> {
+	const all = await Promise.all(identifiers.map(async (identifier) => await find(identifier)))
+	const sections = [...all.map((consumers) => format_consumers(consumers)), format_draft(all)]
+
+	return { text: sections.join('\n\n'), has_failed: all.some((consumers) => consumers.has_failed) }
+}
+
+const plan_consumers = { kind_of, report }
+
+export { plan_consumers }

package/scripts/josh/agent-session-environment.ts

@@ -1,7 +1,7 @@
 // The environment variables that name the **parent** agent session, and which a child session must
 // not inherit.
 //
-// `scripts/eval/eval-session.ts` and `josh run:wake` both launch a headless session. Two copies of
+// `tools/eval/eval-session.ts` and `josh run:wake` both launch a headless session. Two copies of
 // this list is the clone `CLAUDE.md`
 // prohibits, and this is the shape of clone that fails silently: the copy that drifts does not throw
 // or lint — the child dials the parent's private socket, is refused, and the session dies as

package/scripts/josh/command-usage.ts

@@ -1,36 +1,17 @@
 import { canonical_command, COMMAND_MAP } from './josh-command-map'
 import type { CommandUsage } from './josh-command-types'
-import { AUTOMATION_USAGE } from './josh-usage-automation'
-import { BACKLOG_USAGE } from './josh-usage-backlog'
-import { DEVELOPER_USAGE } from './josh-usage-developer'
-import { HOOK_USAGE } from './josh-usage-hooks'
-import { ISSUE_USAGE } from './josh-usage-issue'
-import { REVIEW_USAGE } from './josh-usage-review'
-import { RUN_USAGE } from './josh-usage-run'
-import { SESSION_USAGE } from './josh-usage-session'
-import { WORKFLOW_USAGE } from './josh-usage-workflow'
 
 // The single renderer of a command's usage. `josh help <command>` prints it and
-// `scripts/document/generate-command-usage.ts` writes it between a reference page's usage markers,
-// so the terminal and the page are one text (#3932).
-
-type UsageTable = Readonly<Record<string, CommandUsage>>
-
-// Which reference page renders each usage table — the one place a table is tied to its page, so the
-// generator's coverage check and `josh help` read the same set (#3981).
-/* eslint-disable @typescript-eslint/naming-convention */
-const USAGE_PAGE_TABLES: Readonly<Record<string, ReadonlyArray<UsageTable>>> = {
-	'docs/josh-commands.md': [DEVELOPER_USAGE],
-	'docs/josh-commands-run.md': [RUN_USAGE, SESSION_USAGE],
-	'docs/josh-commands-backlog.md': [ISSUE_USAGE, BACKLOG_USAGE, REVIEW_USAGE],
-	'docs/josh-commands-automation.md': [AUTOMATION_USAGE, WORKFLOW_USAGE, HOOK_USAGE],
-}
-/* eslint-enable @typescript-eslint/naming-convention */
-const COMMAND_USAGE: UsageTable = Object.fromEntries(
-	Object.values(USAGE_PAGE_TABLES)
-		.flat()
-		.flatMap((table) => Object.entries(table)),
-)
+// `tools/document/generate-command-usage.ts` writes it between a reference page's usage markers,
+// so the terminal and the page are one text (#3932). The usage itself sits on each command's entry
+// (#4185); which page renders it is the page's own `<!-- usage: <command> -->` span.
+
+const USAGE_PAGES: ReadonlyArray<string> = [
+	'docs/josh-commands.md',
+	'docs/josh-commands-run.md',
+	'docs/josh-commands-backlog.md',
+	'docs/josh-commands-automation.md',
+]
 const NOTE_GAP = 3
 
 interface ExampleLine {
@@ -39,7 +20,7 @@ interface ExampleLine {
 }
 
 function usage_for(name: string): CommandUsage | undefined {
-	return Object.hasOwn(COMMAND_USAGE, name) ? COMMAND_USAGE[name] : undefined
+	return Object.hasOwn(COMMAND_MAP, name) ? COMMAND_MAP[name]?.usage : undefined
 }
 
 function example_line(name: string, example: CommandUsage['examples'][number]): ExampleLine {
@@ -80,31 +61,22 @@ function format_usage(name: string): string | undefined {
 	return [format_examples(name, usage), ...flags].join('\n\n')
 }
 
-// `josh help <command>`: the synopsis line, the description, then the usage block when the command
-// has one. An alias resolves to its command; a name that is neither answers `undefined`.
+// `josh help <command>`: the synopsis line, the description, then the usage block. An alias
+// resolves to its command; a name that is neither answers `undefined`.
 function format_command_help(input: string): string | undefined {
 	const name = canonical_command(input)
 	const entry = Object.hasOwn(COMMAND_MAP, name) ? COMMAND_MAP[name] : undefined
 	if (entry === undefined) return undefined
 	const [synopsis] = entry.reference
 	const head = synopsis ? `josh ${name} ${synopsis}` : `josh ${name}`
-	const usage = format_usage(name)
-
-	return [head, '', entry.description, ...(usage === undefined ? [] : ['', usage])].join('\n')
-}
-
-// The commands whose usage blocks a reference page renders — the keys of the tables tied to it.
-function page_commands(page: string): Array<string> {
-	const tables = Object.hasOwn(USAGE_PAGE_TABLES, page) ? USAGE_PAGE_TABLES[page] : undefined
 
-	return (tables ?? []).flatMap((table) => Object.keys(table))
+	return [head, '', entry.description, '', format_usage(name)].join('\n')
 }
 
 const command_usage = {
-	USAGE_PAGES: Object.keys(USAGE_PAGE_TABLES),
+	USAGE_PAGES,
 	format_command_help,
 	format_usage,
-	page_commands,
 }
 
 export { command_usage }