@joshuafolkken/kit 1.872.0

package/scripts-ai/epic-cli-remove.ts

@@ -0,0 +1,71 @@
+import { epic_cli_argv, ISSUE_NUMBER_PATTERN } from './epic-cli-argv'
+
+// `josh epic --remove <E> <M> <N> …`'s argument rules (joshuafolkken/kit#1712).
+//
+// Its own module rather than a fourth parser inside `epic-cli.ts`, which sits at its line ceiling —
+// and because the rules read as one thing: the arguments after the epic are a **path**, which is the
+// one place this command departs from every other form's bare set of child numbers.
+
+const REMOVE_FLAG = '--remove'
+const DECISION_FLAG = '--decision-file'
+// `--remove` takes no positioning flag: there is nothing for a removal to be relative to, and the
+// path itself says which orders go.
+const REMOVE_VALUE_FLAGS: ReadonlySet<string> = new Set([DECISION_FLAG])
+const REMOVE_KNOWN_FLAGS: ReadonlySet<string> = new Set([REMOVE_FLAG, DECISION_FLAG])
+// The shortest path that names an order at all: `<M> <N>`.
+const MINIMUM_PATH_LENGTH = 2
+
+interface RemoveArguments {
+	epic_number: number
+	path: Array<number>
+	decision_path?: string | undefined
+}
+
+// Whether the invocation deletes a declared order rather than creating, promoting or inserting.
+function is_removal(argv: ReadonlyArray<string>): boolean {
+	return argv.includes(REMOVE_FLAG)
+}
+
+// **Not deduplicated, and a non-number refuses the whole path** — unlike a child list, which is a
+// set. The path is a sequence, so its order and its repeats are what the caller said: dropping a
+// repeat would silently delete a different set of orders than the one typed, and skipping an
+// unparsable argument would shift every pair after it.
+function to_path_numbers(raw_path: ReadonlyArray<string>): Array<number> | undefined {
+	if (raw_path.some((raw) => !ISSUE_NUMBER_PATTERN.test(raw))) return undefined
+
+	return raw_path.length < MINIMUM_PATH_LENGTH ? undefined : raw_path.map(Number)
+}
+
+// A flag that makes the whole invocation unreadable, whatever the positional arguments say.
+function has_flag_refusal(argv: ReadonlyArray<string>): boolean {
+	return (
+		epic_cli_argv.has_unknown_flag(argv, REMOVE_KNOWN_FLAGS) ||
+		epic_cli_argv.is_value_unusable(argv, DECISION_FLAG)
+	)
+}
+
+function read_subject(
+	argv: ReadonlyArray<string>,
+): { epic_number: number; path: Array<number> } | undefined {
+	const [raw_epic, ...raw_path] = epic_cli_argv.to_positional_arguments(argv, REMOVE_VALUE_FLAGS)
+	if (raw_epic === undefined || !ISSUE_NUMBER_PATTERN.test(raw_epic)) return undefined
+	const path = to_path_numbers(raw_path)
+
+	return path === undefined ? undefined : { epic_number: Number(raw_epic), path }
+}
+
+function parse_remove_arguments(argv: ReadonlyArray<string>): RemoveArguments | undefined {
+	if (has_flag_refusal(argv)) return undefined
+	const subject = read_subject(argv)
+	if (subject === undefined) return undefined
+
+	return { ...subject, decision_path: epic_cli_argv.read_flag_value(argv, DECISION_FLAG) }
+}
+
+const epic_cli_remove = {
+	is_removal,
+	parse_remove_arguments,
+}
+
+export { epic_cli_remove, REMOVE_FLAG }
+export type { RemoveArguments }

package/scripts-ai/epic-cli.ts

