@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/issue/issue-lint-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_lint_cli } from './issue-lint-cli'
+
+// The `josh issue:lint` entry, kept apart from `issue-lint-cli.ts` because other modules import 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 PATH_ARGUMENT_INDEX = 2
+
+	process.exitCode = await issue_lint_cli.run(process.argv[PATH_ARGUMENT_INDEX])
+}

package/scripts/issue/issue-measured-cli.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_evidence_exit } from '#scripts/issue/issue-evidence-exit'
+import { issue_measured_close } from '#scripts/issue/issue-measured-close'
+
+// `josh issue:measured <N> --evidence-file <path>` — the completion of a measurement-only Issue
+// (`issue-comments.md` → "A measurement-only Issue"): the result comment, the
+// `measured` label, the close and the `run:release`, in that order (`issue-evidence-exit.ts`,
+// `issue-measured-close.ts`). `--unmet` records that the measurement fell short of the expected
+// effect, with the `measured:unmet` label `josh effect:audit` reads.
+
+const ARGV_OFFSET = 2
+const UNMET_FLAG = '--unmet'
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const exit = argv.includes(UNMET_FLAG)
+		? issue_measured_close.MEASURED_UNMET_EXIT
+		: issue_measured_close.MEASURED_EXIT
+
+	return await issue_evidence_exit.run(
+		argv.filter((argument) => argument !== UNMET_FLAG),
+		exit,
+	)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const issue_measured_cli = { run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_measured_cli }

package/scripts/issue/issue-measured-close.ts

@@ -0,0 +1,58 @@
+import { epic_close } from '#scripts/epic/epic-close'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_evidence_exit, type EvidenceExit } from '#scripts/issue/issue-evidence-exit'
+import { MEASURED_LABEL, MEASURED_UNMET_LABEL } from '#scripts/issue/issue-labels'
+import { session_cite } from '#scripts/issue/session-cite'
+
+// The writes that complete a measurement-only Issue — the result comment, the `measured` label and
+// the close — shared by `josh issue:measured` and `backlog:drive`'s declared measurement
+// (`backlog-measure-close.ts`), out of the CLI so the drive imports no main guard.
+//
+// **The close is the run's own**: such an Issue changes no code, so no pull request's `closes #N`
+// can close it, and an OPEN child `run:merge` reads as `failed` and parks with `run:stalled`. A
+// CLOSED one it reads as `merged` (`run-merge.ts` → `classify_child`). The label goes on before the
+// close because it is what every sweep — `run:carry --end`, `run:tidy` — tells this close from a
+// person's by (`issue-merged.ts`); a close without it would be one they never count as merged.
+
+async function apply_label(issue_number: string, label: string = MEASURED_LABEL): Promise<boolean> {
+	const write = await git_gh_command.issue_apply_label(issue_number, label)
+
+	if (!write.is_applied) console.error(`${label} not applied: ${write.reason}`)
+
+	return write.is_applied
+}
+
+// A closed measurement may be its epic's last child, and no `followup` runs for it — so the epic
+// auto-close is run here, through the one entry every child close takes (`epic-close.ts`).
+async function close_issue(issue_number: string): Promise<boolean> {
+	const is_closed = await git_gh_command.issue_close(issue_number, undefined)
+
+	if (is_closed) await epic_close.close_completed_epics({ issue_number, is_merged: true })
+	else console.error(`Issue ${session_cite.issue(issue_number)} not closed`)
+
+	return is_closed
+}
+
+async function label_and_close(issue_number: string): Promise<boolean> {
+	return (await apply_label(issue_number)) && (await close_issue(issue_number))
+}
+
+// A measurement that fell short carries `measured:unmet` too, put on first: the close is the last write.
+async function mark_unmet_and_close(issue_number: string): Promise<boolean> {
+	return (
+		(await apply_label(issue_number, MEASURED_UNMET_LABEL)) && (await label_and_close(issue_number))
+	)
+}
+
+const COMMAND = 'issue:measured'
+const MEASURED_EXIT: EvidenceExit = { command: COMMAND, finish: label_and_close }
+const MEASURED_UNMET_EXIT: EvidenceExit = { command: COMMAND, finish: mark_unmet_and_close }
+
+// The same writes for evidence composed in process, with no hold of its own to release.
+async function close(issue_number: string, evidence: string): Promise<boolean> {
+	return await issue_evidence_exit.write({ issue_number, evidence }, MEASURED_EXIT)
+}
+
+const issue_measured_close = { MEASURED_EXIT, MEASURED_UNMET_EXIT, close }
+
+export { issue_measured_close }

