@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,85 @@
+import { execSync } from 'node:child_process'
+
+// Environment variables that git reads from the environment. A test that sets these affects every
+// subsequent git command in the same worker when isolation is disabled.
+const GIT_ENV_KEYS: ReadonlyArray<string> = [
+	'GIT_DIR',
+	'GIT_INDEX_FILE',
+	'GIT_OBJECT_DIRECTORY',
+	'GIT_WORK_TREE',
+	'GIT_COMMON_DIR',
+]
+
+interface StateSnapshot {
+	branch: string
+	status: string
+	git_env: Record<string, string | undefined>
+}
+
+function run_git(args: string): string {
+	try {
+		return execSync(`git ${args}`, { encoding: 'utf8', stdio: 'pipe' }).trim()
+	} catch {
+		return '(error)'
+	}
+}
+
+function capture_git_environment(): Record<string, string | undefined> {
+	return Object.fromEntries(GIT_ENV_KEYS.map((key) => [key, process.env[key]]))
+}
+
+function capture_state(): StateSnapshot {
+	return {
+		branch: run_git('rev-parse --abbrev-ref HEAD'),
+		status: run_git('status --porcelain'),
+		git_env: capture_git_environment(),
+	}
+}
+
+function environment_diff(
+	before: Record<string, string | undefined>,
+	after: Record<string, string | undefined>,
+): Array<string> {
+	return GIT_ENV_KEYS.filter((key) => before[key] !== after[key]).map(
+		(key) => `  ${key}: ${String(before[key])} → ${String(after[key])}`,
+	)
+}
+
+function format_violations(before: StateSnapshot, after: StateSnapshot): string | undefined {
+	const lines: Array<string> = []
+
+	if (before.branch !== after.branch) {
+		lines.push(`  branch: ${before.branch} → ${after.branch}`)
+	}
+
+	if (before.status !== after.status) {
+		lines.push('  working tree changed (run "git status" to inspect)')
+	}
+
+	lines.push(...environment_diff(before.git_env, after.git_env))
+
+	if (lines.length === 0) return undefined
+
+	return `test-state-guard: tests mutated repository state:\n${lines.join('\n')}`
+}
+
+function setup(): () => void {
+	const before = capture_state()
+
+	return function disarm(): void {
+		const after = capture_state()
+		const violation = format_violations(before, after)
+
+		if (violation !== undefined) throw new Error(violation)
+	}
+}
+
+const test_state_guard = {
+	GIT_ENV_KEYS,
+	capture_state,
+	env_diff: environment_diff,
+	format_violations,
+}
+
+export type { StateSnapshot }
+export { setup, test_state_guard }

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

@@ -0,0 +1,54 @@
+import { beforeEach } from 'vitest'
+
+// **Fixture writes to the real streams no longer reach the gate's output** (joshuafolkken/kit#2296).
+// A unit test that drives a CLI `main`/`run` — `test:declared --match`, `run:review` with a bad
+// argument — writes its `match:` / `Usage: josh …` lines straight to `process.stdout` and
+// `process.stderr`, which Vitest forwards from the worker verbatim. Those lines then sat at the tail
+// of `pnpm josh test:unit`, and a run reading the gate with `tail` took them for the suite's own
+// output. Silencing the two streams for the body of every test drops them; console.* is untouched, so
+// a deliberate debug line still shows, and the restore is a per-test teardown so nothing leaks between
+// tests or into Vitest's own reporter.
+
+type WriteFunction = typeof process.stdout.write
+
+interface SavedWrites {
+	stdout: WriteFunction
+	stderr: WriteFunction
+}
+
+function swallow(): true {
+	return true
+}
+
+// Swaps both streams' `write` for a no-op and returns what was there, so the caller restores exactly
+// what it replaced rather than a stream reference captured somewhere else — Vitest wraps these in the
+// worker, and that wrapper is what must come back.
+function silence_streams(): SavedWrites {
+	const saved: SavedWrites = { stdout: process.stdout.write, stderr: process.stderr.write }
+
+	process.stdout.write = swallow
+	process.stderr.write = swallow
+
+	return saved
+}
+
+function restore_streams(saved: SavedWrites): void {
+	process.stdout.write = saved.stdout
+	process.stderr.write = saved.stderr
+}
+
+// The teardown is returned from `beforeEach` rather than kept in a module binding, so two tests never
+// share one saved pair and nothing here writes to a top-level variable from inside a hook. The hook
+// registration is the setup file's whole purpose, so its top-level effect is deliberate.
+// eslint-disable-next-line unicorn/no-top-level-side-effects
+beforeEach(() => {
+	const saved = silence_streams()
+
+	return () => {
+		restore_streams(saved)
+	}
+})
+
+const test_stdout_guard = { restore_streams, silence_streams }
+
+export { test_stdout_guard }

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

