@namzu/sandbox 23.0.1 → 25.0.0

package/src/local-virtual-computer/setup/host.ts

@@ -0,0 +1,100 @@
+import { homedir, release } from 'node:os'
+import { join, win32 } from 'node:path'
+import { LocalCommandError, nodeCommandRunner } from '../engine.js'
+import { type CreateWslcSetupHost, RESUME_AT_SIGN_IN_KEY } from './contract.js'
+import { PROBE_LIMIT_MS, ProbeTimeoutError, runLimited } from './limits.js'
+import { queryRegistryKey } from './registry.js'
+
+/** `10.0.19045` becomes 19045; undefined when the release string has no build. */
+function windowsBuildOf(platform: NodeJS.Platform): number | undefined {
+	if (platform !== 'win32') return undefined
+	const build = Number(release().split('.')[2])
+	return Number.isInteger(build) ? build : undefined
+}
+
+/**
+ * The processor type of the PC. On Windows a 32-bit process sees its own
+ * type in `PROCESSOR_ARCHITECTURE`; the PC's is in `PROCESSOR_ARCHITEW6432`.
+ * Neither is `process.arch`, which names the Node build, not the machine.
+ */
+export function windowsArchitectureOf(env: NodeJS.ProcessEnv): string {
+	const claimed = (env.PROCESSOR_ARCHITEW6432 ?? env.PROCESSOR_ARCHITECTURE ?? '').toUpperCase()
+	if (claimed === 'AMD64') return 'x64'
+	if (claimed === 'ARM64') return 'arm64'
+	return claimed === '' ? process.arch : claimed.toLowerCase()
+}
+
+function defaultStateDirectory(env: NodeJS.ProcessEnv, platform: NodeJS.Platform): string {
+	if (platform === 'win32') {
+		const base = env.LOCALAPPDATA ?? win32.join(homedir(), 'AppData', 'Local')
+		return win32.join(base, 'Namzu', 'setup')
+	}
+	return join(homedir(), '.namzu', 'setup')
+}
+
+/** `REG_DWORD    0x1f` becomes 31; anything else is undefined. */
+export function parseRegDword(output: string): number | undefined {
+	const match = /REG_DWORD\s+0x([0-9a-f]+)/i.exec(output)
+	return match ? Number.parseInt(match[1] as string, 16) : undefined
+}
+
+/** The real Windows host, with `overrides` applied. */
+export const createWslcSetupHost: CreateWslcSetupHost = (overrides = {}) => {
+	const platform = overrides.platform ?? process.platform
+	const env = overrides.env ?? process.env
+	const runner = overrides.runner ?? nodeCommandRunner
+	const host = {
+		platform,
+		arch: platform === 'win32' ? windowsArchitectureOf(env) : process.arch,
+		windowsBuild: windowsBuildOf(platform),
+		env,
+		runner,
+		stateDirectory: defaultStateDirectory(env, platform),
+		resumeRegistryKey: RESUME_AT_SIGN_IN_KEY,
+		now: () => new Date(),
+		async readDword(key: string, name: string): Promise<number | undefined> {
+			try {
+				return parseRegDword(
+					await runLimited(runner, 'reg.exe', ['query', key, '/v', name], PROBE_LIMIT_MS.command),
+				)
+			} catch (error) {
+				// reg.exe exits 1 for an absent key or value; that is "not set". A
+				// check that did not answer in time is not known: it propagates, so a
+				// policy read that timed out never reads as "not set" (allowed).
+				if (error instanceof LocalCommandError) return undefined
+				throw error
+			}
+		},
+		async keyExists(key: string): Promise<boolean | 'unknown'> {
+			try {
+				const listing = await queryRegistryKey(
+					(args) => runLimited(runner, 'reg.exe', args, PROBE_LIMIT_MS.command),
+					key,
+				)
+				return listing !== undefined
+			} catch (error) {
+				// Denied, a failed parent or no answer in time: not known, never "absent".
+				if (error instanceof LocalCommandError || error instanceof ProbeTimeoutError)
+					return 'unknown'
+				throw error
+			}
+		},
+		async bootTime(): Promise<Date> {
+			const output = await runLimited(
+				runner,
+				'powershell.exe',
+				[
+					'-NoProfile',
+					'-NonInteractive',
+					'-Command',
+					"(Get-CimInstance Win32_OperatingSystem).LastBootUpTime.ToUniversalTime().ToString('o')",
+				],
+				PROBE_LIMIT_MS.powershell,
+			)
+			const parsed = new Date(output.trim())
+			if (Number.isNaN(parsed.getTime())) throw new Error('Windows did not report its boot time')
+			return parsed
+		},
+	}
+	return { ...host, ...overrides }
+}

