@joshuafolkken/kit 1.947.0 → 1.957.0

package/scripts/git/stash-sweep-lock.ts

@@ -1,123 +1,18 @@
-import { randomUUID } from 'node:crypto'
-import { linkSync, renameSync, rmSync } from 'node:fs'
-import { setTimeout as sleep } from 'node:timers/promises'
-import { process_identity } from '#scripts/josh/process-identity'
-import { stamp_file } from '#scripts/josh/stamp-file'
-import { git_common_directory } from './git-common-directory'
+import { repository_lock } from './repository-lock'
 
 // One stash sweep at a time per repository (joshuafolkken/kit#2701). The stash is a single stack every
 // work tree shares, and a `backlogrun` runs one sweep per lane seat at once: two sweeps that each
 // resolve the same entry to `stash@{n}` and drop it would have the second drop land on whichever entry
-// moved into that position, and two that carry the same ledger lines would both append them. The lock
-// is keyed on the git common directory, so every work tree of one repository contends for one record.
+// moved into that position, and two that carry the same ledger lines would both append them. The
+// locking itself is `repository-lock.ts`, shared with the work-tree writes (joshuafolkken/kit#2736).
 
 const LOCK_PREFIX = 'josh-stash-sweep-lock-'
 // The locked phase is local git and one file append per entry, so a holder finishes in well under the
 // wait; the cap only bounds a holder that hung, and a sweep that gives up keeps its entries.
-const POLL_INTERVAL_MS = 200
 const MAX_WAIT_MS = 30_000
 
-interface LockOwner {
-	pid: number
-	process_start?: string
-}
-
 function lock_path(cwd: string = process.cwd()): string {
-	return stamp_file.stamp_path(LOCK_PREFIX, git_common_directory.repository(cwd) ?? cwd)
-}
-
-type IsGone = (owner: LockOwner) => boolean
-
-function parse_owner(raw: string | undefined): LockOwner | undefined {
-	if (raw === undefined) return undefined
-
-	try {
-		return JSON.parse(raw) as LockOwner
-	} catch {
-		return undefined
-	}
-}
-
-function read_owner(target: string): LockOwner | undefined {
-	return parse_owner(stamp_file.read_stamp_text(target))
-}
-
-function is_owner_gone(owner: LockOwner): boolean {
-	return process_identity.is_same_process(owner.pid, owner.process_start) === false
-}
-
-// Put back a record that turned out not to be the stale one. `linkSync` refuses an existing path, so
-// a lock someone claimed in the meantime is never overwritten.
-function restore(aside: string, target: string): void {
-	try {
-		linkSync(aside, target)
-	} catch {
-		// Another claim already holds the path; the record set aside is dropped below.
-	}
-}
-
-// The record's text when its owner is certainly gone, else `undefined`.
-function stale_record(target: string, is_gone: IsGone): string | undefined {
-	const raw = stamp_file.read_stamp_text(target)
-	const owner = parse_owner(raw)
-
-	return owner !== undefined && is_gone(owner) ? raw : undefined
-}
-
-// The path the record was moved to, or `undefined` when another sweep moved it first.
-function move_aside(target: string): string | undefined {
-	const aside = `${target}.${String(process.pid)}.${randomUUID()}`
-
-	try {
-		renameSync(target, aside)
-
-		return aside
-	} catch {
-		return undefined
-	}
-}
-
-// A record whose process is certainly gone is a crashed sweep's, and is cleared before the claim; an
-// unreadable record or an uncertain answer is left in place, since clearing a live holder's lock is the
-// very race the lock exists to close. **The clear is a rename, then a compare**: two sweeps can both
-// judge the same record stale, and the slower one's plain remove would delete the lock the faster one
-// had just claimed. Renaming moves exactly one file aside atomically, and only a record byte-identical
-// to the one judged stale is discarded — any other is a fresh claim and goes back.
-function clear_stale(target: string, is_gone: IsGone = is_owner_gone): void {
-	const raw = stale_record(target, is_gone)
-
-	if (raw === undefined) return
-
-	const aside = move_aside(target)
-
-	if (aside === undefined) return
-	if (stamp_file.read_stamp_text(aside) !== raw) restore(aside, target)
-	rmSync(aside, { force: true })
-}
-
-function claim(target: string): boolean {
-	clear_stale(target)
-
-	return stamp_file.create_stamp(target, process_identity.own_fields())
-}
-
-function release(target: string): void {
-	const owner = read_owner(target)
-
-	if (owner !== undefined && process_identity.is_own_process(owner.pid, owner.process_start)) {
-		stamp_file.remove_stamp(target)
-	}
-}
-
-async function acquire(target: string, max_wait_ms: number): Promise<boolean> {
-	const deadline = Date.now() + max_wait_ms
-
-	while (!claim(target)) {
-		if (Date.now() >= deadline) return false
-		await sleep(POLL_INTERVAL_MS)
-	}
-
-	return true
+	return repository_lock.lock_path(LOCK_PREFIX, cwd)
 }
 
 // Runs `work` holding the lock and answers its result, or `undefined` without running it when another
