@joshuafolkken/kit 1.972.0 → 1.983.0

package/scripts/init/init-install.ts

@@ -4,6 +4,7 @@ interface InstallStep {
 	label: string
 	command: string
 	args: ReadonlyArray<string>
+	env?: Readonly<Record<string, string>>
 }
 
 interface InstallRequest {
@@ -40,6 +41,7 @@ function did_step_succeed(step: InstallStep, project_root: string): boolean {
 	console.info(`\n$ ${step.label}`)
 	const result = execaSync(step.command, step.args, {
 		cwd: project_root,
+		env: step.env ?? {},
 		stdio: 'inherit',
 		reject: false,
 	})
@@ -60,5 +62,6 @@ function run_post_init_steps(project_root: string): string | undefined {
 	return undefined
 }
 
-const init_install = { NO_INSTALL_FLAG, split_install_flag, run_post_init_steps }
+const init_install = { NO_INSTALL_FLAG, split_install_flag, did_step_succeed, run_post_init_steps }
 export { init_install }
+export type { InstallStep }

package/scripts/init/init-logic-workspace.ts

@@ -138,6 +138,6 @@ function merge_workspace_yaml(existing: string, template: string): string {
 	return append_user_blocks(cleaned, new_keys, template)
 }
 
-const init_logic_workspace = { merge_workspace_yaml }
+const init_logic_workspace = { merge_workspace_yaml, template_build_values }
 
 export { init_logic_workspace }

package/scripts/init/init.ts

@@ -15,12 +15,13 @@ import { execaSync } from 'execa'
 import { z } from 'zod'
 import { init_actions, PRETTIER_CONFIG_JS, type FileAction } from './init-actions'
 import { init_ai_copy } from './init-ai-copy'
+import { init_bootstrap } from './init-bootstrap'
 import { init_install } from './init-install'
 import { init_logic } from './init-logic'
 import { PACKAGE_DIR, PROJECT_ROOT } from './init-paths'
 import { init_static } from './init-static'
 import { plugin_install_hint_module } from './plugin-install-hint'
-import { project_profile, type ProjectShape } from './project-profile'
+import { project_profile, type ProjectProfile, type ProjectShape } from './project-profile'
 
 const PACKAGE_JSON = 'package.json'
 const KIT_PACKAGE_NAME = '@joshuafolkken/kit'
@@ -320,10 +321,18 @@ function finish_dependencies(shape: ProjectShape, is_install: boolean): void {
 	if (failure !== undefined) throw new Error(failure)
 }
 
-function main(args: ReadonlyArray<string> = []): void {
-	if (did_refuse_self_run(PACKAGE_DIR, PROJECT_ROOT)) return
-	const { is_install, rest } = init_install.split_install_flag(args)
-	const requested = project_profile.requested_profile(rest, INIT_USAGE)
+// A kit run from outside the project — `pnpm dlx`, a global install — sets nothing up itself: it
+// installs the project's kit and hands the whole run to that one (joshuafolkken/kit#2794). Under
+// `--no-install` nothing is installed, so the running kit does the setup as before.
+function did_hand_off(args: ReadonlyArray<string>): boolean {
+	if (init_bootstrap.is_project_kit(PACKAGE_DIR, PROJECT_ROOT)) return false
+	const failure = init_bootstrap.hand_off(PACKAGE_DIR, PROJECT_ROOT, args)
+	if (failure !== undefined) throw new Error(failure)
+
+	return true
+}
+
+function set_up_project(requested: ProjectProfile | undefined, is_install: boolean): void {
 	const shape = project_profile.inspect_project(PROJECT_ROOT, requested)
 
 	initialize_project(shape)
@@ -331,6 +340,15 @@ function main(args: ReadonlyArray<string> = []): void {
 	console.info('\n✅ Done.\n')
 }
 
+function main(args: ReadonlyArray<string> = []): void {
+	if (did_refuse_self_run(PACKAGE_DIR, PROJECT_ROOT)) return
+	const { is_install, rest } = init_install.split_install_flag(args)
+	// Validated before the hand-off, so a malformed invocation is refused before kit is installed.
+	const requested = project_profile.requested_profile(rest, INIT_USAGE)
+
+	if (!is_install || !did_hand_off(args)) set_up_project(requested, is_install)
+}
+
 function run_cli(args: ReadonlyArray<string>): void {
 	try {
 		main(args)

package/scripts/init/start-plan.ts

@@ -46,7 +46,7 @@ const STEP_LABELS: Readonly<Record<StartStep, string>> = {
 	initialize: 'Initialize kit (the same setup as josh init)',
 	commit: 'Commit every file as the initial commit',
 	repository: 'Create the GitHub repository and push main',
-	labels: 'Add the workflow labels the repository is missing',
+	labels: 'Add the workflow and release-classification labels the repository is missing',
 }
 
 function refused(refusal: string): StepPlan {

package/scripts/init/start-steps.ts

@@ -1,6 +1,6 @@
 import path from 'node:path'
 import { git_gh_exec } from '#scripts/git/git-gh-exec'
-import { WORKFLOW_LABELS } from '#scripts/git/issue-labels'
+import { repository_labels } from '#scripts/repo/repository-labels'
 import { self_sync_guard } from '#scripts/self-sync-guard/self-sync-guard-logic'
 import { execaSync } from 'execa'
 import { main as init_main } from './init'
@@ -14,10 +14,7 @@ interface StepContext {
 	visibility: Visibility
 }
 
-type WorkflowLabel = (typeof WORKFLOW_LABELS)[number]
-
 const DEFAULT_BRANCH = 'main'
-const LABELS_ENDPOINT = 'repos/{owner}/{repo}/labels'
 const GH_INSTALL_HINT =
 	'GitHub CLI (gh) is not installed. Install it from https://cli.github.com/, run gh auth login, then run josh start again. Nothing was changed.'
 const GH_AUTH_HINT =
@@ -100,29 +97,10 @@ function create_github_repository(context: StepContext): void {
 	run('gh', ['repo', 'create', name, visibility, ...source], context.root)
 }
 
-// Labels already present are left as they are — only the missing ones are created, so a repository
-// that recolored a label keeps its choice. GitHub compares label names case-insensitively.
-function missing_workflow_labels(existing: ReadonlyArray<string>): ReadonlyArray<WorkflowLabel> {
-	const names = new Set(existing.map((name) => name.toLowerCase()))
-
-	return WORKFLOW_LABELS.filter((label) => !names.has(label.name))
-}
-
-function create_label(label: WorkflowLabel, root: string): void {
-	const fields = [`name=${label.name}`, `color=${label.color}`, `description=${label.description}`]
-
-	run('gh', ['api', LABELS_ENDPOINT, ...fields.flatMap((field) => ['-f', field]), '--silent'], root)
-	console.info(`  ✔ label ${label.name}`)
-}
-
-function add_missing_labels(context: StepContext): void {
-	const listing = execaSync('gh', ['api', '--paginate', LABELS_ENDPOINT, '--jq', '.[].name'], {
-		...git_gh_exec.direct_environment(),
-		cwd: context.root,
-	})
-	const existing = listing.stdout.split('\n').filter((name) => name.length > 0)
-
-	for (const label of missing_workflow_labels(existing)) create_label(label, context.root)
+// The repository was created by the step before, so `gh` resolves the placeholder from the
+// directory `josh start` runs in, which is the root.
+function add_missing_labels(): void {
+	repository_labels.ensure_labels('{owner}/{repo}')
 }
 
 const STEP_ACTIONS: Readonly<Record<StartStep, (context: StepContext) => void>> = {
@@ -160,7 +138,6 @@ const start_steps = {
 	read_git_state,
 	github_cli_refusal,
 	self_run_refusal,
-	missing_workflow_labels,
 	run_steps,
 }
 export { start_steps }

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

@@ -0,0 +1,188 @@
+#!/usr/bin/env tsx
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { repo_party } from '#scripts/discovery/repo-party'
+import { epic_bundle_cli } from '#scripts/epic/epic-bundle-cli'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
+import { git_gh_issue_write } from '#scripts/git/git-gh-issue-write'
+import { github_issue_url } from '#scripts/git/github-issue-url'
+import { issue_file, type FileArguments } from './issue-file'
+import { issue_lint_cli } from './issue-lint-cli'
+import { issue_scout_cli } from './issue-scout-cli'
+
+// `josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>]…
+// [--repo <owner/repo>] [--distinct <N,…>]` — 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 duplicate scout, the create call carrying every label, and `epic:bundle` after it.
+// 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,…>]'
+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 =
+	'✖ third-party target: a tracker we do not own is Tier C — draft the Issue for a person to post instead (`CLAUDE.md` → "Third-party repositories are Tier C").'
+// `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'
+
+interface Filing {
+	args: FileArguments
+	body: string
+	target: string
+	current: string
+}
+
+async function read_body(path: string): Promise<string | undefined> {
+	try {
+		return await readFile(path, 'utf8')
+	} catch {
+		return undefined
+	}
+}
+
+function is_third_party(target: string): boolean {
+	const party = repo_party.classify(repo_party.current_owner(), repo_party.target_owner(target))
+
+	return party === repo_party.THIRD_PARTY
+}
+
+// Every refusal the filing can meet before a request is sent, in the order the steps run — `[]` when
+// the filing may go on to the scout.
+function refusals_of(filing: Filing): ReadonlyArray<string> {
+	if (is_third_party(filing.target)) return [THIRD_PARTY_MESSAGE]
+	const problems = issue_lint_cli.problems(filing.body).map((problem) => `✖ ${problem}`)
+	const origin = issue_file.origin_problem(filing.body, filing.target, filing.current)
+
+	return origin === undefined ? problems : [...problems, `✖ ${origin}`]
+}
+
+function unacknowledged_message(numbers: ReadonlyArray<number>): string {
+	const listed = numbers.map(String).join(',')
+
+	return `✖ duplicate candidate(s) ${listed} not declared separate — read each (\`issue-fold-existing.md\`); fold into a duplicate, or reissue with \`--distinct ${listed}\` when each is a separate deliverable.`
+}
+
+// Set before the scout and left set for `epic:bundle`, so both read the target's backlog.
+function point_listings_at(filing: Filing): void {
+	if (issue_file.is_same_repository(filing.target, filing.current)) return
+
+	process.env[GH_REPO_VARIABLE] = filing.target
+}
+
+// The scout's report is printed whatever it finds, and the filing is held until every candidate it
+// names is declared separate.
+async function is_scout_clear(filing: Filing): Promise<boolean> {
+	point_listings_at(filing)
+	const outcome = await issue_scout_cli.scout(
+		{ title: filing.args.title, body: filing.body },
+		filing.target,
+	)
+
+	if (outcome === undefined) return false
+	console.info(outcome.report)
+	const open = issue_file.unacknowledged(outcome.candidates, filing.args.distinct)
+
+	if (open.length > 0) console.error(unacknowledged_message(open))
+
+	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.
+async function create(filing: Filing): Promise<string | undefined> {
+	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),
+		repo: filing.target,
+	})
+
+	try {
+		return await git_gh_exec.exec_gh_api(request)
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error)
+
+		console.error(`✖ the create call failed: ${reason}`)
+
+		return undefined
+	}
+}
+
+// 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 exit_code = Number.isSafeInteger(issue_number)
+		? await epic_bundle_cli.report_for(issue_number, target)
+		: FAILURE_EXIT_CODE
+
+	if (exit_code !== SUCCESS_EXIT_CODE) {
+		console.error(`⚠ epic:bundle did not answer for ${url} — run \`pnpm josh epic:bundle <N>\`.`)
+	}
+}
+
+async function file(filing: Filing): Promise<number> {
+	const refusals = refusals_of(filing)
+
+	if (refusals.length > 0) {
+		console.error(refusals.join('\n'))
+
+		return FAILURE_EXIT_CODE
+	}
+
+	if (!(await is_scout_clear(filing))) return FAILURE_EXIT_CODE
+	const url = await create(filing)
+
+	if (url === undefined) return FAILURE_EXIT_CODE
+	console.info(url)
+	await place(url, filing.target)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function filing_of(args: FileArguments): Promise<Filing | string> {
+	const body = await read_body(args.body_file)
+
+	if (body === undefined) return `Could not read the body file ${args.body_file}.`
+	const current = await git_gh_command.repo_get_name_with_owner()
+
+	if (current === undefined) return UNKNOWN_REPO_MESSAGE
+
+	return { args, body, target: args.repo ?? current, current }
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const args = issue_file.parse(argv)
+
+	if (args === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const filing = await filing_of(args)
+
+	if (typeof filing === 'string') {
+		console.error(filing)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await file(filing)
+}
+
+// `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_file_cli = { USAGE, THIRD_PARTY_MESSAGE, UNKNOWN_REPO_MESSAGE, run, main }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_file_cli }

package/scripts/issue/issue-file.ts

@@ -0,0 +1,192 @@
+import { parseArgs } from 'node:util'
+import { epic_issue } from '#scripts/epic/epic-issue'
+import { github_issue_url } from '#scripts/git/github-issue-url'
+import { DEPTH_LABEL_ORDER, FILING_ROUTE_LABELS, has_label_name } from '#scripts/git/issue-labels'
+import { issue_backlinks } from './issue-backlinks'
+import { issue_classification } from './issue-classification'
+import { markdown_section } from './markdown-section'
+
+// The decisions behind `josh issue:file` (joshuafolkken/kit#2808), kept apart from the command that
+// reads the network so each one is a pure answer a test can pin. Every filing used to be a hand-built
+// `gh api …/issues` call beside five steps spread over as many documents, and joshuafolkken/kit#2805
+// ran two of them and skipped the lint and the labels. Here the steps are the command's arguments:
+// a label the filing owes is a required option rather than a line to remember.
+
+const DEPTH_PREFIX = 'depth:'
+const ROUTE_PREFIX = 'route:'
+const LIST_SEPARATOR = ','
+const WORD_SEPARATOR = /\s+/u
+const CODE_SPAN = /`/gu
+// Prose written against a reference with no space — `(owner/repo#N)`, `owner/repo#N。`, Japanese text
+// after the number — is trimmed off, so the anchored parsers below still see the reference itself.
+const LEADING_NON_WORD = /^[^\w]+/u
+const DIGIT = /\d/u
+
+interface FileArguments {
+	title: string
+	body_file: string
+	depth: string
+	route: string | undefined
+	labels: ReadonlyArray<string>
+	repo: string | undefined
+	distinct: ReadonlyArray<number>
+}
+
+const OPTIONS = {
+	'body-file': { type: 'string' },
+	depth: { type: 'string' },
+	route: { type: 'string' },
+	label: { type: 'string', multiple: true },
+	repo: { type: 'string' },
+	distinct: { type: 'string', multiple: true },
+} as const
+
+// The label a `--depth` / `--route` value names, or `undefined` when it names none — read against the
+// label sets `issue-labels.ts` defines, so the command cannot apply a depth or route nobody provisions.
+function label_of(
+	prefix: string,
+	value: string | undefined,
+	known: ReadonlyArray<string>,
+): string | undefined {
+	if (value === undefined) return undefined
+	const label = value.startsWith(prefix) ? value : `${prefix}${value}`
+
+	return known.includes(label) ? label : undefined
+}
+
+const ROUTE_NAMES: ReadonlyArray<string> = FILING_ROUTE_LABELS.map((label) => label.name)
+
+// `--distinct 12,34 --distinct 56` → `[12, 34, 56]`; `undefined` when any entry is not an issue number,
+// so a typo is refused rather than read as an acknowledgement of nothing.
+function distinct_numbers(values: ReadonlyArray<string>): ReadonlyArray<number> | undefined {
+	const numbers = values
+		.flatMap((value) => value.split(LIST_SEPARATOR))
+		.map((raw) => {
+			return Number(raw.trim().replace('#', ''))
+		})
+
+	return numbers.every((number) => Number.isSafeInteger(number) && number > 0) ? numbers : undefined
+}
+
+type ParsedValues = ReturnType<typeof parseArgs<{ options: typeof OPTIONS }>>['values']
+
+function route_of(values: ParsedValues): string | undefined | false {
+	if (values.route === undefined) return undefined
+
+	return label_of(ROUTE_PREFIX, values.route, ROUTE_NAMES) ?? false
+}
+
+function has_text(value: string | undefined): value is string {
+	return value !== undefined && value.trim() !== ''
+}
+
+// The labelled half of the arguments, or `undefined` when a depth, route or `--distinct` entry is not
+// one the command knows.
+function labelled_of(
+	values: ParsedValues,
+): Pick<FileArguments, 'depth' | 'route' | 'distinct'> | undefined {
+	const depth = label_of(DEPTH_PREFIX, values.depth, DEPTH_LABEL_ORDER)
+	const route = route_of(values)
+	const distinct = distinct_numbers(values.distinct ?? [])
+
+	if (route === false || depth === undefined || distinct === undefined) return undefined
+
+	return { depth, route, distinct }
+}
+
+function arguments_of(values: ParsedValues, title: string | undefined): FileArguments | undefined {
+	const labelled = labelled_of(values)
+	const body_file = values['body-file']
+
+	if (labelled === undefined || !has_text(title) || !has_text(body_file)) return undefined
+
+	return { title, body_file, ...labelled, labels: values.label ?? [], repo: values.repo }
+}
+
+// An unknown flag makes `parseArgs` throw; caught so the answer is the usage line, not a stack trace.
+function parse(argv: ReadonlyArray<string>): FileArguments | undefined {
+	try {
+		const { values, positionals } = parseArgs({
+			args: [...argv],
+			options: OPTIONS,
+			allowPositionals: true,
+		})
+
+		return arguments_of(values, positionals[0])
+	} catch {
+		return undefined
+	}
+}
+
+// A classification label is the body's to declare, so an extra `--label` naming one the body does not
+// declare is dropped rather than applied — the label then always matches what `issue:lint` reads.
+function is_undeclared_classification(label: string, body: string): boolean {
+	const is_classification = has_label_name(issue_classification.CLASSIFICATION_LABELS, label)
+
+	return is_classification && !has_label_name(issue_classification.required_labels(body), label)
+}
+
+// Every label the filing carries: the depth, the route when there is one, the classification labels
+// the body declares (`issue_classification.labels_for`, which merges case-insensitively), then any
+// extra `--label`. One request applies them all, so no label is a separate step to forget.
+function labels_of(args: FileArguments, body: string): ReadonlyArray<string> {
+	const extra = args.labels.filter((label) => !is_undeclared_classification(label, body))
+	const declared = [args.depth, ...(args.route === undefined ? [] : [args.route]), ...extra]
+
+	return issue_classification.labels_for(body, declared)
+}
+
+function is_same_repository(target: string, current: string): boolean {
+	return target.toLowerCase() === current.toLowerCase()
+}
+
+// `owner/repo#N` or a github.com issue URL — the qualified forms the issue template's backlink section
+// requires, never a bare `#N`, which resolves to whichever repository renders it. Read through the
+// parsers that already know both forms rather than a third pattern.
+function without_trailing_prose(text: string): string {
+	let end = text.length
+
+	while (end > 0 && !DIGIT.test(text.charAt(end - 1))) end -= 1
+
+	return text.slice(0, end)
+}
+
+function is_qualified_reference(word: string): boolean {
+	const bare = without_trailing_prose(word.replaceAll(CODE_SPAN, '').replace(LEADING_NON_WORD, ''))
+
+	return (
+		epic_issue.parse_epic_reference(bare)?.repo !== undefined ||
+		github_issue_url.parse(bare) !== undefined
+	)
+}
+
+function cites_origin(line: string): boolean {
+	return line.split(WORD_SEPARATOR).some((word) => is_qualified_reference(word))
+}
+
+// Why a cross-repository filing is refused, or `undefined` when it is not refused. A filing into the
+// session's own repository owes no `## Origin`; one into another repository owes the section with a
+// qualified reference back to the Issue that found it (`issue-template.md`, the backlink section).
+function origin_problem(body: string, target: string, current: string): string | undefined {
+	if (is_same_repository(target, current)) return undefined
+	const lines = markdown_section.section_lines(body, issue_backlinks.ORIGIN_HEADING)
+
+	if (lines.some((line) => cites_origin(line))) return undefined
+
+	return `filing into ${target} from ${current} needs a \`${issue_backlinks.ORIGIN_HEADING}\` section citing the originating Issue as \`owner/repo#N\` or its URL`
+}
+
+// The duplicate candidates the caller has not declared separate. The scan cannot tell a duplicate from
+// a neighbor — that is a reading of each candidate (`issue-fold-existing.md`) — so the command holds
+// the filing until every candidate it printed is named back with `--distinct`.
+function unacknowledged(
+	candidates: ReadonlyArray<number>,
+	distinct: ReadonlyArray<number>,
+): ReadonlyArray<number> {
+	return candidates.filter((candidate) => !distinct.includes(candidate))
+}
+
+const issue_file = { parse, labels_of, origin_problem, unacknowledged, is_same_repository }
+
+export type { FileArguments }
+export { issue_file }

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

@@ -58,7 +58,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv[0])
 }
 
-const issue_lint_cli = { run, OK_MESSAGE, USAGE }
+const issue_lint_cli = { problems, run, OK_MESSAGE, USAGE }
 
 const ARGV_OFFSET = 2