package/scripts/issue/issue-merged.ts

@@ -1,5 +1,6 @@
 import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { MEASURED_LABEL } from '#scripts/issue/issue-labels'
 
 // Whether an issue was closed by a merge, read from its REST timeline. The
 // issue's own `state_reason` cannot tell: a pull request's `closes #N` and a person's "Close as
@@ -8,9 +9,15 @@ import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 // pull request. A manual "completed" close still reads as merged when a merged pull request also
 // references the issue — the one case the timeline cannot separate — and every other doubt falls to
 // `false`, because a sweep deletes work on this answer.
+//
+// **A measurement-only issue stands in for the merge with its `measured` label**: it changes no code,
+// so no pull request closes it, and `josh issue:measured` labels it before closing it. A completed
+// close while the label is on is the run's own, so every sweep reading this answer agrees on it.
 
 const CLOSED_EVENT = 'closed'
 const REOPENED_EVENT = 'reopened'
+const LABELED_EVENT = 'labeled'
+const UNLABELED_EVENT = 'unlabeled'
 const MERGED_REFERENCE = 'merged-reference'
 // A close by a pull request's `closes #N` carries no reason in the timeline; a person's "Close as
 // completed" carries `completed`. Any other reason — `not_planned`, `duplicate` — is not a merge, and
@@ -19,13 +26,16 @@ const COMPLETED_REASONS: ReadonlySet<string> = new Set(['', 'completed'])
 const FIELD_SEPARATOR = '\t'
 const LINE_SEPARATOR = '\n'
 // One `<event>\t<state_reason>` line per closed/reopened event, and a `merged-reference` line per
-// merged pull request that cross-references the issue — the three kinds the answer reads.
+// merged pull request that cross-references the issue, and a `labeled` / `unlabeled` line per change of
+// the `measured` label — the kinds the answer reads.
 const TIMELINE_FILTER = [
 	'.[]',
 	'| if .event == "cross-referenced" and .source.issue.pull_request.merged_at != null',
 	String.raw`then "${MERGED_REFERENCE}\t"`,
 	`elif .event == "${CLOSED_EVENT}" or .event == "${REOPENED_EVENT}"`,
 	String.raw`then "\(.event)\t\(.state_reason // "")"`,
+	`elif (.event == "${LABELED_EVENT}" or .event == "${UNLABELED_EVENT}") and .label.name == "${MEASURED_LABEL}"`,
+	String.raw`then "\(.event)\t"`,
 	'else empty end',
 ].join(' ')
 
@@ -45,6 +55,13 @@ function parse_rows(raw: string): Array<TimelineRow> {
 		})
 }
 