@@ -127,15 +22,9 @@ async function with_lock<T>(
 	target: string = lock_path(),
 	max_wait_ms: number = MAX_WAIT_MS,
 ): Promise<T | undefined> {
-	if (!(await acquire(target, max_wait_ms))) return undefined
-
-	try {
-		return await work()
-	} finally {
-		release(target)
-	}
+	return await repository_lock.with_lock(work, target, max_wait_ms)
 }
 
-const stash_sweep_lock = { clear_stale, lock_path, with_lock }
+const stash_sweep_lock = { clear_stale: repository_lock.clear_stale, lock_path, with_lock }
 
 export { stash_sweep_lock }

package/scripts/init/project-profile.ts

@@ -29,12 +29,16 @@ function parse_profile(value: unknown): ProjectProfile | undefined {
 	return undefined
 }
 
-function requested_profile(args: ReadonlyArray<string>): ProjectProfile | undefined {
-	if (args.length === 0) return undefined
+function is_profile_pair(args: ReadonlyArray<string>): boolean {
+	return args.length === PROFILE_ARG_LENGTH && args[0] === '--profile'
+}
 
-	if (args.length !== PROFILE_ARG_LENGTH || args[0] !== '--profile') {
-		throw new Error('Usage: josh init [--profile static|node]')
-	}
+function requested_profile(
+	args: ReadonlyArray<string>,
+	usage = 'josh init [--profile static|node]',
+): 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

package/scripts/init/start-plan.ts

@@ -0,0 +1,145 @@
+import type { ProjectProfile } from './project-profile'
+
+type Visibility = 'private' | 'public'
+
+interface StartOptions {
+	profile: ProjectProfile | undefined
+	is_yes: boolean
+	is_github: boolean
+	visibility: Visibility
+}
+
+type StartStep = 'git_init' | 'initialize' | 'commit' | 'repository' | 'labels'
+
+interface GitState {
+	has_git: boolean
+	has_github: boolean
+	has_origin: boolean
+	branch: string | undefined
+	has_commits: boolean
+}
+
+interface StepPlan {
+	steps: ReadonlyArray<StartStep>
+	refusal: string | undefined
+}
+
+type Interaction = 'interactive' | 'unattended'
+type Consent = 'granted' | 'ask'
+
+interface Verdict<T> {
+	value: T | undefined
+	refusal: string | undefined
+}
+
+const DEFAULT_BRANCH = 'main'
+const FULL_STEPS: ReadonlyArray<StartStep> = [
+	'git_init',
+	'initialize',
+	'commit',
+	'repository',
+	'labels',
+]
+
+const STEP_LABELS: Readonly<Record<StartStep, string>> = {
+	git_init: 'Create a Git repository on main',
+	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',
+}
+
+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.
+function existing_git_steps(state: GitState): StepPlan {
+	if (!state.has_commits) return { steps: FULL_STEPS.slice(1), refusal: undefined }
+
+	if (state.branch !== DEFAULT_BRANCH) {
+		return refused(
+			`josh start pushes ${DEFAULT_BRANCH}, but this repository is on ${state.branch ?? 'a detached HEAD'}. Switch to ${DEFAULT_BRANCH}, or run josh init to set up without GitHub.`,
+		)
+	}
+
+	return { steps: ['initialize', 'repository', 'labels'], refusal: undefined }
+}
+
+// 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.
+function plan_steps(state: GitState): StepPlan {
+	if (state.has_github) return { steps: ['initialize', 'labels'], refusal: undefined }
+
+	if (state.has_origin) {
+		return refused(
+			'josh start creates the GitHub repository as origin, but this repository already has an origin that is not on GitHub. Remove or rename it, or run josh init to set up without GitHub.',
+		)
+	}
+
+	if (state.has_git) return existing_git_steps(state)
+
+	return { steps: FULL_STEPS, refusal: undefined }
+}
+
+function interaction_of(options: StartOptions, is_tty: boolean): Verdict<Interaction> {
+	if (options.is_yes) return { value: 'unattended', refusal: undefined }
+	if (is_tty) return { value: 'interactive', refusal: undefined }
+
+	return {
+		value: undefined,
+		refusal:
+			'josh start needs a terminal to confirm its choices. Pass --yes to accept the detected profile, and --github to create the GitHub repository.',
+	}
+}
+
+// `--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.
+function github_consent(
+	steps: ReadonlyArray<StartStep>,
+	options: StartOptions,
+	interaction: Interaction,
+): Verdict<Consent> {
+	if (!steps.includes('repository') || 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.',
+	}
+}
+
+// What a failed run prints, so the user can tell how far it got before deciding how to resume.
+function progress_report(
+	failed: StartStep,
+	completed: ReadonlyArray<StartStep>,
+	cause: string,
+): string {
+	const done =
+		completed.length === 0 ? 'nothing' : completed.map((step) => STEP_LABELS[step]).join('; ')
+
+	return `josh start stopped at: ${STEP_LABELS[failed]}\nCompleted: ${done}\nCause: ${cause}`
+}
+
+function plan_summary(steps: ReadonlyArray<StartStep>): string {
+	const lines = steps.map((step, index) => `  ${String(index + 1)}. ${STEP_LABELS[step]}`)
+
+	return ['josh start will:', ...lines].join('\n')
+}
+
+const start_plan = {
+	plan_steps,
+	interaction_of,
+	github_consent,
+	progress_report,
+	plan_summary,
+	STEP_LABELS,
+}
+export { start_plan }
+export type { Consent, GitState, Interaction, StartOptions, StartStep, StepPlan, Visibility }

package/scripts/init/start-prompt.ts

@@ -0,0 +1,55 @@
+import path from 'node:path'
+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'
+
+interface Choices {
+	options: StartOptions
+	shape: ProjectShape
+	consent: Consent
+	root: string
+}
+
+const DECLINED =
+	'Stopped before creating the GitHub repository. Nothing was changed. Run josh init to set up without GitHub.'
+
+// 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 raw_answer = await prompt.question(question)
+	const answer = raw_answer.trim()
+	if (answer.length === 0) return shape.profile
+
+	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): `
+
+	if (!(await ask_yes_no_simple(prompt, question))) throw new Error(DECLINED)
+}
+
+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)
+
+	return profile
+}
+
+async function confirm_choices(choices: Choices): Promise<ProjectProfile> {
+	const prompt = createInterface({ input, output })
+
+	try {
+		return await ask_choices(prompt, choices)
+	} finally {
+		prompt.close()
+	}
+}
+
+const start_prompt = { confirm_choices }
+export { start_prompt }
+export type { Choices }

package/scripts/init/start-steps.ts

@@ -0,0 +1,167 @@
+import path from 'node:path'
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
+import { WORKFLOW_LABELS } from '#scripts/git/issue-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 type { ProjectProfile, ProjectShape } from './project-profile'
+import { start_plan, type GitState, type StartStep, type Visibility } from './start-plan'
+
+interface StepContext {
+	root: string
+	profile: ProjectProfile
+	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 =
+	'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' })
+}
+
+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 }
+	}
+
+	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)
+
+	return { has_git, has_github, has_origin, branch, has_commits }
+}
+
+// Every step talks to GitHub, so the CLI is checked before the first write rather than at the step
+// that needs it — a missing `gh` then leaves the directory exactly as it was.
+function github_cli_refusal(root: string): string | undefined {
+	if (!succeeds('gh', ['--version'], root)) return GH_INSTALL_HINT
+	if (!succeeds('gh', ['auth', 'status'], root)) return GH_AUTH_HINT
+
+	return undefined
+}
+
+// `josh init` refuses to run inside the kit source repository by printing and setting the exit code
+// rather than throwing, so its step would pass and the later steps would commit and publish the
+// source repository. The same check is raised before the first write instead.
+function self_run_refusal(root: string): string | undefined {
+	return self_sync_guard.self_sync_refusal(PACKAGE_DIR, root)
+}
+
+function create_git_repository(context: StepContext): void {
+	run('git', ['init', `--initial-branch=${DEFAULT_BRANCH}`], context.root)
+}
+
+// The same setup `josh init` runs, called rather than copied, with the profile the user confirmed.
+function initialize(context: StepContext): void {
+	init_main(['--profile', context.profile])
+}
+
+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
+	// 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`.
+	run('git', ['branch', '--move', '--force', DEFAULT_BRANCH], context.root)
+}
+
+function create_github_repository(context: StepContext): void {
+	const name = path.basename(context.root)
+	const visibility = `--${context.visibility}`
+	const source = ['--source', '.', '--remote', 'origin', '--push']
+
+	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)
+}
+
+const STEP_ACTIONS: Readonly<Record<StartStep, (context: StepContext) => void>> = {
+	git_init: create_git_repository,
+	initialize,
+	commit: commit_all,
+	repository: create_github_repository,
+	labels: add_missing_labels,
+}
+
+function run_step(
+	step: StartStep,
+	context: StepContext,
+	completed: ReadonlyArray<StartStep>,
+): void {
+	try {
+		STEP_ACTIONS[step](context)
+	} catch (error) {
+		const cause = error instanceof Error ? error.message : String(error)
+
+		throw new Error(start_plan.progress_report(step, completed, cause), { cause: error })
+	}
+}
+
+function run_steps(steps: ReadonlyArray<StartStep>, context: StepContext): 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))
+	}
+}
+
+const start_steps = {
+	read_git_state,
+	github_cli_refusal,
+	self_run_refusal,
+	missing_workflow_labels,
+	run_steps,
+}
+export { start_steps }
+export type { StepContext }

