@joshuafolkken/kit 1.887.0 → 1.929.0

package/scripts/gate/project-checks.ts

@@ -0,0 +1,145 @@
+import { existsSync, globSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { find_local_bin_upwards } from '#scripts/build/local-bin'
+import { SKIP_MARKER } from '#scripts/test/skip-marker'
+
+const PACKAGE_JSON = 'package.json'
+const IGNORED_DIRS = new Set([
+	'node_modules',
+	'.git',
+	'.venv',
+	'venv',
+	'target',
+	'dist',
+	'build',
+	'.svelte-kit',
+])
+const WEB_FILES = '**/*.{html,css,js,jsx,mjs,cjs}'
+const SCRIPT_FILES = '**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}'
+const TYPE_FILES = '**/*.{ts,tsx,mts,cts}'
+const ESLINT_CONFIGS = [
+	'eslint.config.js',
+	'eslint.config.mjs',
+	'eslint.config.cjs',
+	'eslint.config.ts',
+	'eslint.config.mts',
+	'eslint.config.cts',
+]
+const CSPELL_CONFIGS = [
+	'cspell.config.yaml',
+	'cspell.config.yml',
+	'cspell.config.json',
+	'cspell.config.js',
+	'cspell.config.cjs',
+	'cspell.config.mjs',
+	'cspell.json',
+	'cspell.yaml',
+]
+const TYPE_CONFIGS = ['tsconfig.json', 'jsconfig.json']
+
+function project_root(directory: string): string {
+	let current = directory
+
+	while (!existsSync(path.join(current, PACKAGE_JSON))) {
+		const parent = path.dirname(current)
+		if (parent === current) return directory
+		current = parent
+	}
+
+	return current
+}
+
+function is_ignored(entry: string): boolean {
+	return entry.split(/[/\\]/u).some((part) => IGNORED_DIRS.has(part))
+}
+
+function has_files(directory: string, pattern: string): boolean {
+	return globSync(pattern, { cwd: project_root(directory), exclude: is_ignored }).length > 0
+}
+
+function has_config(directory: string, names: ReadonlyArray<string>): boolean {
+	return names.some((name) => existsSync(path.join(project_root(directory), name)))
+}
+
+function has_bin(directory: string, bin_name: string): boolean {
+	return find_local_bin_upwards(directory, bin_name) !== undefined
+}
+
+function josh_settings(manifest: unknown): unknown {
+	if (typeof manifest !== 'object' || manifest === null || !('josh' in manifest)) return undefined
+
+	return manifest.josh
+}
+
+function is_static_manifest(manifest: unknown): boolean {
+	const josh = josh_settings(manifest)
+	if (typeof josh !== 'object' || josh === null || !('profile' in josh)) return false
+
+	return josh.profile === 'static'
+}
+
+function is_static(directory: string): boolean {
+	try {
+		const manifest_path = path.join(project_root(directory), PACKAGE_JSON)
+		const manifest: unknown = JSON.parse(readFileSync(manifest_path, 'utf8'))
+
+		return is_static_manifest(manifest)
+	} catch {
+		return false
+	}
+}
+
+function skip_notice(check: string, reason: string): string {
+	return `josh ${check}: ${reason} ${SKIP_MARKER} ${check}.`
+}
+
+function type_check_skip_reason(directory: string): string | undefined {
+	if (!is_static(directory)) return undefined
+	if (!has_files(directory, TYPE_FILES)) return 'no TypeScript files were found'
+	if (!has_config(directory, TYPE_CONFIGS)) return 'no TypeScript configuration was found'
+	if (!has_bin(directory, 'tsc')) return 'typescript is not installed'
+
+	return undefined
+}
+
+// Shared by `josh lint` and `josh format`, so a static project without Web files — a Python or Rust
+// project, which `josh init` gives no Prettier — is skipped for the same reason by both
+// (joshuafolkken/kit#2606).
+function prettier_skip_reason(directory: string): string | undefined {
+	if (!is_static(directory)) return undefined
+	if (!has_files(directory, WEB_FILES)) return 'no HTML, CSS or JavaScript files were found'
+	if (!has_bin(directory, 'prettier')) return 'prettier is not installed'
+
+	return undefined
+}
+
+// Shared by `josh lint` and `josh format`, so a static project without ESLint is skipped for the
+// same reason by both (joshuafolkken/kit#2693).
+function eslint_skip_reason(directory: string): string | undefined {
+	if (!is_static(directory)) return undefined
+	if (!has_files(directory, SCRIPT_FILES)) return 'no JavaScript or TypeScript files were found'
+	if (!has_config(directory, ESLINT_CONFIGS)) return 'no ESLint configuration was found'
+	if (!has_bin(directory, 'eslint')) return 'eslint is not installed'
+
+	return undefined
+}
+
+const project_checks = {
+	CSPELL_CONFIGS,
+	ESLINT_CONFIGS,
+	SCRIPT_FILES,
+	TYPE_CONFIGS,
+	TYPE_FILES,
+	WEB_FILES,
+	eslint_skip_reason,
+	has_bin,
+	has_config,
+	has_files,
+	is_static,
+	prettier_skip_reason,
+	project_root,
+	skip_notice,
+	type_check_skip_reason,
+}
+
+export { project_checks }

package/scripts/gate/verification-gate.ts

@@ -10,12 +10,13 @@ import { review_stamps } from '#scripts/review/review-stamps'
 import { review_tree } from '#scripts/review/review-tree'
 import { unit_worker_share } from '#scripts/test/unit-worker-share'
 import { core_budget } from './core-budget'
-import { gate_plan, type GateCheck, type GatePlan } from './gate-plan'
+import { gate_plan, type GatePlan } from './gate-plan'
 import { gate_report, type GateStep, type GateStepResult } from './gate-report'
 import { gate_skip } from './gate-skip'
+import { build_gate_step, build_gate_steps, UNIT_WORKER_FLAG } from './gate-steps'
 import { gate_tree, type GateTree } from './gate-tree'
+import { project_checks } from './project-checks'
 import { scoped_green, type ScopedSources } from './scoped-green'
-import { type_check_step } from './type-check-step'
 
 // joshuafolkken/kit#914: the completion gate's four checks are independent and share no mutable
 // state, yet every entry point ran them one after another — paid again on every `epicrun` child,
@@ -33,55 +34,25 @@ import { type_check_step } from './type-check-step'
 // `process.argv` is [runner, script, ...arguments].
 const FIRST_ARGUMENT_INDEX = 2
 
-const JOSH = 'josh'
-const { GATE_CHECKS, TYPE_CHECK_LABEL, UNIT_LABEL } = gate_plan
+const { GATE_CHECKS } = gate_plan
 
 const GATE_TARGETS: ReadonlyArray<string> = GATE_CHECKS.map((check) => check.target)
 
-// vitest's own flag, appended to the sub-command rather than set in `vitest.config.ts`: the config
-// is one project's, and the number this carries is a property of the machine the gate is running
-// on (joshuafolkken/kit#1258). `josh test:unit` forwards what it is given straight to
-// `vitest run`, so nothing between here and vitest has to know about it.
-const UNIT_WORKER_FLAG = '--maxWorkers'
-
-function unit_worker_args(check: GateCheck, plan: GatePlan): ReadonlyArray<string> {
-	if (check.label !== UNIT_LABEL || plan.unit_worker_cap === undefined) return []
-
-	return [`${UNIT_WORKER_FLAG}=${String(plan.unit_worker_cap)}`]
-}
-
-// Only the type check is resolved per project (joshuafolkken/kit#934) — a SvelteKit project
-// type-checks through its own toolkit, not through `tsc --noEmit`. Resolving inside the step keeps
-// the probe concurrent with the other three checks rather than delaying every one of them.
-async function build_gate_step(
-	check: GateCheck,
-	start_directory: string,
-	plan: GatePlan = gate_plan.resolve_gate_plan(),
-): Promise<GateStep> {
-	if (check.label !== TYPE_CHECK_LABEL) {
+async function run_gate_step(step: GateStep): Promise<GateStepResult> {
+	if (step.skip_reason !== undefined) {
 		return {
-			label: check.label,
-			command_args: [JOSH, check.target, ...unit_worker_args(check, plan)],
+			label: step.label,
+			command: step.command_args.join(' '),
+			output: project_checks.skip_notice('check', step.skip_reason),
+			exit_code: 0,
+			elapsed_ms: 0,
 		}
 	}
 
-	return {
-		label: check.label,
-		command_args: await type_check_step.resolve_type_check_args(start_directory),
-	}
-}
-
-async function build_gate_steps(
-	start_directory: string,
-	plan: GatePlan = gate_plan.resolve_gate_plan(),
-): Promise<ReadonlyArray<GateStep>> {
-	return await Promise.all(
-		plan.checks.map(async (check) => await build_gate_step(check, start_directory, plan)),
+	const result = await buffered_process.run_buffered_process(
+		step.command_args,
+		step.cwd === undefined ? {} : { cwd: step.cwd },
 	)
-}
-
-async function run_gate_step(step: GateStep): Promise<GateStepResult> {
-	const result = await buffered_process.run_buffered_process(step.command_args)
 
 	return { label: step.label, command: step.command_args.join(' '), ...result }
 }

package/scripts/git/git-common-directory.ts

@@ -33,6 +33,14 @@ function resolve(cwd: string): string | undefined {
 	}
 }
 
-const git_common_directory = { resolve, select_linked }
+function repository(cwd: string): string | undefined {
+	try {
+		return read_directories(cwd)[COMMON_GIT_DIRECTORY]
+	} catch {
+		return undefined
+	}
+}
+
+const git_common_directory = { repository, resolve, select_linked }
 
 export { git_common_directory }

package/scripts/git/git-gh-pr-rollup.ts

@@ -29,6 +29,7 @@ const check_runs_page_schema = z.looseObject({
 	// answer an empty rollup — which `git-pr-followup.ts` reports as "this branch has no checks".
 	check_runs: z.array(rollup_element_schema),
 })
+const check_run_app_schema = z.object({ id: z.number() })
 
 const status_page_schema = z.looseObject({
 	statuses: z.array(rollup_element_schema),
@@ -50,10 +51,37 @@ function read_pages<T>(raw_json: string, schema: z.ZodType<T>, message: string):
 	return pages
 }
 
+function check_run_group_key(run: RollupElement): string | undefined {
+	const { name, app: raw_app } = run
+	if (typeof name !== 'string') return undefined
+	const app = check_run_app_schema.safeParse(raw_app)
+
+	return JSON.stringify([name, app.success ? app.data.id : undefined])
+}
+
+function remember_newest_run(run: RollupElement, latest_ids: Map<string, number>): void {
+	const key = check_run_group_key(run)
+	const { id } = run
+	if (key === undefined || typeof id !== 'number') return
+	const previous_id = latest_ids.get(key)
+	if (previous_id === undefined || id > previous_id) latest_ids.set(key, id)
+}
+
+function is_newest_run(run: RollupElement, latest_ids: Map<string, number>): boolean {
+	const key = check_run_group_key(run)
+	const { id } = run
+	if (key === undefined || typeof id !== 'number') return true
+
+	return id === latest_ids.get(key)
+}
+
 function to_check_run_items(check_runs_json: string): Array<RollupElement> {
 	const pages = read_pages(check_runs_json, check_runs_page_schema, NOT_A_CHECK_RUNS_LISTING)
+	const runs = pages.flatMap((page) => page.check_runs)
+	const latest_ids = new Map<string, number>()
+	for (const run of runs) remember_newest_run(run, latest_ids)
 
-	return pages.flatMap((page) => page.check_runs)
+	return runs.filter((run) => is_newest_run(run, latest_ids))
 }
 
 function to_status_context_items(status_json: string): Array<RollupElement> {

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

@@ -1,4 +1,6 @@
+import { pr_classification, type ReleaseClassification } from '#scripts/ci/pr-classification'
 import { poll } from '#scripts/lib/poll'
+import { z } from 'zod'
 import { git_command } from './git-command'
 import { git_gh_api_path } from './git-gh-api-path'
 import { git_gh_exec } from './git-gh-exec'
@@ -46,6 +48,44 @@ const MERGE_UNCONFIRMED_MESSAGE =
 	'gh api could not read the pull request back after the merge request failed'
 const MERGE_READ_BACK_ATTEMPTS = 3
 const MERGE_READ_BACK_INTERVAL_MS = 1000
+const PR_NUMBER_PATTERN = /\/pull\/([1-9]\d*)$/u
+const LABELS_SEGMENT = '/labels'
+const PR_LABELS = z.array(z.object({ name: z.string() }))
+
+async function add_pr_classification(number: string, label: ReleaseClassification): Promise<void> {
+	await git_gh_exec.exec_gh_api({
+		path: `${git_gh_api_path.issue_api_path(number)}${LABELS_SEGMENT}`,
+		body: JSON.stringify({ labels: [label] }),
+	})
+}
+
+async function pr_get_classification(
+	branch_name: string,
+): Promise<ReleaseClassification | undefined> {
+	const number = await require_pr_number(branch_name)
+	const response = await git_gh_exec.exec_gh_api({
+		path: `${git_gh_api_path.issue_api_path(String(number))}${LABELS_SEGMENT}`,
+	})
+	const names = PR_LABELS.parse(JSON.parse(response)).map((label) => label.name.toLowerCase())
+	const selected = names.filter((name) => pr_classification.is_classification(name))
+	if (selected.length === 0) return undefined
+
+	const error = pr_classification.classification_error(names, 'human')
+	if (error !== undefined) throw new Error(error)
+
+	return selected[0]
+}
+
+async function pr_ensure_classification(
+	branch_name: string,
+	label: ReleaseClassification,
+): Promise<void> {
+	if ((await pr_get_classification(branch_name)) !== undefined) return
+
+	const number = await require_pr_number(branch_name)
+
+	await add_pr_classification(String(number), label)
+}
 
 // **`head` is required and `gh pr create` never asked for it.** The CLI inferred it from the current
 // branch; REST does not, and a request without it is a 422. The branch is read from git rather than
@@ -64,7 +104,7 @@ const MERGE_READ_BACK_INTERVAL_MS = 1000
 // `to_gh_error` appends stdout (joshuafolkken/kit#1029); the `already exists` match itself is
 // unchanged, because both wordings contain it and the 422 carries no machine-readable code for the
 // case (`"code":"custom"`).
-async function pr_create(title: string, body: string): Promise<string> {
+async function post_pull_request(title: string, body: string): Promise<string> {
 	const base = await git_command.get_default_branch()
 	const head = await git_command.branch()
 
@@ -81,6 +121,24 @@ async function pr_create(title: string, body: string): Promise<string> {
 	}
 }
 
+async function pr_create(
+	title: string,
+	body: string,
+	label: ReleaseClassification,
+): Promise<string> {
+	const classification_error = pr_classification.classification_error([label], 'human')
+	if (classification_error !== undefined) throw new Error(classification_error)
+
+	const url = await post_pull_request(title, body)
+	const number = PR_NUMBER_PATTERN.exec(url)?.[1]
+
+	if (number === undefined) throw new Error(`Could not identify the created pull request: ${url}`)
+
+	await add_pr_classification(number, label)
+
+	return url
+}
+
 // **`gh pr checkout` does use GraphQL** — one `POST /graphql` to resolve the pull request, measured
 // with `GH_DEBUG=api` on the throwaway pull request (joshuafolkken/kit#1029). Everything after that
 // is git, so only the resolution had to move: `pr_head_reference` is the REST read that already
@@ -210,6 +268,8 @@ const git_gh_pr = {
 	...git_gh_pr_read,
 	...git_gh_pr_snapshot,
 	pr_create,
+	pr_get_classification,
+	pr_ensure_classification,
 	pr_checkout,
 	pr_comment,
 	pr_merge,

package/scripts/git/git-pr.ts

@@ -1,3 +1,4 @@
+import { pr_classification, type ReleaseClassification } from '#scripts/ci/pr-classification'
 import { animation_helpers, type AnimationOptions } from './animation-helpers'
 import { git_gh_command } from './git-gh-command'
 import type { IssueInfo } from './git-issue'
@@ -12,7 +13,11 @@ import { pr_info_schema } from './schemas'
 // in the same instant the pull request was created it can answer nothing, and `pr_get_url` folds
 // "not there yet" and "the read failed" into the same `undefined`. The five-second sleep used to
 // cover that gap incidentally.
-async function create_pr(title: string, body: string): Promise<string | undefined> {
+async function create_pr(
+	title: string,
+	body: string,
+	label: ReleaseClassification,
+): Promise<string | undefined> {
 	const config: AnimationOptions<string> = {
 		icon_selector: () => '✅',
 		error_message: 'Failed to create PR',
@@ -22,7 +27,7 @@ async function create_pr(title: string, body: string): Promise<string | undefine
 	try {
 		return await animation_helpers.execute_with_animation(
 			'Creating pull request...',
-			async () => await git_gh_command.pr_create(title, body),
+			async () => await git_gh_command.pr_create(title, body, label),
 			config,
 		)
 	} catch (error) {
@@ -72,8 +77,13 @@ async function report_open_pr(branch_name: string, created_url?: string): Promis
 
 const PR_STATE_MERGED = 'MERGED'
 
-async function create_and_report(title: string, body: string, branch_name: string): Promise<void> {
-	const created_url = await create_pr(title, body)
+async function create_and_report(
+	title: string,
+	body: string,
+	branch_name: string,
+	label: ReleaseClassification,
+): Promise<void> {
+	const created_url = await create_pr(title, body, label)
 
 	await report_open_pr(branch_name, created_url)
 }
@@ -113,7 +123,9 @@ async function report_existing_pr(
 	body: string,
 	branch_name: string,
 	should_replace_body: boolean,
+	label: ReleaseClassification,
 ): Promise<void> {
+	await git_gh_command.pr_ensure_classification(branch_name, label)
 	if (should_replace_body) await git_gh_command.pr_update_body(branch_name, body)
 
 	await report_open_pr(branch_name)
@@ -123,35 +135,36 @@ async function handle_existing_pr(
 	title: string,
 	body: string,
 	branch_name: string,
-	should_replace_body: boolean,
+	options: { label: ReleaseClassification; should_replace_body: boolean },
 ): Promise<void> {
 	const pr_state_result = await get_pr_state_safe(branch_name)
 
 	if (is_pr_state_merged(pr_state_result)) {
 		git_pr_messages.display_merged_pr_message()
-		await create_and_report(title, body, branch_name)
+		await create_and_report(title, body, branch_name, options.label)
 
 		return
 	}
 
-	await report_existing_pr(body, branch_name, should_replace_body)
+	await report_existing_pr(body, branch_name, options.should_replace_body, options.label)
 }
 
 async function create(
 	title: string,
 	body: string,
 	branch_name: string,
-	should_replace_body = false,
+	options: { label: ReleaseClassification; should_replace_body?: boolean },
 ): Promise<void> {
+	const { label, should_replace_body = false } = options
 	const has_pr = await git_gh_command.pr_exists(branch_name)
 
 	if (!has_pr) {
-		await create_and_report(title, body, branch_name)
+		await create_and_report(title, body, branch_name, label)
 
 		return
 	}
 
-	await handle_existing_pr(title, body, branch_name, should_replace_body)
+	await handle_existing_pr(title, body, branch_name, { label, should_replace_body })
 }
 
 function build_title(issue_info: IssueInfo): string {
@@ -166,11 +179,47 @@ function build_body(issue_info: IssueInfo, extra_body?: string): string {
 	return `${closes}\n\n${extra_body}`
 }
 
+async function existing_pr_label(branch_name: string): Promise<ReleaseClassification | undefined> {
+	if (!(await git_gh_command.pr_exists(branch_name))) return undefined
+	if (is_pr_state_merged(await get_pr_state_safe(branch_name))) return undefined
+
+	return await git_gh_command.pr_get_classification(branch_name)
+}
+
+async function create_for_issue(
+	issue_info: IssueInfo,
+	extra_body: string | undefined,
+	label: ReleaseClassification,
+): Promise<void> {
+	await create(
+		build_title(issue_info),
+		build_body(issue_info, extra_body),
+		issue_info.branch_name,
+		{
+			label,
+			should_replace_body: extra_body !== undefined,
+		},
+	)
+}
+
 async function create_with_issue_info(issue_info: IssueInfo, extra_body?: string): Promise<void> {
-	const title = build_title(issue_info)
-	const body = build_body(issue_info, extra_body)
+	const existing_label = await existing_pr_label(issue_info.branch_name)
+
+	if (existing_label !== undefined) {
+		await create_for_issue(issue_info, extra_body, existing_label)
+
+		return
+	}
+
+	const issue_json = await git_gh_command.issue_view_json(issue_info.number, 'labels,body')
+
+	if (issue_json === undefined) {
+		throw new Error(`Could not read issue #${issue_info.number} for release classification`)
+	}
+
+	const label = pr_classification.select_issue_classification(issue_json)
 
-	await create(title, body, issue_info.branch_name, extra_body !== undefined)
+	await create_for_issue(issue_info, extra_body, label)
 }
 
 const git_pr = {

package/scripts/git/issue-labels.ts

@@ -2,6 +2,9 @@
 // labeler and the next-issues display all key on these exact strings, and a drifted copy would
 // fail silently — an epic filtered on the wrong name is simply never closed or never excluded.
 const EPIC_LABEL = 'epic'
+const BUG_LABEL = 'bug'
+const ENHANCEMENT_LABEL = 'enhancement'
+const BREAKING_CHANGE_LABEL = 'breaking-change'
 const IN_PROGRESS_LABEL = 'in-progress'
 // Parks a child that cannot advance without a person deciding something. `epic:next` is what reads
 // it: a parked child is why a run reports "nothing left that time will fix" rather than waiting
@@ -237,6 +240,9 @@ const REVIEW_ROUND2_SKIPPED_LABEL = 'review-round2-skipped'
 
 const ALL_LABELS: ReadonlySet<string> = new Set([
 	EPIC_LABEL,
+	BUG_LABEL,
+	ENHANCEMENT_LABEL,
+	BREAKING_CHANGE_LABEL,
 	IN_PROGRESS_LABEL,
 	NEEDS_DECISION_LABEL,
 	AUTO_OK_LABEL,
@@ -256,12 +262,15 @@ export {
 	ALL_LABELS,
 	ALREADY_DONE_LABEL,
 	AUTO_OK_LABEL,
+	BUG_LABEL,
+	BREAKING_CHANGE_LABEL,
 	depth_label_of,
 	DEPTH_0_LABEL,
 	DEPTH_1_LABEL,
 	DEPTH_2_LABEL,
 	DEPTH_LABEL_ORDER,
 	DEPTH_LABELS,
+	ENHANCEMENT_LABEL,
 	EPIC_LABEL,
 	FILING_ROUTE_LABELS,
 	has_any_label,

package/scripts/init/distributed-paths.ts

@@ -20,8 +20,10 @@ const GITHUB_REPO_TREE_BASE = 'https://github.com/joshuafolkken/kit/tree/main/'
 // The consumer imports kit's published, already path-transformed rules. A tracked bootstrap note
 // remains readable before installation, while the rule body stays in the package (kit#1878).
 const CLAUDE_MD_IMPORT_LINE = '@node_modules/@joshuafolkken/kit/dist/CLAUDE.md'
-const CLAUDE_MD_BOOTSTRAP =
+const OLD_CLAUDE_MD_BOOTSTRAP =
 	'> Fresh checkout: if kit is not installed, run `pnpm install` first, then reread this file before doing any other work.'
+const CLAUDE_MD_BOOTSTRAP =
+	'> Fresh checkout: before `pnpm install`, run `pnpm config get "@joshuafolkken:registry"` from the project root to check the effective registry, including user-level settings. If it points to GitHub Packages, [set up authentication](https://github.com/joshuafolkken/kit/blob/main/docs/authentication.md#1-get-a-token-from-the-gh-cli) first. Then run `pnpm install` and reread this file before doing any other work.'
 
 // A span containing `*` is excluded: it is a **glob**, not a reference to a file a consumer can
 // open. A distributed document that writes a directory set as `prompts/**` means "anything beneath
@@ -84,13 +86,15 @@ function transform_distributed_paths(content: string): string {
 function ensure_claude_md_import(existing: string | undefined): string {
 	if (existing === undefined) return `${CLAUDE_MD_BOOTSTRAP}\n\n${CLAUDE_MD_IMPORT_LINE}\n`
 
-	if (existing.includes(CLAUDE_MD_IMPORT_LINE)) {
-		if (existing.includes(CLAUDE_MD_BOOTSTRAP)) return existing
+	const updated = existing.replace(OLD_CLAUDE_MD_BOOTSTRAP, () => CLAUDE_MD_BOOTSTRAP)
+
+	if (updated.includes(CLAUDE_MD_IMPORT_LINE)) {
+		if (updated.includes(CLAUDE_MD_BOOTSTRAP)) return updated
 
-		return `${CLAUDE_MD_BOOTSTRAP}\n\n${existing}`
+		return `${CLAUDE_MD_BOOTSTRAP}\n\n${updated}`
 	}
 
-	return `${CLAUDE_MD_BOOTSTRAP}\n\n${CLAUDE_MD_IMPORT_LINE}\n\n${existing}`
+	return `${CLAUDE_MD_BOOTSTRAP}\n\n${CLAUDE_MD_IMPORT_LINE}\n\n${updated}`
 }
 
 const distributed_paths = {

package/scripts/init/hook-command-bootstrap.ts

@@ -10,6 +10,11 @@ interface HookResult {
 	stderr: string
 }
 
+interface CheckoutOptions {
+	git_overrides?: Record<string, string>
+	is_external_git?: boolean
+}
+
 function create_partial_install(temporary_root: string): void {
 	const package_root = path.join(temporary_root, 'node_modules/@joshuafolkken/kit')
 	const hook_path = path.join(package_root, 'dist/hooks/pretool-guard.js')
@@ -19,25 +24,52 @@ function create_partial_install(temporary_root: string): void {
 	writeFileSync(hook_path, "process.stdout.write('guard ran')")
 }
 
-function run_in_temporary_checkout(command: string, is_partial_install = false): HookResult {
-	const temporary_root = mkdtempSync(path.join(tmpdir(), 'kit-hook-bootstrap-'))
+function execution_directory(temporary_root: string, is_nested: boolean): string {
+	if (!is_nested) return temporary_root
+
+	const nested_root = path.join(temporary_root, 'src')
+
+	mkdirSync(nested_root)
+
+	return nested_root
+}
+
+function checkout_environment(temporary_root: string, options: CheckoutOptions): NodeJS.ProcessEnv {
+	const metadata_root = path.join(temporary_root, 'metadata')
 	const git_environment = {
 		...process.env,
 		...git_location_environment.location_free_environment(),
 	}
+	const git_arguments = options.is_external_git
+		? ['init', '--bare', '-q', metadata_root]
+		: ['init', '-q']
+
+	spawnSync('git', git_arguments, { cwd: temporary_root, env: git_environment })
+
+	if (options.is_external_git) {
+		return { ...git_environment, GIT_DIR: metadata_root, GIT_WORK_TREE: temporary_root }
+	}
+
+	return { ...git_environment, ...options.git_overrides }
+}
+
+function run_in_temporary_checkout(
+	command: string,
+	is_partial_install = false,
+	is_nested = false,
+	options: CheckoutOptions = {},
+): HookResult {
+	const temporary_root = mkdtempSync(path.join(tmpdir(), 'kit-hook-bootstrap-'))
 
 	try {
-		spawnSync('git', ['init', '-q'], {
-			cwd: temporary_root,
-			env: git_environment,
-		})
+		const hook_environment = checkout_environment(temporary_root, options)
 
 		if (is_partial_install) create_partial_install(temporary_root)
 
 		const { status, stdout, stderr } = spawnSync('sh', ['-c', command], {
-			cwd: temporary_root,
+			cwd: execution_directory(temporary_root, is_nested),
 			encoding: 'utf8',
-			env: git_environment,
+			env: hook_environment,
 		})
 
 		return { status, stdout, stderr }