+// The last `labeled` / `unlabeled` event of the `measured` label is whether it is on now.
+function is_measured(rows: ReadonlyArray<TimelineRow>): boolean {
+	const last = rows.findLast((row) => row.event === LABELED_EVENT || row.event === UNLABELED_EVENT)
+
+	return last?.event === LABELED_EVENT
+}
+
 // The last closed/reopened event is the issue's current state, so a reopened issue is not merged
 // even with a merged reference from an earlier attempt.
 function is_merged_close(rows: ReadonlyArray<TimelineRow>): boolean {
@@ -52,7 +69,7 @@ function is_merged_close(rows: ReadonlyArray<TimelineRow>): boolean {
 
 	if (last?.event !== CLOSED_EVENT || !COMPLETED_REASONS.has(last.reason)) return false
 
-	return rows.some((row) => row.event === MERGED_REFERENCE)
+	return is_measured(rows) || rows.some((row) => row.event === MERGED_REFERENCE)
 }
 
 // `undefined` when the timeline could not be read, so a caller that keeps the answer can tell "not

package/scripts/issue/issue-not-before-label.ts

@@ -0,0 +1,135 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { epic_issue_schema } from '#scripts/git/git-schemas'
+import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
+import { error_text } from '#scripts/lib/error-message'
+import { has_label_name, NOT_BEFORE_LABEL, REPOSITORY_LABELS } from './issue-labels'
+import { issue_not_before } from './issue-not-before'
+import { issue_sample_prime } from './issue-sample-prime'
+import { session_cite } from './session-cite'
+
+// joshuafolkken/kit#4079: the body's start-time declaration held an issue back from `backlog:next`,
+// but neither the issue listing nor `run:board` showed it waited on the clock. `not-before` is a copy
+// of that declaration, kept here alone: the body stays the source, and this module is the one place
+// that decides whether the copy is owed.
+
+type LabelChange = 'add' | 'remove'
+
+// One issue as the listings return it; `labels` may be absent.
+interface LabelledIssue {
+	number: number
+	body?: string | undefined
+	labels?: ReadonlyArray<{ name: string }> | undefined
+}
+
+const DEFINITION = REPOSITORY_LABELS.find((label) => label.name === NOT_BEFORE_LABEL)
+const NOT_APPLIED = 'the label was not applied'
+const LABELLED_LIMIT = 200
+
+function is_waiting(body: string | undefined, now: number): boolean {
+	return !issue_not_before.is_due(body, now)
+}
+
+// What the label owes one issue: `add` while the declared time is ahead and the label is absent,
+// `remove` once the time has passed or the declaration is gone, else nothing.
+function change_of(
+	body: string | undefined,
+	labels: ReadonlyArray<string>,
+	now: number = Date.now(),
+): LabelChange | undefined {
+	const is_labelled = has_label_name(labels, NOT_BEFORE_LABEL)
+
+	if (is_waiting(body, now) === is_labelled) return undefined
+
+	return is_labelled ? 'remove' : 'add'
+}
+
+// The labels a new issue is filed with — the label added when its body declares a time still ahead.
+function with_label(
+	labels: ReadonlyArray<string>,
+	body: string,
+	now: number = Date.now(),
+): ReadonlyArray<string> {
+	return change_of(body, labels, now) === 'add' ? [...labels, NOT_BEFORE_LABEL] : labels
+}
+
+function changes_of(
+	issues: ReadonlyArray<LabelledIssue>,
+	now: number,
+): ReadonlyArray<readonly [LabelledIssue, LabelChange]> {
+	return issues.flatMap(function change(issue): Array<readonly [LabelledIssue, LabelChange]> {
+		const names = (issue.labels ?? []).map((label) => label.name)
+		const owed = change_of(issue.body, names, now)
+
+		return owed === undefined ? [] : [[issue, owed]]
+	})
+}
+
+// The addition answers `false` where the removal throws; both fail here the same way.
+async function write(number: string, owed: LabelChange): Promise<void> {
+	if (owed === 'remove') {
+		await git_gh_issue_write.issue_remove_label(number, NOT_BEFORE_LABEL)
+
+		return
+	}
+
+	if (!(await git_gh_issue_write.issue_add_label(number, NOT_BEFORE_LABEL))) {
+		throw new Error(NOT_APPLIED)
+	}
+}
+
+// A failed write is named and left: the next scan owes the same change and makes it then.
+async function apply(issue: LabelledIssue, owed: LabelChange): Promise<void> {
+	try {
+		await write(String(issue.number), owed)
+	} catch (error) {
+		const cited = session_cite.issue(issue.number)
+
+		console.warn(
+			`${cited}: could not ${owed} \`${NOT_BEFORE_LABEL}\`: ${error_text.message_of(error)}`,
+		)
+	}
+}
+
+// Brings every issue's label in line with its body. The label is created before the first addition,
+// so it carries its color and description rather than the ones GitHub generates for a missing label.
+async function sync(issues: ReadonlyArray<LabelledIssue>, now: number = Date.now()): Promise<void> {
+	const changes = changes_of(issues, now)
+
+	if (DEFINITION !== undefined && changes.some(([, owed]) => owed === 'add')) {
+		await git_gh_issue_write.label_ensure(DEFINITION)
+	}
+
+	await Promise.all(
+		changes.map(async ([issue, owed]) => {
+			await apply(issue, owed)
+		}),
+	)
+}
+
+// Every open issue already carrying the label. A failed read is an empty list: the next scan reads it
+// again.
+async function read_labelled(): Promise<ReadonlyArray<LabelledIssue>> {
+	const { json } = await git_gh_command.issue_list_by_label(NOT_BEFORE_LABEL, LABELLED_LIMIT)
+	const rows =
+		json === undefined ? undefined : parse_json_array_or_undefined(json, epic_issue_schema)
+
+	return (rows ?? []).map((row) => ({ ...row, labels: [{ name: NOT_BEFORE_LABEL }] }))
+}
+
+// `sync` over the scanned issues plus every issue the label is on. `issue:file` labels a filing that
+// may never be scanned — one never opted in — so only the label's own listing reaches it to remove it.
+async function sweep(
+	scanned: ReadonlyArray<LabelledIssue>,
+	now: number = Date.now(),
+): Promise<void> {
+	const seen = new Set(scanned.map((issue) => issue.number))
+	const labelled = await read_labelled()
+
+	await issue_sample_prime.prime(labelled.map((issue) => issue.body))
+	await sync([...scanned, ...labelled.filter((issue) => !seen.has(issue.number))], now)
+}
+
+const issue_not_before_label = { change_of, sweep, sync, with_label }
+
+export { issue_not_before_label }

package/scripts/issue/issue-not-before.ts

@@ -0,0 +1,114 @@
+import { issue_sample_gate } from './issue-sample-gate'
+import { markdown_section } from './markdown-section'
+
+// joshuafolkken/kit#4007: a follow-up measurement filed with `auto-ok` ("measure three days after #N
+// merges") was offered by `backlog:next` the day it was filed, and its lane could only hand the hold
+// back. The body now names the earliest time the work can start, and the pickup holds the issue until
+// then. One UTC spelling only — a date a reader has to guess the zone of is not a deadline.
+// A body may instead wait on samples recorded after a pull request merged (`issue-sample-gate.ts`);
+// this module answers for both, so every reader holds an issue back the same way.
+
+const BACKGROUND_HEADING = '## 背景'
+const PREFIX = '- 実施可能日:'
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}Z$/u
+// What `toISOString` writes after the minutes the declaration spells.
+const ISO_TAIL = ':00.000Z'
+// The refusal ends in a line ready to paste (joshuafolkken/kit#5225); a far-future date, so the
+// example never reads as already due.
+const EXAMPLE = `${PREFIX} 2099-01-01T09:00Z`
+const MALFORMED = `\`${PREFIX}\` must be a UTC time written YYYY-MM-DDTHH:MMZ\n${EXAMPLE}`
+const HEADING_MARKS = /^#{1,6}\s+/u
+// joshuafolkken/kit#4438: a start condition written as its own heading is never read — every reader
+// sees only the declaration line under the background heading — so the issue is offered at once.
+const STRAY_HEADINGS = [
+	{ name: '実施可能日', declaration: `${PREFIX} YYYY-MM-DDTHH:MMZ` },
+	{ name: '実施可能条件', declaration: issue_sample_gate.DECLARATION },
+]
+
+// The value after the declaration under the background heading, or `undefined` when the body declares none.
+function declared_value(body: string): string | undefined {
+	const background = markdown_section.section_lines(body, BACKGROUND_HEADING).join('\n')
+	const line = markdown_section
+		.unfenced_lines(background)
+		.map((text) => text.trim())
+		.find((text) => text.startsWith(PREFIX))
+
+	return line?.slice(PREFIX.length).trim()
+}
+
+// The round trip refuses a calendar-impossible value (`2026-02-30T09:30Z`, `T24:00Z`) that
+// `Date.parse` silently rolls over into a different time.
+function is_valid(value: string): boolean {
+	if (!DATE_PATTERN.test(value)) return false
+
+	const time = Date.parse(value)
+
+	return !Number.isNaN(time) && new Date(time).toISOString() === `${value.slice(0, -1)}${ISO_TAIL}`
+}
+
+// The declared time, or `undefined` when there is none or it does not parse. A malformed date reads as
+// absent: `issue:file` refuses it, and holding a hand-edited one forever would lose the issue silently.
+function date_of(body = ''): string | undefined {
+	const value = declared_value(body)
+
+	return value !== undefined && is_valid(value) ? value : undefined
+}
+
+function is_date_due(body: string | undefined, now: number): boolean {
+	const date = date_of(body)
+
+	return date === undefined || Date.parse(date) <= now
+}
+
+// Whether the issue may start: its declared time has arrived and its declared samples are recorded.
+function is_due(body: string | undefined, now: number = Date.now()): boolean {
+	return is_date_due(body, now) && issue_sample_gate.wait_of(body) === undefined
+}
+
+// The declared time as epoch milliseconds while it is still ahead, or `undefined` when it has arrived —
+// for a reader that spells the time its own way (`run:board` in the local zone).
+function waiting_ms(body: string | undefined, now: number = Date.now()): number | undefined {
+	if (is_date_due(body, now)) return undefined
+
+	return Date.parse(String(date_of(body)))
+}
+
+// The declared time as written while it is still ahead, or `undefined` when it has arrived.
+function waiting_date(body: string | undefined, now: number = Date.now()): string | undefined {
+	return is_date_due(body, now) ? undefined : date_of(body)
+}
+
+// Why `backlog:next` holds an issue back, or `undefined` when it is due. The caller cites the issue.
+function waiting_reason(body: string | undefined, now: number = Date.now()): string | undefined {
+	const date = waiting_date(body, now)
+
+	if (date !== undefined) return `not before ${date}`
+
+	const wait = issue_sample_gate.wait_of(body)
+
+	return wait === undefined ? undefined : issue_sample_gate.reason_of(wait)
+}
+
+function stray_heading_problems(body: string): ReadonlyArray<string> {
+	const headings = markdown_section
+		.unfenced_lines(body)
+		.map((line) => line.trim())
+		.filter((line) => HEADING_MARKS.test(line))
+		.map((line) => line.replace(HEADING_MARKS, ''))
+
+	return STRAY_HEADINGS.filter(({ name }) => headings.some((text) => text.startsWith(name))).map(
+		({ name, declaration }) =>
+			`heading \`${name}\` is not read — declare it under \`${BACKGROUND_HEADING}\` as \`${declaration}\``,
+	)
+}
+
+function problems(body: string): ReadonlyArray<string> {
+	const value = declared_value(body)
+	const date_problems = value === undefined || is_valid(value) ? [] : [MALFORMED]
+
+	return [...stray_heading_problems(body), ...date_problems, ...issue_sample_gate.problems(body)]
+}
+
+const issue_not_before = { is_due, problems, waiting_date, waiting_ms, waiting_reason }
+
+export { issue_not_before }