@@ -0,0 +1,90 @@
+import { appendFileSync } from 'node:fs'
+import { expect } from 'vitest'
+import { GUARD_LOG_KEY } from './unit-guard-environment'
+
+// **A unit test that forgets to mock a notification must fail rather than notify**
+// (joshuafolkken/kit#2494). A lane child's new test drove `run_carry_cli.run(['--end', '--stopped',
+// …])` without replacing `./run-stop-notify`, and two runs of it sent two real "backlogrun stopped"
+// confirmations — while the run was still going — and the test passed. `telegram-notify.ts` posts
+// with Node's own `fetch`, which the `gh` / `git` `PATH` shims in `test-network-guard.ts` never see.
+//
+// **This wraps `fetch` in every worker rather than mocking the notifier module**, for the reason the
+// network guard shims a binary rather than mocking a module: any caller that reaches Telegram is
+// caught, not only the import graph a mock was written against. Anything not addressed to Telegram
+// is handed to the real `fetch` untouched, and a test that stubs `fetch` itself replaces this
+// wrapper for its own duration, so the correctly mocked suites (`telegram-notify.test.ts`) see
+// nothing of it.
+//
+// **The attempt is recorded in the network guard's own log, not a second one.** `disarm` already
+// reads that record at teardown and throws with every line in it, so a Telegram send fails the run
+// and is reported exactly as a live `gh api` is — naming the test that made it, since a `fetch` has
+// no command line to quote. The call itself is refused either way, so even an unarmed run sends
+// nothing.
+//
+// **Only this process is covered.** A CLI a test spawns as a subprocess loads no setup file; the
+// unit suite's Telegram sends so far have all been in-process, and the subprocess case is left to
+// the notifier's own mocks.
+
+const TELEGRAM_HOST = 'api.telegram.org'
+const RECORD_NAME = 'telegram'
+const BLOCKED_MESSAGE =
+	'josh: the unit suite must not send a Telegram notification — mock it instead'
+const UNKNOWN_TEST = '(outside a test)'
+// Marks a `fetch` that is already this wrapper. `isolate: false` re-runs a setup file for every test
+// file in one worker, and wrapping the wrapper each time would stack one closure per file.
+const GUARDED_MARK = Symbol.for('josh.unit-telegram-guard')
+
+type Fetch = typeof globalThis.fetch
+type GuardedFetch = Fetch & { [GUARDED_MARK]?: true }
+
+function request_url(input: Parameters<Fetch>[0]): string {
+	if (typeof input === 'string') return input
+
+	return input instanceof URL ? input.href : input.url
+}
+
+// The host, compared exactly. The URL carries the bot token in its path, so nothing of it is kept.
+function is_telegram(input: Parameters<Fetch>[0]): boolean {
+	return URL.parse(request_url(input))?.hostname === TELEGRAM_HOST
+}
+
+function current_test(): string {
+	const state = expect.getState()
+
+	return [state.testPath, state.currentTestName ?? UNKNOWN_TEST].filter(Boolean).join(' > ')
+}
+
+// `>>`-style append, for `shim_shell.record_line`'s reason: every worker writes the one record.
+function record(log_file: string | undefined): void {
+	if (log_file !== undefined) appendFileSync(log_file, `${RECORD_NAME} ${current_test()}\n`)
+}
+
+function guarded_fetch(real_fetch: Fetch): GuardedFetch {
+	const guarded: GuardedFetch = async function (input, init) {
+		if (!is_telegram(input)) return await real_fetch(input, init)
+
+		record(process.env[GUARD_LOG_KEY])
+
+		throw new Error(BLOCKED_MESSAGE)
+	}
+
+	guarded[GUARDED_MARK] = true
+
+	return guarded
+}
+
+// A plain assignment rather than `vi.stubGlobal`: a test's own `vi.unstubAllGlobals` restores what
+// was there before the *first* stub, which would be the unguarded `fetch` had this been one.
+function install(): void {
+	const current: GuardedFetch = fetch
+
+	if (current[GUARDED_MARK] !== true) Reflect.set(globalThis, 'fetch', guarded_fetch(current))
+}
+
+// The wrapping is the setup file's whole purpose, so its top-level effect is deliberate.
+// eslint-disable-next-line unicorn/no-top-level-side-effects
+install()
+
+const test_telegram_guard = { BLOCKED_MESSAGE, RECORD_NAME, guarded_fetch, is_telegram }
+
+export { test_telegram_guard }

