@joshuafolkken/kit 1.978.0 → 1.983.0

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

@@ -7,18 +7,17 @@ import { epic_bundle, type BacklogIssue, type BundleDecision } from '#scripts/ep
 import { epic_bundle_cli } from '#scripts/epic/epic-bundle-cli'
 import { epic_bundle_gaps } from '#scripts/epic/epic-bundle-gaps'
 import { git_gh_command } from '#scripts/git/git-gh-command'
-import { EPIC_LABEL, has_any_label } from '#scripts/git/issue-labels'
-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 { issue_citation } from '#scripts/rules/issue-citation'
-import { z } from 'zod'
 import {
 	issue_scout,
 	type DuplicateCandidate,
 	type DuplicateSearch,
 	type ScoutIssue,
 } from './issue-scout'
+import { issue_scout_closed, type ClosedScan } from './issue-scout-closed'
+
+const { CLOSED_CEILING_LINE, CLOSED_UNREADABLE_LINE, read_recently_closed, warn_about_closed } =
+	issue_scout_closed
 
 // `josh issue:scout "<title>" [--body "<summary>"]` — before an issue is filed, answer the two
 // questions every `new` entry point asks first: has this already been filed, and which epic does it
@@ -44,87 +43,6 @@ const UNKNOWN_REPO_MESSAGE =
 // to be one. Zero is not a valid issue number, so it collides with nothing in the listing.
 const DRAFT_NUMBER = 0
 