package/scripts/issue/issue-number-shape.ts

@@ -22,6 +22,20 @@ function require_issue_number(issue: string): void {
 	if (!is_issue_number(issue)) throw new Error(`${BAD_ISSUE_MESSAGE}${issue}`)
 }
 
-const issue_number_shape = { ISSUE_NUMBER_PATTERN, is_issue_number, require_issue_number }
+// A command whose one positional is the issue it writes to: a missing, malformed or second number
+// answers `undefined`, so the caller refuses the whole call rather than writing to some other issue.
+function single_of(positionals: ReadonlyArray<string>): string | undefined {
+	const [issue_number, ...rest] = positionals
+	const is_single = rest.length === 0 && issue_number !== undefined
+
+	return is_single && ISSUE_NUMBER_PATTERN.test(issue_number) ? issue_number : undefined
+}
+
+const issue_number_shape = {
+	ISSUE_NUMBER_PATTERN,
+	is_issue_number,
+	require_issue_number,
+	single_of,
+}
 
 export { issue_number_shape }

package/scripts/issue/issue-park.ts

@@ -0,0 +1,28 @@
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+
+// A park on GitHub: the label that keeps an issue from being offered again, and the comment that says
+// why. `run:park` (a lane child's `needs-decision`), `run:merge` and the ship relaunch cap (both
+// `run:stalled`) park the same way, so the pair is written once here (joshuafolkken/kit#4132).
+//
+// **The label goes first and the comment only on it.** The label is what every offer reads; a comment
+// on an issue whose label failed would explain a park that did not happen.
+
+interface ParkWrite {
+	is_labelled: boolean
+	is_commented: boolean
+}
+
+async function apply(issue: string, label: string, body: string): Promise<ParkWrite> {
+	const is_labelled = await git_gh_issue_write.issue_add_label(issue, label)
+
+	if (!is_labelled) return { is_labelled, is_commented: false }
+
+	const is_commented = await git_gh_issue_write.issue_try_comment(issue, body)
+
+	return { is_labelled, is_commented }
+}
+
+const issue_park = { apply }
+
+export type { ParkWrite }
+export { issue_park }

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

