@joshuafolkken/kit 1.1178.0 → 1.1240.0

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

@@ -9,26 +9,29 @@ import { git_gh_issue_list, MAX_SCANNED } from '#scripts/gh/git-gh-issue-list'
 import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
 import { github_issue_url } from '#scripts/gh/github-issue-url'
 import { error_text } from '#scripts/lib/error-message'
+import type { PollOptions } from '#scripts/lib/poll'
 import { repository_labels } from '#scripts/repo/repository-labels'
 import { issue_auto_ok } from './issue-auto-ok'
 import { issue_file, type FileArguments } from './issue-file'
 import { issue_lint_cli } from './issue-lint-cli'
+import { issue_release_cli } from './issue-release-cli'
 import { issue_scout_cli } from './issue-scout-cli'
 import { issue_wip } from './issue-wip'
 
 // `josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>]…
-// [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok]` — file an Issue with every
-// filing step run in order (joshuafolkken/kit#2808): the third-party refusal, the body lint, the
-// `## Origin` check for another repository, the WIP cap count (joshuafolkken/kit#3181), the duplicate
-// scout, the missing workflow labels created (joshuafolkken/kit#3176), the `auto-ok` decision
-// (joshuafolkken/kit#3213), the create call carrying every label, and `epic:bundle` after it.
+// [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--release]` — file an Issue
+// with every filing step run in order (joshuafolkken/kit#2808): the third-party refusal, the body
+// lint, the `## Origin` check for another repository, the `auto-ok` decision (joshuafolkken/kit#3213)
+// with the run label it owes (joshuafolkken/kit#3313), the WIP cap count (joshuafolkken/kit#3181), the
+// duplicate scout, the missing workflow labels created (joshuafolkken/kit#3176), the create call
+// carrying every label, the release link on `--release` (joshuafolkken/kit#3360), and `epic:bundle`.
 // A direct `gh api …/issues` filing is refused by the `direct-filing` delivered rule and pointed here.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const USAGE =
-	'Usage: josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <tier-a|split|interrupt|review-cap>] [--label <name>]… [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok]'
+	'Usage: josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <tier-a|split|interrupt|review-cap>] [--label <name>]… [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--release]'
 const UNKNOWN_REPO_MESSAGE =
 	'Could not read this repository from `git remote`, so the filing has no repository to compare against — check `gh auth status`.'
 const THIRD_PARTY_MESSAGE =
@@ -36,6 +39,9 @@ const THIRD_PARTY_MESSAGE =
 // `GH_REPO` is the variable `gh` reads `{owner}/{repo}` from, so setting it points every listing the
 // scout and `epic:bundle` make at the target repository rather than at this checkout.
 const GH_REPO_VARIABLE = 'GH_REPO'
