@joshuafolkken/kit 1.1094.0 → 1.1136.0

package/scripts/gate/scoped-green.ts

@@ -2,6 +2,7 @@ import { file_map_stamp, type FileMapStampAccess } from '#scripts/josh/file-map-
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { review_brief } from '#scripts/review/review-brief'
 import { review_stamps } from '#scripts/review/review-stamps'
+import { test_unit_guard } from '#scripts/test/test-unit-guard'
 import { gate_tree, type GateTree } from './gate-tree'
 
 // Whether the two scoped checks have been green on *this exact tree* by the time the review is
@@ -60,26 +61,36 @@ interface ScopedCheck {
 
 // The record paths, overridable so a test can plant one without overwriting the record a real run in
 // this checkout relies on — the same reason `gate_skip.reusable_green_gate` takes a `source`.
+// `is_unit_skipped` is overridable for the same reason, so a suite running in a checkout with vitest
+// can stand in for a project without one.
 interface ScopedSources {
 	lint?: string
 	test?: string
+	is_unit_skipped?: boolean
 }
 
+// **`test:related` is required only where it can ever answer** (joshuafolkken/kit#3136). In a project
+// whose unit guard skips — vitest absent, or a basic project with no test file — `test:related` runs
+// nothing and so writes no record, and requiring one refused the gate forever with no way through.
+// The guard's own decision is asked rather than re-derived, so the writer and this reader agree; a
+// project with a unit suite still needs the record, and a run that executed nothing still writes none.
 function checks_of(sources: ScopedSources): ReadonlyArray<ScopedCheck> {
-	return [
-		{
-			script: LINT_SCRIPT,
-			command: LINT_COMMAND,
-			stamp: review_stamps.lint_related_stamp,
-			source: sources.lint,
-		},
-		{
-			script: TEST_SCRIPT,
-			command: TEST_COMMAND,
-			stamp: review_stamps.test_related_stamp,
-			source: sources.test,
-		},
-	]
+	const lint = {
+		script: LINT_SCRIPT,
+		command: LINT_COMMAND,
+		stamp: review_stamps.lint_related_stamp,
+		source: sources.lint,
+	}
+	const test = {
+		script: TEST_SCRIPT,
+		command: TEST_COMMAND,
+		stamp: review_stamps.test_related_stamp,
+		source: sources.test,
+	}
+
+	return (sources.is_unit_skipped ?? test_unit_guard.is_skipping(process.cwd()))
+		? [lint]
+		: [lint, test]
 }
 
 // **An unreadable record reads as an absent one, and that is the safe direction.** `read` swallows a

package/scripts/gh/git-gh-issue-list.ts

@@ -1,3 +1,4 @@
+import { bounded_pool } from '#scripts/lib/bounded-pool'
 import { git_gh_api_path } from './git-gh-api-path'
 import { git_gh_exec } from './git-gh-exec'
 import { read_blocked_by } from './git-gh-issue-read'
@@ -198,21 +199,21 @@ async function fetch_selected(request: IssueListRequest): Promise<SelectedRows>
 // issue GitHub itself reports as unblocked costs no request. A backlog with no declared blockers
 // therefore costs exactly what `gh` cost — one listing — rather than one request per row.
 //
-// Sequential rather than a burst: the only caller that asks for the field is the `auto-ok` pickup,
-// whose listing is already narrowed by a label, and a rate limit reached in parallel would fail rows
-// that a paced pass reads.
+// Bounded rather than sequential (joshuafolkken/kit#3103): the pass was paced one request at a time,
+// which made every `backlog:plan` wait about 0.7 s per opted-in issue declaring a blocker. The width
+// is the one `epic:bundle` already reads the same endpoint at, so the burst stays bounded while a
+// rate-limited read still fails the whole listing rather than a row (`bounded-pool.ts`).
+const RELATION_CONCURRENCY = 8
+
 async function read_relations(
 	rows: ReadonlyArray<RestIssue>,
 	repo?: string,
 ): Promise<Array<BlockedBy>> {
-	const relations: Array<BlockedBy> = []
-
-	for (const row of rows) {
-		// eslint-disable-next-line no-await-in-loop -- paced reads, so a rate limit does not fail rows
-		relations.push(await read_blocked_by(String(row.number), row, repo))
-	}
-
-	return relations
+	return await bounded_pool.bounded_map(
+		rows,
+		RELATION_CONCURRENCY,
+		async (row) => await read_blocked_by(String(row.number), row, repo),
+	)
 }
 
 // The listing, plus what it could not cover. `json` is `undefined` — never `'[]'` — when the listing

package/scripts/gh/git-gh-issue-write.ts

@@ -1,3 +1,4 @@
+import { error_text } from '#scripts/lib/error-message'
 import { git_gh_api_path } from './git-gh-api-path'
 import { git_gh_exec, type GhApiRequest } from './git-gh-exec'
 
@@ -43,7 +44,9 @@ async function did_write_succeed(write: () => Promise<unknown>): Promise<boolean
 		await write()
 
 		return true
-	} catch {
+	} catch (error) {
+		error_text.trace_swallowed('git_gh_issue_write.did_write_succeed', error)
+
 		return false
 	}
 }

