@namzu/sandbox 24.0.0 → 26.0.0

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

@@ -0,0 +1,386 @@
+import { stat } from 'node:fs/promises'
+import {
+	LocalCommandError,
+	type LocalComputerCommandRunner,
+	LocalComputerSetupError,
+} from '../engine.js'
+import { WSLC_MINIMUM_VERSION, mapWslcFailure, parseWslcVersion } from '../wslc-engine.js'
+import type {
+	InspectWslcReadiness,
+	WslcReadiness,
+	WslcReadinessState,
+	WslcSetupHost,
+	WslcUnsupportedReason,
+} from './contract.js'
+import { createWslcSetupHost } from './host.js'
+import { PROBE_LIMIT_MS, ProbeTimeoutError, runLimited } from './limits.js'
+import { clearRestartMarker, markerPath, readRestartMarker } from './restart.js'
+import {
+	archivePathOf,
+	parseImageInspect,
+	readImageRecord,
+	readManifest,
+	wslcBinaryOf,
+} from './wslc-shared.js'
+
+const POLICY_KEY = 'HKLM\\Software\\Policies\\WSL'
+/** Windows' own pending-restart markers; both can be read without administrator rights. */
+const PENDING_RESTART_KEYS = [
+	'HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Component Based Servicing\\RebootPending',
+	'HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\WindowsUpdate\\Auto Update\\RebootRequired',
+] as const
+const MINIMUM_BUILD = 19041
+const WINDOWS_11_BUILD = 22000
+
+/** `wsl.exe --version` is UTF-16LE and localised: strip NULs, never read a label. */
+export function parseWslVersion(output: string): string | undefined {
+	const text = output.replace(/\0/g, '').replace(/^/, '')
+	const firstLine = text.split(/\r?\n/).find((line) => line.trim() !== '') ?? ''
+	return /\d+\.\d+\.\d+\.\d+/.exec(firstLine)?.[0]
+}
+
+export function wslcAtLeastMinimum(version: string): boolean {
+	const parts = version.split('.').map(Number)
+	for (let i = 0; i < WSLC_MINIMUM_VERSION.length; i++) {
+		const found = parts[i] ?? 0
+		const floor = WSLC_MINIMUM_VERSION[i] ?? 0
+		if (found !== floor) return found > floor
+	}
+	return true
+}
+
+/** 1060 is "service does not exist"; any other failure leaves it unknown. */
+async function serviceExists(
+	runner: LocalComputerCommandRunner,
+	name: string,
+	signal: AbortSignal | undefined,
+): Promise<boolean | 'unknown'> {
+	try {
+		await runLimited(runner, 'sc.exe', ['query', name], PROBE_LIMIT_MS.command, { signal })
+		return true
+	} catch (error) {
+		signal?.throwIfAborted()
+		if (error instanceof LocalCommandError && /\(1060\)/.test(error.message)) return false
+		return 'unknown'
+	}
+}
+
+async function hypervisorPresent(
+	runner: LocalComputerCommandRunner,
+	signal: AbortSignal | undefined,
+): Promise<boolean | 'unknown'> {
+	try {
+		const output = await runLimited(
+			runner,
+			'powershell.exe',
+			[
+				'-NoProfile',
+				'-NonInteractive',
+				'-Command',
+				'(Get-CimInstance Win32_ComputerSystem).HypervisorPresent',
+			],
+			PROBE_LIMIT_MS.powershell,
+			{ signal },
+		)
+		const answer = output.trim().toLowerCase()
+		if (answer === 'true') return true
+		if (answer === 'false') return false
+		return 'unknown'
+	} catch {
+		signal?.throwIfAborted()
+		return 'unknown'
+	}
+}
+
+async function wslVersionOf(
+	runner: LocalComputerCommandRunner,
+	signal: AbortSignal | undefined,
+): Promise<string | undefined> {
+	try {
+		return parseWslVersion(
+			await runLimited(runner, 'wsl.exe', ['--version'], PROBE_LIMIT_MS.command, { signal }),
+		)
+	} catch {
+		signal?.throwIfAborted()
+		return undefined
+	}
+}
+
+async function wslcVersionOf(
+	runner: LocalComputerCommandRunner,
+	binary: string,
+	signal: AbortSignal | undefined,
+): Promise<string | undefined> {
+	try {
+		const parsed = parseWslcVersion(
+			await runLimited(runner, binary, ['version'], PROBE_LIMIT_MS.command, { signal }),
+		)
+		return parsed?.join('.')
+	} catch (error) {
+		signal?.throwIfAborted()
+		// Without an answer there is no telling "not installed" from "slow": the
+		// state cannot be decided, so say so rather than plan an install.
+		if (error instanceof ProbeTimeoutError) throw couldNotCheck(error)
+		return undefined
+	}
+}
+
+/** A policy value; a read that did not answer in time cannot be taken as "not set". */
+async function readPolicy(host: WslcSetupHost, name: string): Promise<number | undefined> {
+	try {
+		return await host.readDword(POLICY_KEY, name)
+	} catch (error) {
+		if (error instanceof ProbeTimeoutError) throw couldNotCheck(error)
+		throw error
+	}
+}
+
+/** The state cannot be decided: a plain message the CLI and Desktop show with Details. */
+function couldNotCheck(cause: unknown): LocalComputerSetupError {
+	return new LocalComputerSetupError(
+		'Linux container support did not answer, so Namzu could not check this PC. Try again in a moment.',
+		undefined,
+		{ cause },
+	)
+}
+
+/**
+ * Windows' own markers that a restart is pending. A marker that cannot be
+ * read is neither set nor clear: say so, because guessing "clear" would send a
+ * PC that only needs a restart to the firmware settings.
+ */
+async function windowsWantsRestart(host: WslcSetupHost): Promise<boolean | 'unknown'> {
+	let unknown = false
+	for (const key of PENDING_RESTART_KEYS) {
+		const set = await host.keyExists(key)
+		if (set === true) return true
+		if (set === 'unknown') unknown = true
+	}
+	return unknown ? 'unknown' : false
+}
+
+async function bundledOf(
+	manifestPath: string | undefined,
+): Promise<{ manifestPath: string; archivePath: string; imageId: string } | undefined> {
+	if (manifestPath === undefined) return undefined
+	try {
+		const manifest = await readManifest(manifestPath)
+		const archivePath = archivePathOf(manifestPath, manifest)
+		await stat(archivePath)
+		return { manifestPath, archivePath, imageId: manifest.imageId }
+	} catch {
+		return undefined
+	}
+}
+
+type ProbeResult =
+	| { readonly kind: 'loaded' | 'absent' }
+	| { readonly kind: 'state'; readonly state: WslcReadinessState }
+
+/** Start the session (wslc image inspect does) and see what answers. */
+async function probeImage(
+	host: WslcSetupHost,
+	binary: string,
+	ref: string,
+	expectedId: string | undefined,
+	signal: AbortSignal | undefined,
+): Promise<ProbeResult> {
+	try {
+		const output = await runLimited(
+			host.runner,
+			binary,
+			['image', 'inspect', '-f', 'json', ref],
+			PROBE_LIMIT_MS.session,
+			{ signal },
+		)
+		const found = parseImageInspect(output)
+		if (found === undefined) return { kind: 'absent' }
+		return expectedId === undefined || found.id === expectedId
+			? { kind: 'loaded' }
+			: { kind: 'absent' }
+	} catch (error) {
+		signal?.throwIfAborted()
+		const mapped = mapWslcFailure(error)
+		if (mapped?.code === 'virtualization-off') return { kind: 'state', state: 'virtualization-off' }
+		if (mapped?.code === 'blocked-by-policy') return { kind: 'state', state: 'blocked-by-policy' }
+		if (mapped?.code === 'sdk-mismatch') return { kind: 'state', state: 'sdk-mismatch' }
+		if (mapped?.code === 'image-missing') return { kind: 'absent' }
+		// A missing image makes the command exit non-zero with the not-found code
+		// or with a bare exit status 1 and no code (observed on wslc 3.0.1, where the PC answers
+		// "not found" and nothing else). A command that ran and failed with any
+		// other code, or did not start, is the engine failing.
+		if (
+			error instanceof LocalCommandError &&
+			(error.errorCodes.includes('WSLC_E_IMAGE_NOT_FOUND') ||
+				(error.errorCodes.length === 0 && error.exitCode === 1))
+		)
+			return { kind: 'absent' }
+		throw couldNotCheck(error)
+	}
+}
+
+/**
+ * Inspect the PC without changing anything. Without `probeSession` no command
+ * runs that starts the wslc session (`wslc version` does not; `ps` and `image`
+ * do), so opening a panel never starts a virtual machine.
+ */
+export const inspectWslcReadiness: InspectWslcReadiness = async (options) => {
+	const host = createWslcSetupHost(options.host)
+	const { signal } = options
+	const checkedAt = host.now().toISOString()
+	const bundled = await bundledOf(options.bundledManifestPath)
+	const bundledPaths = bundled
+		? { manifestPath: bundled.manifestPath, archivePath: bundled.archivePath }
+		: undefined
+	const base = {
+		policy: { allowWsl: true, allowWslContainer: true },
+		components: {
+			virtualMachinePlatform: 'unknown' as const,
+			wslOptionalComponent: 'unknown' as const,
+			hypervisorPresent: 'unknown' as const,
+		},
+		wsl: {},
+		image: {
+			ref: options.imageRef,
+			loaded: false,
+			...(bundledPaths ? { bundled: bundledPaths } : {}),
+		},
+		checkedAt,
+	}
+
+	let unsupported: WslcUnsupportedReason | undefined
+	if (host.platform !== 'win32') unsupported = 'platform'
+	else if (host.arch !== 'x64') unsupported = 'architecture'
+	else if (host.windowsBuild === undefined || host.windowsBuild < MINIMUM_BUILD)
+		unsupported = 'windows-build'
+	if (unsupported !== undefined || host.windowsBuild === undefined) {
+		return {
+			state: 'unsupported',
+			unsupportedReason: unsupported ?? 'windows-build',
+			...base,
+		}
+	}
+
+	const build = host.windowsBuild
+	const isWindows11 = build >= WINDOWS_11_BUILD
+	const binary = wslcBinaryOf(host)
+	const { runner } = host
+
+	const [
+		allowWsl,
+		allowContainer,
+		markerRead,
+		hns,
+		vmcompute,
+		lxss,
+		hypervisor,
+		wslVersion,
+		wslcVersion,
+	] = await Promise.all([
+		readPolicy(host, 'AllowWSL'),
+		readPolicy(host, 'AllowWSLContainer'),
+		readRestartMarker(host).then(
+			(marker) => ({ marker }),
+			() => ({ marker: undefined, unreadable: true as const }),
+		),
+		serviceExists(runner, 'HNS', signal),
+		serviceExists(runner, 'vmcompute', signal),
+		isWindows11
+			? Promise.resolve('not-needed' as const)
+			: serviceExists(runner, 'LxssManager', signal),
+		hypervisorPresent(runner, signal),
+		wslVersionOf(runner, signal),
+		wslcVersionOf(runner, binary, signal),
+	])
+
+	const policy = { allowWsl: allowWsl !== 0, allowWslContainer: allowContainer !== 0 }
+	const vmp: boolean | 'unknown' =
+		hns === false || vmcompute === false
+			? false
+			: hns === true && vmcompute === true
+				? true
+				: 'unknown'
+	const components = {
+		virtualMachinePlatform: vmp,
+		wslOptionalComponent: lxss,
+		hypervisorPresent: hypervisor,
+	}
+
+	let restart: WslcReadiness['restart']
+	let restartUnrecorded = false
+	const { marker } = markerRead
+	let recordedAt: string | undefined = marker?.recordedAt
+	if ('unreadable' in markerRead) {
+		// A marker that cannot be read still has a file date, and a restart since
+		// then ends it like any other. With no date either, the state cannot be
+		// decided: it reads as restart-pending with no record to compare against
+		// and no remaining steps, rather than failing the inspection.
+		try {
+			recordedAt = (await stat(markerPath(host.stateDirectory))).mtime.toISOString()
+		} catch {
+			restartUnrecorded = true
+		}
+	}
+	if (recordedAt !== undefined) {
+		let boot: Date | undefined
+		try {
+			boot = await host.bootTime()
+		} catch {
+			signal?.throwIfAborted()
+		}
+		if (boot === undefined) restart = { recordedAt }
+		else if (boot.getTime() > Date.parse(recordedAt)) {
+			try {
+				await clearRestartMarker(host)
+			} catch {
+				// A marker that stays is checked again next time; the PC has restarted.
+			}
+		} else restart = { recordedAt, bootTime: boot.toISOString() }
+	}
+
+	const wsl = {
+		...(wslVersion ? { version: wslVersion } : {}),
+		...(wslcVersion ? { wslcBinary: binary, wslcVersion } : {}),
+	}
+	const wslcUsable = wslcVersion !== undefined && wslcAtLeastMinimum(wslcVersion)
+
+	let loaded = false
+	if (options.probeSession !== true) {
+		const record = await readImageRecord(host)
+		loaded =
+			record !== undefined &&
+			record.imageRef === options.imageRef &&
+			(bundled === undefined || record.imageId === bundled.imageId)
+	}
+
+	const result = (state: WslcReadinessState, imageLoaded = loaded): WslcReadiness => ({
+		state,
+		windows: { build, architecture: 'x64', isWindows11 },
+		policy,
+		components,
+		wsl,
+		image: { ...base.image, loaded: imageLoaded },
+		...(restart ? { restart } : {}),
+		checkedAt,
+	})
+
+	if (!policy.allowWsl || !policy.allowWslContainer) return result('blocked-by-policy')
+	if (restart || restartUnrecorded) return result('restart-pending')
+	if (vmp === false || lxss === false) return result('platform-off')
+	if (!wslcUsable) return result(wslVersion ? 'wsl-outdated' : 'wsl-missing')
+	if (vmp === true && hypervisor === false && options.probeSession !== true) {
+		// Turning the platform on outside Namzu leaves no hypervisor until the PC
+		// restarts; Windows says so in its own markers. Only without one is it the
+		// firmware setting. With a probe the session's own failure decides.
+		const pending = await windowsWantsRestart(host)
+		if (pending === 'unknown') throw couldNotCheck(undefined)
+		return result(pending ? 'restart-pending' : 'virtualization-off')
+	}
+
+	if (options.probeSession === true) {
+		const probe = await probeImage(host, binary, options.imageRef, bundled?.imageId, signal)
+		if (probe.kind === 'state') return result(probe.state)
+		loaded = probe.kind === 'loaded'
+	}
+	return result(loaded ? 'ready' : 'image-missing', loaded)
+}

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