package/scripts/test/test-type-logic.ts

@@ -0,0 +1,31 @@
+// The test type a changed path calls for — `Unit` or `E2E` — decided from the path alone
+// (joshuafolkken/kit#2181).
+//
+// **This mechanizes `prompts/testing-guide.md` §1's two-row table**, whose last line used to be "When
+// ambiguous, ask the user" — a Tier B stop on a question the path already answers. The table routes
+// `src/routes/` pages and interactive UI to E2E and everything else (utilities, `src/lib/server/`,
+// display-only components) to Unit. The mechanically certain half of that is location: a change under
+// `src/routes/` is a page whose behavior is observed through the browser, so it takes E2E; every other
+// runtime path is exercised by a colocated unit test. A component with interaction is reached through
+// the route that renders it, and that route is under `src/routes/` — so the location rule covers it
+// without reading the file.
+
+type TestType = 'Unit' | 'E2E'
+
+const UNIT: TestType = 'Unit'
+const E2E: TestType = 'E2E'
+
+// The paths whose changes are observed through the browser, so their test is an E2E spec. Everything
+// else is a utility, a server module or a display-only component — all Unit.
+const E2E_PREFIXES: ReadonlyArray<string> = ['src/routes/']
+
+function test_type_for(path: string): TestType {
+	const normalized = path.trim()
+
+	return E2E_PREFIXES.some((prefix) => normalized.startsWith(prefix)) ? E2E : UNIT
+}
+
+const test_type_logic = { E2E, E2E_PREFIXES, UNIT, test_type_for }
+
+export type { TestType }
+export { test_type_logic }

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