package/scripts/gh/git-gh-pr-auto-merge.ts

@@ -1,3 +1,4 @@
+import { error_text } from '#scripts/lib/error-message'
 import { git_gh_api_path } from './git-gh-api-path'
 import { git_gh_exec } from './git-gh-exec'
 import { read_pull, require_pr_number } from './git-gh-pr-read'
@@ -40,7 +41,9 @@ async function pr_enable_auto_merge(branch_name: string): Promise<void> {
 async function pr_is_merged(branch_name: string): Promise<boolean> {
 	try {
 		return git_gh_pr_rest.is_merged(await read_pull(await require_pr_number(branch_name)))
-	} catch {
+	} catch (error) {
+		error_text.trace_swallowed('git_gh_pr_auto_merge.pr_is_merged', error)
+
 		return false
 	}
 }

package/scripts/git/git-command.ts

@@ -1,6 +1,8 @@
 import { PORCELAIN_FLAG, UNTRACKED_FILES_FLAG } from './constants'
+import { create_spawn_error } from './git-execa-error'
 import { git_push_transport } from './git-push-transport'
 import { git_spawn } from './git-spawn'
+import { git_spawn_sync } from './git-spawn-sync'
 
 async function branch(): Promise<string> {
 	return await git_spawn.read(['rev-parse', '--abbrev-ref', 'HEAD'])
@@ -31,7 +33,10 @@ async function status(directory?: string): Promise<string> {
 // onto the working directory resolves to nothing, and a digest map built that way collapses to
 // "every file absent" — which compares *equal* to another such map (joshuafolkken/kit#1241).
 async function repository_root(): Promise<string> {
-	return await git_spawn.read(['rev-parse', '--show-toplevel'])
+	const result = git_spawn_sync.toplevel()
+	if (result.exit_code !== 0) throw create_spawn_error('rev-parse', result.exit_code)
+
+	return result.stdout.trim()
 }
 
 // The commit this checkout is sitting on, as opposed to `change_base_commit`'s commit a change is

package/scripts/git/git-spawn-sync.ts

@@ -0,0 +1,65 @@
+import { read_spawn_stderr, read_spawn_stdout } from '#scripts/lib/spawn-exit'
+import { execaSync } from 'execa'
+import { git_utilities } from './constants'
+
+// The one place a synchronous git command is spawned from (joshuafolkken/kit#3065) — the sync
+// counterpart of `git-spawn.ts`. Every caller here wants an answer rather than an exception, so a
+// non-zero exit is returned as a result, and every call is bounded: a git that never answers is an
+// unknown the caller already handles, never a hang.
+
+const GIT_TIMEOUT_MS = 10_000
+const SUCCESS_EXIT_CODE = 0
+// git translates its messages, so a caller matching stderr would fail under any non-English locale.
+const C_LOCALE: Record<string, string> = { LC_ALL: 'C', LANGUAGE: 'C' }
+
+interface GitSyncOptions {
+	cwd?: string
+	timeout?: number
+	env?: Record<string, string | undefined>
+}
+
+interface GitSyncResult {
+	exit_code: number | undefined
+	stdout: string
+	stderr: string
+}
+
+function run(args: ReadonlyArray<string>, options: GitSyncOptions = {}): GitSyncResult {
+	// execa runs the binary directly with an argument array and no `shell` option; the git command and
+	// args are internally controlled, never untrusted input. tssecurity:S8705 is a false positive here.
+	const result = execaSync(git_utilities.get_git_command_for_spawn(), args, {
+		...options,
+		extendEnv: true,
+		reject: false,
+		timeout: options.timeout ?? GIT_TIMEOUT_MS,
+	}) // NOSONAR
+
+	return {
+		exit_code: result.exitCode,
+		stdout: read_spawn_stdout(result),
+		stderr: read_spawn_stderr(result),
+	}
+}
+
+// The trimmed output of a command that succeeded, or undefined for any failure.
+function read(args: ReadonlyArray<string>, options: GitSyncOptions = {}): string | undefined {
+	const result = run(args, options)
+
+	return result.exit_code === SUCCESS_EXIT_CODE ? result.stdout.trim() : undefined
+}
+
+// The configured `origin` URL, or undefined when the repository has none.
+function origin_url(cwd: string): string | undefined {
+	return read(['config', '--get', 'remote.origin.url'], { cwd })
+}
+
+// The absolute repository (or worktree) root, asked under the C locale so a caller can tell "not a
+// repository" apart from every other failure by its stderr.
+function toplevel(timeout: number = GIT_TIMEOUT_MS): GitSyncResult {
+	return run(['rev-parse', '--show-toplevel'], { env: C_LOCALE, timeout })
+}
+
+const git_spawn_sync = { GIT_TIMEOUT_MS, C_LOCALE, run, read, origin_url, toplevel }
+
+export { git_spawn_sync }
+export type { GitSyncResult }

package/scripts/git/git-spawn.ts

@@ -18,10 +18,11 @@ import { git_ssh_keepalive } from './git-ssh-keepalive'
 // **`git-push-transport.ts` is the one deliberate exception among the command modules** and is not a
 // second helper of this kind: a push needs a transport-fault retry that no other command has, so it
 // spawns git itself. The timeout it carries is shared here by `read_remote` / `with_output_remote`. Those two files are the spawn sites of the ordinary command
-// modules — the claim stops there. Other parts of this package spawn git for their own purposes
-// (`scripts/run/run-progress-clock.ts`, `scripts/propagate/propagate-git.ts`,
-// `scripts/doctor/doctor-io.ts`, `scripts/git/git-fixture-workspace.ts`), and an audit of how the git
-// binary is resolved has to read those too.
+// modules — the claim stops there. A synchronous caller goes through `git-spawn-sync.ts`, the same
+// binary resolution with a result instead of an exception (joshuafolkken/kit#3065). Other parts of
+// this package spawn git for their own purposes (`scripts/run/run-progress-clock.ts`,
+// `scripts/git/git-fixture-workspace.ts`), and an audit of how the git binary is resolved has to read
+// those too.
 
 async function read(arguments_: Array<string>): Promise<string> {
 	const git_cmd = git_utilities.get_git_command_for_spawn()

package/scripts/git/stash/stash-pop-args.ts

@@ -21,12 +21,7 @@ interface Request {
 }
 
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	return cli_flags.parse_or_undefined({
-		args: [...argv],
-		options: OPTIONS,
-		strict: true,
-		allowPositionals: true,
-	})
+	return cli_flags.arguments_of(argv, OPTIONS)
 }
 
 // The message is the sole positional and must be a non-empty string: an empty message matches every

package/scripts/init/claude-kit-only-settings.ts

@@ -0,0 +1,29 @@
+import { patch_json_key } from '#scripts/config-merge/patch-json-key'
+import { claude_plugin_config } from './claude-plugin-config'
+
+// Keys kit's own `.claude/settings.json` sets for its sessions but never ships. `enableArtifact:
+// false` keeps the Artifact tool's ~12k tokens out of every call of a kit run
+// (joshuafolkken/kit#3140), but Claude Code lets any layer that sets it to `false` win, so a
+// consumer given it could not turn the tool back on from `.claude/settings.local.json`.
+const KIT_ONLY_SETTING_KEYS: ReadonlyArray<string> = ['enableArtifact']
+
+function strip_kit_only_settings(content: string): string {
+	let stripped = content
+	for (const key of KIT_ONLY_SETTING_KEYS) stripped = patch_json_key.remove_json_key(stripped, key)
+
+	return stripped
+}
+
+function apply_kit_only_strip_for_destination(destination_path: string, content: string): string {
+	return destination_path.endsWith(claude_plugin_config.CLAUDE_SETTINGS_DESTINATION)
+		? strip_kit_only_settings(content)
+		: content
+}
+
+const claude_kit_only_settings = {
+	KIT_ONLY_SETTING_KEYS,
+	strip_kit_only_settings,
+	apply_kit_only_strip_for_destination,
+}
+
+export { claude_kit_only_settings }

package/scripts/init/init-copy-content.ts

@@ -1,6 +1,7 @@
 import { managed_marker_logic } from '#scripts/managed-marker/managed-marker-logic'
 import { workflow_pin_logic } from '#scripts/sync/workflow-pin-logic'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
+import { claude_kit_only_settings } from './claude-kit-only-settings'
 import { claude_plugin_config } from './claude-plugin-config'
 import { hook_command_rewrite } from './hook-command-rewrite'
 import { init_logic } from './init-logic'
@@ -19,7 +20,8 @@ import { init_logic } from './init-logic'
  * workflow-pin-logic.ts for why the template refs are not authoritative, and
  * managed-marker-logic.ts for why the stamp is on the file rather than in a list.
  *
- * The consumer's `.claude/settings.json` gets two further passes. The kit plugin's marketplace and
+ * The consumer's `.claude/settings.json` gets three further passes. The keys kit sets only for its
+ * own sessions are removed (joshuafolkken/kit#3140, see claude-kit-only-settings.ts). The kit plugin's marketplace and
  * `enabledPlugins` declaration is injected, because the skills that used to be copied now ship as the
  * `kit` plugin and load from that declaration (joshuafolkken/kit#1879). And its hook commands are
  * rewritten from `pnpm josh` to the published bundle invoked directly with node
@@ -36,10 +38,14 @@ function transform_copied_content(destination_path: string, content: string): st
 		with_pins,
 		KIT_PACKAGE_NAME,
 	)
-	const with_plugin = claude_plugin_config.apply_plugin_config_for_destination(
+	const with_kit_only_stripped = claude_kit_only_settings.apply_kit_only_strip_for_destination(
 		destination_path,
 		with_marker,
 	)
+	const with_plugin = claude_plugin_config.apply_plugin_config_for_destination(
+		destination_path,
+		with_kit_only_stripped,
+	)
 
 	return hook_command_rewrite.apply_hook_command_rewrite_for_destination(
 		destination_path,

package/scripts/init/init-file-action.ts

@@ -0,0 +1,54 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import type { FileAction } from './init-actions'
+
+const SAMPLE_INDENT_WIDTH = 4
+const SAMPLE_INDENT = ' '.repeat(SAMPLE_INDENT_WIDTH)
+
+function write_new_file(action: FileAction, destination_path: string): void {
+	mkdirSync(path.dirname(destination_path), { recursive: true })
+	writeFileSync(destination_path, action.create())
+	console.info(`  ✔ created   ${action.dest}`)
+}
+
+function show_sample(action: FileAction): void {
+	console.info(`  ⚠ exists    ${action.dest} — add manually:`)
+	console.info('')
+	console.info(action.create().replaceAll(/^/gmu, () => SAMPLE_INDENT))
+}
+
+// A file that already holds the sample needs nothing added, so only one that differs gets it shown —
+// for a create-only file (no merge) as for a merge that only migrates a kit-written line (#3069).
+function report_unchanged(action: FileAction, existing: string): void {
+	const is_sample_missing = existing !== action.create()
+	const should_show_sample =
+		action.merge === undefined || action.should_show_sample_when_unchanged === true
+
+	if (is_sample_missing && should_show_sample) show_sample(action)
+	else console.info(`  ✔ unchanged ${action.dest}`)
+}
+
+function merge_existing_file(action: FileAction, destination_path: string): void {
+	const existing = readFileSync(destination_path, 'utf8')
+	const merged = action.merge === undefined ? existing : action.merge(existing)
+
+	if (merged === existing) {
+		report_unchanged(action, existing)
+
+		return
+	}
+
+	writeFileSync(destination_path, merged)
+	console.info(`  ✔ updated   ${action.dest}`)
+}
+
+function execute_file_action(action: FileAction, project_root: string): void {
+	const destination_path = path.join(project_root, action.dest)
+
+	if (existsSync(destination_path)) merge_existing_file(action, destination_path)
+	else write_new_file(action, destination_path)
+}
+
+const init_file_action = { execute_file_action }
+
+export { init_file_action }

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

@@ -4,6 +4,27 @@ const PREINSTALL_KEY = 'preinstall'
 const JF_PREFIX = 'jf-'
 const JOSH_PREFIX = 'josh '
 
+// The plain values kit wrote before its scripts became josh subcommands (#80). `check` is left out:
+// its value is the one `sv create` writes itself, so it cannot be told apart from the project's own.
+const PRE_JOSH_SCRIPT_VALUES: ReadonlyMap<string, string> = new Map([
+	['lint', 'pnpm lint:prettier && pnpm lint:eslint'],
+	['lint:prettier', 'prettier --check .'],
+	['lint:eslint', 'eslint . --cache --cache-strategy content'],
+	['format', 'pnpm format:prettier && pnpm format:eslint'],
+	['format:prettier', 'prettier --write .'],
+	['format:eslint', 'eslint . --fix --cache --cache-strategy content'],
+	['cspell', 'cspell lint --no-must-find-files --no-progress "**/*.{ts,js,md,yaml,yml,json}"'],
+	['cspell:dot', 'pnpm cspell . --dot'],
+	['test:unit', 'vitest run'],
+	['lefthook:install', 'lefthook install'],
+	['lefthook:uninstall', 'lefthook uninstall'],
+	['lefthook:commit', 'lefthook run pre-commit'],
+	['lefthook:push', 'lefthook run pre-push'],
+	['main:sync', 'git checkout main && git pull'],
+	['main:merge', 'git pull origin main'],
+	['check:ci', 'svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --threshold error'],
+])
+
 const RETIRED_MANAGED_SCRIPTS = new Set<string>([
 	'git',
 	'git:followup',
@@ -18,30 +39,15 @@ const RETIRED_MANAGED_SCRIPTS = new Set<string>([
 	'version:patch',
 	'version:current',
 	'overrides:check',
-	'lint',
-	'lint:prettier',
-	'lint:eslint',
-	'format',
-	'format:prettier',
-	'format:eslint',
-	'cspell',
-	'cspell:dot',
-	'test:unit',
 	'test:e2e',
 	'test',
-	'lefthook:install',
-	'lefthook:uninstall',
-	'lefthook:commit',
-	'lefthook:push',
-	'main:sync',
-	'main:merge',
 	'latest',
 	'latest:corepack',
 	'latest:update',
 	'check',
-	'check:ci',
 	'check:svelte',
 	'check:svelte:ci',
+	...PRE_JOSH_SCRIPT_VALUES.keys(),
 ])
 
 function migrate_jf_value(value: string): string {
@@ -62,9 +68,21 @@ function apply_jf_migrations(scripts: Record<string, string>): Record<string, st
 	)
 }
 
+function is_kit_written(key: string, value: string): boolean {
+	if (value.startsWith(JOSH_PREFIX) || value.startsWith(JF_PREFIX)) return true
+
+	return PRE_JOSH_SCRIPT_VALUES.get(key) === value
+}
+
+// A retired name alone does not make a script kit's: `sv create` writes its own `check`, which must
+// survive `josh init` (joshuafolkken/kit#3069). Only a value kit itself wrote is retired.
+function is_retired_script(key: string, value: string): boolean {
+	return RETIRED_MANAGED_SCRIPTS.has(key) && is_kit_written(key, value)
+}
+
 function remove_retired_scripts(scripts: Record<string, string>): Record<string, string> {
 	return Object.fromEntries(
-		Object.entries(scripts).filter(([key]) => !RETIRED_MANAGED_SCRIPTS.has(key)),
+		Object.entries(scripts).filter(([key, value]) => !is_retired_script(key, value)),
 	)
 }
 

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

@@ -5,7 +5,7 @@ const SECRETLINT_RULE_PRESET = '@secretlint/secretlint-rule-preset-recommend'
 
 // secretlint resolves both its CLI and every rule package from the project it runs in, not
 // transitively through the kit — the same constraint that forces the prettier plugins into
-// consumer devDependencies (see PRETTIER_PLUGIN_DEV_DEPS in init-logic.ts). Omitting either
+// consumer devDependencies (as kit peers, see init.ts). Omitting either
 // entry makes the pre-commit hook fail with "Cannot find module". Versions mirror the kit's
 // own devDependencies.
 const SECRETLINT_DEV_DEPS: Record<string, string> = {

package/scripts/init/init-logic.ts

@@ -92,10 +92,13 @@ const AI_COPY_FILES: ReadonlyArray<string> = [
 	'.github/workflows/production.yml',
 	'.github/workflows/sonar-qube.yml',
 	'.github/workflows/pr-classification.yml',
-	// Called by `pr-classification.yml` as `uses: ./.github/actions/setup-pnpm`; without it the
-	// consumer's job cannot resolve the action and the Release classification check fails
-	// (joshuafolkken/kit#3013).
+	// Called by `ci.yml` and `pr-classification.yml` as `uses: ./.github/actions/setup-pnpm`; without
+	// it the consumer's jobs cannot resolve the action and their checks fail (joshuafolkken/kit#3013,
+	// joshuafolkken/kit#3095).
 	'.github/actions/setup-pnpm/action.yml',
+	// The one place the workflows' Node.js version is written, called by every distributed workflow
+	// that sets Node.js up (joshuafolkken/kit#3084).
+	'.github/actions/setup-node/action.yml',
 	'.github/pull_request_template.md',
 	'.github/release.yml',
 	'.github/dependabot.yml',
@@ -220,20 +223,6 @@ const SUGGESTED_SCRIPTS_COMMON: Record<string, string> = {
 	josh: 'josh',
 }
 
-// prettier resolves its `plugins[]` from the consumer project, not transitively through the kit,
-// so every package that uses the kit prettier preset must declare these as devDependencies. The
-// preset references all three unconditionally (prettier/index.js → plugins), hence all three are
-// added regardless of project — omitting any breaks `prettier`/`josh lint` with a
-// "Cannot find package" error. Versions mirror the kit's own devDependencies.
-const SORT_IMPORTS_PLUGIN_KEY = '@ianvs/prettier-plugin-sort-imports'
-const PRETTIER_SVELTE_PLUGIN_KEY = 'prettier-plugin-svelte'
-const PRETTIER_TAILWIND_PLUGIN_KEY = 'prettier-plugin-tailwindcss'
-const PRETTIER_PLUGIN_DEV_DEPS: Record<string, string> = {
-	[SORT_IMPORTS_PLUGIN_KEY]: '^4.7.1',
-	[PRETTIER_SVELTE_PLUGIN_KEY]: '^4.1.1',
-	[PRETTIER_TAILWIND_PLUGIN_KEY]: '^0.8.0',
-}
-
 // format_json rather than JSON.stringify: it lays arrays out the way prettier does — inline while
 // they fit within printWidth, one element per line once they do not — so the file kit writes is
 // `prettier --check`-clean in the consumer whatever the entry count happens to be (#660).
@@ -433,10 +422,6 @@ function strip_managed_postinstall(content: string): string {
 	)
 }
 
-function merge_prettier_plugin_development_deps(content: string): string {
-	return init_logic_json_merge.merge_development_dependencies(content, PRETTIER_PLUGIN_DEV_DEPS)
-}
-
 const init_logic = {
 	...init_logic_templates,
 	...init_logic_workspace,
@@ -454,7 +439,6 @@ const init_logic = {
 	generate_npmrc,
 	merge_npmrc,
 	merge_gitignore,
-	merge_prettier_plugin_development_deps,
 	get_tsconfig_extends_entry,
 	get_tsconfig_preset_filename,
 	get_lefthook_extends_value,

package/scripts/init/init.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env tsx
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { resolve_local_bin } from '#scripts/build/local-bin'
@@ -7,6 +7,7 @@ import { doctor_io } from '#scripts/doctor/doctor-io'
 import { error_text } from '#scripts/lib/error-message'
 import { package_version_schema, with_package_manager_schema } from '#scripts/lib/schemas'
 import { auto_merge_setting } from '#scripts/repo/auto-merge-setting'
+import { pack_hook } from '#scripts/safe-chain/pack-hook'
 import { project_config } from '#scripts/safe-chain/project-config'
 import { security_updates } from '#scripts/security/security-updates'
 import { did_refuse_self_run } from '#scripts/self-sync-guard/self-sync-refusal'
@@ -14,10 +15,11 @@ import { sync } from '#scripts/sync/sync'
 import { package_manager_version } from '#scripts/version/package-manager-version'
 import { execaSync } from 'execa'
 import { z } from 'zod'
-import { init_actions, PRETTIER_CONFIG_JS, type FileAction } from './init-actions'
+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_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'
@@ -27,69 +29,10 @@ import { project_profile, type ProjectProfile, type ProjectShape } from './proje
 const PACKAGE_JSON = 'package.json'
 const KIT_PACKAGE_NAME = '@joshuafolkken/kit'
 const LEFTHOOK_BIN = 'lefthook'
-const SAMPLE_INDENT_WIDTH = 4
 const ARGUMENT_START_INDEX = 2
-const SAMPLE_INDENT = ' '.repeat(SAMPLE_INDENT_WIDTH)
 const INSTALL_HINT = '→ run `pnpm install` to install what package.json lists'
 const INIT_USAGE = 'josh init [--profile basic|full] [--no-install]'
 
-function write_new_file(action: FileAction, destination_path: string): void {
-	mkdirSync(path.dirname(destination_path), { recursive: true })
-	writeFileSync(destination_path, action.create())
-	console.info(`  ✔ created   ${action.dest}`)
-}
-
-function show_sample(action: FileAction): void {
-	console.info(`  ⚠ exists    ${action.dest} — add manually:`)
-	console.info('')
-	console.info(action.create().replaceAll(/^/gmu, () => SAMPLE_INDENT))
-}
-
-// A file that already holds the sample needs nothing added, so only one that differs gets it shown.
-function report_unchanged(action: FileAction, existing: string): void {
-	const is_sample_missing = existing !== action.create()
-
-	if (is_sample_missing && action.should_show_sample_when_unchanged === true) show_sample(action)
-	else console.info(`  ✔ unchanged ${action.dest}`)
-}
-
-function merge_existing_file(
-	merge_function: (existing: string) => string,
-	destination_path: string,
-	action: FileAction,
-): void {
-	const existing = readFileSync(destination_path, 'utf8')
-	const merged = merge_function(existing)
-
-	if (merged === existing) {
-		report_unchanged(action, existing)
-
-		return
-	}
-
-	writeFileSync(destination_path, merged)
-	console.info(`  ✔ updated   ${action.dest}`)
-}
-
-function execute_file_action(action: FileAction): void {
-	const destination_path = path.join(PROJECT_ROOT, action.dest)
-	const is_existing = existsSync(destination_path)
-
-	if (!is_existing) {
-		write_new_file(action, destination_path)
-
-		return
-	}
-
-	if (action.merge === undefined) {
-		show_sample(action)
-
-		return
-	}
-
-	merge_existing_file(action.merge, destination_path, action)
-}
-
 const engine_pin_schema = z.looseObject({ name: z.string(), version: z.string() })
 
 const published_development_engines_schema = z.looseObject({
@@ -124,10 +67,10 @@ function get_kit_self_dependency(): Record<string, string> {
 }
 
 // Each config `init` generates runs a CLI or imports types the consumer has to resolve itself:
-// `prettier.config.js` → prettier, `cspell.config.yaml` → cspell, `playwright.config.ts` →
-// @types/node (with @playwright/test among the peers), `lefthook.yml` → lefthook. Without them the
-// first `josh gate` after `pnpm install` fails (joshuafolkken/kit#2710).
-const TOOL_DEVELOPMENT_DEPENDENCIES = ['prettier', 'cspell', '@types/node']
+// `cspell.config.yaml` → cspell, `playwright.config.ts` → @types/node, `lefthook.yml` → lefthook.
+// Prettier, its preset plugins and @playwright/test come in as peers. Without them the first
+// `josh gate` after `pnpm install` fails (joshuafolkken/kit#2710).
+const TOOL_DEVELOPMENT_DEPENDENCIES = ['cspell', '@types/node']
 const LEFTHOOK_DEVELOPMENT_DEPENDENCY = 'lefthook'
 
 function tool_dependency_names(has_git: boolean): ReadonlyArray<string> {
@@ -164,9 +107,8 @@ function apply_dependency_merges(content: string, has_git = true): string {
 			? suggested
 			: Object.fromEntries(Object.entries(suggested).filter(([key]) => key !== 'prepare')),
 	)
-	const with_prettier = init_logic.merge_prettier_plugin_development_deps(merged)
 	const with_toolchain = init_logic.merge_development_dependencies(
-		with_prettier,
+		merged,
 		get_toolchain_development_dependencies(has_git),
 	)
 	const with_secretlint = init_logic.merge_secretlint_development_deps(with_toolchain)
@@ -262,7 +204,7 @@ function run_config_file_actions(shape: ProjectShape): void {
 	}
 
 	for (const action of init_actions.build_file_actions(shape)) {
-		execute_file_action(action)
+		init_file_action.execute_file_action(action, PROJECT_ROOT)
 	}
 }
 
@@ -305,6 +247,7 @@ function initialize_project(shape: ProjectShape): void {
 	merge_project_package_json(shape)
 
 	run_ai_file_actions(shape)
+	pack_hook.sync_pack_hook(PROJECT_ROOT, PACKAGE_DIR)
 	if (shape.profile === 'full') project_config.sync_project_config(PROJECT_ROOT)
 }