@joshuafolkken/kit 1.1435.0 → 1.1453.0

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

@@ -0,0 +1,189 @@
+import { createHash } from 'node:crypto'
+import {
+	constants,
+	cpSync,
+	existsSync,
+	lstatSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+	statSync,
+} from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { resolve_tsx_runner } from '#scripts/josh/josh-logic'
+import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
+import { execaSync } from 'execa'
+import { init_bootstrap } from './init-bootstrap'
+import { init_dry_run_report, type FileChange } from './init-dry-run-report'
+import { init_install } from './init-install'
+import { PACKAGE_DIR, package_path } from './init-paths'
+import { project_profile, type ProjectProfile } from './project-profile'
+import { start_exec } from './start-exec'
+
+// `josh init --dry-run` and `josh start --dry-run` answer "what would the setup change?" without
+// a second copy of the setup's decisions: the real `josh init` runs on a scratch copy of the project,
+// and the plan is the difference it left there. Every create, merge and skip is decided by the code
+// that decides it for real, so the plan cannot drift from the run (#3830).
+
+interface DryRunRequest {
+	root: string
+	profile: ProjectProfile | undefined
+	// Whether the setup meets a repository — `josh start` creates one before its setup runs.
+	has_git: boolean
+	is_install: boolean
+}
+
+interface DryRunSplit {
+	is_dry_run: boolean
+	rest: ReadonlyArray<string>
+}
+
+const DRY_RUN_FLAG = '--dry-run'
+const INIT_SCRIPT = 'scripts/init/init.ts'
+const SCRATCH_PREFIX = 'josh-init-dry-run-'
+const DEFAULT_BRANCH = 'main'
+const TITLE = 'josh init --dry-run — nothing was written. The setup would:'
+
+function split_dry_run_flag(args: ReadonlyArray<string>): DryRunSplit {
+	return {
+		is_dry_run: args.includes(DRY_RUN_FLAG),
+		rest: args.filter((argument) => argument !== DRY_RUN_FLAG),
+	}
+}
+
+// A directory is copied unless the project scan skips it: an ignored one, or a link — followed, a
+// link to the project or an ancestor would copy it into itself until the path is too long.
+function is_copied_directory(source: string): boolean {
+	return (
+		!lstatSync(source).isSymbolicLink() &&
+		!project_profile.is_ignored_directory(path.basename(source))
+	)
+}
+
+// A link to a file is copied as the file it points to, so no write in the scratch copy can follow a
+// link back into the project; a dangling one is left out, as the project scan leaves out what it
+// cannot read. The root itself is always copied: `cpSync` filters it too, so a project in a
+// directory named `build` or `dist` would otherwise be planned as an empty one.
+function is_copied(root: string, source: string): boolean {
+	if (source === root) return true
+	if (!existsSync(source)) return false
+
+	return !statSync(source).isDirectory() || is_copied_directory(source)
+}
+
+// The scratch repository answers the setup's git questions as the project's does: one exists, and
+// its origin is the same URL, so a GitHub project is planned as one.
+function mirror_git(root: string, scratch: string): void {
+	start_exec.git_succeeds(['init', '--quiet', `--initial-branch=${DEFAULT_BRANCH}`], scratch)
+	const origin = git_spawn_sync.origin_url(root)
+
+	if (origin !== undefined) start_exec.git_succeeds(['remote', 'add', 'origin', origin], scratch)
+}
+
+function prepare_scratch(root: string, has_git: boolean): string {
+	const scratch = mkdtempSync(path.join(os.tmpdir(), SCRATCH_PREFIX))
+
+	// A copy-on-write clone where the file system supports one, so mirroring a large project costs
+	// next to nothing there; a plain copy elsewhere.
+	cpSync(root, scratch, {
+		recursive: true,
+		dereference: true,
+		mode: constants.COPYFILE_FICLONE,
+		filter: (source) => is_copied(root, source),
+	})
+	if (has_git) mirror_git(root, scratch)
+
+	return scratch
+}
+
+function digest_of(file: string): string {
+	return createHash('sha256').update(readFileSync(file)).digest('hex')
+}
+
+// A snapshot holds each file's digest, not its content, so a project with large files is compared
+// without holding them in memory; only the files the setup changed are read in full.
+function snapshot(root: string): Map<string, string> {
+	const files = project_profile.list_files(root)
+
+	return new Map(files.map((file) => [path.relative(root, file), digest_of(file)]))
+}
+
+function content_of(
+	root: string,
+	file: string,
+	digests: ReadonlyMap<string, string>,
+): string | undefined {
+	return digests.has(file) ? readFileSync(path.join(root, file), 'utf8') : undefined
+}
+
+// The project itself still holds what the scratch copy held before the setup ran.
+function changes_since(
+	request: DryRunRequest,
+	scratch: string,
+	before: ReadonlyMap<string, string>,
+): Array<FileChange> {
+	const after = snapshot(scratch)
+
+	return init_dry_run_report.changed_files(before, after).map((change) => ({
+		path: change.path,
+		before: content_of(request.root, change.path, before),
+		after: content_of(scratch, change.path, after),
+	}))
+}
+
+// `--no-install` keeps the install out of the scratch copy, and the hand-off variable keeps this
+// kit doing the setup itself — the scratch copy has no kit of its own to hand it to.
+function run_init(scratch: string, profile: ProjectProfile | undefined): void {
+	const runner = resolve_tsx_runner()
+	const profile_args = profile === undefined ? [] : ['--profile', profile]
+	const args = [package_path(INIT_SCRIPT), init_install.NO_INSTALL_FLAG, ...profile_args]
+	const result = execaSync(runner.executable, [...runner.leading_arguments, ...args], {
+		cwd: scratch,
+		env: { [init_bootstrap.HANDOFF_ENV]: '1' },
+		all: true,
+		reject: false,
+	})
+
+	if (result.exitCode !== 0) throw new Error(`the simulated josh init failed:\n${result.all}`)
+}
+
+function simulate(request: DryRunRequest): Array<FileChange> {
+	const scratch = prepare_scratch(request.root, request.has_git)
+
+	try {
+		const before = snapshot(scratch)
+
+		run_init(scratch, request.profile)
+
+		return changes_since(request, scratch, before)
+	} finally {
+		rmSync(scratch, { recursive: true, force: true })
+	}
+}
+
+// The same two questions the real run asks: whether to install at all, and whether this kit is the
+// project's own or hands the setup to the one it installs.
+function dependency_lines(root: string, is_install: boolean): Array<string> {
+	if (!is_install) return [`skip the install and the format (${init_install.NO_INSTALL_FLAG})`]
+	const steps = `run ${init_install.INSTALL_STEP.label}, then ${init_install.FORMAT_STEP.label}`
+
+	if (init_bootstrap.is_project_kit(PACKAGE_DIR, root)) return [steps]
+
+	return [`install ${KIT_PACKAGE_NAME} into the project and hand the setup to its josh init`, steps]
+}
+
+function plan_report(request: DryRunRequest, title: string = TITLE): string {
+	const changes = simulate(request)
+
+	return init_dry_run_report.format_report(
+		title,
+		changes,
+		dependency_lines(request.root, request.is_install),
+	)
+}
+
+const init_dry_run = { DRY_RUN_FLAG, split_dry_run_flag, plan_report }
+export { init_dry_run }
+export type { DryRunRequest }