@@ -0,0 +1,50 @@
+import { LocalCommandError } from '../engine.js'
+
+/** Run `reg.exe` with these arguments and return what it printed. */
+export type RegistryRun = (args: readonly string[]) => Promise<string>
+
+function parentOf(key: string): string | undefined {
+	const cut = key.lastIndexOf('\\')
+	return cut > 0 ? key.slice(0, cut) : undefined
+}
+
+/**
+ * `reg query` exits 1 both for a key that is not there and for one the caller
+ * may not read, and its words are localised, so the exit status alone cannot
+ * tell them apart. Ask the parent instead: its listing of subkeys names the
+ * key in every language. When the parent is absent too, the same test climbs
+ * to the grandparent, and so on. A key an ancestor lists but the query cannot
+ * read is not absent, and neither is an ancestor that cannot be read or a
+ * climb that reaches a hive root without an answer.
+ *
+ * Returns the key's listing, or undefined when the key is provably absent.
+ * Anything else rethrows the failure.
+ */
+export async function queryRegistryKey(run: RegistryRun, key: string): Promise<string | undefined> {
+	try {
+		return await run(['query', key])
+	} catch (error) {
+		if (!(error instanceof LocalCommandError) || error.exitCode !== 1) throw error
+		const parent = parentOf(key)
+		if (parent === undefined) throw error
+		// The parent may itself be absent (no Windows Update key on an offline or
+		// managed image): walk up until an ancestor answers.
+		const listing = await queryRegistryKey(run, parent)
+		if (listing === undefined) return undefined
+		const leaf = key.slice(parent.length + 1).toLowerCase()
+		const listed = listing
+			.split(/\r?\n/)
+			.some((line) => line.trim().toLowerCase().endsWith(`\\${leaf}`))
+		if (listed) throw error
+		return undefined
+	}
+}
+
+/** True when a `reg query <key>` listing carries a value of this name. */
+export function listingHasValue(listing: string, name: string): boolean {
+	const wanted = name.toLowerCase()
+	return listing.split(/\r?\n/).some((line) => {
+		const match = /^\s+(.+?)\s+REG_[A-Z_]+(?:\s|$)/.exec(line)
+		return match?.[1]?.toLowerCase() === wanted
+	})
+}

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