package/src/local-virtual-computer/setup/idle.ts

@@ -0,0 +1,39 @@
+import type { StopIdleWslcSession } from './contract.js'
+import { createWslcSetupHost } from './host.js'
+import { wslcBinaryOf } from './wslc-shared.js'
+
+/** A row of `wslc system session list`: id, creator pid, display name. */
+const SESSION_ROW = /^\s*\d+\s+\d+\s+(\S+)/
+
+/**
+ * Whether the default wslc session is running. `wslc system session list`
+ * reads the session manager and does not start a session (unlike `list` and
+ * `image`, which do). The default session is the one wslc names `wslc-cli-*`.
+ */
+export function defaultSessionRunning(listOutput: string): boolean {
+	return listOutput
+		.split(/\r?\n/)
+		.some((line) => (SESSION_ROW.exec(line)?.[1] ?? '').startsWith('wslc-cli'))
+}
+
+/**
+ * Stop the wslc session's virtual machine when nothing runs in it. Answers
+ * `busy` and does nothing while any container runs, Namzu's or not, and
+ * `not-running` when there is no session to stop.
+ *
+ * A container could start between the check and the terminate; the window is
+ * milliseconds and the caller owns the sessions it starts. If the check itself
+ * fails, the error is thrown and the session is left alone.
+ */
+export const stopIdleWslcSession: StopIdleWslcSession = async (options) => {
+	const host = createWslcSetupHost(options.host)
+	const binary = wslcBinaryOf(host)
+	const { signal } = options
+	const sessions = await host.runner.run(binary, ['system', 'session', 'list'], { signal })
+	if (!defaultSessionRunning(sessions)) return { outcome: 'not-running' }
+	// Running containers only: `list` without `--all`.
+	const running = await host.runner.run(binary, ['list', '-q'], { signal })
+	if (running.trim() !== '') return { outcome: 'busy' }
+	await host.runner.run(binary, ['system', 'session', 'terminate'], { signal })
+	return { outcome: 'stopped' }
+}

package/src/local-virtual-computer/setup/image.ts