package/scripts/init/init-install.ts

@@ -62,6 +62,13 @@ function run_post_init_steps(project_root: string): string | undefined {
 	return undefined
 }
 
-const init_install = { NO_INSTALL_FLAG, split_install_flag, did_step_succeed, run_post_init_steps }
+const init_install = {
+	NO_INSTALL_FLAG,
+	INSTALL_STEP,
+	FORMAT_STEP,
+	split_install_flag,
+	did_step_succeed,
+	run_post_init_steps,
+}
 export { init_install }
 export type { InstallStep }

package/scripts/init/init.ts

@@ -19,20 +19,27 @@ import { init_actions, PRETTIER_CONFIG_JS } from './init-actions'
 import { init_ai_copy } from './init-ai-copy'
 import { init_basic } from './init-basic'
 import { init_bootstrap } from './init-bootstrap'
+import { init_dry_run } from './init-dry-run'
 import { init_file_action } from './init-file-action'
 import { init_install } from './init-install'
 import { init_logic } from './init-logic'
 import { PACKAGE_DIR, PROJECT_ROOT } from './init-paths'
-import { kit_setup_state } from './kit-setup-state'
 import { package_manager_pin } from './package-manager-pin'
 import { project_profile, type ProjectProfile, type ProjectShape } from './project-profile'