@@ -0,0 +1,413 @@
+import type { InsertKind, InsertPosition } from '../scripts/git/git-epic-chains'
+import { git_epic_parse, type ExternalChild } from '../scripts/git/git-epic-parse'
+import { cli_body } from '../scripts/josh/cli-body'
+import { epic_cli_argv, ISSUE_NUMBER_PATTERN } from './epic-cli-argv'
+import { epic_cli_remove } from './epic-cli-remove'
+
+// Parsing lives apart from the entry point so the argument rules can be asserted without spawning a
+// process or reaching GitHub. The entry point is then a thin shell around these two functions.
+
+const ORDERED_FLAG = '--ordered'
+const RATIONALE_FLAG = '--rationale-file'
+const ORIGIN_FLAG = '--origin'
+const PROMOTE_FLAG = '--promote'
+const ADD_FLAG = '--add'
+// `--reconcile <E>`: bring the epic's declaration and its recorded relations back into agreement
+// (joshuafolkken/kit#2235). It takes no value flags — the epic number is the whole subject.
+const RECONCILE_FLAG = '--reconcile'
+const BEFORE_FLAG = '--before'
+const AFTER_FLAG = '--after'
+// The same two places with the declaration withheld: move the task-list row and write neither the
+// dependency declaration nor the `blocked-by` relation (joshuafolkken/kit#1738). They exist because
+// `epic:next` offers children in task-list order, so "no dependency, but run this one first" had no
+// spelling at all — only a false dependency, or a row nobody would reach.
+const ORDER_BEFORE_FLAG = '--order-before'
+const ORDER_AFTER_FLAG = '--order-after'
+// The decision record for an insertion, read the same way `--rationale-file` is read for a creation:
+// from a file, or from stdin as `-`. The text is a judgement, so the caller writes it; what the command
+// contributes is placing it in the epic's `## Decisions` and on each child (joshuafolkken/kit#1350).
+const DECISION_FLAG = '--decision-file'
+// Which flags consume the argument after them — per parser, for the reason `epic-cli-argv.ts` gives.
+const VALUE_FLAGS: ReadonlySet<string> = new Set([RATIONALE_FLAG, ORIGIN_FLAG])
+const ADD_VALUE_FLAGS: ReadonlySet<string> = new Set([
+	BEFORE_FLAG,
+	AFTER_FLAG,
+	ORDER_BEFORE_FLAG,
+	ORDER_AFTER_FLAG,
+	DECISION_FLAG,
+])
+const ADD_KNOWN_FLAGS: ReadonlySet<string> = new Set([
+	ADD_FLAG,
+	BEFORE_FLAG,
+	AFTER_FLAG,
+	ORDER_BEFORE_FLAG,
+	ORDER_AFTER_FLAG,
+	DECISION_FLAG,
+])
+
+const { count_flag, is_value_unusable, read_flag_value } = epic_cli_argv
+
+interface CreateArguments {
+	title: string
+	children: Array<number>
+	is_ordered: boolean
+	rationale_path?: string | undefined
+	origin?: string | undefined
+}
+
+// `--promote <N> <N1> <N2> …`: the issue to promote, then its children. No title — the issue already
+// has one, and the discussion in it is usually the split rationale (joshuafolkken/kit#865).
+interface PromoteArguments {
+	epic_number: number
+	children: Array<number>
+	is_ordered: boolean
+	rationale_path?: string | undefined
+	origin?: string | undefined
+}
+
+function to_positional_arguments(
+	argv: ReadonlyArray<string>,
+	value_flags: ReadonlySet<string> = VALUE_FLAGS,
+): Array<string> {
+	return epic_cli_argv.to_positional_arguments(argv, value_flags)
+}
+
+// Deduplicated because a repeated number would render a duplicate task-list row, and with
+// `--ordered` would ask GitHub to make an issue block itself.
+function to_child_numbers(raw_children: ReadonlyArray<string>): Array<number> {
+	const numbers = raw_children
+		.filter((raw) => ISSUE_NUMBER_PATTERN.test(raw))
+		.map(Number)
+		.filter((value) => Number.isSafeInteger(value))
+
+	return [...new Set(numbers)]
+}
+
+// The title comes first so the children can stay a bare list of numbers, which is how they are
+// written down when the split is made.
+function parse_create_arguments(argv: ReadonlyArray<string>): CreateArguments | undefined {
+	const [title, ...raw_children] = to_positional_arguments(argv)
+	if (title === undefined || title.length === 0) return undefined
+
+	const children = to_child_numbers(raw_children)
+	if (children.length === 0) return undefined
+
+	return {
+		title,
+		children,
+		is_ordered: argv.includes(ORDERED_FLAG),
+		rationale_path: read_flag_value(argv, RATIONALE_FLAG),
+		origin: read_flag_value(argv, ORIGIN_FLAG),
+	}
+}
+
+// Whether the invocation is a promotion rather than a creation.
+function is_promotion(argv: ReadonlyArray<string>): boolean {
+	return argv.includes(PROMOTE_FLAG)
+}
+
+// Whether the invocation reconciles an epic rather than creating, promoting or editing one.
+function is_reconciliation(argv: ReadonlyArray<string>): boolean {
+	return argv.includes(RECONCILE_FLAG)
+}
+
+interface ReconcileArguments {
+	epic_number: number
+}
+
+// The epic to reconcile. The number after `--reconcile` is the only subject; there are no children
+// and no position — the repair reads what the epic already records rather than being told an order.
+function parse_reconcile_arguments(argv: ReadonlyArray<string>): ReconcileArguments | undefined {
+	const [raw_epic] = to_positional_arguments(argv)
+	if (raw_epic === undefined || !ISSUE_NUMBER_PATTERN.test(raw_epic)) return undefined
+
+	return { epic_number: Number(raw_epic) }
+}
+
+// The promoted issue and its children. The number after `--promote` is the epic; everything else
+// positional is a child. Refused when the epic would also be listed as its own child, which would
+// have it block itself under `--ordered`.
+function parse_promote_arguments(argv: ReadonlyArray<string>): PromoteArguments | undefined {
+	const [raw_epic, ...raw_children] = to_positional_arguments(argv)
+	if (raw_epic === undefined || !ISSUE_NUMBER_PATTERN.test(raw_epic)) return undefined
+	const epic_number = Number(raw_epic)
+	const children = to_child_numbers(raw_children).filter((child) => child !== epic_number)
+	if (children.length === 0) return undefined
+
+	return {
+		epic_number,
+		children,
+		is_ordered: argv.includes(ORDERED_FLAG),
+		rationale_path: read_flag_value(argv, RATIONALE_FLAG),
+		origin: read_flag_value(argv, ORIGIN_FLAG),
+	}
+}
+
+// `--add <E> <N...> [--before <M> | --after <M> | --order-before <M> | --order-after <M>]`: the epic
+// to insert into, then the children. The epic comes first for the same reason it does under
+// `--promote`, so the children stay a bare list of numbers (joshuafolkken/kit#890).
+interface AddArguments {
+	epic_number: number
+	children: Array<number>
+	position?: InsertPosition | undefined
+	// `--order-before` / `--order-after` rather than `--before` / `--after`: the row moves and nothing
+	// else is written (joshuafolkken/kit#1738).
+	is_order_only?: boolean | undefined
+	decision_path?: string | undefined
+}
+
+// Whether the invocation inserts into an existing epic rather than creating or promoting one.
+function is_addition(argv: ReadonlyArray<string>): boolean {
+	return argv.includes(ADD_FLAG)
+}
+
+// The outcome of reading a positioning flag: the position, nothing, or a refusal. One shape for all
+// three so the caller branches on a field rather than on a value's type. `is_order_only` rides on the
+// same value because one flag decides both halves — where the row goes, and whether a dependency is
+// written behind it (joshuafolkken/kit#1738).
+interface PositionOutcome {
+	position?: InsertPosition
+	is_order_only?: boolean
+	is_refused: boolean
+}
+
+const NO_POSITION: PositionOutcome = { is_refused: false }
+const REFUSED_POSITION: PositionOutcome = { is_refused: true }
+
+// The four positioning flags as one table: the place each one names, and whether a dependency is
+// written behind the row it moves. **One table rather than two branches** (joshuafolkken/kit#1738) —
+// `--order-before` asks the same placement question `--before` does, so a second parsing path could
+// come to disagree with this one about what a repeated flag or a non-numeric target means.
+interface PositionFlag {
+	flag: string
+	kind: InsertKind
+	is_order_only: boolean
+}
+
+const POSITION_FLAGS: ReadonlyArray<PositionFlag> = [
+	{ flag: BEFORE_FLAG, kind: 'before', is_order_only: false },
+	{ flag: AFTER_FLAG, kind: 'after', is_order_only: false },
+	{ flag: ORDER_BEFORE_FLAG, kind: 'before', is_order_only: true },
+	{ flag: ORDER_AFTER_FLAG, kind: 'after', is_order_only: true },
+]
+
+// More than one positioning flag names more than one place, whether they are the same flag twice, one
+// of each direction, or a dependency-writing flag beside an order-only one. `read_flag_value` would
+// answer with the first, which is a silent choice rather than a refusal — and here the silent choice
+// would decide whether a `blocked-by` is written at all.
+function is_position_ambiguous(argv: ReadonlyArray<string>): boolean {
+	return POSITION_FLAGS.reduce((total, entry) => total + count_flag(argv, entry.flag), 0) > 1
+}
+
+interface PositionTarget extends PositionFlag {
+	raw: string
+}
+
+function to_position_target(
+	argv: ReadonlyArray<string>,
+	entry: PositionFlag,
+): PositionTarget | undefined {
+	const raw = read_flag_value(argv, entry.flag)
+
+	return raw === undefined ? undefined : { ...entry, raw }
+}
+
+function read_position_target(argv: ReadonlyArray<string>): PositionTarget | undefined {
+	if (is_position_ambiguous(argv)) return undefined
+
+	return POSITION_FLAGS.map((entry) => to_position_target(argv, entry)).find(
+		(found) => found !== undefined,
+	)
+}
+
+// A target that is not an issue number is refused for the same reason two flags are: guessing would
+// insert somewhere.
+function parse_position(argv: ReadonlyArray<string>): PositionOutcome {
+	const has_flag = POSITION_FLAGS.some((entry) => argv.includes(entry.flag))
+	const target = read_position_target(argv)
+	if (target === undefined) return has_flag ? REFUSED_POSITION : NO_POSITION
+	if (!ISSUE_NUMBER_PATTERN.test(target.raw)) return REFUSED_POSITION
+
+	return {
+		position: { kind: target.kind, target: Number(target.raw) },
+		is_order_only: target.is_order_only,
+		is_refused: false,
+	}
+}
+
+function has_unknown_flag(argv: ReadonlyArray<string>): boolean {
+	return epic_cli_argv.has_unknown_flag(argv, ADD_KNOWN_FLAGS)
+}
+
+// Whether *this* is why the insertion could not be read, so the refusal can say so. Without it the
+// caller prints the generic requirements line, and a shell that expanded `--decision-file $REC` to
+// nothing is answered with "an epic number and at least one child issue number are required" — advice
+// about the part the person got right.
+function is_decision_path_unusable(argv: ReadonlyArray<string>): boolean {
+	return is_value_unusable(argv, DECISION_FLAG)
+}
+
+function read_add_subject(
+	argv: ReadonlyArray<string>,
+): { epic_number: number; children: Array<number> } | undefined {
+	const [raw_epic, ...raw_children] = to_positional_arguments(argv, ADD_VALUE_FLAGS)
+	if (raw_epic === undefined || !ISSUE_NUMBER_PATTERN.test(raw_epic)) return undefined
+	const epic_number = Number(raw_epic)
+	const children = to_child_numbers(raw_children).filter((child) => child !== epic_number)
+
+	return children.length === 0 ? undefined : { epic_number, children }
+}
+
+function parse_add_arguments(argv: ReadonlyArray<string>): AddArguments | undefined {
+	if (has_unknown_flag(argv) || is_decision_path_unusable(argv)) return undefined
+	const subject = read_add_subject(argv)
+	if (subject === undefined) return undefined
+	const outcome = parse_position(argv)
+	if (outcome.is_refused) return undefined
+
+	return {
+		...subject,
+		position: outcome.position,
+		is_order_only: outcome.is_order_only,
+		decision_path: read_flag_value(argv, DECISION_FLAG),
+	}
+}
+
+// The one refusal `--add` has to explain rather than merely report. `into owner/repo#N` is a legal
+// thing for a person to type, and this command cannot serve it: it reads and edits issues in the
+// repository it is run from. Falling through to the usage line would read as "that form does not
+// exist" when what it means is "run it in the other checkout" (joshuafolkken/kit#985).
+interface CrossRepoAddTarget {
+	epic: ExternalChild
+	local: AddArguments
+}
+
+// The same invocation with the cross-repository target replaced by its bare number. Answering only
+// when *that* parses is what keeps the suggestion honest: an invocation wrong in some other way — a
+// mistyped positioning flag, no children, a `--before` naming two places — is not a repository
+// problem, and
+// a suggestion built from it would drop or mangle what the person typed.
+function find_cross_repo_add_target(argv: ReadonlyArray<string>): CrossRepoAddTarget | undefined {
+	const [raw_epic] = to_positional_arguments(argv, ADD_VALUE_FLAGS)
+	if (raw_epic === undefined) return undefined
+	const epic = git_epic_parse.parse_external_reference(raw_epic)
+	if (epic === undefined) return undefined
+
+	const local = parse_add_arguments(
+		argv.map((argument) => (argument === raw_epic ? String(epic.number) : argument)),
+	)
+
+	return local === undefined ? undefined : { epic, local }
+}
+
+// Rebuilt from the parsed values rather than echoed from `argv`, so the suggested command is exactly
+// what the other checkout would read — and carries the position, which is the one part of the
+// instruction the epic itself does not record.
+function format_add_arguments(local: AddArguments): string {
+	const { position } = local
+	// The order-only prefix rides along, since it is what decides whether the other checkout writes a
+	// dependency — a suggestion that dropped it would be a different instruction (joshuafolkken/kit#1738).
+	const prefix = local.is_order_only === true ? '--order-' : '--'
+	const suffix =
+		position === undefined ? '' : ` ${prefix}${position.kind} ${String(position.target)}`
+
+	return `${[local.epic_number, ...local.children].map(String).join(' ')}${suffix}`
+}
+
+// **`--decision-file` is named rather than relayed** (joshuafolkken/kit#1350). The suggestion is a
+// command to run in a *different* checkout, and the path was resolved against this one: a relative path
+// does not exist there, `-` cannot be re-read from a consumed stdin, and an unquoted path with a space
+// would break the line the person copies. So the flag is asked for again instead of pasted in wrong.
+function format_decision_note(local: AddArguments): Array<string> {
+	if (local.decision_path === undefined) return []
+
+	return [
+		`  The decision record is not carried over — pass \`${DECISION_FLAG}\` there with a path that checkout can read.`,
+	]
+}
+
+// A fully-qualified reference to *this* repository is the same instruction spelled longer, not a
+// cross-repository one — and `into owner/repo#N` is exactly how the suffix is documented, so a run
+// inside that repository would otherwise be refused and told to go to the checkout it is already in
+// (joshuafolkken/kit#985). An unreadable current repository resolves to a refusal rather than to a
+// write: refusing costs one command, and guessing wrong writes into the wrong epic.
+function resolve_local_add(
+	found: CrossRepoAddTarget,
+	current_repo: string | undefined,
+): AddArguments | undefined {
+	return current_repo === found.epic.repo ? found.local : undefined
+}
+
+// What to type instead. `josh doctor` prints the checkout for each repository, which is the part a
+// run cannot guess.
+function format_cross_repo_refusal(found: CrossRepoAddTarget): string {
+	const reference = `${found.epic.repo}#${String(found.epic.number)}`
+
+	return [
+		`✖ ${reference} is an epic in another repository; this command reads and writes issues in the repository it runs from.`,
+		`  Run \`pnpm josh epic --add ${format_add_arguments(found.local)}\` in that repository's checkout (\`pnpm josh doctor\` prints where each one is).`,
+		...format_decision_note(found.local),
+	].join('\n')
+}
+
+function parse_check_argument(argv: ReadonlyArray<string>): number | undefined {
+	const [raw] = to_positional_arguments(argv)
+	if (raw === undefined || !ISSUE_NUMBER_PATTERN.test(raw)) return undefined
+
+	return Number(raw)
+}
+
+// `-` reads stdin, matching `gh issue create --body-file -`. The reader is `cli_body`'s, shared with
+// `josh notify --body-file` and `josh followup --notify-message-file` rather than copied per entry
+// point (joshuafolkken/kit#1198), so the stdin form cannot come to mean one thing here and something
+// else there.
+const { read_file_or_stdin } = cli_body
+
+// An omitted path yields an empty rationale, which the body builder replaces with a visible
+// placeholder rather than a blank section.
+function read_rationale(rationale_path: string | undefined): string {
+	return rationale_path === undefined ? '' : read_file_or_stdin(rationale_path)
+}
+
+// `undefined` rather than `''` for an omitted path: an insertion that records no decision is the
+// ordinary case, and an empty string is a record that says nothing — which `epic --add` refuses
+// (joshuafolkken/kit#1350).
+function read_decision(decision_path: string | undefined): string | undefined {
+	return decision_path === undefined ? undefined : read_file_or_stdin(decision_path)
+}
+
+const epic_cli = {
+	is_promotion,
+	is_addition,
+	is_reconciliation,
+	...epic_cli_remove,
+	find_cross_repo_add_target,
+	is_decision_path_unusable,
+	resolve_local_add,
+	format_cross_repo_refusal,
+	parse_add_arguments,
+	parse_create_arguments,
+	parse_promote_arguments,
+	parse_reconcile_arguments,
+	parse_check_argument,
+	read_decision,
+	read_rationale,
+}
+
+export {
+	epic_cli,
+	ADD_FLAG,
+	AFTER_FLAG,
+	BEFORE_FLAG,
+	DECISION_FLAG,
+	ORDER_AFTER_FLAG,
+	ORDER_BEFORE_FLAG,
+	ORDERED_FLAG,
+	ORIGIN_FLAG,
+	PROMOTE_FLAG,
+	RATIONALE_FLAG,
+	RECONCILE_FLAG,
+}
+export { REMOVE_FLAG } from './epic-cli-remove'
+export type { AddArguments, CreateArguments, CrossRepoAddTarget, PromoteArguments }
+export type { RemoveArguments } from './epic-cli-remove'