@@ -0,0 +1,159 @@
+import { createHash } from 'node:crypto'
+import { createReadStream } from 'node:fs'
+import { stat } from 'node:fs/promises'
+import { LocalComputerSetupError } from '../engine.js'
+import { mapWslcFailure } from '../wslc-engine.js'
+import type { LoadWslcImage, WslcImageManifest } from './contract.js'
+import { createWslcSetupHost } from './host.js'
+import {
+	ManifestError,
+	archivePathOf,
+	parseImageInspect,
+	readManifest,
+	writeImageRecord,
+	wslcBinaryOf,
+} from './wslc-shared.js'
+
+const HASH_CHUNK_BYTES = 4 * 1024 * 1024
+
+async function sha256Of(
+	path: string,
+	total: number,
+	onProgress: ((done: number) => void) | undefined,
+	signal: AbortSignal | undefined,
+): Promise<string> {
+	const hash = createHash('sha256')
+	let done = 0
+	const stream = createReadStream(path, { highWaterMark: HASH_CHUNK_BYTES, signal })
+	for await (const chunk of stream) {
+		hash.update(chunk as Buffer)
+		done += (chunk as Buffer).byteLength
+		onProgress?.(Math.min(done, total))
+	}
+	return hash.digest('hex')
+}
+
+/** The image the engine reports under `ref`, or undefined when it has none. */
+async function inspectImage(
+	host: ReturnType<typeof createWslcSetupHost>,
+	ref: string,
+	signal: AbortSignal | undefined,
+): Promise<
+	| { readonly kind: 'found'; readonly id: string; readonly protocol: string | undefined }
+	| { readonly kind: 'absent' }
+	| { readonly kind: 'engine'; readonly detail: string }
+> {
+	try {
+		const output = await host.runner.run(
+			wslcBinaryOf(host),
+			['image', 'inspect', '-f', 'json', ref],
+			{ signal },
+		)
+		const parsed = parseImageInspect(output)
+		return parsed ? { kind: 'found', id: parsed.id, protocol: parsed.protocol } : { kind: 'absent' }
+	} catch (error) {
+		signal?.throwIfAborted()
+		const mapped = mapWslcFailure(error)
+		if (mapped === undefined) return { kind: 'absent' }
+		if (mapped.code === 'image-missing') return { kind: 'absent' }
+		return { kind: 'engine', detail: mapped.message }
+	}
+}
+
+/**
+ * Check the bundled archive against its manifest, load it with `wslc load`,
+ * and check what loaded. Nothing is loaded that failed a check.
+ */
+export const loadWslcImage: LoadWslcImage = async (options) => {
+	const host = createWslcSetupHost(options.host)
+	const { signal } = options
+	let manifest: WslcImageManifest
+	try {
+		manifest = await readManifest(options.manifestPath)
+	} catch (error) {
+		if (error instanceof ManifestError)
+			return { outcome: 'failed', code: 'image-corrupt', detail: error.message }
+		throw error
+	}
+	const record = async (): Promise<void> => {
+		await writeImageRecord(host, {
+			imageRef: manifest.imageRef,
+			imageId: manifest.imageId,
+			loadedAt: host.now().toISOString(),
+		})
+	}
+
+	const existing = await inspectImage(host, manifest.imageRef, signal)
+	if (existing.kind === 'engine')
+		return { outcome: 'failed', code: 'image-load-failed', detail: existing.detail }
+	if (existing.kind === 'found' && existing.id === manifest.imageId) {
+		await record()
+		return { outcome: 'already-loaded' }
+	}
+
+	const archive = archivePathOf(options.manifestPath, manifest)
+	let size: number
+	try {
+		size = (await stat(archive)).size
+	} catch {
+		return {
+			outcome: 'failed',
+			code: 'image-corrupt',
+			detail: 'The Pal computer image file is missing from this installation.',
+		}
+	}
+	if (size !== manifest.compressedBytes)
+		return {
+			outcome: 'failed',
+			code: 'image-corrupt',
+			detail: 'The Pal computer image file is incomplete or damaged.',
+		}
+	const digest = await sha256Of(
+		archive,
+		manifest.compressedBytes,
+		(done) =>
+			options.onProgress?.({
+				step: 'load-image',
+				phase: 'progress',
+				done,
+				total: manifest.compressedBytes,
+				unit: 'bytes',
+			}),
+		signal,
+	)
+	if (digest !== manifest.sha256)
+		return {
+			outcome: 'failed',
+			code: 'image-corrupt',
+			detail: 'The Pal computer image file is incomplete or damaged.',
+		}
+
+	try {
+		await host.runner.run(wslcBinaryOf(host), ['load', '-q', '-i', archive], { signal })
+	} catch (error) {
+		signal?.throwIfAborted()
+		const mapped = mapWslcFailure(error)
+		return {
+			outcome: 'failed',
+			code: 'image-load-failed',
+			detail:
+				mapped instanceof LocalComputerSetupError
+					? mapped.message
+					: 'Windows could not load the Pal computer image.',
+		}
+	}
+
+	const loaded = await inspectImage(host, manifest.imageRef, signal)
+	if (
+		loaded.kind !== 'found' ||
+		loaded.id !== manifest.imageId ||
+		loaded.protocol !== manifest.protocol
+	)
+		return {
+			outcome: 'failed',
+			code: 'image-mismatch',
+			detail: 'The image that loaded is not the one this version of Namzu expects.',
+		}
+	await record()
+	return { outcome: 'loaded' }
+}

package/src/local-virtual-computer/setup/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Windows Pal computer setup: inspect the machine, plan, and run the plan
+ * after the person agrees. Separate from the provider, which never installs,
+ * loads or starts anything.
+ */
+export * from './contract.js'
+export { createWslcSetupHost } from './host.js'
+export { stopIdleWslcSession } from './idle.js'
+export { loadWslcImage } from './image.js'
+export { planWslcSetup } from './plan.js'
+export { inspectWslcReadiness } from './readiness.js'
+export { clearRestartMarker, readRestartMarker, writeRestartMarker } from './restart.js'
+export { clearResumeAtSignIn, registerResumeAtSignIn } from './resume.js'
+export { runWslcSetup } from './run.js'
+export { runElevatedWslcSteps } from './elevated.js'
+export { downloadWslPackage, PINNED_WSL_PACKAGE } from './wsl-package.js'

