@joshuafolkken/kit 1.1387.0 → 1.1453.0

package/scripts/init/start-dry-run.ts

@@ -0,0 +1,70 @@
+import path from 'node:path'
+import { repository_labels } from '#scripts/repo/repository-labels'
+import { init_dry_run } from './init-dry-run'
+import type { ProjectProfile } from './project-profile'
+import type { StartStep } from './start-plan'
+import type { Choices } from './start-prompt'
+import { start_setup_pr } from './start-setup-pr'
+import { workflow_mark } from './workflow-mark'
+
+// What `josh start --dry-run` adds to the plan `josh start` prints: what each GitHub step would
+// create, and what its setup step would write. Nothing here creates, pushes or writes (#3830).
+
+const TITLE = 'josh start --dry-run — nothing was written. Its setup step would:'
+const NONE = '(none)'
+const UNREAD_LABELS =
+	'add the workflow labels it lacks — the repository’s labels could not be read to name them'
+
+// The labels are read from the repository when it already exists — the same listing the real step
+// compares against — and a repository this run would create has none.
+function label_line(steps: ReadonlyArray<StartStep>): string {
+	const repo = steps.includes('repository') ? undefined : '{owner}/{repo}'
+	const labels = repository_labels.planned_labels(repo)
+
+	if (labels === undefined) return UNREAD_LABELS
+
+	return `add the labels it lacks: ${labels.length === 0 ? NONE : labels.join(', ')}`
+}
+
+function github_lines({ steps, root, options }: Choices): Array<string> {
+	const lines: Readonly<Partial<Record<StartStep, string | undefined>>> = {
+		repository: `create the ${options.visibility} repository ${path.basename(root)} as origin, and push main`,
+		labels: steps.includes('labels') ? label_line(steps) : undefined,
+		setup_pr: `open the Issue "${start_setup_pr.SETUP_TITLE}" (or reuse the open one), push a branch named after it, and open a pull request into main`,
+	}
+
+	return steps.map((step) => lines[step]).filter((line) => line !== undefined)
+}
+
+function github_report(choices: Choices): string {
+	const lines = github_lines(choices).map((line) => `  ${line}`)
+
+	return ['GitHub:', ...(lines.length === 0 ? [`  ${NONE}`] : lines)].join('\n')
+}
+
+// A caller's setup command writes files kit cannot name, so it is named rather than simulated. Kit's
+// own setup runs on a scratch copy, told it sets up the GitHub workflow as the real step tells it,
+// with the repository the run would have created by then.
+function setup_report({ steps, root, options, shape }: Choices): string | undefined {
+	if (!steps.includes('initialize')) return undefined
+	const profile: ProjectProfile = options.profile ?? shape.profile
+
+	if (options.init_command !== undefined) {
+		return `The setup step would run ${options.init_command} --profile ${profile}, which is not simulated.`
+	}
+
+	workflow_mark.request()
+	const has_git = shape.has_git || steps.includes('git_init')
+
+	return init_dry_run.plan_report({ root, profile, has_git, is_install: true }, TITLE)
+}
+
+function report(choices: Choices): string {
+	const setup = setup_report(choices)
+	const sections = [github_report(choices), ...(setup === undefined ? [] : [setup])]
+
+	return `\n${sections.join('\n\n')}`
+}
+
+const start_dry_run = { report }
+export { start_dry_run }

package/scripts/init/start-exec.ts

@@ -1,6 +1,6 @@
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { git_location_environment } from '#scripts/git/git-location-environment'
-import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { git_spawn_sync, type GitSyncOptions } from '#scripts/git/git-spawn-sync'
 import { COMMAND_TIMEOUT_MS, SUITE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execaSync } from 'execa'
 import type { Visibility } from './start-plan'
