@joshuafolkken/kit 1.1387.0 → 1.1453.0

package/scripts/fresh-machine/fresh-machine-image.ts

@@ -0,0 +1,62 @@
+// The "fresh machine" of `josh fresh:run`: a Debian image with curl and without Node.js, pnpm, git or
+// gh, on which a normal user runs the Linux route of `docs/setup/prerequisites.md` and nothing else.
+// The Dockerfile is built here rather than kept as a file because `docs/` is not in the published
+// package and a consumer toolkit builds the same machine; `fresh-machine-image.test.ts` holds the
+// commands below to the guide's own lines.
+
+const BASE_IMAGE = 'buildpack-deps:bookworm-curl'
+const MACHINE_USER = 'dev'
+const HOME_DIRECTORY = `/home/${MACHINE_USER}`
+const TAG_PREFIX = 'josh-fresh-machine'
+
+// `docs/setup/prerequisites.md` → "Linux and macOS". The first line runs in the shell a new machine
+// starts with; the guide then says to open a new terminal, which is what `NEW_TERMINAL` does.
+const INSTALL_PNPM = 'curl -fsSL https://get.pnpm.io/install.sh | sh -'
+const NEW_TERMINAL_COMMANDS = ['pnpm runtime set node 22 -g', 'node --version']
+
+// The guide sends a Linux reader to the gh installation page; these are that page's Debian steps,
+// run as root in place of `sudo`, with the curl the image already has. git comes from the same
+// package manager, and so does procps: kit's lane commands read processes with its ps and pgrep, which
+// the slim base image does not ship. Only a GitHub scenario's machine has any of them.
+const KEYRING = '/etc/apt/keyrings/githubcli-archive-keyring.gpg'
+const APT_UPDATE = 'apt-get update'
+const GITHUB_TOOLS = [
+	APT_UPDATE,
+	'apt-get install -y git procps',
+	'mkdir -p -m 755 /etc/apt/keyrings',
+	`curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg -o ${KEYRING}`,
+	`chmod go+r ${KEYRING}`,
+	`echo "deb [arch=$(dpkg --print-architecture) signed-by=${KEYRING}] https://cli.github.com/packages stable main" > /etc/apt/sources.list.d/github-cli.list`,
+	APT_UPDATE,
+	'apt-get install -y gh',
+].join(' && ')
+
+function new_terminal(command: string): string {
+	return `RUN bash -ic '${command}'`
+}
+
+// `SHELL` is the one line the guide does not have: the pnpm installer reads it to pick the profile
+// it edits, and a container build does not set it.
+function dockerfile(requires_github: boolean): string {
+	const github_tools = requires_github ? [`RUN ${GITHUB_TOOLS}`] : []
+
+	return [
+		`FROM ${BASE_IMAGE}`,
+		...github_tools,
+		`RUN useradd --create-home --shell /bin/bash ${MACHINE_USER}`,
+		`USER ${MACHINE_USER}`,
+		`WORKDIR ${HOME_DIRECTORY}`,
+		'ENV SHELL=/bin/bash',
+		`RUN ${INSTALL_PNPM}`,
+		...NEW_TERMINAL_COMMANDS.map((command) => new_terminal(command)),
+		'',
+	].join('\n')
+}
+
+function tag(requires_github: boolean): string {
+	return `${TAG_PREFIX}:${requires_github ? 'github' : 'base'}`
+}
+
+const fresh_machine_image = { dockerfile, tag }
+
+export { fresh_machine_image }

package/scripts/fresh-machine/fresh-machine-log.ts