package/src/local-virtual-computer/setup/limits.ts

@@ -0,0 +1,68 @@
+import type { LocalComputerCommandRunner } from '../engine.js'
+
+/**
+ * Every probe command has its own time limit, so a stuck Windows tool degrades
+ * one fact to `unknown` instead of hanging the whole inspection.
+ */
+export const PROBE_LIMIT_MS = {
+	/** reg.exe, sc.exe, wsl.exe, wslc version: local and quick. */
+	command: 10_000,
+	/** PowerShell starts slowly on a cold PC. */
+	powershell: 15_000,
+	/** The command that starts the wslc session (a virtual machine). */
+	session: 60_000,
+} as const
+
+/** A probe command did not answer within its limit. */
+export class ProbeTimeoutError extends Error {
+	override readonly name = 'ProbeTimeoutError'
+	constructor() {
+		super('A Windows check did not answer in time.')
+	}
+}
+
+/**
+ * Run one command with its own limit. The limit aborts the runner's signal and
+ * also stops waiting, so a runner that ignores the signal cannot hold the
+ * caller. The caller's own signal still wins: its abort rejects with its
+ * reason, not with a timeout.
+ */
+export async function runLimited(
+	runner: LocalComputerCommandRunner,
+	binary: string,
+	args: readonly string[],
+	limitMs: number,
+	options: {
+		readonly signal?: AbortSignal
+		readonly env?: NodeJS.ProcessEnv
+		readonly cwd?: string
+	} = {},
+): Promise<string> {
+	options.signal?.throwIfAborted()
+	const controller = new AbortController()
+	let timer: ReturnType<typeof setTimeout> | undefined
+	let onOuterAbort: (() => void) | undefined
+	const stop = new Promise<never>((_, reject) => {
+		timer = setTimeout(() => {
+			// Reject first: aborting makes a well-behaved runner reject at once, and
+			// the caller must see the timeout, not that rejection.
+			reject(new ProbeTimeoutError())
+			controller.abort()
+		}, limitMs)
+		onOuterAbort = () => {
+			reject(options.signal?.reason)
+			controller.abort()
+		}
+		options.signal?.addEventListener('abort', onOuterAbort, { once: true })
+	})
+	// Whichever side loses the race must not become an unhandled rejection.
+	stop.catch(() => undefined)
+	try {
+		const running = runner.run(binary, args, { ...options, signal: controller.signal })
+		running.catch(() => undefined)
+		return await Promise.race([running, stop])
+	} finally {
+		if (timer !== undefined) clearTimeout(timer)
+		if (onOuterAbort) options.signal?.removeEventListener('abort', onOuterAbort)
+	}
+}

package/src/local-virtual-computer/setup/plan.ts