package/scripts/init/start.ts

@@ -1,30 +1,106 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { main as init_main } from './init'
-import { project_profile, type ProjectShape } from './project-profile'
+import { project_profile, type ProjectProfile } from './project-profile'
+import {
+	start_plan,
+	type Consent,
+	type Interaction,
+	type StartOptions,
+	type StartStep,
+} from './start-plan'
+import { start_prompt, type Choices } from './start-prompt'
+import { start_steps } from './start-steps'
 
 const ARGUMENT_START_INDEX = 2
+const READY_MESSAGE = 'GitHub workflow ready. Use kickoff new in your assistant to plan an Issue.'
+const START_USAGE = 'josh start [--profile static|node] [--yes] [--github] [--public]'
+const YES_FLAG = '--yes'
+const GITHUB_FLAG = '--github'
+const PUBLIC_FLAG = '--public'
+const SWITCHES: ReadonlySet<string> = new Set([YES_FLAG, GITHUB_FLAG, PUBLIC_FLAG])
 
-function prerequisite(shape: ProjectShape): string | undefined {
-	if (!shape.has_git) return 'josh start requires Git. Run git init, or use josh init without Git.'
-	if (!shape.has_github) return 'josh start requires a GitHub origin. Add one, or use josh init.'
+interface Prepared {
+	steps: ReadonlyArray<StartStep>
+	interaction: Interaction
+	choices: Choices
+}
+
+// The switches are peeled off first, so what remains is exactly the `--profile` pair `josh init`
+// accepts — one parser for the profile in both commands.
+function parse_start_options(args: ReadonlyArray<string>): StartOptions {
+	const profile_args = args.filter((argument) => !SWITCHES.has(argument))
+
+	return {
+		profile: project_profile.requested_profile(profile_args, START_USAGE),
+		is_yes: args.includes(YES_FLAG),
+		is_github: args.includes(GITHUB_FLAG),
+		visibility: args.includes(PUBLIC_FLAG) ? 'public' : 'private',
+	}
+}
+
+function settle<T>(verdict: { value: T | undefined; refusal: string | undefined }): T {
+	if (verdict.value === undefined) throw new Error(verdict.refusal)
 
-	return undefined
+	return verdict.value
 }
 
-function main(args: ReadonlyArray<string> = []): void {
-	// --profile uses the same override as josh init.
-	const requested = project_profile.requested_profile(args)
-	const shape = project_profile.inspect_project(process.cwd(), requested)
-	const message = prerequisite(shape)
-	if (message !== undefined) throw new Error(message)
-	init_main(args)
-	console.info('GitHub workflow ready. Use kickoff in your assistant to plan an Issue.')
+function stop_on(refusal: string | undefined): void {
+	if (refusal !== undefined) throw new Error(refusal)
+}
+
+// An unattended run already holds every answer: `--profile` or the detected one, and a consent that
+// `github_consent` only grants when `--github` was given.
+async function resolve_profile(
+	choices: Choices,
+	interaction: Interaction,
+): Promise<ProjectProfile> {
+	if (interaction === 'unattended') return choices.options.profile ?? choices.shape.profile
+
+	return await start_prompt.confirm_choices(choices)
+}
+
+// Every refusal is raised here, before the first write, so a run that stops here changed nothing.
+function prepare(args: ReadonlyArray<string>, is_tty: boolean, root: string): Prepared {
+	stop_on(start_steps.self_run_refusal(root))
+	const options = parse_start_options(args)
+	const interaction = settle(start_plan.interaction_of(options, is_tty))
+	const shape = project_profile.inspect_project(root, options.profile)
+	const plan = start_plan.plan_steps(start_steps.read_git_state(root, shape))
+
+	stop_on(plan.refusal)
+	const consent: Consent = settle(start_plan.github_consent(plan.steps, options, interaction))
+
+	stop_on(start_steps.github_cli_refusal(root))
+
+	return { steps: plan.steps, interaction, choices: { options, shape, consent, root } }
+}
+
+async function main(args: ReadonlyArray<string>, is_tty: boolean): Promise<void> {
+	const { steps, interaction, choices } = prepare(args, is_tty, process.cwd())
+
+	console.info(start_plan.plan_summary(steps))
+	const profile = await resolve_profile(choices, interaction)
+	const { root, options } = choices
+
+	start_steps.run_steps(steps, { root, profile, visibility: options.visibility })
+	console.info(`\n${READY_MESSAGE}`)
+}
+
+async function run(args: ReadonlyArray<string>, is_tty: boolean): Promise<number> {
+	try {
+		await main(args, is_tty)
+
+		return 0
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error))
+
+		return 1
+	}
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	main(process.argv.slice(ARGUMENT_START_INDEX))
+	process.exitCode = await run(process.argv.slice(ARGUMENT_START_INDEX), process.stdin.isTTY)
 }
 
-const start = { prerequisite }
+const start = { run, parse_start_options }
 export { start }

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

@@ -1103,12 +1103,13 @@ exports[`COMMAND_MAP — reference metadata > keeps every canonical command and
       ],
     ],
     "start": [
-      "[--profile static|node]",
+      "[--profile static|node] [--yes] [--github] [--public]",
       "developer",
       [
         "files",
         "git",
         "network",
+        "processes",
       ],
     ],
     "stash:pop": [