+import { working_tree } from './working-tree'
 
 const PACKAGE_JSON = 'package.json'
 const KIT_PACKAGE_NAME = '@joshuafolkken/kit'
 const LEFTHOOK_BIN = 'lefthook'
 const ARGUMENT_START_INDEX = 2
 const INSTALL_HINT = '→ run `pnpm install` to install what package.json lists'
-const INIT_USAGE = 'josh init [--profile basic|full] [--no-install]'
+const INIT_USAGE = 'josh init [--profile basic|full] [--no-install] [--dry-run]'
+
+interface InitRequest {
+	is_dry_run: boolean
+	is_install: boolean
+	requested: ProjectProfile | undefined
+}
 
 const engine_pin_schema = z.looseObject({ name: z.string(), version: z.string() })
 
@@ -265,14 +272,21 @@ function set_up_project(requested: ProjectProfile | undefined, is_install: boole
 	console.info('\n✅ Done.\n')
 }
 
-// True when this process set the project up — false when it refused, or handed the run to the
-// project's own kit, which then speaks for itself.
-function main(args: ReadonlyArray<string> = []): boolean {
-	if (did_refuse_self_run(PACKAGE_DIR, PROJECT_ROOT)) return false
-	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)
+// A dry run sets nothing up, so it answers false and points nowhere onward.
+function print_dry_run({ requested, is_install }: InitRequest): false {
+	const has_git = project_profile.has_git(PROJECT_ROOT)
 
+	console.info(
+		init_dry_run.plan_report({ root: PROJECT_ROOT, profile: requested, has_git, is_install }),
+	)
+
+	return false
+}
+
+function did_set_up_here(
+	{ requested, is_install }: InitRequest,
+	args: ReadonlyArray<string>,
+): boolean {
 	const is_set_up_here = !is_install || !did_hand_off(args)
 
 	if (is_set_up_here) set_up_project(requested, is_install)
@@ -280,19 +294,43 @@ function main(args: ReadonlyArray<string> = []): boolean {
 	return is_set_up_here
 }
 
-// Only the command a person typed points onward to `josh start`: `josh start` calls `main` itself and
-// is already the next step.
-// A setup that failed after writing, such as a failed install, sets the exit code and points nowhere.
-function print_start_hint(): void {
-	if (process.exitCode !== undefined && process.exitCode !== 0) return
-	const hint = kit_setup_state.start_hint(PROJECT_ROOT)
+// The flags are peeled off first, so what remains is exactly the `--profile` pair.
+// Validated before the hand-off, so a malformed invocation is refused before kit is installed.
+function parse_init_args(args: ReadonlyArray<string>): InitRequest {
+	const { is_dry_run, rest: run_args } = init_dry_run.split_dry_run_flag(args)
+	const { is_install, rest } = init_install.split_install_flag(run_args)
+
+	return { is_dry_run, is_install, requested: project_profile.requested_profile(rest, INIT_USAGE) }
+}
+
+// True when this process set the project up — false when it refused, or handed the run to the
+// project's own kit, which then speaks for itself.
+function main(args: ReadonlyArray<string> = []): boolean {
+	if (did_refuse_self_run(PACKAGE_DIR, PROJECT_ROOT)) return false
+	const request = parse_init_args(args)
 
-	if (hint !== undefined) console.info(`${hint}\n`)
+	return request.is_dry_run ? print_dry_run(request) : did_set_up_here(request, args)
+}
+
+// Only the command a person typed is refused, before anything is written or installed. `josh start`
+// calls `main` itself and decides about its own tree (#3835); a handed-off run follows the check
+// its caller already passed, on a tree the kit install it just made has changed.
+function did_refuse_dirty_tree(): boolean {
+	const refusal = init_bootstrap.is_handed_off()
+		? undefined
+		: working_tree.dirty_tree_refusal(PROJECT_ROOT, 'josh init')
+
+	if (refusal === undefined) return false
+	console.error(`\n${refusal}\n`)
+	process.exitCode = 1
+
+	return true
 }
 
 function run_cli(args: ReadonlyArray<string>): void {
 	try {
-		if (main(args)) print_start_hint()
+		if (did_refuse_dirty_tree()) return
+		main(args)
 	} catch (error) {
 		console.error(`\n✖ ${error_text.message_of(error)}\n`)
 		process.exitCode = 1
@@ -312,5 +350,5 @@ const init = {
 }
 
 // `init` is the entry point; `main` is exported for its own unit test, the way `sync.ts` exports the
-// `main()` its self-run guard lives in.
-export { init, main }
+// `main()` its self-run guard lives in, and `run_cli` for the refusal only the typed command makes.
+export { init, main, run_cli }

package/scripts/init/kit-setup-state.ts

@@ -1,30 +1,24 @@
+import { json_value } from '#scripts/lib/json-value'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
 import { start_exec } from './start-exec'
+import { workflow_mark } from './workflow-mark'
 
-const START_HINT =
-	'To use the GitHub Issue workflow, run pnpm exec josh start next: it puts this setup on GitHub, through a pull request when main already has commits.'
-
-// Whether the commit checked out records kit in its manifest — the sign that kit's setup has already
-// reached the branch, so `josh start` has no setup pull request to open.
+// Whether the commit checked out holds `josh start`'s setup — its manifest lists kit and records the
+// GitHub workflow mark — the sign that the setup has already reached the branch, so `josh start` has
+// no setup pull request to open. Kit alone is not enough: a committed `josh init` setup lacks the mark
+// and, on `basic`, `.claude/settings.json`, which `josh start`'s setup then writes and only a setup
+// pull request carries to `main` (#3835).
 function is_kit_committed(root: string): boolean {
 	// `./` resolves the path from `root` rather than from the repository's top level.
 	const manifest = start_exec.git_read(['show', 'HEAD:./package.json'], root)
 
-	return manifest?.includes(`"${KIT_PACKAGE_NAME}"`) ?? false
-}
-
-function is_git_work_tree(root: string): boolean {
-	return start_exec.git_succeeds(['rev-parse', '--is-inside-work-tree'], root)
-}
+	if (manifest?.includes(`"${KIT_PACKAGE_NAME}"`) !== true) return false
 
-// The line `josh init` ends with in a Git repository whose checkout does not hold kit yet: the setup is
-// still uncommitted, and `josh start` is what carries it to GitHub.
-function start_hint(root: string): string | undefined {
-	if (!is_git_work_tree(root) || is_kit_committed(root)) return undefined
+	const parsed = json_value.parse_or_undefined(manifest)
 
-	return START_HINT
+	return workflow_mark.is_recorded(json_value.is_record(parsed) ? parsed : undefined)
 }
 
-const kit_setup_state = { is_kit_committed, start_hint }
+const kit_setup_state = { is_kit_committed }
 
 export { kit_setup_state }

package/scripts/init/own-formatter.ts

@@ -0,0 +1,21 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+
+// The configuration files of a formatter other than Prettier. A `basic` project holding one already
+// formats its own files, so `josh init` gives it no Prettier and `josh format` / `josh gate` skip it
+// (joshuafolkken/kit#3832).
+const OWN_FORMATTER_CONFIGS = [
+	'biome.json',
+	'biome.jsonc',
+	'dprint.json',
+	'dprint.jsonc',
+	'.dprint.json',
+	'.dprint.jsonc',
+]
+
+function find_config(root: string): string | undefined {
+	return OWN_FORMATTER_CONFIGS.find((name) => existsSync(path.join(root, name)))
+}
+
+const own_formatter = { find_config }
+export { own_formatter }

package/scripts/init/project-profile.ts

@@ -5,6 +5,7 @@ import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
 import { json_value } from '#scripts/lib/json-value'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
 import { kit_written_paths } from './kit-written-paths'
+import { own_formatter } from './own-formatter'
 import { workflow_mark } from './workflow-mark'
 
 type ProjectProfile = 'basic' | 'full'
@@ -15,7 +16,8 @@ interface ProfileResult {
 }
 
 interface ProjectShape extends ProfileResult {
-	has_web: boolean
+	// Web files, and no formatter of the project's own (`own-formatter.ts`).
+	should_use_prettier: boolean
 	has_typescript: boolean
 	has_git: boolean
 	has_github: boolean
@@ -127,8 +129,12 @@ function resolve_profile(root: string, requested?: ProjectProfile): ProfileResul
 	return inferred_profile(manifest)
 }
 
+function is_ignored_directory(name: string): boolean {
+	return IGNORED_DIRECTORIES.has(name)
+}
+
 function should_visit(entry: Dirent): boolean {
-	return entry.isDirectory() && !IGNORED_DIRECTORIES.has(entry.name)
+	return entry.isDirectory() && !is_ignored_directory(entry.name)
 }
 
 function scan_directory(directory: string, pending: Array<string>): Array<string> {
@@ -152,7 +158,9 @@ function is_project_file(root: string, file: string): boolean {
 	return !kit_written_paths.is_kit_written(relative_path)
 }
 
-function file_extensions(root: string): Array<string> {
+// Every file under `root` outside the directories no setup reads — the one walk the project scan and
+// the `josh init --dry-run` snapshot share.
+function list_files(root: string): Array<string> {
 	const pending = [root]
 	const files: Array<string> = []
 
@@ -160,15 +168,24 @@ function file_extensions(root: string): Array<string> {
 		files.push(...scan_directory(directory, pending))
 	}
 
-	return files.filter((file) => is_project_file(root, file)).map((file) => path.extname(file))
+	return files
+}
+
+function file_extensions(root: string): Array<string> {
+	return list_files(root)
+		.filter((file) => is_project_file(root, file))
+		.map((file) => path.extname(file))
 }
 
-function scan_files(root: string): { has_web: boolean; has_typescript: boolean } {
+// A project that formats with its own tool gets no Prettier even with Web files: two formatters
+// would rewrite each other's output (joshuafolkken/kit#3832).
+function scan_files(root: string): { should_use_prettier: boolean; has_typescript: boolean } {
 	const extensions = file_extensions(root)
 	const has_web = extensions.some((extension) => WEB_EXTENSIONS.has(extension))
+	const should_use_prettier = has_web && own_formatter.find_config(root) === undefined
 	const has_typescript = extensions.some((extension) => TYPESCRIPT_EXTENSIONS.has(extension))
 
-	return { has_web, has_typescript }
+	return { should_use_prettier, has_typescript }
 }
 
 function has_github_remote(root: string): boolean {
@@ -205,6 +222,8 @@ const project_profile = {
 	resolve_profile,
 	has_git,
 	inspect_project,
+	is_ignored_directory,
+	list_files,
 	requested_profile,
 	with_legacy_profile_names,
 }

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-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
@@ -120,8 +121,9 @@ 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 {
@@ -133,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 {

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 }