@@ -0,0 +1,64 @@
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type {
+	ClearRestartMarker,
+	ReadRestartMarker,
+	WriteRestartMarker,
+	WslcRestartMarker,
+	WslcSetupStepKind,
+} from './contract.js'
+
+const STEP_KINDS: readonly WslcSetupStepKind[] = [
+	'download-wsl',
+	'enable-windows-features',
+	'install-wsl',
+	'restart',
+	'load-image',
+]
+
+export function markerPath(directory: string): string {
+	return join(directory, 'restart.json')
+}
+
+function parseMarker(text: string): WslcRestartMarker | undefined {
+	let value: unknown
+	try {
+		value = JSON.parse(text)
+	} catch {
+		return undefined
+	}
+	if (typeof value !== 'object' || value === null) return undefined
+	const { recordedAt, planId, remaining } = value as Record<string, unknown>
+	if (typeof recordedAt !== 'string' || Number.isNaN(Date.parse(recordedAt))) return undefined
+	if (typeof planId !== 'string' || !Array.isArray(remaining)) return undefined
+	if (!remaining.every((step) => STEP_KINDS.includes(step as WslcSetupStepKind))) return undefined
+	return { recordedAt, planId, remaining: remaining as WslcSetupStepKind[] }
+}
+
+/** The recorded restart, or undefined when absent or not one this code wrote. */
+export const readRestartMarker: ReadRestartMarker = async (host) => {
+	try {
+		return parseMarker(await readFile(markerPath(host.stateDirectory), 'utf8'))
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined
+		throw error
+	}
+}
+
+/** Temp file plus rename, so a reader never sees half a marker. */
+export const writeRestartMarker: WriteRestartMarker = async (host, marker) => {
+	await mkdir(host.stateDirectory, { recursive: true })
+	const target = markerPath(host.stateDirectory)
+	const temp = `${target}.${process.pid}.tmp`
+	await writeFile(temp, `${JSON.stringify(marker)}\n`, 'utf8')
+	try {
+		await rename(temp, target)
+	} catch (error) {
+		await rm(temp, { force: true })
+		throw error
+	}
+}
+
+export const clearRestartMarker: ClearRestartMarker = async (host) => {
+	await rm(markerPath(host.stateDirectory), { force: true })
+}

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