package/scripts-ai/epic.ts

@@ -0,0 +1,192 @@
+#!/usr/bin/env tsx
+/**
+ * Create an epic Issue that satisfies every requirement the auto-close and the order warning read.
+ *
+ * Usage: tsx scripts-ai/epic.ts "<title>" <N1> <N2> ... [--ordered] [--rationale-file <path|->]
+ *                                                       [--origin <owner/repo#N>]
+ *        tsx scripts-ai/epic.ts --promote <N> <N1> <N2> ... [same flags]
+ *        tsx scripts-ai/epic.ts --add <E> <N1> <N2> ... [--before <M> | --after <M>]
+ *                                                      [--decision-file <path|->]
+ *        tsx scripts-ai/epic.ts --remove <E> <M> <N> ... [--decision-file <path|->]
+ */
+import { git_epic_add, type AddChildrenInput } from '../scripts/git/git-epic-add'
+import { git_epic_reconcile } from '../scripts/git/git-epic-reconcile'
+import { git_epic_remove } from '../scripts/git/git-epic-remove'
+import { git_epic_run } from '../scripts/git/git-epic-run'
+import { git_gh_command } from '../scripts/git/git-gh-command'
+import { epic_cli, type AddArguments, type CrossRepoAddTarget } from './epic-cli'
+
+const ARGV_OFFSET = 2
+const FLAGS = '[--ordered] [--rationale-file <path|->] [--origin <owner/repo#N>]'
+const USAGE = [
+	`Usage: josh epic "<title>" <N1> <N2> ... ${FLAGS}`,
+	`       josh epic --promote <N> <N1> <N2> ... ${FLAGS}`,
+	'       josh epic --add <E> <N1> <N2> ... [--before <M> | --after <M>] [--decision-file <path|->]',
+	'       josh epic --add <E> <N1> <N2> ... [--order-before <M> | --order-after <M>] [--decision-file <path|->]',
+	'       josh epic --remove <E> <M> <N> ... [--decision-file <path|->]',
+	'       josh epic --reconcile <E>',
+].join('\n')
+const FAILURE_EXIT_CODE = 1
+
+async function run_promotion(argv: ReadonlyArray<string>): Promise<number> {
+	const parsed = epic_cli.parse_promote_arguments(argv)
+
+	if (parsed === undefined) {
+		console.error(`✖ An issue number and at least one child issue number are required.\n${USAGE}`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await git_epic_run.promote_epic({
+		epic_number: parsed.epic_number,
+		children: parsed.children,
+		rationale: epic_cli.read_rationale(parsed.rationale_path),
+		is_ordered: parsed.is_ordered,
+		origin: parsed.origin,
+	})
+}
+
+// The parsed insertion as the writer's input: the decision file becomes the decision itself, read here
+// rather than inside the writer so nothing reaches GitHub before the file has been found. **Both
+// insertion paths go through it** — the bare form and the `owner/repo#N` one that resolves to this
+// repository — because passing the parsed arguments straight through drops `decision_path` in silence,
+// the field having a different name on either side.
+function to_add_input(parsed: AddArguments): AddChildrenInput {
+	return {
+		epic_number: parsed.epic_number,
+		children: parsed.children,
+		position: parsed.position,
+		is_order_only: parsed.is_order_only,
+		decision: epic_cli.read_decision(parsed.decision_path),
+	}
+}
+
+// A qualified target — `owner/repo#N`. Naming this repository it is the same insertion written
+// longer, so it is performed; naming another it is refused with the command to run there, because
+// this command reads and writes only the repository it runs from (joshuafolkken/kit#985).
+async function run_qualified_addition(found: CrossRepoAddTarget): Promise<number> {
+	const local = epic_cli.resolve_local_add(found, await git_gh_command.repo_get_name_with_owner())
+
+	if (local !== undefined) return await git_epic_add.add_children(to_add_input(local))
+
+	console.error(epic_cli.format_cross_repo_refusal(found))
+
+	return FAILURE_EXIT_CODE
+}
+
+// Why an insertion could not be read. A qualified target is answered on its own terms; an unusable
+// `--decision-file` path is named, because the generic line below would send the person after the epic
+// number and the positioning flag when what went missing is the record path a shell expanded to
+// nothing (joshuafolkken/kit#1350); anything else gets the requirements and the usage line.
+async function refuse_addition(argv: ReadonlyArray<string>): Promise<number> {
+	const qualified = epic_cli.find_cross_repo_add_target(argv)
+
+	if (qualified !== undefined) return await run_qualified_addition(qualified)
+
+	if (epic_cli.is_decision_path_unusable(argv)) {
+		console.error(
+			`✖ \`--decision-file\` needs exactly one readable path (\`-\` reads stdin); nothing was written.\n${USAGE}`,
+		)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	console.error(
+		`✖ An epic number, at least one child issue number, and at most one valid \`--before\` / \`--after\` target are required.\n${USAGE}`,
+	)
+
+	return FAILURE_EXIT_CODE
+}
+
+// Insertion into an existing epic. No rationale and no `--ordered`: the epic already declares both,
+// and the insertion is positioned relative to what is there rather than restating it.
+//
+// `--decision-file` is the one text an insertion does carry, and it is a *decision* rather than the
+// epic's rationale: it says why this child was placed here, and it goes to the epic's `## Decisions`
+// and to each child (joshuafolkken/kit#1350).
+async function run_addition(argv: ReadonlyArray<string>): Promise<number> {
+	const parsed = epic_cli.parse_add_arguments(argv)
+
+	if (parsed === undefined) return await refuse_addition(argv)
+
+	return await git_epic_add.add_children(to_add_input(parsed))
+}
+
+// Deleting a declared order. No position and no `--ordered`: the path itself says which orders go,
+// and what is deleted is only ever what it names — the ends are never reconnected, since a removal
+// that wrote an order would be declaring one nobody stated (joshuafolkken/kit#1712).
+async function run_removal(argv: ReadonlyArray<string>): Promise<number> {
+	const parsed = epic_cli.parse_remove_arguments(argv)
+
+	if (parsed === undefined) {
+		console.error(
+			`✖ An epic number and at least two child issue numbers are required, and \`--decision-file\` needs exactly one readable path (\`-\` reads stdin).\n${USAGE}`,
+		)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await git_epic_remove.remove_order({
+		epic_number: parsed.epic_number,
+		path: parsed.path,
+		decision: epic_cli.read_decision(parsed.decision_path),
+	})
+}
+
+// Reconcile an epic's declaration with its recorded relations. No decision file and no children: the
+// repair reads what the epic already records rather than being told an order (joshuafolkken/kit#2235).
+async function run_reconciliation(argv: ReadonlyArray<string>): Promise<number> {
+	const parsed = epic_cli.parse_reconcile_arguments(argv)
+
+	if (parsed === undefined) {
+		console.error(`✖ An epic number is required.\n${USAGE}`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await git_epic_reconcile.reconcile_epic(parsed.epic_number)
+}
+
+async function run_creation(argv: ReadonlyArray<string>): Promise<number> {
+	const parsed = epic_cli.parse_create_arguments(argv)
+
+	if (parsed === undefined) {
+		console.error(`✖ A title and at least one child issue number are required.\n${USAGE}`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await git_epic_run.create_epic({
+		title: parsed.title,
+		children: parsed.children,
+		rationale: epic_cli.read_rationale(parsed.rationale_path),
+		is_ordered: parsed.is_ordered,
+		origin: parsed.origin,
+	})
+}
+
+// `--add` is checked before `--promote`: both name an existing issue first, and only the flag
+// distinguishes "insert into this epic" from "turn this issue into one".
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	if (epic_cli.is_reconciliation(argv)) return await run_reconciliation(argv)
+	if (epic_cli.is_removal(argv)) return await run_removal(argv)
+	if (epic_cli.is_addition(argv)) return await run_addition(argv)
+	if (epic_cli.is_promotion(argv)) return await run_promotion(argv)
+
+	return await run_creation(argv)
+}
+
+async function main(): Promise<void> {
+	const exit_code = await run(process.argv.slice(ARGV_OFFSET))
+
+	if (exit_code !== 0) process.exit(exit_code)
+}
+
+// A `gh` failure carries its stderr as the message, which is the useful part; printing it alone
+// keeps a routine "not authenticated" or "label not found" from arriving as a stack trace.
+try {
+	await main()
+} catch (error) {
+	console.error(`✖ ${error instanceof Error ? error.message : String(error)}`)
+	process.exit(FAILURE_EXIT_CODE)
+}