@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/sync/directory-copy-guard.ts

@@ -1,7 +1,8 @@
-import { cpSync, lstatSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { cpSync, lstatSync, readdirSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { transform_copied_content } from '#scripts/init/init-copy-content'
 import { error_text } from '#scripts/lib/error-message'
+import { file_reader } from '#scripts/lib/read-file'
 import { file_content } from './file-content'
 
 // `josh init` and `josh sync` both copy a distributed directory with `cpSync`, and both have to
@@ -20,17 +21,11 @@ type DestinationKind = 'absent' | 'directory' | 'other'
 // says the opposite — something is there and cannot be inspected — and ENOTDIR says a component of
 // the path is a file, which is also something rather than nothing. Reading either as absent would
 // send the caller into the `cpSync` that then throws uncaught, the abort this module exists to stop.
-const ABSENT_CODE = 'ENOENT'
-
-function error_code_of(error: unknown): string {
-	return error instanceof Error && 'code' in error ? String(error.code) : ''
-}
-
 function classify_path(candidate_path: string): DestinationKind {
 	try {
 		return lstatSync(candidate_path).isDirectory() ? 'directory' : 'other'
 	} catch (error) {
-		return error_code_of(error) === ABSENT_CODE ? 'absent' : 'other'
+		return file_reader.is_absent(error) ? 'absent' : 'other'
 	}
 }
 
@@ -79,7 +74,7 @@ function is_transformable(candidate_path: string): boolean {
 function transform_copied_file(file_path: string): void {
 	const content = readFileSync(file_path, 'utf8')
 	const transformed = transform_copied_content(file_path, content)
-	if (transformed !== content) writeFileSync(file_path, transformed)
+	if (transformed !== content) file_content.write_contained(file_path, transformed)
 }
 
 // The walk reads the SOURCE listing and rewrites the matching destination paths, never the

package/scripts/sync/file-content.ts

@@ -1,9 +1,10 @@
-import { lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { lstatSync, mkdirSync, readFileSync, readlinkSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { file_reader } from '#scripts/lib/read-file'
 
-function is_absent_error(error: unknown): boolean {
-	return error instanceof Error && 'code' in error && error.code === 'ENOENT'
-}
+const PATH_SEPARATORS = path.sep === '\\' ? /[/\\]/u : /\//u
+const MAX_RESOLVE_STEPS = 4096
 
 function is_read_denied(error: unknown): boolean {
 	return (
@@ -15,7 +16,7 @@ function is_regular_existing_file(destination_path: string): boolean {
 	try {
 		return lstatSync(destination_path).isFile()
 	} catch (error) {
-		if (is_absent_error(error)) return false
+		if (file_reader.is_absent(error)) return false
 		throw error
 	}
 }
@@ -37,13 +38,82 @@ function is_same_file_content(destination_path: string, content: string | Buffer
 	return does_read_match(destination_path, expected)
 }
 
-function write_text_if_changed(destination_path: string, content: string): boolean {
-	if (is_same_file_content(destination_path, content)) return false
+function read_symlink(target: string): string | undefined {
+	if (!lstatSync(target, { throwIfNoEntry: false })?.isSymbolicLink()) return undefined
+
+	return readlinkSync(target)
+}
+
+function split_components(target: string): Array<string> {
+	return target.split(PATH_SEPARATORS).filter((part) => part !== '' && part !== '.')
+}
+
+// One component, as the kernel takes it: `..` steps up from the real directory reached so far, and
+// a link — dangling or not — splices its own text in, from the root when it is absolute.
+function enter_component(current: string, name: string, pending: Array<string>): string {
+	if (name === '..') return path.dirname(current)
+
+	const next = path.join(current, name)
+	const link = read_symlink(next)
+	if (link === undefined) return next
+	const root = path.isAbsolute(link) ? path.parse(link).root : ''
+
+	pending.unshift(...split_components(link.slice(root.length)))
+
+	return root === '' ? current : root
+}
+
+// Where a write to `target` lands. The path is walked component by component rather than through
+// `path.resolve` or `realpathSync`: the first folds `link/..` lexically while the kernel climbs
+// out of where `link` points, and the second refuses the not-yet-created file a dangling link
+// names. A link cycle the walk would never leave is cut off rather than spun on.
+function resolve_write_path(target: string): string {
+	const absolute = path.isAbsolute(target) ? target : `${process.cwd()}${path.sep}${target}`
+	let current = path.parse(absolute).root
+	const pending = split_components(absolute.slice(current.length))
+
+	for (let steps = 0; steps <= MAX_RESOLVE_STEPS; steps += 1) {
+		const name = pending.shift()
+		if (name === undefined) return current
+		current = enter_component(current, name, pending)
+	}
+
+	throw new Error(`Refusing to write ${target}: too many links`)
+}
+
+function is_within(root: string, target: string): boolean {
+	const relative = path.relative(root, target)
+
+	return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)
+}
+
+// Only a path named inside the project is held to it: one the caller names elsewhere (a scratch
+// directory) is that caller's choice, and the link the guard is for sits inside the project.
+function does_escape_project(destination_path: string): boolean {
+	if (!is_within(path.resolve(PROJECT_ROOT), path.resolve(destination_path))) return false
+
+	return !is_within(resolve_write_path(PROJECT_ROOT), resolve_write_path(destination_path))
+}
+
+// A symlinked destination is written through, and one pointing outside the project (`~/.zshrc`)
+// would let a sync overwrite a file the project does not own. A link that stays inside —
+// `CLAUDE.md` → `AGENTS.md`, `.agents/skills` — is written through as before. The check runs before
+// the parent directories are created, so a directory link to outside gets none created through it.
+function write_contained(destination_path: string, content: string | Buffer): void {
+	if (does_escape_project(destination_path)) {
+		throw new Error(`Refusing to write ${destination_path}: it resolves outside the project`)
+	}
 
 	mkdirSync(path.dirname(destination_path), { recursive: true })
 	writeFileSync(destination_path, content)
+}
+
+function write_text_if_changed(destination_path: string, content: string): boolean {
+	if (is_same_file_content(destination_path, content)) return false
+
+	write_contained(destination_path, content)
 
 	return true
 }
 
-export const file_content = { is_same_file_content, write_text_if_changed }
+export const file_content = { is_same_file_content, write_contained, write_text_if_changed }

package/scripts/sync/sync-ai-files.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { init_ai_copy } from '#scripts/init/init-ai-copy'
 import { transform_copied_content } from '#scripts/init/init-copy-content'
@@ -16,7 +16,6 @@ import { skill_migration, type MigrationResult } from './skill-migration'
 import { sync_hook_safety } from './sync-hook-safety'
 
 const WORKSPACE_YAML = 'pnpm-workspace.yaml'
-const PACKAGE_JSON = 'package.json'
 const CLAUDE_MD_FILENAME = 'CLAUDE.md'
 const CLAUDE_SETTINGS_FILE = '.claude/settings.json'
 const CODEX_HOOKS_FILE = '.codex/hooks.json'
@@ -37,7 +36,7 @@ function should_skip_hook_file(filename: string): boolean {
 	if (filename !== CLAUDE_SETTINGS_FILE && filename !== CODEX_HOOKS_FILE) return false
 	const warning = sync_hook_safety.hook_write_warning(
 		PROJECT_ROOT,
-		sync_hook_safety.read_version_at(path.join(PACKAGE_DIR, PACKAGE_JSON)),
+		sync_hook_safety.read_version_at(PACKAGE_DIR),
 		filename,
 	)
 	if (warning === undefined) return false
@@ -191,8 +190,7 @@ function sync_claude_md(destination_path: string, shape?: ProjectShape): void {
 		return
 	}
 
-	mkdirSync(path.dirname(destination_path), { recursive: true })
-	writeFileSync(destination_path, ensured)
+	file_content.write_contained(destination_path, ensured)
 	console.info(`  ✔ synced    ${CLAUDE_MD_FILENAME}`)
 }
 

package/scripts/sync/sync-configs.ts

@@ -1,9 +1,10 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { init_logic } from '#scripts/init/init-logic'
 import { PACKAGE_DIR } from '#scripts/init/init-paths'
 import { vscode_tasks } from '#scripts/init/vscode-tasks'
 import { string_array_schema, vscode_settings_schema } from '#scripts/lib/schemas'
+import { file_content } from './file-content'
 
 type MergeFunction = (existing: string) => string
 
@@ -26,7 +27,7 @@ function sync_with_merge(
 		return
 	}
 
-	writeFileSync(destination_path, merged)
+	file_content.write_contained(destination_path, merged)
 	console.info(`  ✔ synced    ${destination_name}`)
 }
 
@@ -107,7 +108,7 @@ function sync_secretlint_config(destination_path: string): void {
 		return
 	}
 
-	writeFileSync(destination_path, init_logic.generate_secretlint_config())
+	file_content.write_contained(destination_path, init_logic.generate_secretlint_config())
 	console.info('  ✔ created   .secretlintrc.json')
 }
 
@@ -143,29 +144,16 @@ function sync_vscode_settings_json(destination_path: string): void {
 	)
 }
 
-// Creates the file when absent, unlike the other `.vscode` syncs: the folder-open board task is the
-// whole point of distributing it, and a consumer
-// without a tasks.json has nothing of its own to protect. An existing file keeps every task whose
-// label kit does not ship.
+// Like the other `.vscode` syncs, never creates the file: `josh init` does, and a project without it
+// opted out. An existing file keeps every task whose label kit does not ship.
 function sync_vscode_tasks_json(destination_path: string): void {
-	const kit_content = readFileSync(
-		path.join(PACKAGE_DIR, '.vscode', vscode_tasks.VSCODE_TASKS_FILENAME),
-		'utf8',
+	const kit_tasks = vscode_tasks.read_kit_tasks(
+		readFileSync(path.join(PACKAGE_DIR, '.vscode', vscode_tasks.VSCODE_TASKS_FILENAME), 'utf8'),
 	)
 
-	if (existsSync(destination_path)) {
-		const kit_tasks = vscode_tasks.read_kit_tasks(kit_content)
-
-		sync_with_merge(destination_path, '.vscode/tasks.json', (existing) =>
-			vscode_tasks.merge_tasks(existing, kit_tasks),
-		)
-
-		return
-	}
-
-	mkdirSync(path.dirname(destination_path), { recursive: true })
-	writeFileSync(destination_path, kit_content)
-	console.info('  ✔ created   .vscode/tasks.json')
+	sync_with_merge(destination_path, '.vscode/tasks.json', (existing) =>
+		vscode_tasks.merge_tasks(existing, kit_tasks),
+	)
 }
 
 const sync_configs = {

package/scripts/sync/sync-hook-safety.ts

@@ -1,6 +1,5 @@
-import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
-import { json_value } from '#scripts/lib/json-value'
+import { package_manifest } from '#scripts/lib/package-manifest'
 import { package_version_schema } from '#scripts/lib/schemas'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
 import semver from 'semver'
@@ -18,20 +17,15 @@ import semver from 'semver'
 
 const NODE_MODULES = 'node_modules'
 
-function read_version_at(package_json_path: string): string | undefined {
-	if (!existsSync(package_json_path)) return undefined
-	const parsed = package_version_schema.safeParse(
-		json_value.parse_or_undefined(readFileSync(package_json_path, 'utf8')),
-	)
-
-	return parsed.success ? parsed.data.version : undefined
+function read_version_at(package_directory: string): string | undefined {
+	return package_manifest.read_manifest_if_valid(package_directory, package_version_schema)?.version
 }
 
 // The version of kit installed in the consumer's node_modules — the bundle the rewritten hooks
 // actually run. Undefined before the first install, which is safe: a fresh install receives the
 // matching bundle, so there is nothing older to break.
 function installed_consumer_version(project_root: string): string | undefined {
-	return read_version_at(path.join(project_root, NODE_MODULES, KIT_PACKAGE_NAME, 'package.json'))
+	return read_version_at(path.join(project_root, NODE_MODULES, KIT_PACKAGE_NAME))
 }
 
 // Unsafe only when both versions are known AND the installed bundle the hooks run is older than the

package/scripts/sync/sync-main.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { main } from './sync'
+
+// The `josh sync` entry, kept apart from `sync.ts` because `init.ts` imports that one: a bundle is one
+// file, so a main guard there would fire for every command that carries it (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	main(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/sync/sync.ts

@@ -1,13 +1,12 @@
-#!/usr/bin/env tsx
-import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync, rmSync } from 'node:fs'
 import path from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { dependabot_cooldown } from '#scripts/dependabot/dependabot-cooldown'
 import { project_checks } from '#scripts/gate/project-checks'
 import { gh_spawn } from '#scripts/gh/gh-spawn'
-import { basic_path_migration } from '#scripts/init/basic-path-migration'
 import { init_logic } from '#scripts/init/init-logic'
 import { PACKAGE_DIR, PROJECT_ROOT } from '#scripts/init/init-paths'
 import { project_profile } from '#scripts/init/project-profile'
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { auto_merge_setting } from '#scripts/repo/auto-merge-setting'
 import { repository_labels } from '#scripts/repo/repository-labels'
 import { project_config } from '#scripts/safe-chain/project-config'
@@ -19,9 +18,7 @@ import { file_content } from './file-content'
 import { sync_ai_files } from './sync-ai-files'
 import { sync_configs } from './sync-configs'
 
-const PACKAGE_JSON = 'package.json'
-const PACKAGE_JSON_UNCHANGED_MSG = '  ✔ unchanged package.json'
-const BASIC_PRETTIER_CONFIG = 'prettier.config.mjs'
+const PACKAGE_JSON_UNCHANGED_MSG = `  ✔ unchanged ${PACKAGE_JSON}`
 
 function did_migrate_prettierrc(destination_path: string): boolean {
 	const legacy_path = path.join(path.dirname(destination_path), '.prettierrc')
@@ -29,7 +26,7 @@ function did_migrate_prettierrc(destination_path: string): boolean {
 
 	const existing = readFileSync(legacy_path, 'utf8')
 
-	writeFileSync(
+	file_content.write_contained(
 		destination_path,
 		init_logic.merge_prettier_config(existing, path.dirname(destination_path)),
 	)
@@ -48,7 +45,7 @@ function write_merged_prettier_config(destination_path: string): void {
 		return
 	}
 
-	writeFileSync(destination_path, merged)
+	file_content.write_contained(destination_path, merged)
 	console.info('  ✔ synced    prettier.config.js')
 }
 
@@ -64,20 +61,6 @@ function sync_prettier_config(destination_path: string): void {
 	write_merged_prettier_config(destination_path)
 }
 
-// A basic project's prettier config written under the static profile name still imports the static
-// preset path; it is moved onto the basic one with the rule `josh init` applies.
-function sync_basic_prettier_config(destination_path: string): void {
-	if (!existsSync(destination_path)) return
-
-	const existing = readFileSync(destination_path, 'utf8')
-	const did_change = file_content.write_text_if_changed(
-		destination_path,
-		basic_path_migration.migrate_basic_paths(existing),
-	)
-
-	console.info(`  ✔ ${did_change ? 'synced   ' : 'unchanged'} ${BASIC_PRETTIER_CONFIG}`)
-}
-
 function sync_playwright_config(destination_path: string): void {
 	if (!existsSync(destination_path)) return
 
@@ -90,7 +73,7 @@ function sync_playwright_config(destination_path: string): void {
 		return
 	}
 
-	writeFileSync(destination_path, template)
+	file_content.write_contained(destination_path, template)
 	console.info('  ✔ synced    playwright.config.ts')
 }
 
@@ -106,7 +89,7 @@ function sync_deploy_vps(destination_path: string): void {
 		return
 	}
 
-	writeFileSync(destination_path, patched)
+	file_content.write_contained(destination_path, patched)
 	console.info('  ✔ synced    deploy-vps.yml')
 }
 
@@ -156,7 +139,7 @@ function sync_package_json_with(
 		return
 	}
 
-	writeFileSync(destination_path, transformed)
+	file_content.write_contained(destination_path, transformed)
 	console.info(synced_message)
 }
 
@@ -255,6 +238,13 @@ function report_repository_settings(name_with_owner: string | undefined): void {
 	repository_labels.ensure_labels(name_with_owner)
 }
 
+// Every file that restates the workspace's `minimumReleaseAge`: Safe Chain's `.aikido` and
+// Dependabot's `cooldown`.
+function sync_release_window_mirrors(root: string): void {
+	project_config.sync_project_config(root)
+	dependabot_cooldown.sync_dependabot_cooldown(root)
+}
+
 function sync_project_artifacts(is_force: boolean): void {
 	sync_ai_files.sync_ai_copy_all(is_force)
 	sync_prettier_config(path.join(PROJECT_ROOT, 'prettier.config.js'))
@@ -267,20 +257,19 @@ function sync_project_artifacts(is_force: boolean): void {
 
 	sync_sonar_with_template(name_with_owner, is_force)
 	sync_config_files()
-	// After `sync_ai_copy_all`, which may add the `pnpm-workspace.yaml` window `.aikido`'s age is
-	// derived from.
-	project_config.sync_project_config(PROJECT_ROOT)
+	// After `sync_ai_copy_all`, which may add the `pnpm-workspace.yaml` window both mirrors are derived
+	// from, and which rewrites `.github/dependabot.yml` itself.
+	sync_release_window_mirrors(PROJECT_ROOT)
 	sync_package_json_migrations(path.join(PROJECT_ROOT, PACKAGE_JSON))
 	report_repository_settings(name_with_owner)
 }
 
-// A basic project gets what `josh init` gives that profile and nothing more: its AI file set and the
-// move of its prettier preset path. The full toolchain's configs, Sonar, package.json migrations and
-// repository settings are never written into it.
+// A basic project gets what `josh init` gives that profile and nothing more: its AI file set. The full
+// toolchain's configs, Sonar, package.json migrations and repository settings are never written into
+// it.
 function sync_basic_artifacts(is_force: boolean): void {
 	console.info('profile: basic (package.json josh.profile)\n')
 	sync_ai_files.sync_ai_copy_all(is_force, project_profile.inspect_project(PROJECT_ROOT, 'basic'))
-	sync_basic_prettier_config(path.join(PROJECT_ROOT, BASIC_PRETTIER_CONFIG))
 }
 
 // Checked before anything is written, never per file: the damage is the whole run, and a partial
@@ -289,10 +278,10 @@ function sync_basic_artifacts(is_force: boolean): void {
 //
 // Only a recorded basic profile switches the file set; an unrecorded one stays full, as every
 // project initialized before the profile was recorded was set up.
-function main(): void {
+function main(args: ReadonlyArray<string> = []): void {
 	if (did_refuse_self_run(PACKAGE_DIR, PROJECT_ROOT)) return
 
-	const is_force = process.argv.includes('--force')
+	const is_force = args.includes('--force')
 
 	console.info('\n🔄 Syncing @joshuafolkken/kit AI files\n')
 	if (project_checks.is_basic(PROJECT_ROOT)) sync_basic_artifacts(is_force)
@@ -300,8 +289,6 @@ function main(): void {
 	console.info('\n✅ Done.\n')
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) main()
-
 const sync = {
 	should_skip_hook_file: sync_ai_files.should_skip_hook_file,
 	sync_file_mapping: sync_ai_files.sync_file_mapping,
@@ -318,6 +305,7 @@ const sync = {
 	sync_prepare_lefthook_warning,
 	sync_safe_chain_preinstall,
 	sync_package_json_migrations,
+	sync_release_window_mirrors,
 	migrate_prettierrc: did_migrate_prettierrc,
 }
 

package/scripts/test/test-declared-changed.ts

@@ -75,8 +75,8 @@ function restore_injection(previous: ReadonlyArray<string> | undefined): void {
 	injected.paths = previous
 }
 
-// The seam the `rule_delivery` call path needs. `is_untested_commit` reads the
-// tree at trigger time rather than from an argument, so a unit test driving `rule_delivery` cannot reach
+// The seam the `delivered_rules.delivery` call path needs. `is_untested_commit` reads the
+// tree at trigger time rather than from an argument, so a unit test driving `delivered_rules.delivery` cannot reach
 // `current_verdict`'s `paths` port from the outside. Running `body` inside `with_paths` fixes the read
 // to `paths` for its duration and restores it afterwards — the `PreToolUse` production path, which never
 // calls this, still reads the live tree.

package/scripts/test/test-declared.ts

@@ -27,7 +27,7 @@ const ARGV_OFFSET = 2
 const NO_DECLARATIONS =
 	'no Test: declarations parsed from stdin — pipe the Step 0 work summary in, e.g. `pnpm josh test:declared --match < summary.md`'
 
-// **An unknown flag is a refusal, not a default** — `scripts/time/time-cli.ts` states the same
+// **An unknown flag is a refusal, not a default** — `tools/time/time-cli.ts` states the same
 // convention. Ignoring `--foo` and re-printing the verdict is what sent a
 // reader off to read the source by hand, so a misspelled or retired flag stops here with the usage.
 const PARSE_ARGS_OPTIONS = {

package/scripts/test/test-e2e-guard.ts

@@ -4,7 +4,9 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { environment_flags } from '@joshuafolkken/kit/env'
 import { core_budget } from '#scripts/gate/core-budget'
+import { gate_tree } from '#scripts/gate/gate-tree'
 import { execa } from 'execa'
+import { test_e2e_stamp } from './test-e2e-stamp'
 
 const PNPM = 'pnpm'
 // `--workers`, `--workers=<n>` and Playwright's `-j` short form.
@@ -93,9 +95,30 @@ async function run_guarded_e2e(
 	return 0
 }
 
+// A filter (`--grep`, a file, `--project`) answers for part of the suite, so only a run whose every
+// argument is a worker count answers for the whole of it.
+function is_whole_suite(extra_arguments: ReadonlyArray<string>): boolean {
+	return extra_arguments.every((argument) => WORKER_FLAGS.test(argument))
+}
+
+// A green answer — a pass or a printed skip — is recorded against the tree it ran on, which is what a
+// stop before commit asks (`test-e2e-stamp.ts`). The tree is read before the run, so an edit made while
+// the suite ran leaves a record that matches nothing.
+async function run_and_record(
+	project_directory: string,
+	extra_arguments: ReadonlyArray<string>,
+): Promise<number> {
+	const tree = await gate_tree.read_gate_tree()
+	const exit_code = await run_guarded_e2e(project_directory, extra_arguments)
+
+	if (exit_code === 0 && is_whole_suite(extra_arguments)) test_e2e_stamp.record(tree)
+
+	return exit_code
+}
+
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	const extra_arguments = process.argv.slice(ARGV_START)
-	const exit_code = await run_guarded_e2e(process.cwd(), extra_arguments)
+	const exit_code = await run_and_record(process.cwd(), extra_arguments)
 
 	process.exit(exit_code)
 }
@@ -104,6 +127,7 @@ const test_e2e_guard = {
 	resolve_guard_action,
 	is_playwright_installed,
 	has_e2e_tests,
+	is_whole_suite,
 	run_guarded_e2e,
 }
 

package/scripts/test/test-e2e-stamp.ts

@@ -0,0 +1,38 @@
+import { gate_tree, type GateTree } from '#scripts/gate/gate-tree'
+import { review_brief } from '#scripts/review/review-brief'
+import { review_stamps } from '#scripts/review/review-stamps'
+
+// The record that `josh test:e2e` answered green on this exact tree (joshuafolkken/kit#4156). A stop
+// before commit — `halfrun`'s, `needs-human-review`'s — has no CI E2E job behind it, so the stop asks
+// this record instead of trusting that the run remembered to run the suite.
+//
+// **A printed skip is recorded too**: a project with no suite, or without `@playwright/test`, has
+// answered the question, and refusing its stop would make the record a requirement no such project
+// could meet. **Any edit after the run moves the tree**, so the record no longer matches — the same
+// reading the gate's own record takes (`gate-skip.ts`).
+
+// Swallowed: a record not written is the safe answer — the stop refuses and the run re-runs the suite.
+function record(tree: GateTree, target?: string): void {
+	try {
+		review_stamps.e2e_stamp.write(tree.files, target, tree.base)
+	} catch {
+		/* no record — the stop asks for the suite again */
+	}
+}
+
+// An unread base or an unreadable record answers no: nothing established, nothing concluded.
+function is_current(tree: GateTree, source?: string): boolean {
+	if (tree.base === undefined) return false
+
+	const stamp = review_brief.matching_stamp(review_stamps.e2e_stamp.read(source), tree.files)
+
+	return stamp?.base === tree.base
+}
+
+async function is_current_tree(): Promise<boolean> {
+	return is_current(await gate_tree.read_gate_tree())
+}
+
+const test_e2e_stamp = { is_current, is_current_tree, record }
+
+export { test_e2e_stamp }