@@ -0,0 +1,61 @@
+// The two rules a `josh fresh:run` log follows: a run never reuses a name, and no token passed to
+// the container reaches the file.
+
+const LOG_EXTENSION = '.log'
+const FIRST_RUN = 1
+
+// What already carries a run's name: the logs of the directory this run writes to and, for a GitHub
+// scenario, the account's repositories — another checkout, or a lane worktree since removed, numbers
+// from its own logs and leaves repositories this directory has no log of.
+interface TakenNames {
+	logs: ReadonlyArray<string>
+	repositories: ReadonlyArray<string>
+}
+
+function logged_names(logs: ReadonlyArray<string>): Array<string> {
+	return logs
+		.filter((file) => file.endsWith(LOG_EXTENSION))
+		.map((file) => file.slice(0, -LOG_EXTENSION.length))
+}
+
+function run_number(scenario_name: string, run_name: string): number | undefined {
+	const prefix = `${scenario_name}-`
+
+	if (!run_name.startsWith(prefix)) return undefined
+
+	const digits = run_name.slice(prefix.length)
+
+	return /^\d+$/u.test(digits) ? Number(digits) : undefined
+}
+
+// The name is the project directory and, for a GitHub scenario, the repository `josh start` creates.
+// It is numbered past every earlier log and repository, so a rerun leaves the last run's repository
+// in place.
+function next_name(scenario_name: string, taken_names: TakenNames): string {
+	const taken = [...logged_names(taken_names.logs), ...taken_names.repositories]
+		.map((run_name) => run_number(scenario_name, run_name))
+		.filter((number) => number !== undefined)
+	const next = taken.length === 0 ? FIRST_RUN : Math.max(...taken) + 1
+
+	return `${scenario_name}-${String(next)}`
+}
+
+function file_name(run_name: string): string {
+	return `${run_name}${LOG_EXTENSION}`
+}
+
+function redact(line: string, secrets: ReadonlyArray<string>): string {
+	const present = secrets.filter((secret) => secret !== '')
+	let redacted = line
+
+	for (const secret of present) {
+		redacted = redacted.replaceAll(secret, '[REDACTED]')
+	}
+
+	return redacted
+}
+
+const fresh_machine_log = { next_name, file_name, redact }
+
+export { fresh_machine_log }
+export type { TakenNames }

package/scripts/fresh-machine/fresh-machine-patterns.ts

