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

package/dist/lifecycle/build-ubuntu.js

@@ -0,0 +1,184 @@
+// build-ubuntu.ts — the ubuntu-vmware build flow: the port of
+// images/ubuntu-arm64-vmware/build.sh (the autoinstall seed server on a
+// fixed port, the vmnet8 subnet read for the watchdog's grub command,
+// the packer pipeline, the optional post-build hardware upgrade).
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { commandExists, isAlive, run, sleep, spawnDetached } from '../lib/exec.js';
+import { logger } from '../lib/logger.js';
+import { announceBuild, buildDirLayout, ensureCacheDir, materializeContext, reportOutputDir, requireAppleSilicon, requireCmd, runPackerBuild, runPackerFmtCheck, runPackerInit, stringVar, upgradeArtifactHardware, verifyIsoSha256, vmnet8SubnetFromDhcpConf, watchdogBootCommand, } from './build-shared.js';
+import { clearBootTypedMarker, startBuildWatchdog, stopBuildWatchdog } from './build-watchdog.js';
+const DEFAULT_FUSION_APP = '/Applications/VMware Fusion.app';
+/** The autoinstall seed port (pinned so the grub URL is known upfront). */
+const SEED_PORT = 8004;
+/** Fusion's vmnet8 DHCP config (the NAT subnet of the guest network). */
+const VMNET8_DHCP = '/Library/Preferences/VMware Fusion/vmnet8/dhcpd.conf';
+/** Builds an ubuntu-vmware image.
+ *
+ * @param image - The catalog image.
+ * @param options - Force/watchdog overrides.
+ */
+export async function buildUbuntuImage(image, options) {
+    requireAppleSilicon('the Ubuntu image can only be built on Apple Silicon (VMware\n' +
+        '       Fusion cannot run ARM64 guests on Intel Macs).');
+    requireCmd('packer', 'brew install packer');
+    const fusionPath = optionalFusionApp();
+    const dirs = buildDirLayout('ubuntu-vmware');
+    ensureCacheDir(dirs.cache);
+    const context = materializeContext(image);
+    announceBuild(image, context);
+    const iso = requireUbuntuIso(image);
+    await verifyIsoSha256(iso, stringVar(image, 'iso_sha256'), 'Ubuntu ISO', image.varsFile);
+    await runUbuntuPacker(image, options, dirs, context, iso);
+    await verifyUbuntuOutput(image, dirs, fusionPath);
+}
+/** The seed server + watchdog + packer pipeline (torn down after). */
+async function runUbuntuPacker(image, options, dirs, context, iso) {
+    const seedPid = await startSeedServer(context.platformDir, dirs.cache);
+    let watchdogPid;
+    try {
+        await runPackerInit(context.templateFile);
+        await runPackerFmtCheck(context.platformDir);
+        if (options.watchdog !== false) {
+            watchdogPid = await startWatchdogWithBootCmd(dirs.cache);
+        }
+        await runPackerBuild({
+            platformDir: context.platformDir,
+            templateFile: context.templateFile,
+            varsFile: image.varsFile,
+            buildDir: dirs.build,
+            force: options.force,
+            env: { PKR_VAR_iso_path: iso },
+        });
+    }
+    finally {
+        await stopBuildWatchdog(watchdogPid);
+        await stopSeedServer(seedPid);
+    }
+}
+/** Verifies the built vmx and upgrades/checks the hardware version. */
+async function verifyUbuntuOutput(image, dirs, fusionPath) {
+    const output = join(dirs.output, `${image.name}.vmx`);
+    if (!existsSync(output)) {
+        throw new Error(`build produced no ${output}\n` +
+            `       Expected the vmware-iso builder's export in ${dirs.output}/.`);
+    }
+    if (fusionPath) {
+        await upgradeArtifactHardware(output, fusionPath);
+    }
+    else {
+        logger.warn(`skipped the hardware upgrade (no Fusion at ${DEFAULT_FUSION_APP}).`);
+    }
+    await reportOutputDir(dirs.output);
+    logger.ok(`Done: ${output} (export with agent-dev-env deploy ${image.name})`);
+}
+/** Upgrades the artifact to the host Fusion's hardware version. */
+/** The bring-your-own Ubuntu ISO (UBUNTU_ISO_PATH).
+ *
+ * @param image - The catalog image (vars file for the error message).
+ * @returns The ISO path.
+ */
+function requireUbuntuIso(image) {
+    const iso = process.env.UBUNTU_ISO_PATH;
+    if (!iso) {
+        throw new Error('UBUNTU_ISO_PATH is not set.\n' +
+            '       Download the Ubuntu Server 24.04 ARM64 ISO (live-server-arm64)\n' +
+            '       from https://cdimage.ubuntu.com/releases/24.04/release/,\n' +
+            '       then set UBUNTU_ISO_PATH to its absolute path.\n' +
+            '       Paste the SHA256 from the release SHA256SUMS into iso_sha256 in\n' +
+            `       ${image.varsFile} to enable integrity verification.`);
+    }
+    if (!existsSync(iso)) {
+        throw new Error(`UBUNTU_ISO_PATH points to a file that does not exist:\n       ${iso}`);
+    }
+    return iso;
+}
+/** Optional Fusion (the build works without it; only the post-build
+ *  hardware upgrade is skipped).
+ *
+ * @returns The Fusion app path, or undefined when missing (warns).
+ */
+function optionalFusionApp() {
+    const path = process.env.FUSION_APP_PATH ?? DEFAULT_FUSION_APP;
+    if (!existsSync(path)) {
+        logger.warn(`VMware Fusion not found at ${path} —\n` +
+            '      the post-build hardware upgrade will be skipped.\n' +
+            '      Install VMware Fusion (free, Broadcom) or set FUSION_APP_PATH.');
+        return undefined;
+    }
+    return path;
+}
+/** Serves the autoinstall seed on the fixed port (the vmware plugin's
+ *  http_directory port is random; the grub URL must be known upfront).
+ *
+ * @param platformDir - The materialized platform dir (autoinstall/).
+ * @param cacheDir - The build cache dir (seed-server.log lands there).
+ * @returns The server pid.
+ */
+async function startSeedServer(platformDir, cacheDir) {
+    const logFile = join(cacheDir, 'seed-server.log');
+    const taken = await run('lsof', ['-nP', `-iTCP:${SEED_PORT}`, '-sTCP:LISTEN']);
+    if (taken.code === 0) {
+        throw new Error(`port ${SEED_PORT} is taken (something else is listening).\n` +
+            '       Stop the other listener before building.');
+    }
+    if (!commandExists('python3')) {
+        throw new Error('python3 is required to serve the autoinstall seed.');
+    }
+    logger.step(`serving the autoinstall seed at http://<host>:${SEED_PORT}/ (autoinstall/ dir)`);
+    const pid = spawnDetached('python3', [
+        '-m',
+        'http.server',
+        String(SEED_PORT),
+        '--bind',
+        '0.0.0.0',
+        '--directory',
+        join(platformDir, 'autoinstall'),
+    ], { logFile });
+    await sleep(1000);
+    if (!isAlive(pid)) {
+        throw new Error(`the seed server exited — see ${logFile}.`);
+    }
+    return pid;
+}
+/** Kills the seed server when still alive. */
+async function stopSeedServer(pid) {
+    if (isAlive(pid)) {
+        try {
+            process.kill(pid);
+        }
+        catch {
+            // already gone
+        }
+    }
+}
+/** Reads the vmnet8 subnet from Fusion's dhcpd.conf (best effort). */
+function readVmnet8Subnet() {
+    try {
+        return vmnet8SubnetFromDhcpConf(readFileSync(VMNET8_DHCP, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Starts the watchdog with the grub autoinstall command (typed once per
+ *  build; the seed URL points at the vmnet8 host address).
+ *
+ * @param cacheDir - The build cache dir.
+ * @returns The watchdog pid, or undefined when skipped.
+ */
+async function startWatchdogWithBootCmd(cacheDir) {
+    const env = {};
+    const subnet = readVmnet8Subnet();
+    if (!subnet) {
+        logger.warn("could not read the vmnet8 subnet from Fusion's DHCP config —\n" +
+            '      the watchdog will not type the autoinstall command.');
+    }
+    else {
+        const natHost = `${subnet.slice(0, subnet.lastIndexOf('.'))}.1`;
+        env.WATCH_BUILD_BOOT_CMD = watchdogBootCommand(natHost, SEED_PORT);
+        clearBootTypedMarker(cacheDir);
+        logger.step(`watchdog will type the autoinstall command for grub (seed at http://${natHost}:${SEED_PORT}/)`);
+    }
+    return startBuildWatchdog({ cacheDir, env });
+}

package/dist/lifecycle/build-watchdog.js

@@ -0,0 +1,146 @@
+// build-watchdog.ts — the VNC build watchdog the wrapper build flows
+// share (scripts/watch-build.sh + scripts/watch-build.py): dependency
+// checks (python3 + vncdotool, swiftc) with warn+skip, the OCR helper
+// compiled if-stale into the watchdog dir, and a detached spawn of the
+// bundled watch-build.py with a log file. The wrapper scripts'
+// start_watchdog/stop_watchdog helpers land here.
+import { existsSync, mkdirSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { commandExists, isExecutable, killTree, run, spawnDetached } from '../lib/exec.js';
+import { logger } from '../lib/logger.js';
+/** The VNC port the packer templates pin (vnc_port_min/max = 5901). */
+const WATCHDOG_VNC_PORT = 5901;
+/** The bundled watchdog asset root (dist/assets/watchdog); the compiled
+ *  module sits at dist/lifecycle/, one level above the assets.
+ *
+ * @returns The watchdog assets dir.
+ */
+function watchdogAssetsRoot() {
+    return fileURLToPath(new URL('../assets/watchdog', import.meta.url));
+}
+/** The watchdog asset paths.
+ *
+ * @param root - The assets root (defaults to the bundled dir).
+ * @returns The python + swift paths.
+ */
+export function watchdogAssets(root = watchdogAssetsRoot()) {
+    return { python: join(root, 'watch-build.py'), ocrSwift: join(root, 'watch-build-ocr.swift') };
+}
+/** @internal — test-only export of the compile-if-stale check (the
+ *  shell's `[ ! -x $ocr ] || [ src -nt $ocr ]`).
+ *
+ * @param ocrPath - The compiled OCR binary.
+ * @param srcPath - The swift source.
+ * @returns True when a compile is due.
+ */
+export function ocrNeedsCompile(ocrPath, srcPath) {
+    if (!existsSync(ocrPath) || !isExecutable(ocrPath) || !existsSync(srcPath)) {
+        return true;
+    }
+    return statSync(srcPath).mtimeMs > statSync(ocrPath).mtimeMs;
+}
+/** @internal — swiftc compile argv (test-only export).
+ *
+ * @param src - The swift source.
+ * @param out - The output binary.
+ * @returns The swiftc argv.
+ */
+export function swiftcArgs(src, out) {
+    return ['-O', src, '-o', out];
+}
+/** @internal — the watch-build.py argv (test-only export).
+ *
+ * @param port - The VNC port.
+ * @param outdir - The frames dir.
+ * @param ocr - The compiled OCR binary.
+ * @param python - The watch-build.py path.
+ * @returns The argv after python3.
+ */
+export function watchdogPyArgs(port, outdir, ocr, python) {
+    return [python, String(port), outdir, ocr];
+}
+/** Whether python3 + vncdotool are available.
+ *
+ * @returns True when the module imports.
+ */
+export async function pythonVncdotoolAvailable() {
+    const res = await run('python3', ['-c', 'import vncdotool']);
+    return res.code === 0;
+}
+/** Warns and returns false when the watchdog deps are missing (the
+ *  build continues without a watchdog).
+ *
+ * @returns True when vncdotool + swiftc are available.
+ */
+async function watchdogDepsAvailable() {
+    if (!(await pythonVncdotoolAvailable())) {
+        logger.warn('vncdotool not installed (pip3 install vncdotool) —\n' +
+            '      the build may stall at build dialogs without the watchdog.');
+        return false;
+    }
+    if (!commandExists('swiftc')) {
+        logger.warn('swiftc not found — the watchdog OCR helper needs the\n' +
+            '      Xcode command line tools; skipping the watchdog.');
+        return false;
+    }
+    return true;
+}
+/** Compiles the OCR helper when stale; returns its path.
+ *
+ * @param outdir - The watchdog frames dir (binary lands there).
+ * @param assets - The watchdog assets.
+ * @returns The OCR binary path, or undefined when the compile fails.
+ */
+export async function compileOcrHelper(outdir, assets) {
+    mkdirSync(outdir, { recursive: true });
+    const ocr = join(outdir, 'watch-build-ocr');
+    if (!ocrNeedsCompile(ocr, assets.ocrSwift)) {
+        return ocr;
+    }
+    logger.step(`compiling the OCR helper (${ocr})`);
+    const res = await run('swiftc', swiftcArgs(assets.ocrSwift, ocr));
+    if (res.code !== 0) {
+        logger.warn(`swiftc failed — skipping the watchdog (${res.stderr.trim()})`);
+        return undefined;
+    }
+    return ocr;
+}
+/** Starts the detached watchdog (warn+skip when deps are missing).
+ *
+ * @param options - Cache dir / env / assets.
+ * @returns The supervisor pid, or undefined when skipped.
+ */
+export async function startBuildWatchdog(options) {
+    const assets = options.assets ?? watchdogAssets();
+    if (!(await watchdogDepsAvailable())) {
+        return undefined;
+    }
+    const outdir = join(options.cacheDir, 'watchdog');
+    const ocr = await compileOcrHelper(outdir, assets);
+    if (!ocr) {
+        return undefined;
+    }
+    logger.step(`starting build watchdog (VNC port ${WATCHDOG_VNC_PORT}, frames in ${outdir})`);
+    const pid = spawnDetached('python3', watchdogPyArgs(WATCHDOG_VNC_PORT, outdir, ocr, assets.python), { logFile: join(options.cacheDir, 'watchdog.log'), env: options.env });
+    return pid > 0 ? pid : undefined;
+}
+/** Stops the watchdog: kill the supervisor tree, then the belt-and-braces
+ *  pkill of any leftover `--worker` subprocesses holding the VNC port.
+ *
+ * @param pid - The supervisor pid (optional).
+ */
+export async function stopBuildWatchdog(pid) {
+    if (pid !== undefined && pid > 0) {
+        await killTree(pid);
+    }
+    await run('pkill', ['-f', 'watch-build.py --worker']);
+}
+/** Removes the .boot-typed marker (the wrappers do this at watchdog
+ *  start so the grub command is typed once per build).
+ *
+ * @param cacheDir - The build cache dir.
+ */
+export function clearBootTypedMarker(cacheDir) {
+    rmSync(join(cacheDir, 'watchdog', '.boot-typed'), { force: true });
+}

package/dist/lifecycle/build-windows-vmware.js

@@ -0,0 +1,112 @@
+// build-windows-vmware.ts — the windows-vmware build flow: the port of
+// images/windows-arm64-vmware/build.sh (Fusion app + ARM64 boot-driver
+// paths, the vmxnet3 trio staged into the unattend CD, the watchdog,
+// packer with the vmware-iso builder, the post-build hardware upgrade).
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { run, runChecked } from '../lib/exec.js';
+import { logger } from '../lib/logger.js';
+import { announceBuild, buildDirLayout, ensureCacheDir, materializeContext, reportOutputDir, requireAppleSilicon, requireCommands, requireWindowsIso, runPackerBuild, runPackerFmtCheck, runPackerInit, stringVar, unzipVmxnet3Args, upgradeArtifactHardware, verifyIsoSha256, } from './build-shared.js';
+import { startBuildWatchdog, stopBuildWatchdog } from './build-watchdog.js';
+const DEFAULT_FUSION_APP = '/Applications/VMware Fusion.app';
+/** Builds a windows-vmware image.
+ *
+ * @param image - The catalog image.
+ * @param options - Force/watchdog overrides.
+ */
+export async function buildWindowsVmwareImage(image, options) {
+    requireAppleSilicon('the Windows image can only be built on Apple Silicon (VMware\n' +
+        '       Fusion cannot run ARM64 guests on Intel Macs).');
+    requireCommands([
+        ['packer', 'brew install packer'],
+        ['unzip', 'comes with macOS'],
+        ['xmllint', 'comes with macOS'],
+    ]);
+    const fusion = requireFusion(image);
+    const dirs = buildDirLayout('windows-vmware');
+    ensureCacheDir(dirs.cache);
+    const context = materializeContext(image);
+    announceBuild(image, context);
+    const winIso = requireWindowsIso(image);
+    await verifyIsoSha256(winIso, stringVar(image, 'iso_sha256'), 'Windows ISO', image.varsFile);
+    stageVmxnet3(fusion.driversZip, dirs.staging);
+    let watchdogPid;
+    if (options.watchdog !== false) {
+        watchdogPid = await startBuildWatchdog({ cacheDir: dirs.cache });
+    }
+    try {
+        logger.step('xmllint autounattend.xml');
+        await runChecked('xmllint', ['--noout', join(context.platformDir, 'autounattend.xml')]);
+        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: {
+                PKR_VAR_iso_path: winIso,
+                PKR_VAR_vmware_fusion_app_path: fusion.path,
+            },
+        });
+    }
+    finally {
+        await stopBuildWatchdog(watchdogPid);
+    }
+    const output = requireVmxOutput(dirs.output, image.name);
+    await upgradeArtifactHardware(output, fusion.path);
+    await reportOutputDir(dirs.output);
+    logger.ok(`Done: ${output} (export with agent-dev-env deploy ${image.name})`);
+}
+/** Resolves the Fusion app (FUSION_APP_PATH → vars → default) and checks
+ *  the ARM64 drivers zip + tools ISO exist.
+ *
+ * @param image - The catalog image.
+ * @returns The fusion paths.
+ */
+function requireFusion(image) {
+    const path = process.env.FUSION_APP_PATH ?? stringVar(image, 'vmware_fusion_app_path') ?? DEFAULT_FUSION_APP;
+    if (!existsSync(path)) {
+        throw new Error(`VMware Fusion not found at ${path}.\n       Install VMware Fusion (free, Broadcom) or set FUSION_APP_PATH.`);
+    }
+    logger.step(`using VMware Fusion at ${path}`);
+    const driversZip = join(path, 'Contents', 'Library', 'isoimages', 'arm64', 'drivers-arm64.zip');
+    const toolsIso = join(path, 'Contents', 'Library', 'isoimages', 'arm64', 'windows.iso');
+    if (!existsSync(driversZip)) {
+        throw new Error(`ARM64 boot drivers not found at ${driversZip}.\n` +
+            '       This Fusion version does not ship the ARM64 Windows drivers —\n' +
+            '       use Fusion 13.6+ (checked from the app bundle).');
+    }
+    if (!existsSync(toolsIso)) {
+        throw new Error(`ARM64 VMware Tools ISO not found at ${toolsIso}.\n` +
+            '       This Fusion version does not ship ARM64 tools —\n' +
+            '       use Fusion 13.6+ (checked from the app bundle).');
+    }
+    return { path, driversZip };
+}
+/** Extracts the vmxnet3 ARM64 inf/sys/cat trio flat into the staging dir
+ *  (packed into the unattend CD).
+ *
+ * @param driversZip - Fusion's drivers-arm64.zip.
+ * @param stagingDir - The staging dir.
+ */
+async function stageVmxnet3(driversZip, stagingDir) {
+    logger.step(`staging vmxnet3 ARM64 drivers into ${stagingDir}`);
+    rmSync(stagingDir, { recursive: true, force: true });
+    mkdirSync(stagingDir, { recursive: true });
+    const res = await run('unzip', unzipVmxnet3Args(driversZip, stagingDir));
+    if (res.code !== 0) {
+        throw new Error(`vmxnet3 ARM64 driver missing from ${driversZip}.\n` +
+            '       Expected vmxnet3/Win10_1709/ARM64/vmxnet3.{inf,sys,cat}.');
+    }
+}
+/** The built vmx (must exist after the vmware-iso build). */
+function requireVmxOutput(outputDir, imageName) {
+    const output = join(outputDir, `${imageName}.vmx`);
+    if (!existsSync(output)) {
+        throw new Error(`build produced no ${output}\n` +
+            `       Expected the vmware-iso builder's export in ${outputDir}/.`);
+    }
+    return output;
+}

package/dist/lifecycle/build.js

@@ -0,0 +1,55 @@
+// build.ts — `agent-dev-env build`: the dispatcher (the port of
+// scripts/build.sh). Resolves the requested images (all catalog images
+// when none are given), then runs the per-platform build flow; the first
+// failure aborts the run (the CLI's top level turns the throw into
+// die()).
+import { logger } from '../lib/logger.js';
+import { buildMacosImage } from './build-macos.js';
+import { buildQemuImage } from './build-qemu.js';
+import { buildUbuntuImage } from './build-ubuntu.js';
+import { buildWindowsVmwareImage } from './build-windows-vmware.js';
+import { resolveRequestedImages } from './catalog.js';
+/** Builds one image with its platform's flow.
+ *
+ * @param image - The catalog image.
+ * @param options - Force/watchdog overrides.
+ */
+async function buildImage(image, options) {
+    const flow = {
+        force: options.force,
+        watchdog: options.watchdog !== false,
+    };
+    switch (image.platform) {
+        case 'macos':
+            await buildMacosImage(image, flow);
+            return;
+        case 'windows-qemu':
+            await buildQemuImage(image, flow);
+            return;
+        case 'windows-vmware':
+            await buildWindowsVmwareImage(image, flow);
+            return;
+        case 'ubuntu-vmware':
+            await buildUbuntuImage(image, flow);
+            return;
+    }
+}
+/** `agent-dev-env build [image...] [--force] [--no-watchdog]`.
+ *
+ * @param requested - Image names (all images when empty).
+ * @param options - Force/watchdog overrides.
+ * @returns The exit code (0 on success).
+ */
+export async function buildCmd(requested = [], options = {}) {
+    const targets = resolveRequestedImages(requested);
+    if (requested.length === 0) {
+        logger.title('Building all images:');
+        for (const image of targets) {
+            logger.info(image.name);
+        }
+    }
+    for (const image of targets) {
+        await buildImage(image, options);
+    }
+    return 0;
+}

package/dist/lifecycle/catalog.js

@@ -0,0 +1,165 @@
+// catalog.ts — the image catalog: discovers images from the per-image
+// vars files (images/<platform>/vars/<image>.pkrvars.hcl) and maps name
+// <-> platform <-> vars file <-> defaults.
+//
+// Replaces list_images()/find_vars_file() from scripts/build.sh,
+// scripts/deploy.sh, scripts/tag.sh and the wrapper resolution in each
+// runner.
+//
+// Roots (first match wins, deduped by image name):
+//   1. the checkout's images/ — when this process runs inside a clone
+//      (dev mode / repo tooling)
+//   2. the bundled snapshot under dist/assets/images/ — when installed
+//      from npm (the package ships everything it needs)
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findRepoRoot } from '../lib/git.js';
+import { PLATFORM_DIR_MAP } from '../lib/platform.js';
+import { parseVars, readQuotedVar } from '../lib/vars.js';
+function bundledImagesRoot() {
+    // dist/lifecycle/catalog.js -> dist/assets/images (the package ships the
+    // images/ snapshot next to the compiled CLI).
+    return fileURLToPath(new URL('../assets/images', import.meta.url));
+}
+/** @internal — The images roots to search, repo checkout first. */
+export function imagesRoots(cwd = process.cwd()) {
+    const roots = [];
+    const repo = findRepoRoot(cwd);
+    if (repo) {
+        roots.push(join(repo, 'images'));
+    }
+    roots.push(bundledImagesRoot());
+    return [...new Set(roots)];
+}
+/** Vars files under <root>/<platform>/vars/*.pkrvars.hcl, sorted by image
+ *  name for deterministic output. */
+function varsFilesIn(root) {
+    if (!existsSync(root)) {
+        return [];
+    }
+    const out = [];
+    for (const platformDir of readdirSync(root, { withFileTypes: true })) {
+        if (!platformDir.isDirectory()) {
+            continue;
+        }
+        const varsDir = join(root, platformDir.name, 'vars');
+        if (!existsSync(varsDir)) {
+            continue;
+        }
+        for (const entry of readdirSync(varsDir)) {
+            if (entry.endsWith('.pkrvars.hcl')) {
+                out.push(join(varsDir, entry));
+            }
+        }
+    }
+    return out.sort();
+}
+function platformForDir(dir) {
+    const platform = PLATFORM_DIR_MAP[basename(dir)];
+    if (!platform) {
+        throw new Error(`unknown platform directory: ${dir}`);
+    }
+    return platform;
+}
+/** Lists every image in the catalog (repo root first, deduped by name).
+ *
+ * @param options - Explicit images roots (defaults to checkout + bundled).
+ * @returns The catalog entries, sorted by image name.
+ */
+export function listImages(options = {}) {
+    const seen = new Set();
+    const out = [];
+    for (const root of options.roots ?? imagesRoots()) {
+        for (const varsFile of varsFilesIn(root)) {
+            const name = basename(varsFile, '.pkrvars.hcl');
+            if (seen.has(name)) {
+                continue;
+            }
+            seen.add(name);
+            out.push({
+                name,
+                platform: platformForDir(dirname(dirname(varsFile))),
+                varsFile,
+            });
+        }
+    }
+    return out;
+}
+/** Looks an image up by name; throws with the shell's error message.
+ *
+ * @param name - The image name.
+ * @param options - Catalog roots (defaults to the repo + bundled assets).
+ * @returns The catalog image.
+ */
+export function resolveImage(name, options = {}) {
+    const image = listImages(options).find((i) => i.name === name);
+    if (!image) {
+        throw new Error(`No vars file found for image '${name}'. ` +
+            `Expected images/<platform>/vars/${name}.pkrvars.hcl`);
+    }
+    return image;
+}
+/** Returns the catalog's default image for a platform.
+ *
+ * @param platform - The platform to look up.
+ * @param options - Explicit images roots (defaults to checkout + bundled).
+ * @returns The platform's catalog image.
+ * @throws Error when the platform has no image in the catalog.
+ */
+export function defaultImageFor(platform, options = {}) {
+    const image = listImages(options).find((i) => i.platform === platform);
+    if (!image) {
+        throw new Error(`No image found for platform '${platform}' — expected ` +
+            `images/<platform>/vars/*.pkrvars.hcl`);
+    }
+    return image;
+}
+/** Resolves the requested image names — explicit names in order, or the
+ *  whole catalog when empty (no-arg build/deploy/tag semantics).
+ *
+ * @param requested - Image names (empty = all images).
+ * @returns The catalog images, in catalog order for "all".
+ * @throws Error for an unknown name or an empty catalog.
+ */
+export function resolveRequestedImages(requested = []) {
+    if (requested.length > 0) {
+        return requested.map((name) => resolveImage(name));
+    }
+    const all = listImages();
+    if (all.length === 0) {
+        throw new Error('No images found: no vars files under images/*/vars/.');
+    }
+    return all;
+}
+const varsCache = new Map();
+/** Parses all assignments in the image's vars file (cached per file).
+ *
+ * @param image - The catalog image.
+ * @returns The vars file's assignments as a name → value map.
+ */
+export function varsFor(image) {
+    const cached = varsCache.get(image.varsFile);
+    if (cached) {
+        return cached;
+    }
+    const text = readFileSync(image.varsFile, 'utf8');
+    const parsed = parseVars(text);
+    varsCache.set(image.varsFile, parsed);
+    return parsed;
+}
+/** Reads the image's image_version — required, same error as
+ *  deploy.sh/tag.sh.
+ *
+ * @param image - The catalog image.
+ * @returns The version string.
+ * @throws Error when the vars file has no image_version.
+ */
+export function imageVersion(image) {
+    const text = readFileSync(image.varsFile, 'utf8');
+    const version = readQuotedVar(text, 'image_version');
+    if (version === undefined) {
+        throw new Error(`Could not read image_version from ${image.varsFile}`);
+    }
+    return version;
+}