@joshuafolkken/kit 1.1387.0 → 1.1435.0

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

@@ -0,0 +1,204 @@
+#!/usr/bin/env tsx
+import { mkdirSync, readdirSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { claude_token } from '#scripts/auth/claude-token'
+import { gh_cli_token } from '#scripts/gh/gh-cli-token'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { self_sync_guard } from '#scripts/self-sync-guard/self-sync-guard-logic'
+import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
+import { fresh_machine_docker } from './fresh-machine-docker'
+import { fresh_machine_log } from './fresh-machine-log'
+import { fresh_machine_patterns } from './fresh-machine-patterns'
+import { fresh_machine_run, type RunRequest } from './fresh-machine-run'
+import { fresh_machine_spec, type Scenario } from './fresh-machine-spec'
+
+// `josh fresh:run <pattern>` / `josh fresh:run --spec <file>` — run one scenario on a machine that
+// has nothing installed, and keep what happened as a log.
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const USAGE =
+	'Usage: josh fresh:run <pattern> | --spec <file.json> [--package-version <version>] [--log-dir <dir>] [--rebuild] | --list'
+// The scratch directory kit's distributed `.gitignore` already ignores, so a log is never committed
+// from kit or from a consumer toolkit.
+const DEFAULT_LOG_DIRECTORY = '.claude/tmp/fresh-machine'
+const NO_GITHUB_TOKEN =
+	'This scenario uses GitHub and `gh auth token` printed no token. Run `gh auth login` on this machine first.'
+const NO_CLAUDE_TOKEN = `This scenario uses Claude Code and neither the macOS keychain nor ${claude_token.VARIABLE} holds a token. ${claude_token.SETUP_HINT}`
+// The patterns install kit by name, while the tarball and the published version are those of the
+// checkout the command is run from — in a toolkit's checkout the two would be different packages.
+const NOT_A_KIT_CHECKOUT = `The named patterns install ${KIT_PACKAGE_NAME} and run from its checkout only. Write this package's scenario as a JSON file and pass it with --spec.`
+const OWNED_REPOSITORIES = 'user/repos?affiliation=owner&per_page=100'
+const REPOSITORY_NAMES = '.[].name'
+
+// The option names are the CLI's, so the type is read off the parser rather than restated.
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+function parse(argv: ReadonlyArray<string>) {
+	return parseArgs({
+		args: [...argv],
+		allowPositionals: true,
+		options: {
+			spec: { type: 'string' },
+			'package-version': { type: 'string' },
+			'log-dir': { type: 'string' },
+			rebuild: { type: 'boolean' },
+			list: { type: 'boolean' },
+		},
+	})
+}
+
+type CliValues = ReturnType<typeof parse>['values']
+
+function pattern_of(name: string): Scenario | undefined {
+	const scenario = fresh_machine_patterns.find(name)
+
+	if (scenario === undefined) return undefined
+
+	const is_kit_checkout = self_sync_guard.read_package_name(PROJECT_ROOT) === KIT_PACKAGE_NAME
+
+	if (!is_kit_checkout) throw new Error(NOT_A_KIT_CHECKOUT)
+
+	return scenario
+}
+
+function scenario_of(values: CliValues, pattern: string | undefined): Scenario | undefined {
+	if (values.spec !== undefined) {
+		return fresh_machine_spec.parse(readFileSync(path.resolve(PROJECT_ROOT, values.spec), 'utf8'))
+	}
+
+	return pattern === undefined ? undefined : pattern_of(pattern)
+}
+
+// A GitHub run's name is also the repository it creates under the account of the token, and the
+// logs of this checkout are not the only place such a run was started from.
+function repositories_of(scenario: Scenario): Array<string> {
+	if (!scenario.requires_github) return []
+
+	const names = git_gh_exec.exec_gh_api_sync({
+		path: OWNED_REPOSITORIES,
+		should_paginate: true,
+		jq_filter: REPOSITORY_NAMES,
+	})
+
+	return names.split('\n').filter((name) => name !== '')
+}
+
+function request_of(
+	scenario: Scenario,
+	values: CliValues,
+	secrets: Record<string, string>,
+): RunRequest {
+	const log_directory = path.resolve(PROJECT_ROOT, values['log-dir'] ?? DEFAULT_LOG_DIRECTORY)
+
+	mkdirSync(log_directory, { recursive: true })
+
+	const run_name = fresh_machine_log.next_name(scenario.name, {
+		logs: readdirSync(log_directory),
+		repositories: repositories_of(scenario),
+	})
+
+	return {
+		scenario,
+		run_name,
+		log_path: path.join(log_directory, fresh_machine_log.file_name(run_name)),
+		package_version: values['package-version'],
+		secrets,
+		is_rebuild: values.rebuild === true,
+	}
+}
+
+function refuse(message: string): number {
+	console.error(message)
+
+	return FAILURE_EXIT_CODE
+}
+
+// One secret a scenario asks for: where its value is read on the host, and what to say when there is
+// none. Every one is read before Docker starts, so a missing token stops the run with nothing built.
+interface Secret {
+	variable: string
+	is_required: (scenario: Scenario) => boolean
+	read: () => string | undefined
+	missing: string
+}
+
+const SECRETS: ReadonlyArray<Secret> = [
+	{
+		variable: fresh_machine_docker.TOKEN_VARIABLE,
+		is_required: (scenario) => scenario.requires_github,
+		read: gh_cli_token.get,
+		missing: NO_GITHUB_TOKEN,
+	},
+	{
+		variable: claude_token.VARIABLE,
+		is_required: (scenario) => scenario.requires_claude,
+		read: claude_token.read,
+		missing: NO_CLAUDE_TOKEN,
+	},
+]
+
+// The values found, by variable name, and the message of the first secret that has none.
+interface Secrets {
+	values: Record<string, string>
+	missing: string | undefined
+}
+
+function secrets_of(scenario: Scenario): Secrets {
+	const required = SECRETS.filter((secret) => secret.is_required(scenario))
+	const read = required.map((secret) => ({ secret, value: secret.read() }))
+	const found = read.flatMap(({ secret, value }) =>
+		value === undefined ? [] : [[secret.variable, value] as const],
+	)
+
+	return {
+		values: Object.fromEntries(found),
+		missing: read.find(({ value }) => value === undefined)?.secret.missing,
+	}
+}
+
+async function run_scenario(scenario: Scenario, values: CliValues): Promise<number> {
+	const secrets = secrets_of(scenario)
+
+	if (secrets.missing !== undefined) return refuse(secrets.missing)
+
+	const request = request_of(scenario, values, secrets.values)
+	const exit_code = await fresh_machine_run.run(request)
+
+	console.info(`Log: ${request.log_path}`)
+
+	return exit_code
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const { values, positionals } = parse(argv)
+	const patterns = fresh_machine_patterns.names().join('\n')
+
+	if (values.list === true) {
+		console.info(patterns)
+
+		return 0
+	}
+
+	const scenario = scenario_of(values, positionals[0])
+
+	if (scenario === undefined) return refuse(`${USAGE}\n\nPatterns:\n${patterns}`)
+
+	return await run_scenario(scenario, values)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	try {
+		process.exitCode = await run(argv)
+	} catch (error) {
+		process.exitCode = refuse(error instanceof Error ? error.message : String(error))
+	}
+}
+
+const fresh_machine_cli = { run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { fresh_machine_cli }

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

@@ -0,0 +1,65 @@
+import { fresh_machine_script } from './fresh-machine-script'
+
+// The two docker invocations of `josh fresh:run`, as argument lists. A token is passed by name only
+// (`--env GH_TOKEN`): docker reads its value from the environment of the client, so it is in no
+// argument, no image layer and no printed command.
+
+const TOKEN_VARIABLE = 'GH_TOKEN'
+const ENV_FLAG = '--env'
+const VOLUME_FLAG = '--volume'
+
+interface ContainerRun {
+	image: string
+	run_name: string
+	script: string
+	seed_directory: string
+	pack_directory: string
+	// The packed checkout's file name inside `pack_directory`, for a tarball scenario.
+	tarball: string | undefined
+	package_version: string | undefined
+	// The variables whose values the client's environment carries into the container.
+	secret_names: ReadonlyArray<string>
+}
+
+// The Dockerfile arrives on stdin (`-`), so the build has no context to copy a host file from.
+function build_arguments(image: string, is_rebuild: boolean): Array<string> {
+	const cache = is_rebuild ? ['--no-cache'] : []
+
+	return ['build', '--progress', 'plain', ...cache, '--tag', image, '-']
+}
+
+function variables(container: ContainerRun): Array<string> {
+	const { tarball } = container
+	const tarball_path = tarball === undefined ? '' : `${fresh_machine_script.PACK_MOUNT}/${tarball}`
+	const assignments = [
+		`RUN_NAME=${container.run_name}`,
+		`PACKAGE_TARBALL=${tarball_path}`,
+		`PACKAGE_VERSION=${container.package_version ?? ''}`,
+		...container.secret_names,
+	]
+
+	return assignments.flatMap((assignment) => [ENV_FLAG, assignment])
+}
+
+// `bash -i` is the new terminal the prerequisites guide asks for: it reads the profile the pnpm
+// installer edited, which a non-interactive shell on Debian returns from before reaching.
+function run_arguments(container: ContainerRun): Array<string> {
+	return [
+		'run',
+		'--rm',
+		...variables(container),
+		VOLUME_FLAG,
+		`${container.seed_directory}:${fresh_machine_script.SEED_MOUNT}:ro`,
+		VOLUME_FLAG,
+		`${container.pack_directory}:${fresh_machine_script.PACK_MOUNT}:ro`,
+		container.image,
+		'bash',
+		'-ic',
+		container.script,
+	]
+}
+
+const fresh_machine_docker = { build_arguments, run_arguments, TOKEN_VARIABLE }
+
+export { fresh_machine_docker }
+export type { ContainerRun }

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,130 @@
+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_COMMANDS = [
+	EXCLUDE_RELEASE_AGE,
+	INSTALL_PUBLISHED,
+	'pnpm exec josh start --yes --github',
+	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 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 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 = [
+	'pnpm josh 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],
+	})
+}
+
+function start_pattern(
+	project: string,
+	files: Record<string, string>,
+	setup: ReadonlyArray<string>,
+): Scenario {
+	return fresh_machine_spec.define({
+		name: `kit-test-${project}-start`,
+		requires_github: true,
+		package_source: 'published',
+		files,
+		commands: [SIGN_IN, ...setup, ...START_COMMANDS],
+		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, [MACHINE_IDENTITY, BARE_MANIFEST]),
+	init_pattern('html', HTML_FILES, [BARE_MANIFEST]),
+	// Git with a first commit on `main`, no GitHub repository.
+	start_pattern('html', HTML_FILES, [...FIRST_COMMIT, BARE_MANIFEST]),
+	init_pattern('svelte', {}, [CREATE_SVELTEKIT, SV_VERSION, SVELTEKIT_CHECKS], [SVELTEKIT_CHECKS]),
+	// A GitHub repository with `main` already pushed.
+	start_pattern('svelte', {}, [CREATE_SVELTEKIT, ...FIRST_COMMIT, CREATE_REPOSITORY]),
+]
+
+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 }