@@ -0,0 +1,144 @@
+import { createHash } from 'node:crypto'
+import type {
+	PlanWslcSetup,
+	WslcReadiness,
+	WslcSetupBlock,
+	WslcSetupPlan,
+	WslcSetupStep,
+} from './contract.js'
+import { wslcAtLeastMinimum } from './readiness.js'
+import { PINNED_WSL_PACKAGE } from './wsl-package.js'
+
+/** Rough durations for the sentence the person reads; not promises. */
+const ENABLE_FEATURES_SECONDS = 90
+const INSTALL_WSL_SECONDS = 60
+const RESTART_SECONDS = 90
+/** Bytes per second assumed for a download and for loading the image. */
+const DOWNLOAD_BYTES_PER_SECOND = 8_000_000
+/** Measured on a real PC: 3.2 s for the 323 MB archive, so about 5 s plus 150 MB/s. */
+const LOAD_BYTES_PER_SECOND = 150_000_000
+const LOAD_FIXED_SECONDS = 5
+
+const BLOCKED: Partial<Record<WslcReadiness['state'], WslcSetupBlock>> = {
+	unsupported: 'unsupported',
+	'blocked-by-policy': 'blocked-by-policy',
+	'virtualization-off': 'virtualization-off',
+	'sdk-mismatch': 'sdk-mismatch',
+}
+
+/** JSON with sorted keys, so equal plans digest equally. */
+function canonical(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
+	if (typeof value === 'object' && value !== null) {
+		const entries = Object.entries(value as Record<string, unknown>)
+			.filter(([, v]) => v !== undefined)
+			.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+		return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(',')}}`
+	}
+	return JSON.stringify(value)
+}
+
+/**
+ * Turn what a readiness inspection found into the steps that fix it. Pure: the
+ * same facts give the same plan and the same id. Steps come from the facts, not
+ * only from the headline state.
+ */
+export const planWslcSetup: PlanWslcSetup = (readiness, options) => {
+	const pinned = options.wslPackage ?? PINNED_WSL_PACKAGE
+	const manifest = options.manifest
+	const finish = (steps: WslcSetupStep[], blocked?: WslcSetupBlock): WslcSetupPlan => {
+		const id = createHash('sha256')
+			.update(
+				canonical({
+					state: readiness.state,
+					steps,
+					blocked,
+					wslVersion: pinned.version,
+					manifest: manifest?.sha256 ?? null,
+				}),
+			)
+			.digest('hex')
+		return {
+			id,
+			state: readiness.state,
+			steps,
+			elevationPrompts: steps.some((step) => step.elevated) ? 1 : 0,
+			mayRequireRestart: steps.some((step) => step.mayRequireRestart),
+			...(blocked ? { blocked } : {}),
+		}
+	}
+
+	const blocked = BLOCKED[readiness.state]
+	if (blocked) return finish([], blocked)
+	if (readiness.state === 'ready') return finish([])
+
+	const hasImage = readiness.image.bundled !== undefined || manifest !== undefined
+	const loadImage = (): WslcSetupStep => ({
+		kind: 'load-image',
+		elevated: false,
+		...(manifest ? { diskBytes: manifest.sizeBytes } : {}),
+		estimatedSeconds: manifest
+			? LOAD_FIXED_SECONDS + Math.ceil(manifest.compressedBytes / LOAD_BYTES_PER_SECOND)
+			: 60,
+		mayRequireRestart: false,
+	})
+	const needImage = !readiness.image.loaded
+
+	if (readiness.state === 'restart-pending') {
+		const steps: WslcSetupStep[] = [
+			{
+				kind: 'restart',
+				elevated: false,
+				estimatedSeconds: RESTART_SECONDS,
+				mayRequireRestart: true,
+			},
+		]
+		if (needImage) {
+			if (!hasImage) return finish([], 'image-unavailable')
+			steps.push(loadImage())
+		}
+		return finish(steps)
+	}
+
+	const wslcVersion = readiness.wsl.wslcVersion
+	const needWsl = wslcVersion === undefined || !wslcAtLeastMinimum(wslcVersion)
+	const needFeatures =
+		readiness.components.virtualMachinePlatform === false ||
+		readiness.components.wslOptionalComponent === false
+
+	if (needImage && !hasImage) return finish([], 'image-unavailable')
+
+	const steps: WslcSetupStep[] = []
+	if (needWsl)
+		steps.push({
+			kind: 'download-wsl',
+			elevated: false,
+			downloadBytes: pinned.sizeBytes,
+			diskBytes: pinned.sizeBytes,
+			estimatedSeconds: Math.ceil(pinned.sizeBytes / DOWNLOAD_BYTES_PER_SECOND),
+			mayRequireRestart: false,
+		})
+	if (needFeatures)
+		steps.push({
+			kind: 'enable-windows-features',
+			elevated: true,
+			estimatedSeconds: ENABLE_FEATURES_SECONDS,
+			mayRequireRestart: true,
+		})
+	if (needWsl)
+		steps.push({
+			kind: 'install-wsl',
+			elevated: true,
+			estimatedSeconds: INSTALL_WSL_SECONDS,
+			mayRequireRestart: true,
+		})
+	if (needFeatures)
+		steps.push({
+			kind: 'restart',
+			elevated: false,
+			estimatedSeconds: RESTART_SECONDS,
+			mayRequireRestart: true,
+		})
+	if (needImage) steps.push(loadImage())
+	return finish(steps)
+}