@@ -0,0 +1,175 @@
+import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
+import { fresh_machine_spec, type Scenario } from './fresh-machine-spec'
+
+// kit's own six patterns: three projects (one Lua file, one `index.html`, a minimal TypeScript
+// SvelteKit app from `sv`) by two commands (`josh init`, `josh start`), each from the starting state
+// joshuafolkken/kit#2848 gave it. `josh init` installs the packed checkout, so a fix is retested
+// without a release; `josh start` installs a published version, because its setup pull request
+// would carry a tarball path CI cannot resolve.
+
+const KIT = KIT_PACKAGE_NAME
+const ALLOW_BUILDS = '--allow-build=esbuild --allow-build=unrs-resolver'
+// What `pnpm dlx @joshuafolkken/kit init` writes before it installs kit.
+const BARE_MANIFEST = String.raw`printf '{ "private": true }\n' > package.json`
+const CREATE_SVELTEKIT =
+	'pnpm dlx sv create --template minimal --types ts --no-add-ons --install pnpm .'
+// The `sv` that created the project is the one `pnpm dlx` resolved, so its version is recorded.
+const SV_VERSION = 'pnpm dlx sv --version'
+// The app builds and type-checks before kit is installed and still does after it.
+const SVELTEKIT_CHECKS = 'pnpm build && pnpm check'
+const INSTALL_TARBALL = `pnpm add -D ${ALLOW_BUILDS} "$PACKAGE_TARBALL"`
+// A version published minutes ago is inside pnpm's release-age wait; kit alone is excluded from it
+// (joshuafolkken/kit#2869), so every other dependency keeps the wait.
+const EXCLUDE_RELEASE_AGE = String.raw`printf 'minimumReleaseAgeExclude:\n  - "${KIT}"\n' >> pnpm-workspace.yaml`
+const INSTALL_PUBLISHED = `pnpm add -D ${ALLOW_BUILDS} ${KIT}@"$PACKAGE_VERSION"`
+const GATE = 'pnpm josh gate'
+const INIT_COMMANDS = [INSTALL_TARBALL, 'pnpm exec josh init', GATE]
+// `josh start` leaves the project on its setup branch, where the gate asks for the scoped checks
+// first; this is the line its refusal hands back.
+const SCOPED_CHECKS = 'pnpm josh lint:related && pnpm josh test:related'
+const START = 'pnpm exec josh start --yes --github'
+
+// An agent names the profile rather than leaving it to detection, so every pattern passes its own.
+function start_commands(profile: string): Array<string> {
+	return [
+		EXCLUDE_RELEASE_AGE,
+		INSTALL_PUBLISHED,
+		`${START} --profile ${profile}`,
+		SCOPED_CHECKS,
+		GATE,
+	]
+}
+
+// `gh auth login` cannot run without a person, and it is what points git at gh for credentials; with
+// the token in the environment this is the same step.
+const SIGN_IN = 'gh auth setup-git'
+// What the prerequisites guide has a person run once per machine. Only the pattern with no repository
+// uses it: `josh start` makes the first commit there, and stops before writing without it (#3754).
+const MACHINE_IDENTITY =
+	'git config --global user.name kit-test && git config --global user.email kit-test@example.com'
+// The identity is the repository's own, so the machine stays one nobody has configured git on.
+const FIRST_COMMIT = [
+	'git init --initial-branch main',
+	'git config user.name kit-test && git config user.email kit-test@example.com',
+	'git add --all && git commit --message "Initial commit"',
+]
+const CREATE_REPOSITORY = 'gh repo create "$RUN_NAME" --private --source . --push'
+// The labels a repository already had, recorded before `josh start` so the probe after it shows none
+// was removed or changed.
+const LABELS = 'gh label list --limit 100'
+// The setup pull request's CI, waited for and recorded; the pull request itself is never merged.
+const SETUP_CI = 'gh pr checks --watch --interval 60'
+
+// The two states #3712 was found in: a shell that reads no rc file, and a PATH with `node` on it and
+// no `pnpm`.
+const BARE_SHELL =
+	'env -i HOME="$HOME" PATH=/usr/local/bin:/usr/bin:/bin bash --noprofile --norc -c'
+const NODE_ONLY = '"$HOME/node-only"'
+const PATH_PROBES = [
+	`${BARE_SHELL} '${GATE}'`,
+	`mkdir -p ${NODE_ONLY} && ln -sf "$(command -v node)" ${NODE_ONLY}/node && ${BARE_SHELL} 'PATH="$HOME/node-only:$PATH" ./node_modules/.bin/josh gate'`,
+]
+
+// What a `josh start` run is checked against before the PATH states: the profile it recorded, the
+// repository's visibility and branch, its labels, and the files the first commit on `main` holds. Where
+// `main` already had a commit, `josh start` opens a setup Issue and pull request instead of pushing to
+// it; the last four record those, the files the pull request carries and the `main` GitHub holds.
+const PROFILE = 'pnpm josh profile'
+const START_PROBES = [
+	PROFILE,
+	'gh repo view --json visibility,defaultBranchRef',
+	LABELS,
+	'git show --name-only --format= "$(git rev-list --max-parents=0 main)"',
+	'gh issue list --state all --json number,title,state,labels',
+	'gh pr list --state all --json number,title,state,headRefName,labels,closingIssuesReferences',
+	'gh pr diff --name-only',
+	'git log --oneline origin/main',
+]
+
+// What a `josh init` run is checked against after the gate: the profile it chose, the files it left
+// (a `./.git` line is a repository it should not have made), and a second run that changes nothing.
+const PROJECT_FILES =
+	'find . -name node_modules -prune -o -name .git -prune -o -type f -print | sort'
+const CHECKSUMS = `${PROJECT_FILES} | xargs sha256sum`
+const INIT_PROBES = [
+	PROFILE,
+	'find . -name node_modules -prune -o -print | sort',
+	`${CHECKSUMS} > "$HOME/before-second-init.sha" && pnpm exec josh init && ${CHECKSUMS} | diff "$HOME/before-second-init.sha" -`,
+]
+
+const LUA_FILE = 'main.lua'
+const HTML_FILE = 'index.html'
+const LUA_FILES = { [LUA_FILE]: 'print("Hello")\n' }
+const HTML_FILES = { [HTML_FILE]: '<!doctype html><html><body><h1>Hello</h1></body></html>\n' }
+
+function init_pattern(
+	project: string,
+	files: Record<string, string>,
+	setup: ReadonlyArray<string>,
+	project_probes: ReadonlyArray<string> = [],
+): Scenario {
+	return fresh_machine_spec.define({
+		name: `kit-test-${project}-init`,
+		files,
+		commands: [...setup, ...INIT_COMMANDS],
+		probes: [...INIT_PROBES, ...project_probes, ...PATH_PROBES],
+	})
+}
+
+// What a `josh start` pattern adds to the shared steps: the state before the install, the profile it
+// names, the commands that must pass after the gate, and the probes recorded before the PATH states.
+interface StartProject {
+	setup: ReadonlyArray<string>
+	profile: string
+	checks?: ReadonlyArray<string>
+	probes?: ReadonlyArray<string>
+}
+
+function start_pattern(
+	project: string,
+	files: Record<string, string>,
+	{ setup, profile, checks = [], probes = [] }: StartProject,
+): Scenario {
+	return fresh_machine_spec.define({
+		name: `kit-test-${project}-start`,
+		requires_github: true,
+		package_source: 'published',
+		files,
+		commands: [SIGN_IN, ...setup, ...start_commands(profile), ...checks],
+		probes: [...START_PROBES, ...probes, ...PATH_PROBES],
+	})
+}
+
+const PATTERNS: ReadonlyArray<Scenario> = [
+	init_pattern('lua', LUA_FILES, [BARE_MANIFEST]),
+	// No Git: `josh start` creates the repository, the first commit and the GitHub repository.
+	start_pattern('lua', LUA_FILES, { setup: [MACHINE_IDENTITY, BARE_MANIFEST], profile: 'basic' }),
+	init_pattern('html', HTML_FILES, [BARE_MANIFEST]),
+	// Git with a first commit on `main`, no GitHub repository.
+	start_pattern('html', HTML_FILES, { setup: [...FIRST_COMMIT, BARE_MANIFEST], profile: 'basic' }),
+	init_pattern('svelte', {}, [CREATE_SVELTEKIT, SV_VERSION, SVELTEKIT_CHECKS], [SVELTEKIT_CHECKS]),
+	// A GitHub repository with `main` already pushed, its labels recorded before the install; the app
+	// still builds and type-checks on the setup branch, and the setup pull request's CI is waited for.
+	start_pattern(
+		'svelte',
+		{},
+		{
+			setup: [CREATE_SVELTEKIT, SV_VERSION, ...FIRST_COMMIT, CREATE_REPOSITORY, LABELS],
+			profile: 'full',
+			checks: [SVELTEKIT_CHECKS],
+			probes: [SETUP_CI],
+		},
+	),
+]
+
+function names(): Array<string> {
+	return PATTERNS.map((pattern) => pattern.name)
+}
+
+function find(name: string): Scenario | undefined {
+	return PATTERNS.find((pattern) => pattern.name === name)
+}
+
+const fresh_machine_patterns = { names, find }
+
+export { fresh_machine_patterns }