+// The open listing `epic:bundle` reads trails the create call, so the issue just filed is looked for
+// again for up to ten seconds before the placement is given up (joshuafolkken/kit#3332).
+const FRESH_ISSUE_POLL: PollOptions = { attempts: 6, interval_ms: 2000 }
 
 interface Filing {
 	args: FileArguments
@@ -130,22 +136,35 @@ async function is_scout_clear(filing: Filing): Promise<boolean> {
 	return open.length === 0
 }
 
-// `undefined` when the create call failed. `gh`'s standard error is captured into the thrown error
-// rather than printed, so it is printed here — otherwise the filing fails with no reason given. A label
-// the create applies is provisioned first, so it never arrives with a generated color.
-async function create(filing: Filing): Promise<string | undefined> {
-	repository_labels.ensure_labels(filing.target)
+// Every label the create call carries, or `undefined` when an `auto-ok` filing names neither run label
+// (joshuafolkken/kit#3313). Decided before the WIP count and the scout, so a refusal costs no listing.
+async function labels_of(filing: Filing): Promise<ReadonlyArray<string> | undefined> {
 	const auto_ok = await issue_auto_ok.resolve(
 		filing.args.is_auto_ok_opted_out,
 		filing.target,
 		filing.current,
+		filing.args.labels,
 	)
 
 	console.info(issue_auto_ok.line_of(auto_ok))
+	const labels = issue_file.labels_of(filing.args, filing.body, auto_ok.is_applied)
+	const problem = issue_file.triage_problem(labels)
+
+	if (problem === undefined) return labels
+	console.error(`✖ ${problem}`)
+
+	return undefined
+}
+
+// `undefined` when the create call failed. `gh`'s standard error is captured into the thrown error
+// rather than printed, so it is printed here — otherwise the filing fails with no reason given. A label
+// the create applies is provisioned first, so it never arrives with a generated color.
+async function create(filing: Filing, labels: ReadonlyArray<string>): Promise<string | undefined> {
+	repository_labels.ensure_labels(filing.target)
 	const request = git_gh_issue_write.issue_create_request({
 		title: filing.args.title,
 		body: filing.body,
-		labels: issue_file.labels_of(filing.args, filing.body, auto_ok.is_applied),
+		labels,
 		repo: filing.target,
 	})
 
@@ -160,12 +179,32 @@ async function create(filing: Filing): Promise<string | undefined> {
 	}
 }
 
+function issue_number_of(url: string): number {
+	return Number(github_issue_url.parse(url)?.issue_number)
+}
+
+// `--release`: the filed Issue blocks the target's release Issue (joshuafolkken/kit#3360). Reported,
+// never failed, for the reason `place` gives. The re-run hint names the target through `GH_REPO`:
+// `issue:release` links in the repository `gh` resolves, which is not the target on a `--repo` filing.
+async function link_release(url: string, filing: Filing): Promise<void> {
+	if (!filing.args.is_release) return
+	const issue_number = issue_number_of(url)
+	const is_linked =
+		Number.isSafeInteger(issue_number) &&
+		(await issue_release_cli.link(issue_number, filing.target))
+
+	if (is_linked) return
+	console.error(
+		`⚠ the release link did not complete for ${url} — run \`${GH_REPO_VARIABLE}=${filing.target} pnpm josh issue:release <N>\`.`,
+	)
+}
+
 // The Issue exists once `create` returns, so a failed placement is reported rather than failed: a
 // non-zero exit would read as "not filed" and invite the second filing the scout exists to stop.
 async function place(url: string, target: string): Promise<void> {
-	const issue_number = Number(github_issue_url.parse(url)?.issue_number)
+	const issue_number = issue_number_of(url)
 	const exit_code = Number.isSafeInteger(issue_number)
-		? await epic_bundle_cli.report_for(issue_number, target)
+		? await epic_bundle_cli.report_for(issue_number, target, FRESH_ISSUE_POLL)
 		: FAILURE_EXIT_CODE
 
 	if (exit_code !== SUCCESS_EXIT_CODE) {
@@ -173,25 +212,36 @@ async function place(url: string, target: string): Promise<void> {
 	}
 }
 
-async function file(filing: Filing): Promise<number> {
+function is_admitted(filing: Filing): boolean {
 	const refusals = refusals_of(filing)
 
-	if (refusals.length > 0) {
-		console.error(refusals.join('\n'))
+	if (refusals.length === 0) return true
+	console.error(refusals.join('\n'))
 
-		return FAILURE_EXIT_CODE
-	}
+	return false
+}
 
-	if (!(await is_wip_clear(filing)) || !(await is_scout_clear(filing))) return FAILURE_EXIT_CODE
-	const url = await create(filing)
+async function send(filing: Filing, labels: ReadonlyArray<string>): Promise<number> {
+	const url = await create(filing, labels)
 
 	if (url === undefined) return FAILURE_EXIT_CODE
 	console.info(url)
+	await link_release(url, filing)
 	await place(url, filing.target)
 
 	return SUCCESS_EXIT_CODE
 }
 
+async function file(filing: Filing): Promise<number> {
+	if (!is_admitted(filing)) return FAILURE_EXIT_CODE
+	const labels = await labels_of(filing)
+
+	if (labels === undefined) return FAILURE_EXIT_CODE
+	if (!(await is_wip_clear(filing)) || !(await is_scout_clear(filing))) return FAILURE_EXIT_CODE
+
+	return await send(filing, labels)
+}
+
 async function filing_of(args: FileArguments): Promise<Filing | string> {
 	const body = await read_body(args.body_file)
 
@@ -228,7 +278,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const issue_file_cli = { THIRD_PARTY_MESSAGE, run }
+const issue_file_cli = { FRESH_ISSUE_POLL, THIRD_PARTY_MESSAGE, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/issue/issue-file.ts

@@ -1,5 +1,6 @@
 import type { parseArgs } from 'node:util'
 import { epic_issue } from '#scripts/epic/epic-issue'
+import { epic_triage } from '#scripts/epic/epic-triage'
 import { github_issue_url } from '#scripts/gh/github-issue-url'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { issue_backlinks } from './issue-backlinks'
@@ -9,6 +10,8 @@ import {
 	DEPTH_LABEL_ORDER,
 	FILING_ROUTE_LABELS,
 	has_label_name,
+	RUN_LANE_LABEL,
+	RUN_SOLO_LABEL,
 } from './issue-labels'
 import { markdown_section } from './markdown-section'
 
@@ -40,6 +43,9 @@ interface FileArguments {
 	is_over_cap: boolean
 	// `--no-auto-ok`: the Issue needs a person's judgement, so `auto-ok` is not applied (`issue-auto-ok.ts`).
 	is_auto_ok_opted_out: boolean
+	// `--release`: the change reaches a consumer only once published, so the Issue is linked to the
+	// repository's release Issue as a blocker (`issue-release-cli.ts`).
+	is_release: boolean
 }
 
 const OPTIONS = {
@@ -51,6 +57,7 @@ const OPTIONS = {
 	distinct: { type: 'string', multiple: true },
 	'over-cap': { type: 'boolean' },
 	'no-auto-ok': { type: 'boolean' },
+	release: { type: 'boolean' },
 } as const
 
 // The label a `--depth` / `--route` value names, or `undefined` when it names none — read against the
@@ -120,6 +127,7 @@ function arguments_of(values: ParsedValues, title: string | undefined): FileArgu
 		repo: values.repo,
 		is_over_cap: values['over-cap'] === true,
 		is_auto_ok_opted_out: values['no-auto-ok'] === true,
+		is_release: values.release === true,
 	}
 }
 
@@ -152,6 +160,19 @@ function labels_of(args: FileArguments, body: string, is_auto_ok = false): Reado
 	return [...labels, AUTO_OK_LABEL]
 }
 
+// Why an `auto-ok` filing with neither `run:lane` nor `run:solo` is refused, or `undefined` when it is
+// not (joshuafolkken/kit#3313). The offer paths withhold every candidate while one opted-in Issue is
+// untriaged, so a run's own filing without the judgement stopped every lane. No default is applied:
+// `run:solo` is the answer that keeps a verification defect from running beside others, and only a
+// reading of the Issue gives it (`backlogrun-lanes.md`).
+function triage_problem(labels: ReadonlyArray<string>): string | undefined {
+	const is_owed = has_label_name(labels, AUTO_OK_LABEL) && !epic_triage.has_triage_label(labels)
+
+	if (!is_owed) return undefined
+
+	return `an \`${AUTO_OK_LABEL}\` filing needs \`--label ${RUN_LANE_LABEL}\` or \`--label ${RUN_SOLO_LABEL}\` — \`${RUN_SOLO_LABEL}\` only for a defect in kit's own verification that makes unrelated PRs answer wrongly on main now (\`backlogrun-lanes.md\`), else \`${RUN_LANE_LABEL}\``
+}
+
 function is_same_repository(target: string, current: string): boolean {
 	return target.toLowerCase() === current.toLowerCase()
 }
@@ -202,7 +223,14 @@ function unacknowledged(
 	return candidates.filter((candidate) => !distinct.includes(candidate))
 }
 
-const issue_file = { parse, labels_of, origin_problem, unacknowledged, is_same_repository }
+const issue_file = {
+	parse,
+	labels_of,
+	origin_problem,
+	triage_problem,
+	unacknowledged,
+	is_same_repository,
+}
 
 export type { FileArguments }
 export { issue_file }

package/scripts/issue/issue-labels.ts

@@ -65,6 +65,12 @@ const NEEDS_HUMAN_REVIEW_LABEL = 'needs-human-review'
 // takes it off, because taking it off asserts the work is *not* done, which is the same claim in
 // reverse and is no more a run's to make.
 const ALREADY_DONE_LABEL = 'already-done'
+// Marks the Issue that tracks a repository's next release (joshuafolkken/kit#3360). An Issue whose
+// change reaches a consumer only once published is linked to it as a `blocked_by` blocker
+// (`josh issue:release`), so "merged but not yet released" is visible in the backlog. A run applies
+// it; **`auto-ok` never rides on it** — `issue-auto-ok.ts` refuses the default for it on every path,
+// since a release is Tier C — and only a person opts it into unattended execution.
+const RELEASE_LABEL = 'release'
 
 // The four labels that mean an open issue must not be handed to a run as it stands: an `epic`
 // tracks a batch and is never run directly (its children are), `in-progress` is already claimed by
@@ -228,6 +234,11 @@ const WORKFLOW_LABELS: ReadonlyArray<LabelDefinition> = [
 		color: 'e99695',
 		description: 'Offered first in a backlogrun; only a person removes it',
 	},
+	{
+		name: RELEASE_LABEL,
+		color: 'fef2c0',
+		description: 'Tracks the next release; its blockers are the merged work it publishes',
+	},
 	...FILING_ROUTE_LABELS,
 	...DEPTH_LABELS,
 ]
@@ -340,6 +351,7 @@ const ALL_LABELS: ReadonlySet<string> = new Set([
 	NEEDS_HUMAN_REVIEW_LABEL,
 	ALREADY_DONE_LABEL,
 	PRIORITY_HIGH_LABEL,
+	RELEASE_LABEL,
 	INTERRUPT_ROUTE_LABEL,
 	REVIEW_CAP_ROUTE_LABEL,
 	REVIEW_ROUND2_SKIPPED_LABEL,
@@ -386,6 +398,7 @@ export {
 	PRIORITY_HIGH_LABEL,
 	RELEASE_CLASSIFICATION_LABELS,
 	RELEASE_CLASSIFICATION_NAMES,
+	RELEASE_LABEL,
 	REPOSITORY_LABELS,
 	REVIEW_CAP_ROUTE_LABEL,
 	REVIEW_ROUND2_SKIPPED_LABEL,

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

@@ -0,0 +1,155 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { git_gh_issue_list, MAX_SCANNED } from '#scripts/gh/git-gh-issue-list'
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { github_issue_url } from '#scripts/gh/github-issue-url'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { error_text } from '#scripts/lib/error-message'
+import { repository_labels } from '#scripts/repo/repository-labels'
+import { RELEASE_LABEL } from './issue-labels'
+import { issue_release } from './issue-release'
+
+// `josh issue:release <N>` — link Issue `<N>` to its repository's release Issue as a `blocked_by`
+// blocker, filing the release Issue when none is open (joshuafolkken/kit#3360). `josh issue:file
+// --release` calls the same `link` once its Issue exists, so a new and an existing Issue are linked
+// by one body of code.
+//
+// The relation is written through `issue_add_blocked_by`, which addresses the repository `gh`
+// resolves — the current one, or the target a cross-repository `issue:file` has pointed `GH_REPO` at.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
+const USAGE = 'Usage: josh issue:release <issue-number>'
+const NONE = 'none'
+const UNKNOWN_REPO_MESSAGE =
+	'Could not read this repository from `git remote` — check `gh auth status`.'
+
+interface ReleaseIssue {
+	issue_number: number
+	// Filed by this call, rather than found open.
+	is_filed: boolean
+}
+
+// `undefined` when the listing is unreadable, `NONE` when it reads and names no open release Issue.
+async function find_open(target: string): Promise<number | typeof NONE | undefined> {
+	const outcome = await git_gh_issue_list.issue_list({
+		json_fields: 'number',
+		limit: MAX_SCANNED,
+		label: RELEASE_LABEL,
+		repo: target,
+	})
+
+	if (outcome.json === undefined) return undefined
+
+	return issue_release.open_release_of(outcome.json) ?? NONE
+}
+
+// The new release Issue's number, or `undefined` when the create call failed. Never `auto-ok`: the
+// labels are `RELEASE_LABELS`, decided here rather than by `issue_auto_ok`, which refuses the label too.
+async function file_release(target: string): Promise<number | undefined> {
+	repository_labels.ensure_labels(target)
+	const request = git_gh_issue_write.issue_create_request({
+		title: issue_release.title_of(target),
+		body: issue_release.body_of(target),
+		labels: issue_release.RELEASE_LABELS,
+		repo: target,
+	})
+
+	try {
+		const url = await git_gh_exec.exec_gh_api(request)
+		const issue_number = Number(github_issue_url.parse(url)?.issue_number) || undefined
+
+		if (issue_number === undefined) console.error(`✖ the release number is unreadable: ${url}`)
+
+		return issue_number
+	} catch (error) {
+		console.error(`✖ the release Issue could not be filed: ${error_text.message_of(error)}`)
+
+		return undefined
+	}
+}
+
+// An unreadable listing files nothing: a second release Issue beside one the listing failed to show
+// would split the blockers between two releases.
+async function release_of(target: string): Promise<ReleaseIssue | undefined> {
+	const open = await find_open(target)
+
+	if (open === undefined) {
+		console.error(`✖ the open ${RELEASE_LABEL} Issues of ${target} could not be listed`)
+
+		return undefined
+	}
+
+	if (open !== NONE) return { issue_number: open, is_filed: false }
+	const filed = await file_release(target)
+
+	return filed === undefined ? undefined : { issue_number: filed, is_filed: true }
+}
+
+function linked_line(release: ReleaseIssue, issue_number: number): string {
+	const how = release.is_filed ? 'filed' : 'open'
+
+	return `release: #${String(release.issue_number)} (${how}) is blocked by #${String(issue_number)}`
+}
+
+// Whether Issue `issue_number` of `target` now blocks the release Issue. Every outcome is printed.
+async function link(issue_number: number, target: string): Promise<boolean> {
+	const release = await release_of(target)
+
+	if (release === undefined) return false
+	const blocked = String(release.issue_number)
+	const is_linked = await git_gh_issue_write.issue_add_blocked_by(blocked, String(issue_number))
+
+	if (is_linked) console.info(linked_line(release, issue_number))
+	else console.error(`✖ #${String(issue_number)} could not be recorded as a blocker of #${blocked}`)
+
+	return is_linked
+}
+
+// An unknown flag parses to no positionals, so it refuses the call like a missing number.
+function positionals_of(argv: ReadonlyArray<string>): ReadonlyArray<string> {
+	return cli_flags.arguments_of(argv, {})?.positionals ?? []
+}
+
+// The number is the one positional: a missing, malformed or second one refuses the whole call.
+function issue_number_of(argv: ReadonlyArray<string>): number | undefined {
+	const [issue_number, ...rest] = positionals_of(argv)
+	const is_single = rest.length === 0 && issue_number !== undefined
+
+	return is_single && ISSUE_NUMBER_PATTERN.test(issue_number) ? Number(issue_number) : undefined
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const issue_number = issue_number_of(argv)
+
+	if (issue_number === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const current = await git_gh_command.repo_get_name_with_owner()
+
+	if (current === undefined) {
+		console.error(UNKNOWN_REPO_MESSAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return (await link(issue_number, current)) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+// `process.exitCode` rather than `process.exit()`, so the report on standard output drains first.
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const issue_release_cli = { link, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_release_cli }

package/scripts/issue/issue-release.ts

@@ -0,0 +1,58 @@
+import { DEPTH_0_LABEL, RELEASE_LABEL } from './issue-labels'
+
+// The decisions behind `josh issue:release` (joshuafolkken/kit#3360), kept apart from the command
+// that reads the network so each is a pure answer a test can pin. An Issue whose change reaches a
+// consumer only once published used to surface the release only at the end of `followup`'s report;
+// it is now linked to the repository's release Issue, which it blocks until it merges.
+
+interface ListingRow {
+	number: number
+}
+
+function is_listing_row(value: unknown): value is ListingRow {
+	if (typeof value !== 'object' || value === null) return false
+
+	return Number.isSafeInteger(Reflect.get(value, 'number'))
+}
+
+// The open release Issue a listing of `release`-labelled Issues names, or `undefined` when it names
+// none or is unreadable. One release publishes every merge since the last, so a repository holds one
+// release Issue at a time; were a person to open a second, the oldest is the one the next release
+// closes, so it is the one every new blocker joins.
+function open_release_of(json: string): number | undefined {
+	try {
+		const parsed: unknown = JSON.parse(json)
+		const rows = Array.isArray(parsed) ? parsed.filter((row) => is_listing_row(row)) : []
+
+		return rows.length === 0 ? undefined : Math.min(...rows.map((row) => row.number))
+	} catch {
+		return undefined
+	}
+}
+
+function title_of(repo: string): string {
+	return `Release ${repo} (next version)`
+}
+
+// Plain English with no classification declaration: the Issue is not filed through `issue:file`, and
+// its labels are `RELEASE_LABELS` rather than read off the body.
+function body_of(repo: string): string {
+	return [
+		`Tracks the next release of ${repo}.`,
+		'',
+		'Every Issue this one is blocked by changes something a consumer can use only once it is published. Once they have merged, a person runs `pnpm josh release` in the primary checkout.',
+		'',
+		'Close this Issue once that release is published: the next blocker files a new one, so an open release Issue names only unreleased work.',
+		'',
+		'`auto-ok` is never applied to this Issue by a run; a person may apply it.',
+		'',
+	].join('\n')
+}
+
+// The release label and a depth: the subject of a release is what a consumer touches.
+// Never `auto-ok`.
+const RELEASE_LABELS: ReadonlyArray<string> = [RELEASE_LABEL, DEPTH_0_LABEL]
+
+const issue_release = { RELEASE_LABELS, open_release_of, title_of, body_of }
+
+export { issue_release }

package/scripts/issue/issue-scout-closed.ts

@@ -1,7 +1,7 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_label_schema } from '#scripts/git/git-schemas'
 import { PAGE_CEILING_CAUSE } from '#scripts/git/listing-cutoff'
 import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
-import { issue_label_schema } from '#scripts/git/schemas'
 import { z } from 'zod'
 import { EPIC_LABEL, has_any_label } from './issue-labels'
 import type { ScoutIssue } from './issue-scout'

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

@@ -2,6 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { issue_report_failures, type ReadFailureKind } from './issue-report-failures'
 import { issue_state, type IssueState } from './issue-state'
 
@@ -28,9 +29,6 @@ import { issue_state, type IssueState } from './issue-state'
 
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const REPO_FLAG = '--repo'
-const FLAG_PREFIX = '-'
-const INLINE_REPO_FLAG = `${REPO_FLAG}=`
 const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
 const USAGE = 'Usage: josh issue:state <issue-number> [<issue-number> ...] [--repo <owner/repo>]'
 // A blank line between the blocks of a multi-number report, so a person sees where one issue ends
@@ -60,85 +58,43 @@ interface IssueReport {
 	result: StateRead
 }
 
-// `absent` and "given but with nothing usable after it" are different answers. Falling back to the
-// session's repository on the second would print a confident state for a *different* issue of the
-// same number, which is the exact misread the `--repo` argument exists to prevent.
-//
-// A named flag carries the argv positions it actually occupied, never the token text it matched
-// (joshuafolkken/kit#1355). Removing tokens by value removes every token that happens to look like
-// one of them — a second `--repo`, a repeated `owner/repo` — and a token removed is a token nobody
-// is told about, which is the whole failure this file refuses elsewhere.
-type RepoFlag =
-	| { kind: 'absent' }
-	| { kind: 'named'; repo: string; consumed: ReadonlyArray<number> }
-	| { kind: 'incomplete' }
-
-// Both spellings gh itself accepts. `--repo=owner/repo` falling through to the separate-word branch
-// would read as no repository at all, which is the fall back to the session's repository above.
-function read_inline_repo(argv: ReadonlyArray<string>): RepoFlag | undefined {
-	const inline = argv.find((argument) => argument.startsWith(INLINE_REPO_FLAG))
-
-	if (inline === undefined) return undefined
-
-	const repo = inline.slice(INLINE_REPO_FLAG.length)
-
-	if (repo.length === 0) return { kind: 'incomplete' }
-
-	return { kind: 'named', repo, consumed: [argv.indexOf(inline)] }
+// The read goes through `cli_flags`, both spellings gh itself accepts included (`--repo owner/repo`,
+// `--repo=owner/repo`), and is strict (joshuafolkken/kit#3261). An unrecognized flag refuses the
+// call: `--rep=owner/repo` used to be discarded for starting with a dash, so the call fell back to
+// the session's repository and printed a confident state for a *different* repository's issue of
+// that number (joshuafolkken/kit#1355).
+const OPTIONS = { repo: { type: 'string', multiple: true } } as const
+
+// `absent` and "given but with nothing usable" are different answers. Falling back to the session's
+// repository on the second — an empty value, or `--repo` given twice — would print a confident state
+// for a *different* issue of the same number, which is the exact misread `--repo` exists to prevent.
+function read_repo(given: ReadonlyArray<string> | undefined): { repo?: string } | undefined {
+	if (given === undefined) return {}
+	const [repo, ...rest] = given
+
+	return repo !== undefined && rest.length === 0 && repo.length > 0 ? { repo } : undefined
 }
 
-function read_separate_repo(argv: ReadonlyArray<string>): RepoFlag {
-	const index = argv.indexOf(REPO_FLAG)
-
-	if (index === -1) return { kind: 'absent' }
-
-	const value_index = index + 1
-	const repo = argv[value_index]
-
-	if (repo === undefined || repo.startsWith(FLAG_PREFIX)) return { kind: 'incomplete' }
-
-	return { kind: 'named', repo, consumed: [index, value_index] }
-}
-
-function read_repo_flag(argv: ReadonlyArray<string>): RepoFlag {
-	return read_inline_repo(argv) ?? read_separate_repo(argv)
-}
-
-// The argv positions the repository flag occupied, and nothing else. Everything outside this set was
-// offered as an issue number, whatever it looks like — so a flag nobody recognizes reaches the check
-// below and refuses the call instead of vanishing from it (joshuafolkken/kit#1355).
-function consumed_indices(repo_flag: RepoFlag): ReadonlySet<number> {
-	return new Set(repo_flag.kind === 'named' ? repo_flag.consumed : [])
+// A token that is not a number refuses the whole invocation rather than being dropped. Dropping it
+// answers fewer numbers than were asked for and still exits zero — and with one number left, the
+// surviving block prints in the single-number shape, so nothing in the output says a number went
+// unanswered. `#1262` copied out of a `diag` table is exactly that token.
+function is_issue_numbers(positionals: ReadonlyArray<string>): boolean {
+	return (
+		positionals.length > 0 && positionals.every((argument) => ISSUE_NUMBER_PATTERN.test(argument))
+	)
 }
 
 function parse_request(argv: ReadonlyArray<string>): StateRequest | undefined {
-	const repo_flag = read_repo_flag(argv)
-
-	if (repo_flag.kind === 'incomplete') return undefined
-
-	// The repository is read first, flag word and value together, so neither is ever mistaken for an
-	// issue number — and nothing else is removed here. Every remaining token is one the caller offered
-	// as an issue number, whatever it looks like.
-	const consumed = consumed_indices(repo_flag)
-	const rest = argv.filter((_argument, index) => !consumed.has(index))
-	const numbers = rest.filter((argument) => ISSUE_NUMBER_PATTERN.test(argument))
-
-	// A token that is not a number refuses the whole invocation rather than being dropped. Dropping
-	// it answers fewer numbers than were asked for and still exits zero — and with one number left,
-	// the surviving block prints in the single-number shape, so nothing in the output says a number
-	// went unanswered. `#1262` copied out of a `diag` table is exactly that token.
-	//
-	// An unrecognized flag reaches this same check rather than a lenient one of its own
-	// (joshuafolkken/kit#1355). `--rep=owner/repo` used to be discarded for starting with a dash, so
-	// the call fell back to the session's repository and printed a confident state for a *different*
-	// repository's issue of that number — the misread `incomplete` already exists to prevent.
-	if (numbers.length === 0 || numbers.length !== rest.length) return undefined
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+	if (parsed === undefined) return undefined
+	const repo = read_repo(parsed.values.repo)
+
+	if (repo === undefined || !is_issue_numbers(parsed.positionals)) return undefined
 
 	// In the order they were typed, with a repeat dropped: repeating a number would spend a second
 	// read on an answer already in hand, and print a second block a caller counting rows counts twice.
-	const issue_numbers = [...new Set(numbers)]
-
-	return repo_flag.kind === 'named' ? { issue_numbers, repo: repo_flag.repo } : { issue_numbers }
+	return { issue_numbers: [...new Set(parsed.positionals)], ...repo }
 }
 
 // One number's read, reduced to what the report needs and nothing printed yet. Separating the two

package/scripts/josh/josh-command-map.ts

@@ -78,6 +78,8 @@ const ALIASES: Record<string, string> = {
 	rvf: 'review:findings',
 	ruv: 'rule:value',
 	ev: 'eval',
+	lsm: 'lane:sample',
+	lst: 'lane:stats',
 }
 
 // The canonical name of a `josh` subcommand: an alias expands, and anything else passes through