@joshuafolkken/kit 1.978.0 → 1.998.0

package/scripts/init/project-profile.ts

@@ -4,7 +4,7 @@ import { repo_origin } from '#scripts/discovery/repo-origin'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
 import { execaSync } from 'execa'
 
-type ProjectProfile = 'static' | 'node'
+type ProjectProfile = 'basic' | 'full'
 
 interface ProfileResult {
 	profile: ProjectProfile
@@ -22,11 +22,34 @@ const IGNORED_DIRECTORIES = new Set(['.git', 'node_modules', 'dist', 'build', '.
 const WEB_EXTENSIONS = new Set(['.html', '.css', '.js', '.jsx', '.mjs', '.cjs'])
 const TYPESCRIPT_EXTENSIONS = new Set(['.ts', '.tsx'])
 const PROFILE_ARG_LENGTH = 2
+// The names before joshuafolkken/kit#2829. A project that recorded one, or a script that passes one
+// to `--profile`, keeps working: each reads as the profile it was renamed to.
+const PROFILE_NAMES: Readonly<Record<string, ProjectProfile>> = {
+	basic: 'basic',
+	full: 'full',
+	static: 'basic',
+	node: 'full',
+}
 
 function parse_profile(value: unknown): ProjectProfile | undefined {
-	if (value === 'static' || value === 'node') return value
+	return typeof value === 'string' && Object.hasOwn(PROFILE_NAMES, value)
+		? PROFILE_NAMES[value]
+		: undefined
+}
+
+// The pre-rename name of each profile, which every kit with `--profile` accepts — the new one only
+// from joshuafolkken/kit#2829 on.
+const LEGACY_NAMES: Readonly<Record<ProjectProfile, string>> = { basic: 'static', full: 'node' }
 
-	return undefined
+// A `josh init` handed to the project's kit may run an older kit than the one handing off: the
+// project pinned it, or its `minimumReleaseAge` held the new release back. The pre-rename spelling
+// is the one both kits read.
+function with_legacy_profile_names(args: ReadonlyArray<string>): Array<string> {
+	return args.map((argument, index) => {
+		const profile = args[index - 1] === '--profile' ? parse_profile(argument) : undefined
+
+		return profile === undefined ? argument : LEGACY_NAMES[profile]
+	})
 }
 
 function is_profile_pair(args: ReadonlyArray<string>): boolean {
@@ -35,14 +58,14 @@ function is_profile_pair(args: ReadonlyArray<string>): boolean {
 
 function requested_profile(
 	args: ReadonlyArray<string>,
-	usage = 'josh init [--profile static|node]',
+	usage = 'josh init [--profile basic|full]',
 ): ProjectProfile | undefined {
 	if (args.length === 0) return undefined
 	if (!is_profile_pair(args)) throw new Error(`Usage: ${usage}`)
 
 	const profile = parse_profile(args[1])
 	if (profile !== undefined) return profile
-	throw new Error('Profile must be static or node')
+	throw new Error('Profile must be basic or full')
 }
 
 function read_manifest(root: string): Record<string, unknown> | undefined {
@@ -72,8 +95,8 @@ function has_build_script(value: unknown): boolean {
 }
 
 // kit itself is not evidence of a Node toolchain: `pnpm add -D @joshuafolkken/kit` before
-// `josh init` is the documented order, and it must still leave an `index.html` site static
-// (joshuafolkken/kit#2693).
+// `josh init` is the documented order, and it must still leave an `index.html` site on the basic
+// profile (joshuafolkken/kit#2693).
 function has_project_dependencies(value: unknown): boolean {
 	if (!is_record(value)) return false
 
@@ -85,20 +108,20 @@ function inferred_profile(manifest: Record<string, unknown>): ProfileResult {
 		has_project_dependencies(manifest['dependencies']) ||
 		has_project_dependencies(manifest['devDependencies'])
 	) {
-		return { profile: 'node', reason: 'package dependencies' }
+		return { profile: 'full', reason: 'package dependencies' }
 	}
 
 	if (has_build_script(manifest['scripts'])) {
-		return { profile: 'node', reason: 'build or dev script' }
+		return { profile: 'full', reason: 'build or dev script' }
 	}
 
-	return { profile: 'static', reason: 'metadata-only package.json' }
+	return { profile: 'basic', reason: 'metadata-only package.json' }
 }
 
 function resolve_profile(root: string, requested?: ProjectProfile): ProfileResult {
 	if (requested !== undefined) return { profile: requested, reason: 'explicit --profile' }
 	const manifest = read_manifest(root)
-	if (manifest === undefined) return { profile: 'static', reason: 'no package.json' }
+	if (manifest === undefined) return { profile: 'basic', reason: 'no package.json' }
 	const profile = recorded_profile(manifest)
 	if (profile !== undefined) return { profile, reason: 'package.json josh.profile' }
 
@@ -157,6 +180,12 @@ function inspect_project(root: string, requested?: ProjectProfile): ProjectShape
 	return { ...profile, ...files, has_git, has_github: has_git && has_github_remote(root) }
 }
 
-const project_profile = { resolve_profile, inspect_project, requested_profile }
+const project_profile = {
+	parse_profile,
+	resolve_profile,
+	inspect_project,
+	requested_profile,
+	with_legacy_profile_names,
+}
 export { project_profile }
 export type { ProjectProfile, ProjectShape }

package/scripts/init/session-language-environment.ts

@@ -0,0 +1,83 @@
+// `josh init` seeds `JOSH_SESSION_LANG` in `.env` from the OS locale, so a newly adopting user starts
+// in their own language (joshuafolkken/kit#2818). A project already using kit keeps its language: the
+// session language takes effect only through the `session:lang` hook, so a project whose
+// `.claude/settings.json` already wires it is left alone, and an existing `.env` value — the `export`
+// form included — is never touched. The unset default stays `ja`.
+
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { session_language } from '#scripts/josh/session-language'
+import type { FileAction } from './init-actions'
+import { PROJECT_ROOT } from './init-paths'
+
+const ENV_FILE = '.env'
+const CLAUDE_SETTINGS_PATH = path.join('.claude', 'settings.json')
+const SESSION_LANG_HOOK = 'session:lang'
+// POSIX precedence: `LC_ALL` overrides `LC_MESSAGES`, which overrides `LANG`.
+const LOCALE_KEYS = ['LC_ALL', 'LC_MESSAGES', 'LANG'] as const
+const JAPANESE_PREFIX = 'ja'
+const NON_JAPANESE_LANG = 'en'
+const KEY_LINE_PATTERN = new RegExp(
+	String.raw`^\s*(?:export\s+)?${session_language.ENV_KEY}\s*=`,
+	'mu',
+)
+
+type LocaleEnvironment = Readonly<Record<string, string | undefined>>
+
+function lang_from_locale(environment: LocaleEnvironment): string {
+	const locale = LOCALE_KEYS.map((key) => environment[key]?.trim()).find(Boolean) ?? ''
+
+	return locale.toLowerCase().startsWith(JAPANESE_PREFIX) ? JAPANESE_PREFIX : NON_JAPANESE_LANG
+}
+
+// A value the user already exported is their explicit choice, so it wins over the locale.
+function resolve_lang(environment: LocaleEnvironment): string {
+	const exported = environment[session_language.ENV_KEY]?.trim()
+	if (exported) return exported
+
+	return lang_from_locale(environment)
+}
+
+function session_lang_line(lang: string): string {
+	return `${session_language.ENV_KEY}=${lang}\n`
+}
+
+function merge_session_lang(existing: string, lang: string): string {
+	if (KEY_LINE_PATTERN.test(existing)) return existing
+	const separator = existing.length === 0 || existing.endsWith('\n') ? '' : '\n'
+
+	return `${existing}${separator}${session_lang_line(lang)}`
+}
+
+function is_session_lang_hooked(project_root: string): boolean {
+	const settings_path = path.join(project_root, CLAUDE_SETTINGS_PATH)
+
+	return (
+		existsSync(settings_path) && readFileSync(settings_path, 'utf8').includes(SESSION_LANG_HOOK)
+	)
+}
+
+// Built before `init` writes the AI files, so the hook check reads the project as it was.
+function build_session_lang_actions(
+	environment: LocaleEnvironment = process.env,
+	project_root: string = PROJECT_ROOT,
+): ReadonlyArray<FileAction> {
+	if (is_session_lang_hooked(project_root)) return []
+	const lang = resolve_lang(environment)
+
+	return [
+		{
+			dest: ENV_FILE,
+			create: () => session_lang_line(lang),
+			merge: (existing) => merge_session_lang(existing, lang),
+		},
+	]
+}
+
+const session_language_environment = {
+	build_session_lang_actions,
+	lang_from_locale,
+	merge_session_lang,
+}
+
+export { session_language_environment }

package/scripts/init/start-exec.ts

@@ -0,0 +1,28 @@
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
+import { execaSync } from 'execa'
+
+// The three spawn shapes every `josh start` step uses, shared by `start-steps.ts`, the setup pull
+// request step and the `josh init` hint so none of them keeps a copy of its own.
+function succeeds(command: string, args: ReadonlyArray<string>, root: string): boolean {
+	return execaSync(command, args, { cwd: root, reject: false }).exitCode === 0
+}
+
+function read_output(
+	command: string,
+	args: ReadonlyArray<string>,
+	root: string,
+): string | undefined {
+	const result = execaSync(command, args, { cwd: root, reject: false })
+
+	return result.exitCode === 0 ? result.stdout.trim() : undefined
+}
+
+// Every step spawned here dials GitHub directly, past a scanner's loopback proxy, the same as every
+// other `gh` spawn under scripts/ (joshuafolkken/kit#2436); a local `git` step is unaffected by it.
+function run(command: string, args: ReadonlyArray<string>, root: string): void {
+	execaSync(command, args, { ...git_gh_exec.direct_environment(), cwd: root, stdio: 'inherit' })
+}
+
+const start_exec = { succeeds, read_output, run }
+
+export { start_exec }

package/scripts/init/start-plan.ts

@@ -1,4 +1,5 @@
 import type { ProjectProfile } from './project-profile'
+import { start_setup_pr } from './start-setup-pr'
 
 type Visibility = 'private' | 'public'
 
@@ -9,7 +10,7 @@ interface StartOptions {
 	visibility: Visibility
 }
 
-type StartStep = 'git_init' | 'initialize' | 'commit' | 'repository' | 'labels'
+type StartStep = 'git_init' | 'initialize' | 'commit' | 'repository' | 'labels' | 'setup_pr'
 
 interface GitState {
 	has_git: boolean
@@ -17,6 +18,7 @@ interface GitState {
 	has_origin: boolean
 	branch: string | undefined
 	has_commits: boolean
+	has_kit_committed: boolean
 }
 
 interface StepPlan {
@@ -47,14 +49,33 @@ const STEP_LABELS: Readonly<Record<StartStep, string>> = {
 	commit: 'Commit every file as the initial commit',
 	repository: 'Create the GitHub repository and push main',
 	labels: 'Add the workflow and release-classification labels the repository is missing',
+	setup_pr: 'Open an Issue and a pull request that add the kit setup to main',
 }
 
+// The GitHub write steps `--yes` alone never consents to.
+const GITHUB_WRITE_STEPS: ReadonlySet<StartStep> = new Set(['repository', 'setup_pr'])
+
 function refused(refusal: string): StepPlan {
 	return { steps: [], refusal }
 }
 
-// A repository that already has a history keeps it: nothing is committed on the user's behalf, and
-// only `main` is pushed, because the Issue workflow branches from and merges into it.
+// Main already has a history but not kit's setup, so the setup reaches main the way every later change
+// does — an Issue and a pull request a person merges — rather than a commit on main
+// (joshuafolkken/kit#2816). On another branch the pull request would not be based on main, so it waits
+// — except the setup branch a failed hook left checked out, where a re-run resumes. Once kit is
+// committed there, nothing is left for the step, so a later run on that branch plans none.
+function needs_setup_pr(state: GitState): boolean {
+	if (!state.has_commits || state.has_kit_committed) return false
+
+	return state.branch === DEFAULT_BRANCH || start_setup_pr.is_setup_branch(state.branch)
+}
+
+function with_setup_pr(steps: ReadonlyArray<StartStep>, state: GitState): StepPlan {
+	return { steps: needs_setup_pr(state) ? [...steps, 'setup_pr'] : steps, refusal: undefined }
+}
+
+// A repository that already has a history keeps it: nothing is committed on main on the user's
+// behalf, and only `main` is pushed, because the Issue workflow branches from and merges into it.
 function existing_git_steps(state: GitState): StepPlan {
 	if (!state.has_commits) return { steps: FULL_STEPS.slice(1), refusal: undefined }
 
@@ -64,14 +85,15 @@ function existing_git_steps(state: GitState): StepPlan {
 		)
 	}
 
-	return { steps: ['initialize', 'repository', 'labels'], refusal: undefined }
+	return with_setup_pr(['initialize', 'repository', 'labels'], state)
 }
 
-// An existing GitHub origin is never replaced or pushed to: only the additive steps run. Any other
-// origin is refused here, before the first write — `gh repo create --remote origin` cannot add a
-// remote that already exists, so the run would otherwise fail after initializing the directory.
+// An existing GitHub origin is never replaced, and main is never pushed to: only the additive steps
+// run, plus the setup pull request while main lacks kit. Any other origin is refused here, before the
+// first write — `gh repo create --remote origin` cannot add a remote that already exists, so the run
+// would otherwise fail after initializing the directory.
 function plan_steps(state: GitState): StepPlan {
-	if (state.has_github) return { steps: ['initialize', 'labels'], refusal: undefined }
+	if (state.has_github) return with_setup_pr(['initialize', 'labels'], state)
 
 	if (state.has_origin) {
 		return refused(
@@ -96,22 +118,22 @@ function interaction_of(options: StartOptions, is_tty: boolean): Verdict<Interac
 }
 
 // `--yes` accepts the detected defaults, never the creation of a public-facing resource: an
-// unattended run creates and pushes a repository only when `--github` asks for it by name.
+// unattended run creates a repository, pushes, or opens the setup Issue and pull request only when
+// `--github` asks for it by name.
 function github_consent(
 	steps: ReadonlyArray<StartStep>,
 	options: StartOptions,
 	interaction: Interaction,
 ): Verdict<Consent> {
-	if (!steps.includes('repository') || options.is_github) {
-		return { value: 'granted', refusal: undefined }
-	}
+	const is_github_write = steps.some((step) => GITHUB_WRITE_STEPS.has(step))
 
+	if (!is_github_write || options.is_github) return { value: 'granted', refusal: undefined }
 	if (interaction === 'interactive') return { value: 'ask', refusal: undefined }
 
 	return {
 		value: undefined,
 		refusal:
-			'josh start --yes does not create a GitHub repository or push. Add --github to create one, or run josh init to set up without GitHub.',
+			'josh start --yes does not write to GitHub (create a repository, push, or open the setup pull request). Add --github to allow it, or run josh init to set up without GitHub.',
 	}
 }
 

package/scripts/init/start-prompt.ts

@@ -3,22 +3,25 @@ import { stdin as input, stdout as output } from 'node:process'
 import { createInterface, type Interface } from 'node:readline/promises'
 import { ask_yes_no_simple } from '#scripts/git/git-prompt'
 import { project_profile, type ProjectProfile, type ProjectShape } from './project-profile'
-import type { Consent, StartOptions } from './start-plan'
+import type { Consent, StartOptions, StartStep } from './start-plan'
 
 interface Choices {
 	options: StartOptions
 	shape: ProjectShape
 	consent: Consent
 	root: string
+	steps: ReadonlyArray<StartStep>
 }
 
 const DECLINED =
-	'Stopped before creating the GitHub repository. Nothing was changed. Run josh init to set up without GitHub.'
+	'Stopped before writing to GitHub. Nothing was changed. Run josh init to set up without GitHub.'
+const SETUP_PR_QUESTION =
+	'Open an Issue and a pull request on GitHub that add the kit setup to main? (y/n): '
 
 // The detected profile is the default, so pressing Enter accepts it; the reason is shown because an
 // ambiguous project is exactly the case this question exists for.
 async function ask_profile(prompt: Interface, shape: ProjectShape): Promise<ProjectProfile> {
-	const question = `Profile — static or node [${shape.profile}, ${shape.reason}]: `
+	const question = `Profile — basic or full [${shape.profile}, ${shape.reason}]: `
 	const raw_answer = await prompt.question(question)
 	const answer = raw_answer.trim()
 	if (answer.length === 0) return shape.profile
@@ -26,16 +29,27 @@ async function ask_profile(prompt: Interface, shape: ProjectShape): Promise<Proj
 	return project_profile.requested_profile(['--profile', answer]) ?? shape.profile
 }
 
-async function ask_repository(prompt: Interface, choices: Choices): Promise<void> {
-	const name = path.basename(choices.root)
-	const question = `Create a ${choices.options.visibility} GitHub repository "${name}" and push main? (y/n): `
-
+async function ask_or_stop(prompt: Interface, question: string): Promise<void> {
 	if (!(await ask_yes_no_simple(prompt, question))) throw new Error(DECLINED)
 }
 
+// One question per GitHub write the plan holds, every one asked before the first step runs.
+async function ask_github_writes(prompt: Interface, choices: Choices): Promise<void> {
+	if (choices.steps.includes('repository')) {
+		const name = path.basename(choices.root)
+
+		await ask_or_stop(
+			prompt,
+			`Create a ${choices.options.visibility} GitHub repository "${name}" and push main? (y/n): `,
+		)
+	}
+
+	if (choices.steps.includes('setup_pr')) await ask_or_stop(prompt, SETUP_PR_QUESTION)
+}
+
 async function ask_choices(prompt: Interface, choices: Choices): Promise<ProjectProfile> {
 	const profile = choices.options.profile ?? (await ask_profile(prompt, choices.shape))
-	if (choices.consent === 'ask') await ask_repository(prompt, choices)
+	if (choices.consent === 'ask') await ask_github_writes(prompt, choices)
 
 	return profile
 }

package/scripts/init/start-setup-pr.ts

@@ -0,0 +1,138 @@
+import { git_gh_api_path } from '#scripts/git/git-gh-api-path'
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
+import { git_gh_issue_write } from '#scripts/git/git-gh-issue-write'
+import { git_issue, type IssueInfo } from '#scripts/git/git-issue'
+import { git_pr } from '#scripts/git/git-pr'
+import { github_issue_url } from '#scripts/git/github-issue-url'
+import { IGNORE_FOR_RELEASE_LABEL } from '#scripts/git/issue-labels'
+import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
+import { kit_written_paths } from './kit-written-paths'
+import { start_exec } from './start-exec'
+
+const SETUP_TITLE = `Set up ${KIT_PACKAGE_NAME}`
+const SETUP_BODY = [
+	`Adds the files \`josh start\` wrote while setting up ${KIT_PACKAGE_NAME}, so main carries the`,
+	'rules, settings and workflows every later Issue is run with. Only the files kit wrote are in the',
+	'pull request; anything else in the working tree is left as it was.',
+].join('\n')
+const NOTHING_TO_COMMIT = 'The kit setup has no changes to commit, so no pull request was opened.'
+const OPEN_SETUP_ISSUES_QUERY = `?state=open&labels=${IGNORE_FOR_RELEASE_LABEL}&per_page=100`
+const FIRST_SETUP_ISSUE_FILTER = `[.[] | select(.title == "${SETUP_TITLE}") | .number][0] // empty`
+
+function lines_of(output: string | undefined): Array<string> {
+	return (output ?? '').split('\n').filter((line) => line.length > 0)
+}
+
+function setup_issue(issue_number: string): IssueInfo {
+	return git_issue.parse(`${SETUP_TITLE} #${issue_number}`)
+}
+
+// The Issue number when `branch` is the branch an earlier `josh start` created for the setup pull
+// request — the branch a failed commit or push leaves checked out, so a re-run resumes there.
+function setup_branch_number(branch: string | undefined): string | undefined {
+	const issue_number = branch === undefined ? undefined : git_issue.branch_number(branch)
+
+	if (issue_number === undefined) return undefined
+
+	return setup_issue(issue_number).branch_name === branch ? issue_number : undefined
+}
+
+function is_setup_branch(branch: string | undefined): boolean {
+	return setup_branch_number(branch) !== undefined
+}
+
+// Untracked files the ignore rules let through, plus tracked files the setup changed — two plain
+// listings, so nothing has to be parsed out of `git status`. Every kit path is ASCII, so git's
+// quoting of other names never hides one.
+function changed_paths(root: string): Array<string> {
+	const untracked = start_exec.read_output(
+		'git',
+		['ls-files', '--others', '--exclude-standard'],
+		root,
+	)
+	const modified = start_exec.read_output('git', ['diff', '--name-only', 'HEAD'], root)
+
+	return [...lines_of(untracked), ...lines_of(modified)]
+}
+
+// The Issue carries the release classification the pull request is opened with, so the PR step finds
+// one without a person adding it (joshuafolkken/kit#2816).
+function file_setup_issue(): string {
+	const request = git_gh_issue_write.issue_create_request({
+		title: SETUP_TITLE,
+		body: SETUP_BODY,
+		labels: [IGNORE_FOR_RELEASE_LABEL],
+	})
+	const url = git_gh_exec.exec_gh_api_sync(request)
+	const issue_number = github_issue_url.parse(url)?.issue_number
+
+	if (issue_number === undefined) throw new Error(`Could not read the Issue number from ${url}`)
+
+	return issue_number
+}
+
+function open_setup_issue_number(): string | undefined {
+	const issue_number = git_gh_exec.exec_gh_api_sync({
+		path: `${git_gh_api_path.issues_api_path()}${OPEN_SETUP_ISSUES_QUERY}`,
+		jq_filter: FIRST_SETUP_ISSUE_FILTER,
+	})
+
+	return issue_number.length > 0 ? issue_number : undefined
+}
+
+// A re-run after a failed hook reuses what the failed run made — the branch it left checked out, or
+// the setup Issue still open — so no Issue is filed twice.
+function resolve_issue(branch: string | undefined): IssueInfo {
+	const reused = setup_branch_number(branch) ?? open_setup_issue_number()
+
+	return setup_issue(reused ?? file_setup_issue())
+}
+
+// An existing setup branch seen from another branch is not switched to: the setup just rewrote kit's
+// files in this working tree, and a checkout would refuse to overwrite them part-way through.
+function switch_to(branch: string, current: string | undefined, root: string): void {
+	if (current === branch) return
+
+	const reference = `refs/heads/${branch}`
+
+	if (start_exec.succeeds('git', ['rev-parse', '--verify', '--quiet', reference], root)) {
+		throw new Error(
+			`The setup branch ${branch} already exists. Run git switch ${branch}, then josh start again.`,
+		)
+	}
+
+	start_exec.run('git', ['switch', '--create', branch], root)
+}
+
+// The paths are named on the commit as well as on the add, so anything the user had staged before
+// stays out of the setup commit. The project's own hooks run, as on every other commit.
+function commit_kit_paths(paths: ReadonlyArray<string>, issue: IssueInfo, root: string): void {
+	if (paths.length === 0) return
+
+	start_exec.run('git', ['add', '--', ...paths], root)
+	start_exec.run('git', ['commit', '--message', issue.commit_message, '--', ...paths], root)
+}
+
+// Issue → branch → only kit's files committed → push → pull request. The merge is left to a person:
+// it is the one step that changes main.
+async function open(root: string): Promise<void> {
+	const paths = kit_written_paths.select(changed_paths(root))
+
+	if (paths.length === 0) {
+		console.info(NOTHING_TO_COMMIT)
+
+		return
+	}
+
+	const current = start_exec.read_output('git', ['symbolic-ref', '--short', 'HEAD'], root)
+	const issue = resolve_issue(current)
+
+	switch_to(issue.branch_name, current, root)
+	commit_kit_paths(paths, issue, root)
+	start_exec.run('git', ['push', '--set-upstream', 'origin', issue.branch_name], root)
+	await git_pr.create_with_issue_info(issue)
+}
+
+const start_setup_pr = { open, changed_paths, is_setup_branch }
+
+export { start_setup_pr }

package/scripts/init/start-steps.ts

@@ -1,12 +1,13 @@
 import path from 'node:path'
-import { git_gh_exec } from '#scripts/git/git-gh-exec'
 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'
 import { PACKAGE_DIR } from './init-paths'
+import { kit_setup_state } from './kit-setup-state'
 import type { ProjectProfile, ProjectShape } from './project-profile'
+import { start_exec } from './start-exec'
 import { start_plan, type GitState, type StartStep, type Visibility } from './start-plan'
+import { start_setup_pr } from './start-setup-pr'
 
 interface StepContext {
 	root: string
@@ -20,38 +21,28 @@ const GH_INSTALL_HINT =
 const GH_AUTH_HINT =
 	'GitHub CLI is not signed in. Run gh auth login, then run josh start again. Nothing was changed.'
 
-function succeeds(command: string, args: ReadonlyArray<string>, root: string): boolean {
-	return execaSync(command, args, { cwd: root, reject: false }).exitCode === 0
-}
-
-function read_output(
-	command: string,
-	args: ReadonlyArray<string>,
-	root: string,
-): string | undefined {
-	const result = execaSync(command, args, { cwd: root, reject: false })
-
-	return result.exitCode === 0 ? result.stdout.trim() : undefined
-}
-
-// Every step spawned here dials GitHub directly, past a scanner's loopback proxy, the same as every
-// other `gh` spawn under scripts/ (joshuafolkken/kit#2436); a local `git` step is unaffected by it.
-function run(command: string, args: ReadonlyArray<string>, root: string): void {
-	execaSync(command, args, { ...git_gh_exec.direct_environment(), cwd: root, stdio: 'inherit' })
-}
+const { succeeds, read_output, run } = start_exec
 
 function read_git_state(root: string, shape: ProjectShape): GitState {
 	const { has_git, has_github } = shape
 
 	if (!has_git) {
-		return { has_git, has_github, has_origin: false, branch: undefined, has_commits: false }
+		return {
+			has_git,
+			has_github,
+			has_origin: false,
+			branch: undefined,
+			has_commits: false,
+			has_kit_committed: false,
+		}
 	}
 
 	const has_origin = succeeds('git', ['remote', 'get-url', 'origin'], root)
 	const branch = read_output('git', ['symbolic-ref', '--short', 'HEAD'], root)
 	const has_commits = succeeds('git', ['rev-parse', '--verify', '--quiet', 'HEAD'], root)
+	const has_kit_committed = kit_setup_state.is_kit_committed(root)
 
-	return { has_git, has_github, has_origin, branch, has_commits }
+	return { has_git, has_github, has_origin, branch, has_commits, has_kit_committed }
 }
 
 // Every step talks to GitHub, so the CLI is checked before the first write rather than at the step
@@ -82,7 +73,7 @@ function initialize(context: StepContext): void {
 function commit_all(context: StepContext): void {
 	run('git', ['add', '--all'], context.root)
 	// The first commit of a new repository has no branch to come from, so the hook that keeps commits
-	// off main — installed by the initialize step in a node project — would refuse the only commit
+	// off main — installed by the initialize step in a full project — would refuse the only commit
 	// that has to land there.
 	run('git', ['commit', '--no-verify', '--message', 'Initial commit'], context.root)
 	// A repository created by an older `git init` may name its unborn branch `master`.
@@ -103,21 +94,30 @@ function add_missing_labels(): void {
 	repository_labels.ensure_labels('{owner}/{repo}')
 }
 
-const STEP_ACTIONS: Readonly<Record<StartStep, (context: StepContext) => void>> = {
+// Main already has a history here, so the setup reaches it the way every other change does: through
+// an Issue and a pull request a person merges (joshuafolkken/kit#2816).
+async function open_setup_pull_request(context: StepContext): Promise<void> {
+	await start_setup_pr.open(context.root)
+}
+
+type StepAction = (context: StepContext) => void | Promise<void>
+
+const STEP_ACTIONS: Readonly<Record<StartStep, StepAction>> = {
 	git_init: create_git_repository,
 	initialize,
 	commit: commit_all,
 	repository: create_github_repository,
 	labels: add_missing_labels,
+	setup_pr: open_setup_pull_request,
 }
 
-function run_step(
+async function run_step(
 	step: StartStep,
 	context: StepContext,
 	completed: ReadonlyArray<StartStep>,
-): void {
+): Promise<void> {
 	try {
-		STEP_ACTIONS[step](context)
+		await STEP_ACTIONS[step](context)
 	} catch (error) {
 		const cause = error instanceof Error ? error.message : String(error)
 
@@ -125,12 +125,12 @@ function run_step(
 	}
 }
 
-function run_steps(steps: ReadonlyArray<StartStep>, context: StepContext): void {
+async function run_steps(steps: ReadonlyArray<StartStep>, context: StepContext): Promise<void> {
 	for (const [index, step] of steps.entries()) {
 		const position = `${String(index + 1)}/${String(steps.length)}`
 
 		console.info(`\n[${position}] ${start_plan.STEP_LABELS[step]}`)
-		run_step(step, context, steps.slice(0, index))
+		await run_step(step, context, steps.slice(0, index))
 	}
 }