-// How far back the closed half of the scan reaches (joshuafolkken/kit#1679). One page: the duplicate
-// this half exists to catch closed hours ago, not months, and the listing is ordered by update so
-// the newest hundred already covers a run's own day several times over.
-//
-// **It is a window, not a cut, which is why reaching it is not warned about.** Every other listing in
-// this command reports its `limit` as a gap, because there the caller wanted the whole backlog and
-// got part of it; here the hundredth-most-recently-updated closed issue is where the question itself
-// stops. A warning printed on every invocation in any repository with a hundred closed issues would
-// carry no signal and would train a reader past the gap lines beside it that do. **The page ceiling
-// is still reported**, and `ClosedScan` below says why the two are not the same event.
-const CLOSED_LIMIT = 100
-
-// Read through `has_any_label` rather than compared directly, for the casing reason
-// `issue-labels.ts` records: GitHub keeps the spelling a label was created with.
-const EPIC_LABELS: ReadonlySet<string> = new Set([EPIC_LABEL])
-
-// The listing's own label shape, not a second spelling of it: a copy here would be the drift the
-// shared schema module exists to prevent.
-const closed_labels_schema = z.array(issue_label_schema).optional()
-
-const closed_row_schema = z.object({
-	number: z.number(),
-	title: z.string().nullable(),
-	labels: closed_labels_schema,
-})
-
-type ClosedRow = z.infer<typeof closed_row_schema>
-
-// `rows` is `undefined` — never `[]` — when the listing failed: "nothing closed recently" is the
-// answer that sends a run straight on to file the duplicate, which is the failure this half was
-// added to prevent.
-function to_closed_row(row: ClosedRow): ScoutIssue {
-	return {
-		number: row.number,
-		title: row.title ?? '',
-		is_closed: true,
-		// A closed epic is still a container, and `epic_bundle_cli`'s marking cannot reach it: that one
-		// is built from the *open* epic listing. Reported as a duplicate it reads as "this work is
-		// already done" against an epic that never had an implementation of its own.
-		is_epic: has_any_label(row.labels, EPIC_LABELS),
-	}
-}
-
-function to_closed_rows(json: string): Array<ScoutIssue> | undefined {
-	const rows = parse_json_array_or_undefined(json, closed_row_schema)
-
-	return rows?.map((row) => to_closed_row(row))
-}
-
-// The rows, and whether the **page ceiling** stopped the paging short of the window. That is a
-// different thing from the `limit` above, which is the window itself: pull requests are filtered out
-// client-side, so a repository whose recent closures are mostly merged pull requests can select
-// fewer than `CLOSED_LIMIT` issue rows while the listing still has more to give. The scan then covers
-// less than it was asked for, which `git-gh-issue.ts`'s disposition table records as a warning.
-interface ClosedScan {
-	rows: Array<ScoutIssue> | undefined
-	is_capped: boolean
-}
-
-async function read_recently_closed(): Promise<ClosedScan> {
-	const { json, is_capped } = await git_gh_command.issue_list_recently_closed(CLOSED_LIMIT)
-
-	return { rows: json === undefined ? undefined : to_closed_rows(json), is_capped }
-}
-
-// The open half already ran, so both of these are gaps in the answer rather than failures of it —
-// the same disposition every other truncated listing in this command takes.
-const CLOSED_UNREADABLE_LINE =
-	'⚠ The recently closed issues could not be read, so the scan below covers open issues only — work that finished hours ago will not appear in it.'
-const CLOSED_CEILING_LINE = `⚠ The recently closed listing ${PAGE_CEILING_CAUSE}, so a duplicate that closed inside the window may not be below.`
-
-function warn_about_closed(scan: ClosedScan): void {
-	if (scan.rows === undefined) {
-		console.error(CLOSED_UNREADABLE_LINE)
-
-		return
-	}
-
-	if (scan.is_capped) console.error(CLOSED_CEILING_LINE)
-}
-
 interface ScoutArguments {
 	title: string
 	body: string
@@ -333,28 +251,32 @@ function format_epic_answer(
 // are still being worked on, and a closed one can neither gain a sibling nor be recommended as an
 // epic — so widening the placement pool with them would answer a different question from the one it
 // was asked (joshuafolkken/kit#1679).
+function duplicates_of(
+	draft: BacklogIssue,
+	issues: ReadonlyArray<BacklogIssue>,
+	closed: ReadonlyArray<ScoutIssue>,
+): DuplicateSearch {
+	const references = epic_audit_logic.parse_references(draft.body, draft.repo)
+
+	return issue_scout.find_duplicates(draft.title ?? '', [...issues, ...closed], references)
+}
+
 function format_report(
 	draft: BacklogIssue,
 	issues: ReadonlyArray<BacklogIssue>,
 	is_membership_established: boolean,
 	closed: ReadonlyArray<ScoutIssue> = [],
 ): string {
-	const references = epic_audit_logic.parse_references(draft.body, draft.repo)
-	const duplicates = issue_scout.find_duplicates(
-		draft.title ?? '',
-		[...issues, ...closed],
-		references,
-	)
 	const decision = epic_bundle.decide_bundle(draft, issues)
 
 	return [
-		format_duplicates(duplicates),
+		format_duplicates(duplicates_of(draft, issues, closed)),
 		format_epic_answer(draft, decision, issues, is_membership_established),
 	].join('\n')
 }
 
 type Widened = Awaited<ReturnType<typeof epic_bundle_cli.widen_with_referenced>>
-type ClosedListing = Awaited<ReturnType<typeof read_recently_closed>>
+type ClosedListing = ClosedScan
 
 function is_duplicate_scan_incomplete(widened: Widened, closed: ClosedListing): boolean {
 	const has_open_gap = widened.cutoff !== undefined && widened.cutoff !== 'none'
@@ -397,16 +319,23 @@ function linkified_report(
 	return issue_citation.linkify(qualified, repo)
 }
 
+// The scan's answer in both shapes it is read in: the report a person reads, and the candidate numbers
+// `issue:file` holds a filing to (joshuafolkken/kit#2808).
+interface ScoutOutcome {
+	report: string
+	candidates: ReadonlyArray<number>
+}
+
 // The backlog is read without its `blocked-by` relations: a draft has no number, so no recorded
 // dependency can name it and it declares none — the reads cannot change either half of the answer,
 // and skipping them takes one request per open issue off the command a run makes before every filing.
-async function report(args: ScoutArguments, repo: string): Promise<number> {
+async function scout(args: ScoutArguments, repo: string): Promise<ScoutOutcome | undefined> {
 	const backlog = await epic_bundle_cli.read_backlog(repo, { include_relations: false })
 
 	if (!backlog.is_readable) {
 		console.error(epic_bundle_cli.unreadable_backlog_message(backlog))
 
-		return FAILURE_EXIT_CODE
+		return undefined
 	}
 
 	const draft = draft_of(args, repo)
@@ -420,9 +349,22 @@ async function report(args: ScoutArguments, repo: string): Promise<number> {
 
 	epic_bundle_cli.warn_about_gaps(widened)
 	warn_about_closed(closed)
+	const duplicates = duplicates_of(draft, widened.issues, closed.rows ?? [])
+
 	// The same cut `warn_about_gaps` reports on standard error, read once more so standard output is
 	// held to it too — a ⚠ beside an executable instruction is not what stops a run acting on it.
-	console.info(linkified_report(draft, widened, closed, repo))
+	return {
+		report: linkified_report(draft, widened, closed, repo),
+		candidates: duplicates.candidates.map((candidate) => candidate.number),
+	}
+}
+
+async function report(args: ScoutArguments, repo: string): Promise<number> {
+	const outcome = await scout(args, repo)
+
+	if (outcome === undefined) return FAILURE_EXIT_CODE
+
+	console.info(outcome.report)
 
 	return SUCCESS_EXIT_CODE
 }
@@ -473,10 +415,12 @@ const issue_scout_cli = {
 	format_duplicates,
 	format_epic_decision,
 	format_report,
+	scout,
 	run,
 	main,
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 
+export type { ScoutArguments, ScoutOutcome }
 export { issue_scout_cli }

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

@@ -0,0 +1,102 @@
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { EPIC_LABEL, has_any_label } from '#scripts/git/issue-labels'
+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 type { ScoutIssue } from './issue-scout'
+
+// The closed half of `issue:scout`'s duplicate scan (joshuafolkken/kit#1679), held apart from the CLI
+// so the command that reports the scan and the one that files after it (`issue:file`,
+// joshuafolkken/kit#2808) read one listing rather than two.
+
+// How far back the closed half of the scan reaches (joshuafolkken/kit#1679). One page: the duplicate
+// this half exists to catch closed hours ago, not months, and the listing is ordered by update so
+// the newest hundred already covers a run's own day several times over.
+//
+// **It is a window, not a cut, which is why reaching it is not warned about.** Every other listing in
+// this command reports its `limit` as a gap, because there the caller wanted the whole backlog and
+// got part of it; here the hundredth-most-recently-updated closed issue is where the question itself
+// stops. A warning printed on every invocation in any repository with a hundred closed issues would
+// carry no signal and would train a reader past the gap lines beside it that do. **The page ceiling
+// is still reported**, and `ClosedScan` below says why the two are not the same event.
+const CLOSED_LIMIT = 100
+
+// Read through `has_any_label` rather than compared directly, for the casing reason
+// `issue-labels.ts` records: GitHub keeps the spelling a label was created with.
+const EPIC_LABELS: ReadonlySet<string> = new Set([EPIC_LABEL])
+
+// The listing's own label shape, not a second spelling of it: a copy here would be the drift the
+// shared schema module exists to prevent.
+const closed_labels_schema = z.array(issue_label_schema).optional()
+
+const closed_row_schema = z.object({
+	number: z.number(),
+	title: z.string().nullable(),
+	labels: closed_labels_schema,
+})
+
+type ClosedRow = z.infer<typeof closed_row_schema>
+
+// `rows` is `undefined` — never `[]` — when the listing failed: "nothing closed recently" is the
+// answer that sends a run straight on to file the duplicate, which is the failure this half was
+// added to prevent.
+function to_closed_row(row: ClosedRow): ScoutIssue {
+	return {
+		number: row.number,
+		title: row.title ?? '',
+		is_closed: true,
+		// A closed epic is still a container, and `epic_bundle_cli`'s marking cannot reach it: that one
+		// is built from the *open* epic listing. Reported as a duplicate it reads as "this work is
+		// already done" against an epic that never had an implementation of its own.
+		is_epic: has_any_label(row.labels, EPIC_LABELS),
+	}
+}
+
+function to_closed_rows(json: string): Array<ScoutIssue> | undefined {
+	const rows = parse_json_array_or_undefined(json, closed_row_schema)
+
+	return rows?.map((row) => to_closed_row(row))
+}
+
+// The rows, and whether the **page ceiling** stopped the paging short of the window. That is a
+// different thing from the `limit` above, which is the window itself: pull requests are filtered out
+// client-side, so a repository whose recent closures are mostly merged pull requests can select
+// fewer than `CLOSED_LIMIT` issue rows while the listing still has more to give. The scan then covers
+// less than it was asked for, which `git-gh-issue.ts`'s disposition table records as a warning.
+interface ClosedScan {
+	rows: Array<ScoutIssue> | undefined
+	is_capped: boolean
+}
+
+async function read_recently_closed(): Promise<ClosedScan> {
+	const { json, is_capped } = await git_gh_command.issue_list_recently_closed(CLOSED_LIMIT)
+
+	return { rows: json === undefined ? undefined : to_closed_rows(json), is_capped }
+}
+
+// The open half already ran, so both of these are gaps in the answer rather than failures of it —
+// the same disposition every other truncated listing in this command takes.
+const CLOSED_UNREADABLE_LINE =
+	'⚠ The recently closed issues could not be read, so the scan below covers open issues only — work that finished hours ago will not appear in it.'
+const CLOSED_CEILING_LINE = `⚠ The recently closed listing ${PAGE_CEILING_CAUSE}, so a duplicate that closed inside the window may not be below.`
+
+function warn_about_closed(scan: ClosedScan): void {
+	if (scan.rows === undefined) {
+		console.error(CLOSED_UNREADABLE_LINE)
+
+		return
+	}
+
+	if (scan.is_capped) console.error(CLOSED_CEILING_LINE)
+}
+
+const issue_scout_closed = {
+	CLOSED_CEILING_LINE,
+	CLOSED_UNREADABLE_LINE,
+	read_recently_closed,
+	warn_about_closed,
+}
+
+export type { ClosedScan }
+export { issue_scout_closed }

package/scripts/josh/__snapshots__/josh-command-map.test.ts.snap

@@ -48,6 +48,7 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
     "ibl": "issue:backlinks",
     "ici": "issue:cite",
     "icm": "issue:comment",
+    "ifl": "issue:file",
     "ig": "investigation:guard",
     "iln": "issue:lint",
     "ird": "issue:read",
@@ -485,6 +486,13 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
         "network",
       ],
     ],
+    "issue:file": [
+      "<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>]",
+      "automation",
+      [
+        "network",
+      ],
+    ],
     "issue:fold": [
       "<title>... [--not-separable] [--json]",
       "automation",
@@ -765,7 +773,7 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
       ],
     ],
     "propagate": [
-      "[--dry-run] [--skip-publish-wait]",
+      "[--dry-run] [--skip-publish-wait] [--target <repo>]",
       "maintainer",
       [
         "files",

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

@@ -93,6 +93,7 @@ const ALIASES: Record<string, string> = {
 	ird: 'issue:read',
 	ist: 'issue:state',
 	isc: 'issue:scout',
+	ifl: 'issue:file',
 	isf: 'issue:fold',
 	isfe: 'issue:fold-existing',
 	dfr: 'defect:rate',

package/scripts/josh/josh-commands-issue.ts

@@ -63,6 +63,17 @@ const ISSUE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<issue> --body <text> | --body-file <path>', 'automation', ['network']],
 	},
+	'issue:file': {
+		script: 'scripts/issue/issue-file-cli.ts',
+		description:
+			'File an Issue with every filing step: lint, Origin, duplicate scout, labels, then epic:bundle',
+		category: 'AI tools',
+		reference: [
+			'<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>]',
+			'automation',
+			['network'],
+		],
+	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */
 

package/scripts/josh/josh-commands-project.ts

@@ -67,7 +67,11 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 		script: 'scripts/propagate/propagate.ts',
 		description: 'Carry the published release into every consumer repository next to this one',
 		category: 'Project',
-		reference: ['[--dry-run] [--skip-publish-wait]', 'maintainer', ['files', 'network']],
+		reference: [
+			'[--dry-run] [--skip-publish-wait] [--target <repo>]',
+			'maintainer',
+			['files', 'network'],
+		],
 	},
 	adopt: {
 		script: 'scripts/adopt/adopt.ts',

package/scripts/propagate/propagate-run.ts

@@ -64,6 +64,7 @@ const SKIP_REASONS: Readonly<Record<string, string>> = {
 	not_downstream: 'does not depend on this package',
 	missing_checkout: 'no local checkout at the mapped path — reported, not cloned',
 	unreadable: 'package.json could not be read',
+	not_selected: 'not the repository --target named',
 }
 
 // The reason text for a candidate that is not going to be processed. A missing local checkout is

package/scripts/propagate/propagate-select.ts

@@ -0,0 +1,72 @@
+import { propagate_run } from './propagate-run'
+import type { PropagateTarget, TargetState } from './propagate-targets'
+
+// Narrowing a run to the one consumer `--target` names (joshuafolkken/kit#2755).
+//
+// Every other consumer stays in the list as `not_selected`, so the report still accounts for each
+// repository considered and says why it was left alone. A name that matches nothing — or matches a
+// candidate that cannot take the release — refuses the whole run before anything is written, rather
+// than quietly propagating to nobody.
+
+const SELECTABLE_STATES: ReadonlySet<TargetState> = new Set(['ready', 'up_to_date'])
+const REFUSAL_PREFIX = 'Refusing to propagate:'
+
+interface TargetSelection {
+	targets: Array<PropagateTarget>
+	refusal?: string
+}
+
+// A discovery key is `owner/repo`; the bare repository name is accepted too, because that is what a
+// person types.
+function matches_name(repo: string, name: string): boolean {
+	return repo === name || repo.slice(repo.indexOf('/') + 1) === name
+}
+
+function refuse_match(name: string, matches: ReadonlyArray<PropagateTarget>): string | undefined {
+	const [match] = matches
+
+	if (match === undefined) {
+		return `${REFUSAL_PREFIX} no repository named "${name}" is checked out next to this one.`
+	}
+
+	if (matches.length > 1) {
+		return `${REFUSAL_PREFIX} "${name}" names more than one repository; use the owner/repo form.`
+	}
+
+	if (SELECTABLE_STATES.has(match.state)) return undefined
+
+	return `${REFUSAL_PREFIX} ${match.repo}: ${propagate_run.skip_reason(match)}.`
+}
+
+// Only a candidate the run would otherwise have processed becomes `not_selected`. One that was never
+// going to be — not downstream, no checkout — keeps its own reason, which says more than "not named".
+function mark_unselected(
+	target: PropagateTarget,
+	matches: ReadonlyArray<PropagateTarget>,
+): PropagateTarget {
+	if (matches.includes(target) || !SELECTABLE_STATES.has(target.state)) return target
+
+	return { ...target, state: 'not_selected' }
+}
+
+// The run's targets with every other consumer marked `not_selected`, or the reason `name` cannot be
+// targeted. No name leaves the list untouched — the default run still covers every consumer.
+function select_target(
+	targets: ReadonlyArray<PropagateTarget>,
+	name: string | undefined,
+): TargetSelection {
+	if (name === undefined) return { targets: [...targets] }
+	const matches = targets.filter((target) => matches_name(target.repo, name))
+	const refusal = refuse_match(name, matches)
+	if (refusal !== undefined) return { targets: [], refusal }
+
+	return { targets: targets.map((target) => mark_unselected(target, matches)) }
+}
+
+const propagate_select = {
+	matches_name,
+	select_target,
+}
+
+export type { TargetSelection }
+export { propagate_select }

package/scripts/propagate/propagate-targets.ts

@@ -19,8 +19,10 @@ import { z } from 'zod'
 const MANIFEST_NAME = 'package.json'
 const NODE_MODULES = 'node_modules'
 
-// Why a candidate is not going to be processed, or that it is.
-type TargetState = 'ready' | 'up_to_date' | 'not_downstream' | 'missing_checkout' | 'unreadable'
+// Why a candidate is not going to be processed, or that it is. `not_selected` is the one state set
+// after classification: a candidate `--target` left out (joshuafolkken/kit#2755).
+type TargetState =
+	'ready' | 'up_to_date' | 'not_downstream' | 'missing_checkout' | 'unreadable' | 'not_selected'
 
 interface PropagateTarget {
 	repo: string
@@ -156,5 +158,5 @@ const propagate_targets = {
 	resolve_targets,
 }
 
-export type { Manifest, PropagateTarget }
+export type { Manifest, PropagateTarget, TargetState }
 export { propagate_targets }

package/scripts/propagate/propagate.ts

@@ -11,8 +11,9 @@ import { version_targets } from '#scripts/version/version-targets'
 import { propagate_git } from './propagate-git'
 import { propagate_publish } from './propagate-publish'
 import { propagate_run } from './propagate-run'
+import { propagate_select, type TargetSelection } from './propagate-select'
 import { propagate_steps } from './propagate-steps'
-import { propagate_targets } from './propagate-targets'
+import { propagate_targets, type PropagateTarget } from './propagate-targets'
 
 // `josh propagate` — carry the release this repository just published into every consumer checked
 // out next to it (joshuafolkken/kit#863).
@@ -22,25 +23,56 @@ const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const SKIP_PUBLISH_FLAG = '--skip-publish-wait'
 const DRY_RUN_FLAG = '--dry-run'
+const TARGET_FLAG = '--target'
 const KNOWN_FLAGS: ReadonlyArray<string> = [SKIP_PUBLISH_FLAG, DRY_RUN_FLAG]
+// Shown in the usage line only. `--target` carries a value, so it is taken out of argv before the
+// flag-only refusal runs, and this entry never has to match an argument.
+const TARGET_USAGE = `${TARGET_FLAG} <repo>`
 const DRY_RUN_REASON = 'would be propagated'
+const UNTOUCHED_NOTE = 'No consumer was touched.'
 
 interface RunOptions {
 	is_dry_run: boolean
 	is_publish_wait_skipped: boolean
+	// The one consumer to propagate to, when `--target` narrowed the run (joshuafolkken/kit#2755).
+	target?: string
 	// The usage message, when the arguments were not accepted. Carried alongside rather than returned
 	// instead, so the caller has one shape to branch on.
 	usage?: string
 }
 
+interface TargetArgument {
+	rest: Array<string>
+	target?: string
+	usage?: string
+}
+
+// Take `--target <repo>` out of argv. A second `--target` stays in `rest`, where the flag-only
+// refusal rejects it rather than letting one of the two names win silently.
+function split_target(argv: ReadonlyArray<string>): TargetArgument {
+	const index = argv.indexOf(TARGET_FLAG)
+	if (index === -1) return { rest: [...argv] }
+	const target = argv[index + 1]
+	const rest = argv.filter((_, position) => position !== index && position !== index + 1)
+
+	if (target === undefined || target.startsWith('-')) {
+		return { rest, usage: `${TARGET_FLAG} needs a repository name, e.g. ${TARGET_FLAG} app-kit` }
+	}
+
+	return { rest, target }
+}
+
 // Reject anything not on the list rather than ignoring it. `--dryrun` silently falling through to
 // the real write path is the mistake this refusal exists to prevent.
 function parse_options(argv: ReadonlyArray<string>): RunOptions {
+	const { rest, target, usage: target_usage } = split_target(argv)
 	const options: RunOptions = {
-		is_dry_run: argv.includes(DRY_RUN_FLAG),
-		is_publish_wait_skipped: argv.includes(SKIP_PUBLISH_FLAG),
+		is_dry_run: rest.includes(DRY_RUN_FLAG),
+		is_publish_wait_skipped: rest.includes(SKIP_PUBLISH_FLAG),
+		...(target !== undefined && { target }),
 	}
-	const usage = refuse_unknown_flags(argv, KNOWN_FLAGS, 'propagate')
+	const usage =
+		target_usage ?? refuse_unknown_flags(rest, [...KNOWN_FLAGS, TARGET_USAGE], 'propagate')
 
 	return usage === undefined ? options : { ...options, usage }
 }
@@ -126,15 +158,57 @@ async function await_publish(target_version: string, is_skipped: boolean): Promi
 	console.error(
 		`${status_icons.FAIL_ICON} ${target_version} did not become available: ${result.state}.`,
 	)
-	console.error('No consumer was touched.')
+	console.error(UNTOUCHED_NOTE)
 
 	return false
 }
 
-// Everything after the publish wait: resolve the consumers, run each one, print one report.
-function propagate_to_consumers(version: string, is_dry_run: boolean): number {
+// Print whatever the version resolution had to say, and hand back the version when there is one.
+function announce_run_version(resolved: RunVersion): string | undefined {
+	if (resolved.version === undefined) {
+		console.error(resolved.refusal ?? 'Nothing to propagate.')
+
+		return undefined
+	}
+
+	if (resolved.warning !== undefined) console.info(resolved.warning)
+
+	return resolved.version
+}
+
+interface RunPlan {
+	version: string
+	targets: ReadonlyArray<PropagateTarget>
+}
+
+// The consumers this run will consider, narrowed by `--target`. Resolved before the publish wait so
+// a mistyped name fails at once instead of after minutes of polling the registry.
+function resolve_run_targets(version: string, target: string | undefined): TargetSelection {
 	const map = repo_discovery.discover_repositories(PROJECT_ROOT)
 	const targets = propagate_targets.resolve_targets(map, KIT_PACKAGE_NAME, version)
+
+	return propagate_select.select_target(targets, target)
+}
+
+// The version and the consumers, or nothing once whatever stopped the run has been printed.
+function plan_run(options: RunOptions): RunPlan | undefined {
+	const version = announce_run_version(resolve_run_version(PROJECT_ROOT, options.is_dry_run))
+	if (version === undefined) return undefined
+	const selection = resolve_run_targets(version, options.target)
+
+	if (selection.refusal !== undefined) {
+		console.error(selection.refusal)
+		console.error(UNTOUCHED_NOTE)
+
+		return undefined
+	}
+
+	return { version, targets: selection.targets }
+}
+
+// Everything after the publish wait: run each consumer, print one report.
+function propagate_to_consumers(plan: RunPlan, is_dry_run: boolean): number {
+	const { version, targets } = plan
 	const step = is_dry_run
 		? propagate_steps.describe_step
 		: propagate_steps.create_step_runner({
@@ -165,19 +239,6 @@ async function resolve_publish(version: string, options: RunOptions): Promise<bo
 	return await await_publish(version, options.is_dry_run || options.is_publish_wait_skipped)
 }
 
-// Print whatever the version resolution had to say, and hand back the version when there is one.
-function announce_run_version(resolved: RunVersion): string | undefined {
-	if (resolved.version === undefined) {
-		console.error(resolved.refusal ?? 'Nothing to propagate.')
-
-		return undefined
-	}
-
-	if (resolved.warning !== undefined) console.info(resolved.warning)
-
-	return resolved.version
-}
-
 async function run(argv: ReadonlyArray<string>): Promise<number> {
 	const options = parse_options(argv)
 
@@ -187,11 +248,11 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	const version = announce_run_version(resolve_run_version(PROJECT_ROOT, options.is_dry_run))
-	if (version === undefined) return FAILURE_EXIT_CODE
-	if (!(await resolve_publish(version, options))) return FAILURE_EXIT_CODE
+	const plan = plan_run(options)
+	if (plan === undefined) return FAILURE_EXIT_CODE
+	if (!(await resolve_publish(plan.version, options))) return FAILURE_EXIT_CODE
 
-	return propagate_to_consumers(version, options.is_dry_run)
+	return propagate_to_consumers(plan, options.is_dry_run)
 }
 
 async function main(argv: ReadonlyArray<string>): Promise<void> {
@@ -201,6 +262,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 const propagate = {
 	DRY_RUN_REASON,
 	KNOWN_FLAGS,
+	TARGET_FLAG,
 	parse_options,
 	refuse_outside_source_repository,
 	resolve_target_version,