@@ -16,6 +16,8 @@ import type { Visibility } from './start-plan'
 // project's own commit and push hooks, which may run its whole suite, so it takes the suite budget:
 // long enough for that, short enough that a push that never answers ends the run.
 const SUCCESS_EXIT_CODE = 0
+const GIT_DIRECTORY = '.git'
+const IDENTITY_VARIABLES = ['GIT_AUTHOR_IDENT', 'GIT_COMMITTER_IDENT']
 
 function root_environment(): Record<string, string | undefined> {
 	return git_location_environment.location_free_environment()
@@ -29,6 +31,29 @@ function git_read(args: ReadonlyArray<string>, root: string): string | undefined
 	return git_spawn_sync.read(args, { cwd: root, env: root_environment() })
 }
 
+// Asked of git itself, so the answer is the one its commit would reach: config, the environment and
+// the identity git can detect all count (#3754).
+//
+// **Only an answer from git counts as a missing identity.** A git that could not be started or never
+// answered is a different failure, which the first step that runs git reports as what it is.
+function is_identity_refused(variable: string, options: GitSyncOptions): boolean {
+	const { exit_code } = git_spawn_sync.run(['var', variable], options)
+
+	return exit_code !== undefined && exit_code !== SUCCESS_EXIT_CODE
+}
+
+// A plan that creates the repository asks from where it will be: an identity given per directory
+// (`includeIf "gitdir:…"`) is matched against the git directory, which no `cwd` supplies before
+// `git init` has run. The path stays relative to `root` so git resolves it as its commit will — by
+// the path the user reached the directory through as well as the physical one, which is what a
+// `gitdir:` under a symlinked parent is written against.
+function lacks_git_identity(root: string, is_new_repository: boolean): boolean {
+	const location = is_new_repository ? { GIT_DIR: GIT_DIRECTORY } : {}
+	const options = { cwd: root, env: { ...root_environment(), ...location } }
+
+	return IDENTITY_VARIABLES.some((variable) => is_identity_refused(variable, options))
+}
+
 function git_run(args: ReadonlyArray<string>, root: string): void {
 	const options = { cwd: root, env: root_environment(), timeout: SUITE_TIMEOUT_MS }
 	const { exit_code } = git_spawn_sync.run(args, { ...options, stdio: 'inherit' })
@@ -86,6 +111,7 @@ const start_exec = {
 	git_succeeds,
 	git_read,
 	git_run,
+	lacks_git_identity,
 	is_gh_installed,
 	is_gh_signed_in,
 	create_github_repository,

package/scripts/init/start-plan.ts

@@ -7,6 +7,7 @@ interface StartOptions {
 	profile: ProjectProfile | undefined
 	is_yes: boolean
 	is_github: boolean
+	is_dry_run: boolean
 	visibility: Visibility
 	init_command: string | undefined
 	push_preflight_command: string | undefined
@@ -58,6 +59,9 @@ const STEP_LABELS: Readonly<Record<StartStep, string>> = {
 // so they are also the steps a caller's push preflight guards (#3702).
 const GITHUB_WRITE_STEPS: ReadonlySet<StartStep> = new Set(['repository', 'setup_pr'])
 
+// The steps that create a commit, which git refuses without an author identity (#3754).
+const COMMIT_STEPS: ReadonlySet<StartStep> = new Set(['commit', 'setup_pr'])
+
 function refused(refusal: string): StepPlan {
 	return { steps: [], refusal }
 }
@@ -113,8 +117,13 @@ function has_push(steps: ReadonlyArray<StartStep>): boolean {
 	return steps.some((step) => GITHUB_WRITE_STEPS.has(step))
 }
 
+function has_commit(steps: ReadonlyArray<StartStep>): boolean {
+	return steps.some((step) => COMMIT_STEPS.has(step))
+}
+
+// A dry run asks nothing and changes nothing, so it needs neither a terminal nor `--yes`.
 function interaction_of(options: StartOptions, is_tty: boolean): Verdict<Interaction> {
-	if (options.is_yes) return { value: 'unattended', refusal: undefined }
+	if (options.is_yes || options.is_dry_run) return { value: 'unattended', refusal: undefined }
 	if (is_tty) return { value: 'interactive', refusal: undefined }
 
 	return {
@@ -126,13 +135,16 @@ 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 a repository, pushes, or opens the setup Issue and pull request only when
-// `--github` asks for it by name.
+// `--github` asks for it by name. A dry run writes to GitHub no more than it writes anywhere else, so
+// it lists the GitHub steps without that consent.
 function github_consent(
 	steps: ReadonlyArray<StartStep>,
 	options: StartOptions,
 	interaction: Interaction,
 ): Verdict<Consent> {
-	if (!has_push(steps) || options.is_github) return { value: 'granted', refusal: undefined }
+	const is_consented = options.is_github || options.is_dry_run
+
+	if (is_consented || !has_push(steps)) return { value: 'granted', refusal: undefined }
 	if (interaction === 'interactive') return { value: 'ask', refusal: undefined }
 
 	return {
@@ -167,6 +179,12 @@ function preflight_report(command: string, cause: string): string {
 	return `josh start stopped before its first step: the push preflight (${command}) failed. Nothing was changed.\nCause: ${cause}`
 }
 
+// What a run prints when the scanner the pre-push audit needs could not be put in place: every push
+// the plan makes would be refused by that hook, so it stops while nothing has changed (#3755).
+function scanner_report(cause: string): string {
+	return `josh start stopped before its first step: osv-scanner, which the pre-push audit needs, is not installed and could not be fetched. Nothing was changed.\nCause: ${cause}\nInstall osv-scanner (https://google.github.io/osv-scanner/) or restore the network, then run josh start again.`
+}
+
 function plan_summary(
 	steps: ReadonlyArray<StartStep>,
 	labels: Readonly<Record<StartStep, string>> = STEP_LABELS,
@@ -179,10 +197,12 @@ function plan_summary(
 const start_plan = {
 	plan_steps,
 	has_push,
+	has_commit,
 	interaction_of,
 	github_consent,
 	progress_report,
 	preflight_report,
+	scanner_report,
 	plan_summary,
 	step_labels,
 	STEP_LABELS,

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

@@ -9,28 +9,19 @@ import { IGNORE_FOR_RELEASE_LABEL } from '#scripts/issue/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'
+import { working_tree } from './working-tree'
 
 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 the setup wrote are in',
-	'the pull request; anything else in the working tree is left as it was.',
+	'the pull request: `josh start` runs only on a working tree with nothing uncommitted.',
 ].join('\n')
 const NAME_ONLY = '--name-only'
 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`
 
-// Listings are read NUL-separated (`-z`), so a path is never quoted — a name a caller's initialize
-// command wrote need not be ASCII the way kit's own are (#2872).
-function paths_of(output: string | undefined = ''): Array<string> {
-	return output.split('\0').filter((listed) => listed.length > 0)
-}
-
-function listing(args: ReadonlyArray<string>, root: string): Array<string> {
-	return paths_of(start_exec.git_read([...args, '-z'], root))
-}
-
 function setup_issue(issue_number: string): IssueInfo {
 	return git_issue.parse(`${SETUP_TITLE} ${issue_cite.plain(issue_number)}`)
 }
@@ -49,19 +40,10 @@ 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`.
-function changed_paths(root: string): Array<string> {
-	const untracked = listing(['ls-files', '--others', '--exclude-standard'], root)
-	const modified = listing(['diff', NAME_ONLY, 'HEAD'], root)
-
-	return [...untracked, ...modified]
-}
-
 // On the setup branch a failed commit left, that run's `git add` already staged its files, so they
 // read as changed before this run's command ran — the staged ones count as setup output (#2872).
 function carried_paths(root: string, current: string | undefined): Array<string> {
-	return is_setup_branch(current) ? listing(['diff', NAME_ONLY, '--cached'], root) : []
+	return is_setup_branch(current) ? working_tree.listing(['diff', NAME_ONLY, '--cached'], root) : []
 }
 
 // The Issue carries the release classification the pull request is opened with, so the PR step finds
@@ -124,13 +106,15 @@ function commit_kit_paths(paths: ReadonlyArray<string>, issue: IssueInfo, root:
 
 // A caller's initialize command writes files kit cannot name, so with a `baseline` — what was already
 // changed before that command ran — everything changed since joins kit's own files, while a change
-// the user had made before the run still stays out (#2872).
+// the user had made before the run still stays out (#2872). `josh start` refuses a dirty tree on
+// `main` (#3835), so the baseline there is empty; it still keeps the two apart on the setup branch a
+// failed commit left, where the re-run starts with that run's output uncommitted.
 function setup_paths(
 	root: string,
 	baseline: ReadonlyArray<string> | undefined,
 	current: string | undefined,
 ): Array<string> {
-	const changed = changed_paths(root)
+	const changed = working_tree.changed_paths(root)
 	const kit_paths = kit_written_paths.select(changed)
 
 	if (baseline === undefined) return kit_paths
@@ -161,6 +145,11 @@ async function open(root: string, baseline?: ReadonlyArray<string>): Promise<voi
 	await git_pr.create_with_issue_info(issue)
 }
 
-const start_setup_pr = { open, changed_paths, is_setup_branch }
+const start_setup_pr = {
+	SETUP_TITLE,
+	open,
+	changed_paths: working_tree.changed_paths,
+	is_setup_branch,
+}
 
 export { start_setup_pr }

package/scripts/init/start-steps.ts

@@ -2,6 +2,8 @@ import path from 'node:path'
 import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
 import { error_text } from '#scripts/lib/error-message'
 import { repository_labels } from '#scripts/repo/repository-labels'
+import { security_audit } from '#scripts/security/security-audit'
+import { security_audit_provision } from '#scripts/security/security-audit-provision'
 import { self_sync_guard } from '#scripts/self-sync-guard/self-sync-guard-logic'
 import { parseCommandString } from 'execa'
 import { main as init_main } from './init'
@@ -12,6 +14,8 @@ 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'
+import { workflow_mark } from './workflow-mark'
+import { working_tree } from './working-tree'
 
 interface StepContext {
 	root: string
@@ -29,6 +33,12 @@ 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.'
+const GIT_IDENTITY_HINT =
+	'Git has no author identity, which the commit josh start creates needs. Run git config --global user.name "Your Name" and git config --global user.email "you@example.com", then run josh start again. Nothing was changed.'
+// Printed before the scanner is looked for: a first run downloads tens of megabytes, and a terminal
+// that says nothing for minutes reads as a hang the user interrupts (#3755).
+const SCANNER_NOTICE =
+	'Checking for osv-scanner, which the pre-push audit needs. A first run downloads it, which can take a few minutes on a slow connection.'
 
 const { git_succeeds, git_read, run_local } = start_exec
 
@@ -63,6 +73,28 @@ function github_cli_refusal(root: string): string | undefined {
 	return undefined
 }
 
+// A machine Git was just installed on has no author identity, and the commit that needs one comes
+// after the repository and kit's files are written. It is asked for before the first write, and only
+// when the plan commits — a re-run with nothing left to commit is not stopped by it (#3754).
+function git_identity_refusal(steps: ReadonlyArray<StartStep>, root: string): string | undefined {
+	if (!start_plan.has_commit(steps)) return undefined
+
+	return start_exec.lacks_git_identity(root, steps.includes('git_init'))
+		? GIT_IDENTITY_HINT
+		: undefined
+}
+
+// A repository with a history receives the setup as a commit, and the user's own uncommitted change to
+// a file kit also writes would land in it, so the tree must be clean before the first write (#3835).
+// The setup branch a failed commit or push left checked out is the exception: what is uncommitted
+// there is that run's own output, which the re-run resumes with. Without a commit there is nothing to
+// keep apart — the initial commit takes every file.
+function uncommitted_refusal(root: string, state: GitState): string | undefined {
+	if (!state.has_commits || start_setup_pr.is_setup_branch(state.branch)) return undefined
+
+	return working_tree.dirty_tree_refusal(root, 'josh start')
+}
+
 // `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.
@@ -85,7 +117,10 @@ function create_git_repository(context: StepContext): void {
 // A toolkit that layers its files over kit's (`josh-app init`) names its own setup instead, so every
 // other step and guard stays here rather than in a copy of this command (#2872). That command runs
 // without a shell, is given the same profile, and a non-zero exit stops the run before the commit.
+// Either one is told the project is set up for the GitHub Issue workflow (`workflow-mark.ts`).
 function initialize(context: StepContext): void {
+	workflow_mark.request()
+
 	if (context.init_command === undefined) {
 		init_main(['--profile', context.profile])
 
@@ -118,7 +153,9 @@ async function open_setup_pull_request(context: RunContext): Promise<void> {
 // What was already changed before the setup ran, read whenever a setup pull request will follow, so
 // it can tell the setup's files from the user's own (#2872). Kit's own `josh init` needs it as much as
 // a caller's command: its `josh format` rewrites the project's own sources, which kit cannot name, and
-// leaving them out failed the pull request's Prettier check.
+// leaving them out failed the pull request's Prettier check. On `main` it is empty, since a dirty tree
+// is refused there (#3835); it is kept for the setup branch a failed commit left, where the earlier
+// run's output is already uncommitted when the re-run starts.
 function baseline_of(
 	steps: ReadonlyArray<StartStep>,
 	context: StepContext,
@@ -148,6 +185,27 @@ function run_push_preflight(steps: ReadonlyArray<StartStep>, context: StepContex
 	}
 }
 
+// The `full` profile installs kit's pre-push hook, whose audit refuses a push without osv-scanner. The
+// scanner is otherwise fetched at an agent's session start, which a first `josh start` from a terminal
+// has not had, so it is fetched here — forced, because a person asked for this run. A scanner that
+// still cannot be found stops the run before the first step rather than at the push (#3755).
+async function ensure_audit_scanner(
+	steps: ReadonlyArray<StartStep>,
+	context: StepContext,
+): Promise<void> {
+	if (context.profile !== 'full' || !start_plan.has_push(steps)) return
+
+	const { platform, arch } = process
+
+	console.info(`\n${SCANNER_NOTICE}`)
+	const outcome = await security_audit_provision.report(context.root, platform, arch, true)
+
+	console.info(outcome)
+	if (security_audit.resolve_scanner(context.root, platform) !== undefined) return
+
+	throw new Error(start_plan.scanner_report(outcome))
+}
+
 type StepAction = (context: RunContext) => void | Promise<void>
 
 const STEP_ACTIONS: Readonly<Record<StartStep, StepAction>> = {
@@ -178,6 +236,7 @@ async function run_steps(steps: ReadonlyArray<StartStep>, context: StepContext):
 	const labels = start_plan.step_labels(context.init_command)
 
 	run_push_preflight(steps, context)
+	await ensure_audit_scanner(steps, context)
 	const run_context: RunContext = { ...context, baseline: baseline_of(steps, context) }
 
 	for (const [index, step] of steps.entries()) {
@@ -192,7 +251,9 @@ async function run_steps(steps: ReadonlyArray<StartStep>, context: StepContext):
 const start_steps = {
 	read_git_state,
 	github_cli_refusal,
+	git_identity_refusal,
 	self_run_refusal,
+	uncommitted_refusal,
 	run_steps,
 }
 export { start_steps }

package/scripts/init/start.ts

@@ -1,7 +1,9 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { error_text } from '#scripts/lib/error-message'
-import { project_profile, type ProjectProfile } from './project-profile'
+import { init_dry_run } from './init-dry-run'
+import { project_profile, type ProjectProfile, type ProjectShape } from './project-profile'
+import { start_dry_run } from './start-dry-run'
 import {
 	start_plan,
 	type Consent,
@@ -15,13 +17,14 @@ 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 basic|full] [--yes] [--github] [--public] [--init-command <command>] [--push-preflight-command <command>]'
+	'josh start [--profile basic|full] [--yes] [--github] [--public] [--dry-run] [--init-command <command>] [--push-preflight-command <command>]'
 const INIT_COMMAND_FLAG = '--init-command'
 const PUSH_PREFLIGHT_COMMAND_FLAG = '--push-preflight-command'
 const YES_FLAG = '--yes'
 const GITHUB_FLAG = '--github'
 const PUBLIC_FLAG = '--public'
-const SWITCHES: ReadonlySet<string> = new Set([YES_FLAG, GITHUB_FLAG, PUBLIC_FLAG])
+const { DRY_RUN_FLAG } = init_dry_run
+const SWITCHES: ReadonlySet<string> = new Set([YES_FLAG, GITHUB_FLAG, PUBLIC_FLAG, DRY_RUN_FLAG])
 
 interface Prepared {
 	steps: ReadonlyArray<StartStep>
@@ -67,6 +70,7 @@ function parse_start_options(args: ReadonlyArray<string>): StartOptions {
 		profile: project_profile.requested_profile(profile_args, START_USAGE),
 		is_yes: rest.includes(YES_FLAG),
 		is_github: rest.includes(GITHUB_FLAG),
+		is_dry_run: rest.includes(DRY_RUN_FLAG),
 		visibility: rest.includes(PUBLIC_FLAG) ? 'public' : 'private',
 		init_command: init.command,
 		push_preflight_command,
@@ -94,33 +98,34 @@ async function resolve_profile(
 	return await start_prompt.confirm_choices(choices)
 }
 
+function planned_steps(root: string, shape: ProjectShape): ReadonlyArray<StartStep> {
+	const state = start_steps.read_git_state(root, shape)
+	const plan = start_plan.plan_steps(state)
+
+	stop_on(plan.refusal)
+	stop_on(start_steps.uncommitted_refusal(root, state))
+
+	return plan.steps
+}
+
 // 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))
+	const steps = planned_steps(root, shape)
+	const consent: Consent = settle(start_plan.github_consent(steps, options, interaction))
 
 	stop_on(start_steps.github_cli_refusal(root))
+	stop_on(start_steps.git_identity_refusal(steps, root))
 
-	return {
-		steps: plan.steps,
-		interaction,
-		choices: { options, shape, consent, root, steps: plan.steps },
-	}
+	return { steps, interaction, choices: { options, shape, consent, root, steps } }
 }
 
-async function main(args: ReadonlyArray<string>, is_tty: boolean): Promise<void> {
-	const { steps, interaction, choices } = prepare(args, is_tty, process.cwd())
-
+async function run_steps({ steps, interaction, choices }: Prepared): Promise<void> {
 	const { root, options } = choices
 	const { visibility, init_command, push_preflight_command } = options
-
-	console.info(start_plan.plan_summary(steps, start_plan.step_labels(init_command)))
 	const profile = await resolve_profile(choices, interaction)
 	const context = { root, profile, visibility, init_command, push_preflight_command }
 
@@ -128,6 +133,22 @@ async function main(args: ReadonlyArray<string>, is_tty: boolean): Promise<void>
 	console.info(`\n${READY_MESSAGE}`)
 }
 
+// A dry run stops after the plan, adding what each step would create, before the first write.
+async function main(args: ReadonlyArray<string>, is_tty: boolean): Promise<void> {
+	const prepared = prepare(args, is_tty, process.cwd())
+	const { steps, choices } = prepared
+
+	console.info(start_plan.plan_summary(steps, start_plan.step_labels(choices.options.init_command)))
+
+	if (choices.options.is_dry_run) {
+		console.info(start_dry_run.report(choices))
+
+		return
+	}
+
+	await run_steps(prepared)
+}
+
 async function run(args: ReadonlyArray<string>, is_tty: boolean): Promise<number> {
 	try {
 		await main(args, is_tty)

package/scripts/init/workflow-mark.ts

@@ -0,0 +1,35 @@
+import { json_value } from '#scripts/lib/json-value'
+
+// `josh start` sets a project up for the GitHub Issue workflow and `josh init` alone does not. The
+// difference decides whether a `basic` project receives `.claude/settings.json`, whose permissions,
+// hooks and plugin an unattended `backlogrun` agent runs on (#3796).
+//
+// `josh start` hands the mark to the setup it runs through this variable, not an argument: that setup
+// may be the project's own kit it hands off to or a toolkit's command (`--init-command`), and an older
+// one refuses an argument it does not know but ignores a variable. The setup records the mark in
+// `package.json`, where every later `josh init` and `josh sync` reads it.
+const WORKFLOW_ENV = 'JOSH_WORKFLOW'
+const GITHUB_WORKFLOW = 'github'
+
+function is_requested(environment: NodeJS.ProcessEnv = process.env): boolean {
+	return environment[WORKFLOW_ENV] === GITHUB_WORKFLOW
+}
+
+function is_recorded(manifest: Record<string, unknown> | undefined): boolean {
+	const josh = manifest?.['josh']
+
+	return json_value.is_record(josh) && josh['workflow'] === GITHUB_WORKFLOW
+}
+
+function request(environment: NodeJS.ProcessEnv = process.env): void {
+	environment[WORKFLOW_ENV] = GITHUB_WORKFLOW
+}
+
+// The `josh` record's field for the mark — none for a project `josh start` did not set up, so a
+// `josh init` never writes the mark of its own accord.
+function recorded_fields(has_workflow: boolean): Record<string, string> {
+	return has_workflow ? { workflow: GITHUB_WORKFLOW } : {}
+}
+
+const workflow_mark = { is_requested, is_recorded, request, recorded_fields }
+export { workflow_mark }

package/scripts/init/working-tree.ts

@@ -0,0 +1,116 @@
+import { git_location_environment } from '#scripts/git/git-location-environment'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { start_exec } from './start-exec'
+
+const UNTRACKED_ARGUMENTS = ['ls-files', '--others', '--exclude-standard']
+// `--relative` keeps the listing to the project and its paths relative to it, the way `ls-files`
+// already reads them, for a project that sits below its repository's top level.
+const MODIFIED_ARGUMENTS = ['diff', '--name-only', '--relative', 'HEAD']
+// Under an unborn HEAD every indexed file is uncommitted, so the index itself is the listing.
+const INDEXED_ARGUMENTS = ['ls-files', '--cached']
+const HISTORY_ARGUMENTS = ['rev-list', '--max-count=1', '--all']
+const UNBORN_HEAD_EXIT_CODE = 1
+const NOT_A_REPOSITORY = 'not a git repository'
+
+// What a project's working tree holds that is not committed, read one way for every setup command:
+// the setup pull request tells the setup's files from the user's own with it, and `josh init` refuses
+// to write over it.
+
+// Listings are read NUL-separated (`-z`), so a path is never quoted — a name a caller's initialize
+// command wrote need not be ASCII the way kit's own are (#2872).
+function paths_of(output: string | undefined = ''): Array<string> {
+	return output.split('\0').filter((listed) => listed.length > 0)
+}
+
+function listing(args: ReadonlyArray<string>, root: string): Array<string> {
+	return paths_of(start_exec.git_read([...args, '-z'], root))
+}
+
+// Untracked files the ignore rules let through, plus tracked files changed since HEAD, staged or not
+// — two plain listings, so nothing has to be parsed out of `git status`.
+function changed_paths(root: string): Array<string> {
+	const untracked = listing(UNTRACKED_ARGUMENTS, root)
+	const modified = listing(MODIFIED_ARGUMENTS, root)
+
+	return [...untracked, ...modified]
+}
+
+// A read that failed is thrown rather than read as an empty listing: the refusal guards the user's
+// work, so a git that did not answer must never pass for a clean tree.
+function strict_listing(args: ReadonlyArray<string>, root: string): Array<string> {
+	const output = start_exec.git_read([...args, '-z'], root)
+
+	if (output === undefined) throw new Error(`git ${args.join(' ')} failed in ${root}`)
+
+	return paths_of(output)
+}
+
+type HeadState = 'born' | 'unborn' | 'absent'
+
+// Asked of git rather than of a `.git` beside the project, so a project below its repository's top
+// level is still found. `--verify --quiet` exits 1 for an unborn HEAD, and only `not a git repository`
+// (read under the C locale) proves there is no repository; any other failure is an unanswered
+// question, not a missing commit.
+function head_state(root: string): HeadState {
+	const { exit_code, stderr } = git_spawn_sync.run(['rev-parse', '--verify', '--quiet', 'HEAD'], {
+		cwd: root,
+		env: { ...git_spawn_sync.C_LOCALE, ...git_location_environment.location_free_environment() },
+	})
+
+	if (exit_code === 0) return 'born'
+	if (stderr.includes(NOT_A_REPOSITORY)) return 'absent'
+	if (exit_code === UNBORN_HEAD_EXIT_CODE) return 'unborn'
+	throw new Error(`git rev-parse could not read HEAD in ${root}`)
+}
+
+// An unborn HEAD is either the repository `josh start` has yet to make its first commit in, or an
+// orphan branch (`git checkout --orphan`) whose index still holds another branch's files — told
+// apart by whether any ref reaches a commit.
+function has_history(root: string): boolean {
+	const output = start_exec.git_read(HISTORY_ARGUMENTS, root)
+
+	if (output === undefined) throw new Error(`git ${HISTORY_ARGUMENTS.join(' ')} failed in ${root}`)
+
+	return output.trim().length > 0
+}
+
+// What the tracked files are compared with, or undefined when there is nothing to tell the user's
+// work from — a directory outside any repository, or a repository without any commit.
+function tracked_arguments(root: string): ReadonlyArray<string> | undefined {
+	const state = head_state(root)
+
+	if (state === 'born') return MODIFIED_ARGUMENTS
+	if (state === 'unborn' && has_history(root)) return INDEXED_ARGUMENTS
+
+	return undefined
+}
+
+function uncommitted_paths(root: string): Array<string> {
+	const tracked = tracked_arguments(root)
+
+	if (tracked === undefined) return []
+
+	const untracked = strict_listing(UNTRACKED_ARGUMENTS, root)
+	const modified = strict_listing(tracked, root)
+
+	return [...untracked, ...modified]
+}
+
+// The refusal a setup command stops with before its first write, or undefined when nothing is
+// uncommitted: what kit then writes would land in the same files as the user's own work, and
+// `git diff` could no longer tell the two apart.
+function dirty_tree_refusal(root: string, command: string): string | undefined {
+	const paths = uncommitted_paths(root)
+
+	if (paths.length === 0) return undefined
+
+	return [
+		`${command} refuses to run: the working tree has uncommitted changes.`,
+		...paths.map((listed) => `  ${listed}`),
+		`Commit them, or stash them with \`git stash push -u -- .\`, then run ${command} again.`,
+	].join('\n')
+}
+
+const working_tree = { listing, changed_paths, uncommitted_paths, dirty_tree_refusal }
+
+export { working_tree }