agent-dev-env 0.1.0-canary.2.fbbd044

package/dist/lifecycle/build-macos.js

@@ -0,0 +1,23 @@
+// build-macos.ts — the macOS build flow: the plain `packer init` +
+// `packer build -var-file` path of scripts/build.sh's fallback (no
+// staging, no swtpm — the tart plugin owns the VM under ~/.tart/vms/).
+import { logger } from '../lib/logger.js';
+import { announceBuild, materializeContext, requireCmd, runPackerBuild, runPackerInit, } from './build-shared.js';
+/** Builds a macOS image with Packer.
+ *
+ * @param image - The catalog image.
+ * @param options - Force/watchdog overrides.
+ */
+export async function buildMacosImage(image, options) {
+    requireCmd('packer', 'brew install packer');
+    const context = materializeContext(image);
+    announceBuild(image, context);
+    await runPackerInit(context.templateFile);
+    await runPackerBuild({
+        platformDir: context.platformDir,
+        templateFile: context.templateFile,
+        varsFile: image.varsFile,
+        force: options.force,
+    });
+    logger.ok(`Done: ${image.name}`);
+}

package/dist/lifecycle/build-qemu.js

@@ -0,0 +1,204 @@
+// build-qemu.ts — the windows-qemu build flow: the port of
+// images/windows-arm64-qemu/build.sh (ISO + virtio-win staging, swtpm,
+// the watchdog, the packer pipeline with qemu-with-tpm.sh, zstd
+// compression). Failures throw; a kink in the shell flow is the bare
+// start_watchdog call (a missing vncdotool aborts the build under set
+// -e) — the CLI warn+skips like the VMware wrappers do.
+import { cpSync, existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { isAlive, readPidFile, run, runChecked, sleep } from '../lib/exec.js';
+import { logger } from '../lib/logger.js';
+import { announceBuild, buildDirLayout, ensureCacheDir, materializeContext, qemuImgCompressArgs, requireAppleSilicon, requireCommands, requireWindowsIso, runPackerBuild, runPackerFmtCheck, runPackerInit, stringVar, swtpmArgs, verifyIsoSha256, } from './build-shared.js';
+import { startBuildWatchdog, stopBuildWatchdog } from './build-watchdog.js';
+/** The virtio drivers staged into the unattend CD (viostor = boot disk,
+ *  vioscsi belt-and-braces, NetKVM = the NIC, viogpudo = display). */
+const WINPE_DRIVERS = ['viostor', 'vioscsi', 'NetKVM', 'viogpudo'];
+/** Builds a windows-qemu image.
+ *
+ * @param image - The catalog image.
+ * @param options - Force/watchdog overrides.
+ */
+export async function buildQemuImage(image, options) {
+    requireAppleSilicon('the Windows image can only be built on Apple Silicon (QEMU + HVF).');
+    requireCommands([
+        ['packer', 'brew install packer'],
+        ['qemu-system-aarch64', 'brew install qemu'],
+        ['qemu-img', 'brew install qemu'],
+        ['swtpm', 'brew install swtpm'],
+        ['curl', 'comes with macOS'],
+        ['hdiutil', 'comes with macOS'],
+        ['xmllint', 'comes with macOS'],
+    ]);
+    const dirs = buildDirLayout('windows-qemu');
+    ensureCacheDir(dirs.cache);
+    const context = materializeContext(image);
+    announceBuild(image, context);
+    const { winIso, virtioIso } = await prepareQemuInputs(image, dirs);
+    const swtpm = await startSwtpm(dirs.cache);
+    await runQemuPacker(image, options, dirs, context, { winIso, virtioIso, swtpm });
+    await compressQemuOutput(dirs.output, image.name);
+}
+/** Windows ISO + virtio-win.iso verification and driver staging. */
+async function prepareQemuInputs(image, dirs) {
+    const winIso = requireWindowsIso(image);
+    await verifyIsoSha256(winIso, stringVar(image, 'iso_sha256'), 'Windows ISO', image.varsFile);
+    const virtioIso = await requireVirtioWinIso(image, dirs.cache);
+    await stageVirtioDrivers(virtioIso, dirs.staging);
+    return { winIso, virtioIso };
+}
+/** The watchdog + packer pipeline (xmllint/init/fmt/build), with the
+ *  watchdog and swtpm torn down afterwards. */
+async function runQemuPacker(image, options, dirs, context, inputs) {
+    let watchdogPid;
+    if (options.watchdog !== false) {
+        watchdogPid = await startBuildWatchdog({ cacheDir: dirs.cache });
+    }
+    try {
+        await runXmllint(context.platformDir);
+        await runPackerInit(context.templateFile);
+        await runPackerFmtCheck(context.platformDir);
+        await runPackerBuild({
+            platformDir: context.platformDir,
+            templateFile: context.templateFile,
+            varsFile: image.varsFile,
+            buildDir: dirs.build,
+            force: options.force,
+            env: {
+                SWTPM_SOCK: inputs.swtpm.sock,
+                VIRTIO_WIN_ISO_PATH: inputs.virtioIso,
+                QEMU_WITH_TPM_LOG: join(dirs.cache, 'qemu-with-tpm.cmd.log'),
+                PKR_VAR_iso_path: inputs.winIso,
+                PKR_VAR_virtio_win_iso_path: inputs.virtioIso,
+                PKR_VAR_qemu_binary: join(context.platformDir, 'qemu-with-tpm.sh'),
+            },
+        });
+    }
+    finally {
+        await stopBuildWatchdog(watchdogPid);
+        await stopSwtpm(inputs.swtpm.pidFile);
+    }
+}
+/** Resolution of virtio-win.iso: the env override, or a cached download
+ *  from the vars file's virtio_win_url.
+ *
+ * @param image - The catalog image.
+ * @param cacheDir - The build cache dir.
+ * @returns The virtio-win.iso path.
+ */
+async function requireVirtioWinIso(image, cacheDir) {
+    const cachedPath = join(cacheDir, 'virtio-win.iso');
+    const path = process.env.VIRTIO_WIN_ISO_PATH ?? cachedPath;
+    if (!process.env.VIRTIO_WIN_ISO_PATH) {
+        logger.step('VIRTIO_WIN_ISO_PATH unset — downloading virtio-win.iso');
+        if (existsSync(cachedPath)) {
+            logger.info(`already cached: ${cachedPath}`);
+        }
+        else {
+            const url = stringVar(image, 'virtio_win_url');
+            if (!url) {
+                throw new Error(`virtio_win_url is empty in ${image.varsFile}`);
+            }
+            await runChecked('curl', ['-fSL', '-o', cachedPath, url]);
+        }
+        await verifyIsoSha256(cachedPath, stringVar(image, 'virtio_win_sha256') ?? '', 'virtio-win.iso', image.varsFile, `Delete ${cachedPath} and rebuild, or update virtio_win_sha256 in ${image.varsFile}.`);
+    }
+    if (!existsSync(path)) {
+        throw new Error(`VIRTIO_WIN_ISO_PATH points to a file that does not exist:\n       ${path}`);
+    }
+    return path;
+}
+/** Extracts the ARM64 drivers from virtio-win.iso (hdiutil) into the
+ *  staging dir; a failed/missing build still detaches the mount.
+ *
+ * @param virtioIso - The virtio-win.iso path.
+ * @param stagingDir - The staging dir.
+ */
+async function stageVirtioDrivers(virtioIso, stagingDir) {
+    const mountDir = mkdtempSync(join(tmpdir(), 'agent-dev-env-virtio-win.'));
+    const missing = [];
+    logger.step(`mounting ${basename(virtioIso)}`);
+    try {
+        await runChecked('hdiutil', [
+            'attach',
+            '-nobrowse',
+            '-readonly',
+            '-mountpoint',
+            mountDir,
+            virtioIso,
+        ]);
+        rmSync(stagingDir, { recursive: true, force: true });
+        mkdirSync(stagingDir, { recursive: true });
+        for (const driver of WINPE_DRIVERS) {
+            const src = join(mountDir, driver, 'w11', 'ARM64');
+            if (!existsSync(src)) {
+                missing.push(driver);
+                continue;
+            }
+            cpSync(src, join(stagingDir, driver), { recursive: true });
+        }
+    }
+    finally {
+        await run('hdiutil', ['detach', mountDir, '-quiet']);
+        rmSync(mountDir, { recursive: true, force: true });
+    }
+    if (missing.length > 0) {
+        throw new Error('ARM64 driver tree missing from virtio-win.iso for:\n' +
+            `       ${missing.join(' ')}\n` +
+            '       Expected <driver>/w11/ARM64/ to exist. Your virtio-win.iso\n' +
+            '       may pre-date 0.1.240 (the first release with ARM64 builds).');
+    }
+}
+/** Runs swtpm as a daemon and waits for its Unix socket. */
+async function startSwtpm(cacheDir) {
+    const swtpmDir = join(cacheDir, 'swtpm');
+    const sock = join(swtpmDir, 'sock');
+    const pidFile = join(swtpmDir, 'pid');
+    mkdirSync(swtpmDir, { recursive: true });
+    rmSync(sock, { force: true });
+    rmSync(pidFile, { force: true });
+    rmSync(join(swtpmDir, 'tpm2-00.permall'), { recursive: true, force: true });
+    logger.step('starting swtpm (TPM 2.0 emulator)');
+    await runChecked('swtpm', swtpmArgs(swtpmDir, sock, pidFile));
+    await sleep(1000);
+    if (!existsSync(sock)) {
+        throw new Error(`swtpm socket ${sock} did not appear.\n       Check ${swtpmDir}/log.`);
+    }
+    return { pidFile, sock };
+}
+/** Kills swtpm by its pid file and removes the pid file. */
+async function stopSwtpm(pidFile) {
+    const pid = readPidFile(pidFile);
+    if (pid !== undefined && isAlive(pid)) {
+        try {
+            process.kill(pid);
+        }
+        catch {
+            // already gone
+        }
+    }
+    rmSync(pidFile, { force: true });
+}
+/** zstd-compresses the built qcow2 and prints its info lines. */
+async function compressQemuOutput(outputDir, imageName) {
+    const output = join(outputDir, `${imageName}.qcow2`);
+    if (!existsSync(output)) {
+        throw new Error(`build produced no ${output}`);
+    }
+    logger.step(`compressing ${output} (zstd)`);
+    await runChecked('qemu-img', qemuImgCompressArgs(output));
+    renameSync(`${output}.tmp`, output);
+    const info = await run('qemu-img', ['info', output]);
+    for (const line of info.stdout.split('\n')) {
+        if (/virtual size|disk size/.test(line)) {
+            logger.info(line);
+        }
+    }
+    logger.ok(`Done: ${output}`);
+}
+/** `xmllint --noout` on the unattend seed (catches XML typos early). */
+async function runXmllint(platformDir) {
+    logger.step('xmllint autounattend.xml');
+    await runChecked('xmllint', ['--noout', join(platformDir, 'autounattend.xml')]);
+}

package/dist/lifecycle/build-shared.js

@@ -0,0 +1,355 @@
+// build-shared.ts — helpers shared by the per-platform build flows (the
+// port of scripts/build.sh plus the three images/*/build.sh wrappers):
+// host prereqs, the build-dir layout, ISO hash verification, the
+// materialized Packer context, the packer pipeline (init / fmt -check /
+// build), and the pure arg builders the wrappers inline (swtpm,
+// qemu-img, unzip, the Ubuntu seed + grub command).
+//
+// Failures throw (the CLI's top level turns them into die()); helpers
+// keep the shell's exact error wording.
+import { chmodSync, cpSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { commandExists, run, runChecked } from '../lib/exec.js';
+import { logger } from '../lib/logger.js';
+import { buildDir, paths } from '../lib/paths.js';
+import { upgradeVmHardware, vmwareHwVersion } from '../lib/vmrun.js';
+import { varsFor } from './catalog.js';
+/** The build dirs for a platform.
+ *
+ * @param platform - The platform id.
+ * @returns The layout (build/output/cache/staging paths).
+ */
+export function buildDirLayout(platform) {
+    const build = buildDir(platform);
+    return {
+        build,
+        output: join(build, 'output'),
+        cache: join(build, 'packer_cache'),
+        staging: join(build, 'drivers', 'staging'),
+    };
+}
+/** Host check: macOS Apple Silicon (QEMU/VMware cannot virtualize ARM64
+ *  guests on Intel Macs).
+ *
+ * @returns True on an Apple Silicon Mac.
+ */
+function hostIsAppleSilicon() {
+    return process.platform === 'darwin' && process.arch === 'arm64';
+}
+/** Dies with the platform's message when the host is not Apple Silicon.
+ *
+ * @param message - The platform-specific error message.
+ */
+export function requireAppleSilicon(message) {
+    if (!hostIsAppleSilicon()) {
+        throw new Error(message);
+    }
+}
+/** `command -v` check with the shell's install hint.
+ *
+ * @param command - The command name.
+ * @param hint - The install hint (brew install … / comes with macOS).
+ */
+export function requireCmd(command, hint) {
+    if (!commandExists(command)) {
+        throw new Error(`required command '${command}' not found on PATH.\n       Install with: ${hint}`);
+    }
+}
+/** Runs requireCmd for each [command, hint] pair.
+ *
+ * @param checks - The command/hint pairs to check.
+ */
+export function requireCommands(checks) {
+    for (const [command, hint] of checks) {
+        requireCmd(command, hint);
+    }
+}
+/** Reads a quoted-string variable from the image's vars file.
+ *
+ * @param image - The catalog image.
+ * @param name - The variable name.
+ * @returns The value, or undefined when absent/not a string.
+ */
+export function stringVar(image, name) {
+    const value = varsFor(image)[name];
+    return typeof value === 'string' ? value : undefined;
+}
+/** @internal — test-only export of the digest normalizer.
+ *
+ * @param raw - The digest as written.
+ * @returns The normalized digest (lowercase, no whitespace).
+ */
+export function normalizeSha(raw) {
+    return raw.toLowerCase().replace(/\s+/g, '');
+}
+/** SHA256 of a file (shasum -a 256), normalized.
+ *
+ * @param file - The file to hash.
+ * @returns The lowercase hex digest.
+ */
+async function sha256Of(file) {
+    const res = await run('shasum', ['-a', '256', file]);
+    if (res.code !== 0) {
+        throw new Error(`shasum failed: ${res.stderr.trim() || res.stdout.trim()}`);
+    }
+    return normalizeSha(res.stdout.split(/\s+/)[0] ?? '');
+}
+/** Verifies a file against its vars-file sha256 (warns and skips when the
+ *  expected digest is empty, matching the wrappers' behavior).
+ *
+ * @param file - The file to verify.
+ * @param expected - The expected digest (empty = skip).
+ * @param label - The digest context label (e.g. "Windows ISO").
+ * @param varsFile - The vars file (for the error message).
+ * @param failureNote - Optional custom failure hint.
+ */
+export async function verifyIsoSha256(file, expected, label, varsFile, failureNote) {
+    logger.step(`verifying SHA256 of ${basename(file)}`);
+    const want = normalizeSha(expected ?? '');
+    if (!want) {
+        logger.warn(`iso_sha256 is empty in ${varsFile} — skipping ISO verification.`);
+        return;
+    }
+    const got = await sha256Of(file);
+    if (got !== want) {
+        const note = failureNote ?? `Re-download the ISO or update iso_sha256 in ${varsFile}.`;
+        throw new Error(`SHA256 mismatch for the ${label}.\n` + `  expected: ${want}\n  actual:   ${got}\n  ${note}`);
+    }
+}
+/** Copies the image's platform dir into <data>/build-context/ so the
+ *  packed context is writable and self-contained (npm installs cannot
+ *  run builds from the read-only package snapshot), chmod'ing the
+ *  qemu-with-tpm.sh wrapper on demand.
+ *
+ * @param image - The catalog image.
+ * @param options - data-root override (tests).
+ * @returns The materialized context (platform dir + template).
+ */
+export function materializeContext(image, options = {}) {
+    const platformDir = dirname(dirname(image.varsFile));
+    const contextRoot = join(options.dataRoot ?? paths.data, 'build-context', basename(platformDir));
+    rmSync(contextRoot, { recursive: true, force: true });
+    cpSync(platformDir, contextRoot, { recursive: true });
+    chmodQemuWrapper(contextRoot);
+    return { platformDir: contextRoot, templateFile: findTemplateFile(contextRoot) };
+}
+/** chmod +x the qemu-with-tpm.sh wrapper (packer execs it as the qemu
+ *  binary; a copied context may lose the mode).
+ *
+ * @param contextRoot - The materialized platform dir.
+ */
+function chmodQemuWrapper(contextRoot) {
+    const qemu = join(contextRoot, 'qemu-with-tpm.sh');
+    if (existsSync(qemu)) {
+        chmodSync(qemu, 0o755);
+    }
+}
+/** @internal — the first *.pkr.hcl template in the platform dir
+ *  (test-only export; also used by materializeContext).
+ *
+ * @param platformDir - The platform dir.
+ * @returns The template path.
+ * @throws Error when no template exists (shell parity).
+ */
+export function findTemplateFile(platformDir) {
+    const templates = readdirSync(platformDir)
+        .filter((entry) => entry.endsWith('.pkr.hcl'))
+        .sort();
+    if (templates.length === 0) {
+        throw new Error(`No Packer template (*.pkr.hcl) found in ${platformDir}`);
+    }
+    return join(platformDir, templates[0]);
+}
+/** Logs the legacy per-image build header.
+ *
+ * @param image - The image being built.
+ * @param context - The materialized context.
+ */
+export function announceBuild(image, context) {
+    logger.title(`Building image: ${image.name}`);
+    logger.info(`Using template: ${context.templateFile}`);
+    logger.info(`Using vars: ${image.varsFile}`);
+}
+/** `packer init <template>` (installs required plugins).
+ *
+ * @param templateFile - The template to init.
+ */
+export async function runPackerInit(templateFile) {
+    logger.step('packer init');
+    await runChecked('packer', ['init', templateFile]);
+}
+/** `packer fmt -check` — warns (does not fail) when formatting differs.
+ *
+ * @param platformDir - The dir to format-check.
+ */
+export async function runPackerFmtCheck(platformDir) {
+    logger.step('packer fmt -check');
+    const res = await run('packer', ['fmt', '-check', platformDir]);
+    if (res.code !== 0) {
+        logger.warn(`'packer fmt' would change formatting. Run 'packer fmt ${platformDir}' to fix.`);
+    }
+}
+/** `packer build [-force] [-var build_dir=…] -var-file=… <template>`.
+ *
+ * @param options - The build options.
+ */
+export async function runPackerBuild(options) {
+    logger.step('packer build');
+    const args = ['build'];
+    if (options.force) {
+        args.push('-force');
+    }
+    if (options.buildDir) {
+        args.push('-var', `build_dir=${options.buildDir}`);
+    }
+    args.push('-var-file', options.varsFile, options.templateFile);
+    await runChecked('packer', args, { cwd: options.platformDir, env: options.env });
+}
+/** The human size of a path (`du -sh`).
+ *
+ * @param path - The path to measure.
+ * @returns The size string (e.g. "12G"), or '' when du fails.
+ */
+export async function duHuman(path) {
+    const res = await run('du', ['-sh', path]);
+    if (res.code !== 0) {
+        return '';
+    }
+    return res.stdout.trim().split(/\s+/)[0] ?? '';
+}
+/** swtpm invocation (TPM 2.0 emulator, Unix socket control).
+ *
+ * @param tpmDir - The tpmstate dir.
+ * @param sockPath - The control socket path.
+ * @param pidFile - The pid file swtpm writes.
+ * @returns The swtpm argv.
+ */
+export function swtpmArgs(tpmDir, sockPath, pidFile) {
+    return [
+        'socket',
+        '--tpmstate',
+        `dir=${tpmDir}`,
+        '--ctrl',
+        `type=unixio,path=${sockPath}`,
+        '--log',
+        `file=${join(tpmDir, 'log')},level=20`,
+        '--pid',
+        `file=${pidFile}`,
+        '--tpm2',
+        '--daemon',
+    ];
+}
+/** qemu-img zstd conversion of the built qcow2.
+ *
+ * @param output - The qcow2 to compress.
+ * @returns The qemu-img argv (tmp output, renamed by the caller).
+ */
+export function qemuImgCompressArgs(output) {
+    return ['convert', '-c', '-O', 'qcow2', '-o', 'compression_type=zstd', output, `${output}.tmp`];
+}
+/** The vmxnet3 ARM64 driver extraction (flat, at the CD root).
+ *
+ * @param driversZip - Fusion's drivers-arm64.zip.
+ * @param stagingDir - The staging dir.
+ * @returns The unzip argv.
+ */
+export function unzipVmxnet3Args(driversZip, stagingDir) {
+    return [
+        '-jo',
+        driversZip,
+        'vmxnet3/Win10_1709/ARM64/vmxnet3.cat',
+        'vmxnet3/Win10_1709/ARM64/vmxnet3.inf',
+        'vmxnet3/Win10_1709/ARM64/vmxnet3.sys',
+        '-d',
+        stagingDir,
+    ];
+}
+/** The vmnet8 NAT subnet from Fusion's dhcpd.conf
+ *  (`subnet x.y.z.0 netmask …`).
+ *
+ * @param content - The dhcpd.conf content.
+ * @returns The subnet, or undefined when not found.
+ */
+export function vmnet8SubnetFromDhcpConf(content) {
+    for (const line of content.split('\n')) {
+        const match = line.match(/^subnet ([0-9.]+) netmask/);
+        if (match) {
+            return match[1];
+        }
+    }
+    return undefined;
+}
+/** The grub autoinstall command the watchdog types (WATCH_BUILD_BOOT_CMD;
+ *  `\;` escapes the grub command splitter).
+ *
+ * @param natHost - The vmnet8 host address (x.y.z.1).
+ * @param seedPort - The seed server port.
+ * @returns The multi-line grub command.
+ */
+export function watchdogBootCommand(natHost, seedPort) {
+    return (`linux /casper/vmlinuz autoinstall ds=nocloud-net\\;s=http://${natHost}:${seedPort}/ ---\n` +
+        'initrd /casper/initrd\n' +
+        'boot');
+}
+/** Ensures the cache dir exists (never the output dir — packer owns it).
+ *
+ * @param cacheDir - The per-platform packer_cache dir.
+ */
+export function ensureCacheDir(cacheDir) {
+    mkdirSync(cacheDir, { recursive: true });
+}
+/** The bring-your-own Windows ISO (WINDOWS_ISO_PATH).
+ *
+ * @param image - The catalog image (vars file for the error message).
+ * @returns The ISO path.
+ */
+export function requireWindowsIso(image) {
+    const winIso = process.env.WINDOWS_ISO_PATH;
+    if (!winIso) {
+        throw new Error('WINDOWS_ISO_PATH is not set.\n' +
+            '       Download the Windows 11 ARM64 ISO from\n' +
+            '       https://www.microsoft.com/software-download/windows11arm64,\n' +
+            '       then set WINDOWS_ISO_PATH to its absolute path.\n' +
+            '       Paste the SHA256 from the download page into iso_sha256 in\n' +
+            `       ${image.varsFile} to enable integrity verification.`);
+    }
+    if (!existsSync(winIso)) {
+        throw new Error(`WINDOWS_ISO_PATH points to a file that does not exist:\n       ${winIso}`);
+    }
+    return winIso;
+}
+/** Upgrades a built vmx to the host Fusion's hardware version (vmrun
+ *  upgradevm never exits — the 180 s cap lives in upgradeVmHardware).
+ *
+ * @param vmx - The built vmx.
+ * @param fusionPath - The Fusion app path (vmrun resolution).
+ */
+export async function upgradeArtifactHardware(vmx, fusionPath) {
+    const env = { FUSION_APP_PATH: fusionPath };
+    const before = vmwareHwVersion(vmx);
+    let after;
+    try {
+        after = await upgradeVmHardware(vmx, { env });
+    }
+    catch (err) {
+        logger.warn(`${err.message} — cannot upgrade the build output; a GUI start may prompt once.`);
+        return;
+    }
+    if (before && after && after !== before) {
+        logger.step(`build output upgraded to hardware version ${after}`);
+    }
+    else {
+        logger.step(`build output hardware version: ${after ?? 'unknown'}`);
+    }
+}
+/** `du -sh` of the build output dir (the legacy "==> build output" log).
+ *
+ * @param outputDir - The output dir to report.
+ */
+export async function reportOutputDir(outputDir) {
+    logger.step('build output');
+    const size = await duHuman(outputDir);
+    if (size) {
+        logger.info(`${outputDir} (${size})`);
+    }
+}