@@ -0,0 +1,185 @@
+#!/usr/bin/env tsx
+import { existsSync, globSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { PROJECT_ENVIRONMENT_KEYS } from '#ports'
+import { execa } from 'execa'
+import { unit_worker_share } from './unit-worker-share'
+
+const PNPM = 'pnpm'
+const FAIL_EXIT_CODE = 1
+const ARGV_START = 2
+const VITEST_PACKAGE = path.join('node_modules', 'vitest')
+const UNIT_GLOB = '**/*.{test,spec}.{ts,js}'
+const NODE_MODULES = 'node_modules'
+
+// **A unit check that executed nothing may report success only where the project has no unit suite
+// at all** (joshuafolkken/kit#1224). The two halves of "nothing ran" are not the same state:
+//
+// - **`vitest` absent is the young project.** `josh init` installs no vitest and writes no
+//   `test:unit` script, so a freshly-bootstrapped project always lands here — which is the case the
+//   skip was written for, and it keeps it.
+// - **`vitest` present is the project declaring that it runs unit tests.** Zero matching files
+//   there is a broken state rather than a young one — a mis-scoped glob, or a suite that was
+//   deleted — and reporting it as a passing check hands `pnpm josh followup`, which reads
+//   only the exit code, a verification that verified nothing. That half fails.
+//
+// Rejected: leaving both halves green — joshuafolkken/kit#1216's `--verbose` makes the zero count
+// *readable* in the CI log, but nobody reads a green log and the merge gate reads only pass/fail;
+// and putting the failing half behind an opt-in such as `JOSH_REQUIRE_UNIT_TESTS`, which is off in
+// exactly the projects that need it. The full decision, including why the absent-vitest half is
+// deliberately left asymmetric, is on joshuafolkken/kit#1224.
+//
+// **`scripts/test/test-e2e-guard.ts` deliberately keeps both skips, and that divergence is not an
+// oversight.** The argument above rests on the package's presence being a declaration, and
+// `@playwright/test` is not one: it is an optional peer dependency that vitest's browser mode also
+// needs, so a project can legitimately have it installed with no `*.e2e.{ts,js}` file at all.
+const SKIP_ACTION = 'skip-missing-package'
+const FAIL_ACTION = 'fail-no-tests'
+
+type GuardAction = 'run' | typeof SKIP_ACTION | typeof FAIL_ACTION
+
+// The word the gate looks for to know a passing step did not actually run. Exported and reused on
+// both sides rather than matched by eye: joshuafolkken/kit#967 stopped printing a passing check's
+// body, and without this a gate that skipped the whole unit suite printed the same five lines as one
+// that ran it.
+const SKIP_MARKER = '— skipping'
+
+const SKIP_REASON = 'vitest is not installed'
+const FAIL_REASON =
+	'vitest is installed but no *.{test,spec}.{ts,js} test file was found — refusing to report a unit check that ran nothing'
+
+function resolve_guard_action(is_installed: boolean, has_tests: boolean): GuardAction {
+	if (!is_installed) return SKIP_ACTION
+	if (!has_tests) return FAIL_ACTION
+
+	return 'run'
+}
+
+function is_vitest_installed(project_directory: string): boolean {
+	return existsSync(path.join(project_directory, VITEST_PACKAGE))
+}
+
+function is_in_node_modules(entry: string): boolean {
+	return entry.split(/[/\\]/u).includes(NODE_MODULES)
+}
+
+function has_unit_tests(project_directory: string): boolean {
+	const matches = globSync(UNIT_GLOB, {
+		cwd: project_directory,
+		exclude: is_in_node_modules,
+	})
+
+	return matches.length > 0
+}
+
+// A lane's port allocation belongs to its development and preview servers, not to unit fixtures.
+// Passing it into Vitest makes every case that deliberately omits or replaces the seed inherit the
+// checkout's seat instead. Keep the rest of the caller's environment, including CI and PATH guards.
+function isolated_unit_environment(
+	environment: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+	const isolated = { ...environment }
+
+	for (const key of PROJECT_ENVIRONMENT_KEYS) Reflect.deleteProperty(isolated, key)
+
+	return isolated
+}
+
+// The whole vitest invocation after the binary, not just the flags: `josh test:related` runs
+// `vitest related <files> --run` where this command runs `vitest run`, and the two must not grow
+// two copies of the guard, the spawn or the skip notice around that one difference
+// (joshuafolkken/kit#1257).
+// **The share is read from inside the marker, not before it.** This is the one funnel every
+// josh-driven vitest goes through — `test:unit`, `test:related` and the pre-push hook alike — so it is
+// where a run both learns how many others are in flight and announces itself to them
+// (joshuafolkken/kit#1515). The pre-push hook is the reason it is here rather than only in the gate:
+// it passed no cap at all, so vitest opened one worker per core in every lane at once.
+//
+// Reading the share first and claiming afterwards leaves a window in which two hooks firing together
+// both count "alone" and both run uncapped. Inside the marker the number is identical — this run's own
+// record is now on disk and `is_nested_run` therefore contributes nothing — and the window is gone.
+async function run_vitest(vitest_arguments: ReadonlyArray<string>): Promise<number> {
+	return await unit_worker_share.with_run_marker(async () => {
+		const sized = unit_worker_share.worker_arguments(
+			vitest_arguments,
+			unit_worker_share.current_share(),
+		)
+		const result = await execa(PNPM, ['exec', 'vitest', ...vitest_arguments, ...sized], {
+			env: isolated_unit_environment(),
+			extendEnv: false,
+			stdio: 'inherit',
+			reject: false,
+		})
+
+		return result.exitCode ?? FAIL_EXIT_CODE
+	})
+}
+
+// The label names the command the notice is printed for, so a skipped scoped run says
+// `josh test:related` rather than reporting itself as the full suite. `SKIP_MARKER` is unchanged
+// either way: the gate reads that word, never the label.
+const UNIT_COMMAND_LABEL = 'test:unit'
+
+// The two non-running outcomes report through different streams and different exit codes, because
+// they mean different things: one says the project has no unit suite yet, the other says it has one
+// that could not be found (joshuafolkken/kit#1224). Only the first keeps `SKIP_MARKER`, so the
+// gate's "passed without running" handling still means exactly what it did.
+function report_no_run(action: Exclude<GuardAction, 'run'>, command_label: string): number {
+	if (action === FAIL_ACTION) {
+		console.error(`josh ${command_label}: ${FAIL_REASON}.`)
+
+		return FAIL_EXIT_CODE
+	}
+
+	console.info(`josh ${command_label}: ${SKIP_REASON} ${SKIP_MARKER} vitest unit tests.`)
+
+	return 0
+}
+
+// `announcement` is printed only on the branch that actually spawns vitest. A caller that wrote it
+// itself would claim a run before this guard had decided there would be one — the same "a passing
+// step did not actually run" ambiguity `SKIP_MARKER` exists for, reintroduced one layer up
+// (joshuafolkken/kit#1257).
+async function run_guarded_vitest(
+	project_directory: string,
+	vitest_arguments: ReadonlyArray<string>,
+	command_label: string = UNIT_COMMAND_LABEL,
+	announcement?: string,
+): Promise<number> {
+	const is_installed = is_vitest_installed(project_directory)
+	const has_tests = has_unit_tests(project_directory)
+	const action = resolve_guard_action(is_installed, has_tests)
+
+	if (action !== 'run') return report_no_run(action, command_label)
+	if (announcement !== undefined) process.stdout.write(`${announcement}\n`)
+
+	return await run_vitest(vitest_arguments)
+}
+
+async function run_guarded_unit(
+	project_directory: string,
+	extra_arguments: ReadonlyArray<string>,
+): Promise<number> {
+	return await run_guarded_vitest(project_directory, ['run', ...extra_arguments])
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const extra_arguments = process.argv.slice(ARGV_START)
+	const exit_code = await run_guarded_unit(process.cwd(), extra_arguments)
+
+	process.exit(exit_code)
+}
+
+const test_unit_guard = {
+	SKIP_MARKER,
+	resolve_guard_action,
+	is_vitest_installed,
+	has_unit_tests,
+	isolated_unit_environment,
+	run_guarded_unit,
+	run_guarded_vitest,
+}
+
+export type { GuardAction }
+export { test_unit_guard }

package/scripts/test/unit-guard-environment.ts

@@ -0,0 +1,12 @@
+// The environment variable the network guard's record is handed to the test workers under
+// (joshuafolkken/kit#2494). The `gh` and `git` shims carry the record's path baked into their own
+// script, but an in-process guard — the Telegram one wraps `fetch` inside each worker — has nothing
+// baked in, so `arm` exports the path and every worker inherits it with `PATH`.
+//
+// A module of its own because both sides must name it and neither may load the other: the network
+// guard runs in Vitest's main process and must not import `vitest`, and the Telegram guard runs in
+// every worker, where loading the network guard would resolve the guarded repository with a `git`
+// spawn once per test file.
+const GUARD_LOG_KEY = 'JOSH_UNIT_GUARD_LOG'
+
+export { GUARD_LOG_KEY }

package/scripts/test/unit-projects.ts

@@ -0,0 +1,139 @@
+import { agent_session_environment } from '#scripts/josh/agent-session-environment'
+import { PILOT_FILES } from './pilot-files'
+import { VITEST_INCLUDE_GLOBS } from './vitest-include-globs'
+
+// The unit suite runs as two Vitest projects so the isolation-safe files can skip per-file worker
+// isolation, which re-evaluates every shared module once per file (joshuafolkken/kit#2170). Measured
+// back to back on the pilot set, isolate:false ran it in 27.5s against 64.7s isolated — a 57% cut,
+// because module evaluation is about half of a run's wall clock.
+//
+// **The two projects partition the suite exactly.** `pure` runs the classifier's isolation-free set;
+// `isolated` runs everything else the main globs match, excluding the pilot files so no file lands in
+// both. Their union is every included file bar the packed-consumer smoke test, and nothing runs
+// twice — which is what keeps the gate's green condition identical to the single-project suite it
+// replaces. `classify-isolation.ts` lists a file as pure only when it mutates no state a sibling in
+// the same worker could observe, so isolate:false changes how the pure files run, never whether they
+// pass.
+
+const TEST_TIMEOUT_MS = 10_000
+
+// Smoke test packs and installs the real tarball — too slow (~60 s setup) for the unit gate. Run
+// before release with: pnpm vitest run --config vitest.harness.config.ts
+const MAIN_EXCLUDE: ReadonlyArray<string> = ['scripts/build/packed-consumer.test.ts']
+
+// **`JOSH_LANE_CHILD` is blanked so the unit suite never inherits the lane it happens to run in**
+// (joshuafolkken/kit#2310). The gate runs inside a dispatched lane child, whose mark and lane cwd would
+// otherwise make every world-consulting rule guard (`pre-gate-cut`, `implementation-cut`, `lane-park`)
+// read a delivery fixture as a real lane-child call and fire on it. A suite that wants to test
+// lane-child behavior sets the mark itself in its own `beforeEach`, exactly as it always has; blank is
+// the "no dispatch mark" a person's session carries, which `marked_issue` reads as absent.
+//
+// **The proxy spellings are blanked for the same reason** (joshuafolkken/kit#2436): a package-manager
+// wrapper writes its loopback proxy and CA into everything `pnpm` spawns, so a suite asserting what a
+// `gh` spawn receives would pass in CI and fail on a machine with the wrapper. A suite about proxies
+// declares the one it is testing in its own `beforeEach`.
+//
+// **The detached ship supervisor's marks are blanked too** (joshuafolkken/kit#2456): the pre-push unit
+// run inherits `JOSH_SHIP_SUPERVISED` and `JOSH_AGENT_PROVIDER` from the supervisor that pushes, so a
+// ship fixture would take the supervised stop path — and try to relaunch a real lane child — only there.
+const PROXY_ENV: Record<string, string> = Object.fromEntries(
+	[...agent_session_environment.PROXY_KEYS, agent_session_environment.PROXY_CERTIFICATE_KEY].map(
+		(key) => [key, ''],
+	),
+)
+
+const ENV: Record<string, string> = {
+	...PROXY_ENV,
+	CLAUDE_CODE_SESSION_ID: 'vitest-session',
+	CODEX_THREAD_ID: '',
+	JOSH_AGENT_PROVIDER: '',
+	JOSH_LANE_CHILD: '',
+	JOSH_SHIP_SUPERVISED: '',
+}
+
+const PURE_PROJECT = 'pure'
+const ISOLATED_PROJECT = 'isolated'
+
+// The state guard runs on the pure project alone. isolate:false is what lets one file see the git
+// branch, working tree or GIT_* variables a sibling left changed, so that is the only run where a leak
+// is a correctness problem rather than a latent one — and the isolated project keeps exactly the guards
+// the single-project suite had. The network guard is armed once at the root instead, since it arms
+// `PATH` before any worker of either project forks.
+const STATE_GUARD: ReadonlyArray<string> = ['./scripts/test/test-state-guard.ts']
+
+// Runs in every worker of both projects, before each test, and silences the real streams for the test
+// body so a fixture's direct `process.stdout` write cannot leak into `pnpm josh test:unit`'s output
+// (joshuafolkken/kit#2296). `setupFiles` rather than `globalSetup` because it must run inside the
+// worker where the test's writes happen, not once in the main process.
+const STDOUT_GUARD: ReadonlyArray<string> = ['./scripts/test/test-stdout-guard.ts']
+
+// Runs in every worker for the same reason: it wraps that worker's own `fetch`, refusing a real
+// Telegram send and recording which test tried (joshuafolkken/kit#2494).
+const TELEGRAM_GUARD: ReadonlyArray<string> = ['./scripts/test/test-telegram-guard.ts']
+
+interface UnitProjectTest {
+	name: string
+	env: Record<string, string>
+	include: ReadonlyArray<string>
+	exclude: ReadonlyArray<string>
+	isolate: boolean
+	testTimeout: number
+	globalSetup: ReadonlyArray<string>
+	setupFiles: ReadonlyArray<string>
+}
+
+interface UnitProject {
+	test: UnitProjectTest
+}
+
+interface UnitProjectSpec {
+	name: string
+	include: ReadonlyArray<string>
+	isolate: boolean
+	exclude?: ReadonlyArray<string>
+	globalSetup?: ReadonlyArray<string>
+}
+
+function unit_project(spec: UnitProjectSpec): UnitProject {
+	return {
+		test: {
+			name: spec.name,
+			env: ENV,
+			include: [...spec.include],
+			exclude: [...(spec.exclude ?? [])],
+			isolate: spec.isolate,
+			testTimeout: TEST_TIMEOUT_MS,
+			globalSetup: [...(spec.globalSetup ?? [])],
+			setupFiles: [...STDOUT_GUARD, ...TELEGRAM_GUARD],
+		},
+	}
+}
+
+const UNIT_PROJECTS: ReadonlyArray<UnitProject> = [
+	unit_project({
+		name: PURE_PROJECT,
+		include: PILOT_FILES,
+		isolate: false,
+		globalSetup: STATE_GUARD,
+	}),
+	unit_project({
+		name: ISOLATED_PROJECT,
+		include: VITEST_INCLUDE_GLOBS,
+		isolate: true,
+		exclude: [...MAIN_EXCLUDE, ...PILOT_FILES],
+	}),
+]
+
+const unit_projects = {
+	ENV,
+	ISOLATED_PROJECT,
+	MAIN_EXCLUDE,
+	PURE_PROJECT,
+	STATE_GUARD,
+	STDOUT_GUARD,
+	TELEGRAM_GUARD,
+	UNIT_PROJECTS,
+}
+
+export type { UnitProject, UnitProjectTest }
+export { unit_projects }