@@ -0,0 +1,151 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_body_or_comment } from '#scripts/issue/issue-body-or-comment'
+import { PLANNED_LABEL } from '#scripts/issue/issue-labels'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { plan_consumers_section } from '#scripts/issue/plan-consumers-section'
+import { cli_body } from '#scripts/josh/cli-body'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { error_text } from '#scripts/lib/error-message'
+
+// `josh issue:plan <N> --body-file <path> [--title <title>] [--planned]` — record a plan on an issue
+// in one call: the title normalized, the plan written into a blank body or posted as a comment, and
+// `run:planned` applied.
+//
+// **`kickoff` and `fullrun` spelled those three writes out by hand** — a `gh api -X PATCH` for the
+// title, a second one for a blank body or `issue:comment` otherwise, and a third `gh api` for the
+// label — so the blank-body decision lived in three documents. It now lives in
+// `issue-body-or-comment.ts`, which `followup`'s completion notice shares.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const USAGE =
+	'Usage: josh issue:plan <issue-number> --body-file <path> [--title <title>] [--planned] [--repo <owner/name>]'
+
+interface PlanRequest {
+	issue_number: string
+	plan: string
+	title: string | undefined
+	is_planned: boolean
+	repo: string | undefined
+}
+
+const OPTIONS = {
+	'body-file': { type: 'string' },
+	title: { type: 'string' },
+	planned: { type: 'boolean' },
+	repo: { type: 'string' },
+} as const
+
+// The plan is read last, from the path the flags named; an empty plan refuses like a missing one. A
+// plan without its existing-consumers section throws its refusal, printed as-is like a read failure,
+// before any write (`plan-consumers-section.ts`).
+function with_plan(
+	flags: Omit<PlanRequest, 'plan'>,
+	file_path: string | undefined,
+): PlanRequest | undefined {
+	if (file_path === undefined) return undefined
+	const plan = cli_body.read_file_or_stdin(file_path)
+
+	if (plan.trim().length === 0) return undefined
+	const refusal = plan_consumers_section.refusal_of(plan)
+
+	if (refusal !== undefined) throw new Error(refusal)
+
+	return { ...flags, plan }
+}
+
+// An optional string flag, trimmed; given blank it is `''`, which the caller refuses.
+function trimmed(value: string | undefined): string | undefined {
+	return value?.trim()
+}
+
+// A `--title` or `--repo` given blank refuses rather than being dropped: the caller meant to rename
+// the issue, or to address another repository's — a dropped `--repo` would write to this one's.
+function parse_request(argv: ReadonlyArray<string>): PlanRequest | undefined {
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+
+	if (parsed === undefined) return undefined
+	const issue_number = issue_number_shape.single_of(parsed.positionals)
+	const [title, repo] = [trimmed(parsed.values.title), trimmed(parsed.values.repo)]
+
+	if (issue_number === undefined || [title, repo].includes('')) return undefined
+	const is_planned = parsed.values.planned === true
+
+	return with_plan({ issue_number, title, is_planned, repo }, parsed.values['body-file'])
+}
+
+// A file-read failure surfaces as an `Error` naming the resolved path, printed as-is; `undefined` is
+// a malformed call, which `USAGE` explains.
+function resolve_request(argv: ReadonlyArray<string>): PlanRequest | undefined {
+	try {
+		const request = parse_request(argv)
+
+		if (request === undefined) console.error(USAGE)
+
+		return request
+	} catch (error) {
+		console.error(error_text.message_of(error))
+
+		return undefined
+	}
+}
+
+// The title goes first, so the plan and the label land on an issue already carrying the name the
+// plan was written under; the label goes last, so `run:planned` never marks an issue whose plan
+// failed to post.
+async function apply_planned_label(issue_number: string, repo?: string): Promise<boolean> {
+	const is_applied = await git_gh_command.issue_add_label(issue_number, PLANNED_LABEL, repo)
+
+	if (is_applied) console.info(`label: ${PLANNED_LABEL}`)
+	else console.error(`Could not apply ${PLANNED_LABEL} to issue ${issue_number}.`)
+
+	return is_applied
+}
+
+// `--repo` addresses every write — the title, the plan and the label — so `kickoff kit#<N>` run from
+// another checkout records the plan on the named repository's issue, never on this one's.
+async function record_plan(request: PlanRequest): Promise<boolean> {
+	const { issue_number, title, repo } = request
+
+	if (title !== undefined) {
+		console.info(`title: ${await git_gh_command.issue_edit_title(issue_number, title, repo)}`)
+	}
+
+	const posted = await issue_body_or_comment.post(issue_number, request.plan, repo)
+
+	console.info(`${posted.destination}: ${posted.url}`)
+
+	return request.is_planned ? await apply_planned_label(issue_number, repo) : true
+}
+
+// A refused write prints as one line, like a file-read failure, rather than escaping as a stack trace.
+async function try_record_plan(request: PlanRequest): Promise<boolean> {
+	try {
+		return await record_plan(request)
+	} catch (error) {
+		console.error(error_text.message_of(error))
+
+		return false
+	}
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const request = resolve_request(argv)
+
+	if (request === undefined) return FAILURE_EXIT_CODE
+
+	return (await try_record_plan(request)) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const issue_plan_cli = { USAGE, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_plan_cli }