@@ -0,0 +1,65 @@
+import type { ClearResumeAtSignIn, RegisterResumeAtSignIn, WslcSetupHost } from './contract.js'
+import { listingHasValue, queryRegistryKey } from './registry.js'
+import { trustedWindowsDirectory } from './windows-folder.js'
+
+/** The registry value the resume command is stored under. */
+const RESUME_VALUE_NAME = 'NamzuPalComputerSetup'
+/** Windows runs a RunOnce command line of at most this many characters. */
+const MAX_COMMAND_LENGTH = 2048
+
+function regBinary(host: WslcSetupHost): string {
+	return `${trustedWindowsDirectory(host.env)}\\System32\\reg.exe`
+}
+
+function checkKey(key: string): void {
+	if (!/^HK(CU|LM|CR|U|CC)\\[^\r\n\0"]+$/.test(key)) {
+		throw new Error('The sign-in registry key is not a valid registry path.')
+	}
+}
+
+function checkCommand(command: string): void {
+	if (command.trim().length === 0) throw new Error('The sign-in command is empty.')
+	if (command.length > MAX_COMMAND_LENGTH) {
+		throw new Error(`The sign-in command is longer than ${MAX_COMMAND_LENGTH} characters.`)
+	}
+	if (/[\r\n\0]/.test(command)) {
+		throw new Error('The sign-in command must be a single line.')
+	}
+}
+
+/**
+ * Ask Windows to run `command` once at the next sign-in by writing the
+ * `NamzuPalComputerSetup` value (REG_SZ) under `host.resumeRegistryKey`. No
+ * administrator is needed for the default per-user key. Windows deletes a
+ * RunOnce value just before it runs it; writing the value again replaces it.
+ */
+export const registerResumeAtSignIn: RegisterResumeAtSignIn = async (host, command) => {
+	checkKey(host.resumeRegistryKey)
+	checkCommand(command)
+	await host.runner.run(regBinary(host), [
+		'add',
+		host.resumeRegistryKey,
+		'/v',
+		RESUME_VALUE_NAME,
+		'/t',
+		'REG_SZ',
+		'/d',
+		command,
+		'/f',
+	])
+}
+
+/**
+ * Take the command back. A value that is not there is not an error; a key
+ * that cannot be read is, because the command might still be registered.
+ */
+export const clearResumeAtSignIn: ClearResumeAtSignIn = async (host) => {
+	checkKey(host.resumeRegistryKey)
+	const reg = regBinary(host)
+	const listing = await queryRegistryKey(
+		(args) => host.runner.run(reg, [...args]),
+		host.resumeRegistryKey,
+	)
+	if (listing === undefined || !listingHasValue(listing, RESUME_VALUE_NAME)) return
+	await host.runner.run(reg, ['delete', host.resumeRegistryKey, '/v', RESUME_VALUE_NAME, '/f'])
+}