package/scripts/fresh-machine/fresh-machine-run.ts

@@ -0,0 +1,215 @@
+import {
+	appendFileSync,
+	chmodSync,
+	mkdirSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { execa, type Options } from 'execa'
+import { z } from 'zod'
+import { fresh_machine_docker, type ContainerRun } from './fresh-machine-docker'
+import { fresh_machine_image } from './fresh-machine-image'
+import { fresh_machine_log } from './fresh-machine-log'
+import { fresh_machine_script } from './fresh-machine-script'
+import type { Scenario } from './fresh-machine-spec'
+
+// The I/O of `josh fresh:run`: build the machine, stage what the container may read, run the
+// scenario, and put every line of all three into one log.
+
+const DOCKER = 'docker'
+const PNPM = 'pnpm'
+const FAILURE_EXIT_CODE = 1
+const STAGE_PREFIX = 'josh-fresh-machine-'
+// The container's user is not the host's, so what it reads has to be readable by anyone — whatever
+// the host's umask gave the seed files and the tarball `pnpm pack` wrote.
+const SHARED_DIRECTORY_MODE = 0o755
+const SHARED_FILE_MODE = 0o644
+const TARBALL_EXTENSION = '.tgz'
+const MANIFEST_SCHEMA = z.object({ name: z.string() })
+
+interface RunRequest {
+	scenario: Scenario
+	run_name: string
+	log_path: string
+	package_version: string | undefined
+	// Variable name → value, each passed into the container by name and replaced in every line.
+	secrets: Readonly<Record<string, string>>
+	is_rebuild: boolean
+}
+
+interface Stage {
+	root: string
+	seed_directory: string
+	pack_directory: string
+}
+
+type Write = (line: string) => void
+
+function logger(request: RunRequest): Write {
+	const secrets = Object.values(request.secrets)
+
+	return function write(line: string): void {
+		const safe = fresh_machine_log.redact(line, secrets)
+
+		console.info(safe)
+		appendFileSync(request.log_path, `${safe}\n`)
+	}
+}
+
+// One host command, its output streamed line by line into the log. A command that could not start
+// (no docker on the machine) has no exit code, and its reason is the only line there is to log.
+async function stream(
+	file: string,
+	arguments_: Array<string>,
+	options: Options,
+	write: Write,
+): Promise<number> {
+	const subprocess = execa(file, arguments_, { ...options, all: true, reject: false })
+	const lines = subprocess.iterable({ from: 'all' })
+
+	for await (const line of lines) write(String(line))
+
+	const result = await subprocess
+
+	if (result.exitCode === undefined) write(result.shortMessage ?? `${file} did not start`)
+
+	return result.exitCode ?? FAILURE_EXIT_CODE
+}
+
+function staged_directory(root: string, name: string): string {
+	const directory = path.join(root, name)
+
+	mkdirSync(directory)
+
+	return directory
+}
+
+function stage(scenario: Scenario): Stage {
+	const root = mkdtempSync(path.join(os.tmpdir(), STAGE_PREFIX))
+	const seed_directory = staged_directory(root, 'seed')
+
+	for (const [file, content] of Object.entries(scenario.files)) {
+		const target = path.join(seed_directory, file)
+
+		mkdirSync(path.dirname(target), { recursive: true })
+		writeFileSync(target, content)
+	}
+
+	return { root, seed_directory, pack_directory: staged_directory(root, 'pack') }
+}
+
+// Run once everything is staged, so the tarball is covered as well as the seed. The root itself stays
+// as private as `mkdtemp` made it: a bind mount never enters a source through its parent, and on a
+// shared host an open root would let every other user read the tarball for the length of the run.
+function share(root: string): void {
+	const entries = readdirSync(root, { withFileTypes: true, recursive: true })
+
+	for (const entry of entries) {
+		const mode = entry.isDirectory() ? SHARED_DIRECTORY_MODE : SHARED_FILE_MODE
+
+		chmodSync(path.join(entry.parentPath, entry.name), mode)
+	}
+}
+
+// `pnpm pack` runs the checkout's own `prepack`, so the tarball holds what a release of this tree
+// would.
+async function pack(pack_directory: string, write: Write): Promise<string> {
+	const pack_arguments = ['pack', '--pack-destination', pack_directory]
+
+	write(`$ ${PNPM} ${pack_arguments.join(' ')}`)
+	await stream(PNPM, pack_arguments, { cwd: PROJECT_ROOT }, write)
+
+	const tarball = readdirSync(pack_directory).find((file) => file.endsWith(TARBALL_EXTENSION))
+
+	if (tarball === undefined) throw new Error('pnpm pack produced no tarball')
+
+	return tarball
+}
+
+function package_name(): string {
+	const manifest = readFileSync(path.join(PROJECT_ROOT, 'package.json'), 'utf8')
+
+	return MANIFEST_SCHEMA.parse(JSON.parse(manifest)).name
+}
+
+// The published version is always written out in the log and the install command, so a run can be
+// repeated against the same release; without `--package-version` it is the registry's latest.
+async function published_version(requested: string | undefined): Promise<string> {
+	if (requested !== undefined) return requested
+
+	const { stdout } = await execa(PNPM, ['view', package_name(), 'version'], { cwd: PROJECT_ROOT })
+
+	return stdout.trim()
+}
+
+async function container_run(
+	request: RunRequest,
+	staged: Stage,
+	write: Write,
+): Promise<ContainerRun> {
+	const { scenario } = request
+	const is_tarball = scenario.package_source === 'tarball'
+
+	return {
+		image: fresh_machine_image.tag(scenario.requires_github),
+		run_name: request.run_name,
+		script: fresh_machine_script.build(scenario),
+		seed_directory: staged.seed_directory,
+		pack_directory: staged.pack_directory,
+		tarball: is_tarball ? await pack(staged.pack_directory, write) : undefined,
+		package_version: is_tarball ? undefined : await published_version(request.package_version),
+		secret_names: Object.keys(request.secrets),
+	}
+}
+
+async function build_image(request: RunRequest, write: Write): Promise<number> {
+	const { scenario } = request
+	const image = fresh_machine_image.tag(scenario.requires_github)
+	const build_arguments = fresh_machine_docker.build_arguments(image, request.is_rebuild)
+	const input = fresh_machine_image.dockerfile(scenario.requires_github)
+
+	write(`$ ${DOCKER} ${build_arguments.join(' ')}`)
+
+	return await stream(DOCKER, build_arguments, { input }, write)
+}
+
+async function run_container(request: RunRequest, staged: Stage, write: Write): Promise<number> {
+	const container = await container_run(request, staged, write)
+
+	share(staged.root)
+	write(`$ ${DOCKER} run ${container.image} — ${request.run_name}`)
+	write(`# package: ${container.tarball ?? container.package_version ?? ''}`)
+
+	return await stream(
+		DOCKER,
+		fresh_machine_docker.run_arguments(container),
+		{ env: request.secrets },
+		write,
+	)
+}
+
+async function run(request: RunRequest): Promise<number> {
+	const write = logger(request)
+	const build_code = await build_image(request, write)
+
+	if (build_code !== 0) return build_code
+
+	const staged = stage(request.scenario)
+
+	try {
+		return await run_container(request, staged, write)
+	} finally {
+		rmSync(staged.root, { recursive: true, force: true })
+	}
+}
+
+const fresh_machine_run = { run }
+
+export { fresh_machine_run }
+export type { RunRequest }

package/scripts/fresh-machine/fresh-machine-script.ts

@@ -0,0 +1,45 @@
+import type { Scenario } from './fresh-machine-spec'
+
+// The script one container runs. Every command is printed before it runs and its exit status after,
+// so the log reads as a terminal session; the first failing command ends the run, and the probes
+// that follow a clean run are recorded whatever they exit with.
+
+const SEED_MOUNT = '/seed'
+const PACK_MOUNT = '/pack'
+const COPY_SEED = `cp -R ${SEED_MOUNT}/. .`
+const PROBES_HEADING = '# probes — recorded, never failing the run'
+const ESCAPED_QUOTE = String.raw`'\''`
+const PREAMBLE = [
+	String.raw`step() { printf '\n$ %s\n' "$1"; eval "$1"; local code=$?; printf '[exit %s]\n' "$code"; return "$code"; }`,
+	'mkdir -p "$HOME/$RUN_NAME" && cd "$HOME/$RUN_NAME" || exit 1',
+]
+
+function quote(command: string): string {
+	const escaped = command.split("'").join(ESCAPED_QUOTE)
+
+	return `'${escaped}'`
+}
+
+function required(command: string): string {
+	return `step ${quote(command)} || exit $?`
+}
+
+function probe_lines(probes: ReadonlyArray<string>): Array<string> {
+	if (probes.length === 0) return []
+
+	return [
+		String.raw`printf '\n%s\n' ${quote(PROBES_HEADING)}`,
+		...probes.map((probe) => `step ${quote(probe)}`),
+	]
+}
+
+function build(scenario: Scenario): string {
+	const seed = Object.keys(scenario.files).length > 0 ? [COPY_SEED] : []
+	const commands = [...seed, ...scenario.commands].map((command) => required(command))
+
+	return [...PREAMBLE, ...commands, ...probe_lines(scenario.probes), 'exit 0', ''].join('\n')
+}
+
+const fresh_machine_script = { build, SEED_MOUNT, PACK_MOUNT }
+
+export { fresh_machine_script }

package/scripts/fresh-machine/fresh-machine-spec.ts

@@ -0,0 +1,57 @@
+import path from 'node:path'
+import { z } from 'zod'
+
+// A scenario is everything one `josh fresh:run` needs to know: the files that are in the project
+// before anything is installed, the commands a person would type, and the probes recorded after
+// them. kit's own six patterns and a consumer toolkit's spec file are the same shape, so the machine
+// and the log are shared and nothing about them is kit's alone (joshuafolkken/kit#3714).
+//
+// Inside the container a command reads `$RUN_NAME` (the numbered project and repository name),
+// `$PACKAGE_TARBALL` (the packed checkout, for `package_source: tarball`) and `$PACKAGE_VERSION`
+// (the published version, for `package_source: published`).
+
+function is_project_relative(file: string): boolean {
+	const normalized = path.posix.normalize(file)
+
+	return !path.posix.isAbsolute(normalized) && !normalized.startsWith('..')
+}
+
+const COMMAND_SCHEMA = z.string().min(1)
+const SCENARIO_SCHEMA = z.strictObject({
+	name: z.string().regex(/^[a-z0-9][a-z0-9-]*$/u),
+	// A GitHub scenario runs on the image that also has git and gh, and receives the host's token.
+	requires_github: z.boolean().default(false),
+	// A Claude Code scenario receives the host's long-lived token as `CLAUDE_CODE_OAUTH_TOKEN`.
+	requires_claude: z.boolean().default(false),
+	package_source: z.enum(['tarball', 'published']).default('tarball'),
+	files: z.record(z.string().refine(is_project_relative), z.string()).default({}),
+	// A failing command ends the run; a failing probe is only recorded.
+	commands: z.array(COMMAND_SCHEMA).min(1),
+	probes: z.array(COMMAND_SCHEMA).default([]),
+})
+
+type Scenario = z.infer<typeof SCENARIO_SCHEMA>
+type ScenarioInput = z.input<typeof SCENARIO_SCHEMA>
+
+function define(input: ScenarioInput): Scenario {
+	return SCENARIO_SCHEMA.parse(input)
+}
+
+function problems(error: z.ZodError): string {
+	return error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ')
+}
+
+// A spec file is written by hand in another repository, so a mistake is reported as the fields that
+// are wrong rather than as a stack trace.
+function parse(json: string): Scenario {
+	const result = SCENARIO_SCHEMA.safeParse(JSON.parse(json))
+
+	if (!result.success) throw new Error(`Invalid scenario spec — ${problems(result.error)}`)
+
+	return result.data
+}
+
+const fresh_machine_spec = { define, parse }
+
+export { fresh_machine_spec }
+export type { Scenario, ScenarioInput }

package/scripts/fresh-machine/specs/kit-test-backlogrun-python.json

@@ -0,0 +1,34 @@
+{
+	"name": "kit-test-backlogrun-python",
+	"requires_github": true,
+	"package_source": "tarball",
+	"requires_claude": true,
+	"files": {
+		"pyproject.toml": "[project]\nname = \"greeting\"\nversion = \"0.1.0\"\nrequires-python = \">=3.9\"\n",
+		"main.py": "def main() -> None:\n    print(\"Hello\")\n\n\nif __name__ == \"__main__\":\n    main()\n"
+	},
+	"commands": [
+		"gh auth setup-git",
+		"git config --global user.name kit-test && git config --global user.email kit-test@example.com",
+		"printf '{ \"private\": true }\\n' > package.json",
+		"cp \"$PACKAGE_TARBALL\" . && pnpm add -D --allow-build=esbuild --allow-build=unrs-resolver \"./$(basename \"$PACKAGE_TARBALL\")\"",
+		"pnpm exec josh start --yes --github",
+		"pnpm josh profile | grep -x 'profile: basic (package.json josh.profile)'",
+		"grep -q '\"workflow\": \"github\"' package.json && test -f .claude/settings.json",
+		"curl -fsSL https://claude.ai/install.sh | bash && export PATH=\"$HOME/.local/bin:$PATH\" && claude --version",
+		"gh issue create --title 'Print a greeting with a name in main.py' --body 'Make main.py print \"Hello, Josh\" instead of \"Hello\".' --label auto-ok --label run:lane",
+		"timeout 60 pnpm josh backlogrun > \"$HOME/backlogrun.out\" 2>&1; cat \"$HOME/backlogrun.out\"; grep -q '^backlogrun: started' \"$HOME/backlogrun.out\"",
+		"pnpm josh run:event --from 0 | grep 'starting session'",
+		"for i in $(seq 1 90); do pnpm josh run:event --from 0 | grep -q 'dispatching' && break; sleep 10; done; pnpm josh run:event --from 0 | grep 'dispatching'",
+		"for i in $(seq 1 120); do test \"$(gh pr list --state all --json number --jq length)\" -gt 0 && break; sleep 10; done; pnpm josh run:board --chat",
+		"pnpm josh backlogrun --stop"
+	],
+	"probes": [
+		"tail -n 40 \"$(sed -n 's/^backlogrun: started.*; log //p' \"$HOME/backlogrun.out\")\" | cut -c1-400",
+		"grep -c 'requires approval' \"$(sed -n 's/^backlogrun: started.*; log //p' \"$HOME/backlogrun.out\")\"",
+		"grep -c 'run:carry --begin' \"$(sed -n 's/^backlogrun: started.*; log //p' \"$HOME/backlogrun.out\")\"",
+		"tail -n 40 /tmp/josh-lane-dispatch-*.log | cut -c1-400",
+		"cat /tmp/josh-lane-dispatch-*.log | grep -c 'requires approval'",
+		"gh pr list --state all"
+	]
+}