agent-dev-env 0.1.0

package/dist/runners/vmware-image.js

@@ -0,0 +1,242 @@
+// runners/vmware-image.ts — step 1 for the VMware backends (ubuntu-vmware
+// and windows-vmware, Phase 4 + Phase 5): pick the image archive (env
+// override → local build output → cached pull → oras pull), extract the
+// pristine base (identity marker = path|size|mtime, so a rebuild over the
+// same path is detected), clone the working VM + set its display name,
+// and upgrade it once per hardware version (.hw-version). Port of
+// run-{ubuntu,windows}-vmware-sandbox.sh §step 1/2; the CLI's data dir
+// replaces the legacy agent-sandbox one. The per-platform pieces (platform
+// id, the archive override env var) are parameters, so the two VMware
+// backends share one implementation.
+//
+// The thin per-platform wrappers (ubuntu-image.ts / windows-image.ts)
+// bind the platform id + override var; everything else is here.
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { commandExists, run } from '../lib/exec.js';
+import { registryRef, resolveOwner } from '../lib/ghcr.js';
+import { logger } from '../lib/logger.js';
+import { buildDir, imageRootDir, vmwareArchivePath, workingVmxPath } from '../lib/paths.js';
+import { confirmDefault } from '../lib/prompt.js';
+import { cloneVm, setVmDisplayName, upgradeVmHardware, vmwareHwVersion } from '../lib/vmrun.js';
+/** @internal — the pristine-archive identity (path|size|mtime; the same
+ *  scheme as the QEMU runner's backing-image marker — a rebuild packs the
+ *  new image at the SAME path, so the path alone misses it).
+ *
+ * @param path - The archive path.
+ * @param size - File size in bytes.
+ * @param mtimeMs - File mtime (ms since epoch).
+ * @returns The identity string.
+ */
+export function archiveIdentity(path, size, mtimeMs) {
+    return `${path}|${size}|${Math.floor(mtimeMs / 1000)}`;
+}
+/** The base directory of the pristine extraction. */
+function baseDir(platform, image) {
+    return join(imageRootDir(platform, image), 'base');
+}
+/** The pristine base vmx. */
+function baseVmx(platform, image) {
+    return join(baseDir(platform, image), `${image}.vmx`);
+}
+/** The archive identity marker path. */
+function baseMarker(platform, image) {
+    return join(imageRootDir(platform, image), 'base-archive.txt');
+}
+/** The working clone's vmx. */
+export function vmwareWorkingVmx(platform, image) {
+    return workingVmxPath(platform, image);
+}
+/** The .hw-version marker (records the upgraded hardware version). */
+function hwMarker(platform, image) {
+    return join(dirname(vmwareWorkingVmx(platform, image)), '.hw-version');
+}
+/** Step 1: select the archive, extract the base, clone the working VM
+ *  and upgrade it if the installed Fusion supports a newer hardware
+ *  version.
+ *
+ * @param platform - The target platform (state dir naming).
+ * @param overrideEnv - The env var holding a local archive override
+ *   (UBUNTU_VMWARE_IMAGE / WINDOWS_VMWARE_IMAGE).
+ * @param context - The run context.
+ * @param state - The accumulated run state (imageArchive set here).
+ */
+export async function ensureVmwareImage(platform, overrideEnv, context, state) {
+    const archive = await pickImage(platform, overrideEnv, context);
+    state.imageArchive = archive;
+    logger.ok(`Using archive: ${archive}`);
+    await ensureBase(platform, context, archive);
+    if (!(await ensureWorkingVm(platform, context))) {
+        logger.die('could not clone the working VM (see above). Check Fusion\u2019s VM library path and re-run.');
+    }
+    await upgradeWorkingVm(platform, context);
+}
+/** The shell's pick_image: <OVERRIDE_ENV> → local build output (packed on
+ *  demand) → cached pull → oras pull with the owner chain.
+ *
+ * @param platform - The target platform.
+ * @param overrideEnv - The environment override variable name.
+ * @param context - The run context.
+ * @returns The archive path to run.
+ */
+async function pickImage(platform, overrideEnv, context) {
+    const env = context.options.env;
+    const image = context.image;
+    const override = env[overrideEnv];
+    if (override) {
+        if (!existsSync(override)) {
+            logger.die(`${overrideEnv} points to a file that does not exist: ${override}`);
+        }
+        return override;
+    }
+    const outputDir = join(buildDir(platform), 'output');
+    const local = join(outputDir, `${image}.tar.gz`);
+    if (existsSync(join(outputDir, `${image}.vmx`)) && !existsSync(local)) {
+        logger.info(`No archive yet — packing the local build output into ${local}`);
+        const vmdks = readdirSync(outputDir)
+            .filter((file) => file.endsWith('.vmdk'))
+            .map((file) => join(outputDir, file));
+        mkdirSync(dirname(local), { recursive: true });
+        const packed = await run('tar', ['-czf', local, '--exclude=*.log', `${image}.vmx`, `${image}.nvram`, ...vmdks], { cwd: outputDir });
+        if (packed.code !== 0) {
+            logger.die(`failed to pack the local build output:\n${packed.stderr.trim()}`);
+        }
+    }
+    if (existsSync(local)) {
+        return local;
+    }
+    const cached = vmwareArchivePath(platform, image);
+    if (existsSync(cached)) {
+        return cached;
+    }
+    return pullImage(platform, overrideEnv, context, cached);
+}
+/** The oras pull into the image/ cache dir (owner chain + confirm +
+ *  archive presence check).
+ *
+ * @param platform - The target platform.
+ * @param overrideEnv - The environment override variable name (prompts).
+ * @param context - The run context.
+ * @param cached - The destination archive path.
+ * @returns The pulled archive path.
+ */
+async function pullImage(platform, overrideEnv, context, cached) {
+    if (!commandExists('oras')) {
+        logger.die('oras is not installed — needed to pull the image (brew install oras). ' +
+            `Set ${overrideEnv} to a local archive to skip.`);
+    }
+    const owner = await resolveOwner({ owner: context.options.owner, env: context.options.env });
+    const ref = registryRef(context.image, 'latest', owner);
+    const hint = platform === 'windows-vmware' ? '~20 GB' : '~15 GB';
+    if (!(await confirmDefault(`Pull ${ref} (one-time, ${hint} download)?`, {
+        default: 'y',
+        yes: context.options.yes,
+    }))) {
+        logger.die(`aborted — no sandbox image available. Set ${overrideEnv} to a local archive or pull manually.`);
+    }
+    mkdirSync(dirname(cached), { recursive: true });
+    logger.info(`Pulling ${ref} (one-time, ${hint} download)...`);
+    const res = await run('oras', ['pull', ref], { cwd: dirname(cached) });
+    if (res.code !== 0) {
+        logger.die('oras pull failed — check your network connection (public GHCR images pull without a login).');
+    }
+    if (!existsSync(cached)) {
+        logger.die(`oras pull produced no ${cached} — is the image published under ${ref}?`);
+    }
+    return cached;
+}
+/** Extracts the pristine archive into base/ (identity-marker gated; an
+ *  archive change drops base + the working clone).
+ *
+ * @param platform - The target platform.
+ * @param context - The run context.
+ * @param archive - The archive to extract.
+ */
+async function ensureBase(platform, context, archive) {
+    const image = context.image;
+    const markerPath = baseMarker(platform, image);
+    const baseDirPath = baseDir(platform, image);
+    const baseVmxPath = baseVmx(platform, image);
+    const stat = statSync(archive);
+    const id = archiveIdentity(archive, stat.size, stat.mtimeMs);
+    const hadMarker = existsSync(markerPath);
+    const marker = hadMarker ? readFileSync(markerPath, 'utf8').trim() : '';
+    if (hadMarker && marker !== id) {
+        logger.warn('The archive changed (new build or pull) — re-extracting the pristine VM and dropping the working clone.');
+        logger.warn('The working clone\u2019s guest state (installs, config, agent files) is lost with it.');
+        rmSync(baseDirPath, { recursive: true, force: true });
+        rmSync(join(imageRootDir(platform, image), 'working'), { recursive: true, force: true });
+    }
+    if (marker === id && existsSync(baseVmxPath)) {
+        logger.ok(`Pristine VM extracted (${baseDirPath}).`);
+        return;
+    }
+    mkdirSync(baseDirPath, { recursive: true });
+    logger.cmd(`tar -xzf ${archive} -C ${baseDirPath}`);
+    const res = await run('tar', ['-xzf', archive, '-C', baseDirPath]);
+    if (res.code !== 0) {
+        logger.die(`archive extraction failed:\n${res.stderr.trim()}`);
+    }
+    writeFileSync(markerPath, id);
+    if (!existsSync(baseVmxPath)) {
+        logger.die(`archive extraction produced no ${baseVmxPath} (is the archive valid?)`);
+    }
+    logger.ok(`Pristine VM extracted (${baseVmxPath}).`);
+}
+/** Clones the pristine base into the working VM + sets the display name
+ *  (clone inherits the base's — the working VM would show under the
+ *  base's name in Fusion's library otherwise).
+ *
+ * @param platform - The target platform.
+ * @param context - The run context.
+ * @returns True when the clone exists.
+ */
+async function ensureWorkingVm(platform, context) {
+    const image = context.image;
+    const wVmx = vmwareWorkingVmx(platform, image);
+    if (existsSync(wVmx)) {
+        logger.ok(`Working VM exists (${wVmx}).`);
+        return true;
+    }
+    mkdirSync(dirname(wVmx), { recursive: true });
+    logger.cmd(`vmrun -T fusion clone ${baseVmx(platform, image)} ${wVmx} full`);
+    const res = await cloneVm(baseVmx(platform, image), wVmx);
+    if (res.code !== 0) {
+        logger.warn('full clone failed (Fusion may have rejected the destination path).');
+        return false;
+    }
+    logger.cmd(`set displayName "${context.vm}" in ${wVmx}`);
+    if (!setVmDisplayName(wVmx, context.vm)) {
+        logger.warn('could not set the working VM\u2019s display name (Fusion will show the base\u2019s name).');
+    }
+    logger.ok(`Working VM cloned (${wVmx}; display name '${context.vm}').`);
+    return true;
+}
+/** Upgrades the working clone once per hardware version (vmrun
+ *  upgradevm — the no-op hang is why it runs only when the marker
+ *  differs).
+ *
+ * @param platform - The target platform.
+ * @param context - The run context.
+ */
+async function upgradeWorkingVm(platform, context) {
+    const wVmx = vmwareWorkingVmx(platform, context.image);
+    const before = vmwareHwVersion(wVmx);
+    if (!before) {
+        return;
+    }
+    const markerPath = hwMarker(platform, context.image);
+    const marker = existsSync(markerPath) ? readFileSync(markerPath, 'utf8').trim() : '';
+    if (marker === before) {
+        return;
+    }
+    const after = await upgradeVmHardware(wVmx);
+    if (!after) {
+        logger.warn('could not upgrade the working VM (vmrun missing?) — the first GUI start may prompt.');
+        return;
+    }
+    writeFileSync(markerPath, after);
+    if (after !== before) {
+        logger.ok(`Working VM upgraded to hardware version ${after} (the installed Fusion\u2019s current).`);
+    }
+}

package/dist/runners/windows-autologon.js

@@ -0,0 +1,119 @@
+// runners/windows-autologon.ts — the one-time auto-logon step of the
+// two Windows boots (the legacy ensure_autologon): the image's
+// autounattend.xml sets LogonCount=1 (exactly one auto-login — the OOBE
+// boot), after which Windows clears AutoAdminLogon, so every later boot
+// lands on the lock screen and the OpenChamber ONLOGON task never fires.
+// Re-enable it once (the registry keys persist in the working VM) and
+// reboot the guest so the task runs at the auto-logon. The registry
+// snippets are ASCII-only (the packed-agents rule) and ride the ssh2
+// PowerShell transport (windows-guest.ts). The check/enable core
+// (configureAutologon) is shared by the VMware + QEMU backends — only
+// the reboot wait differs (the VMware NAT IP can change; the QEMU
+// hostfwd target is fixed).
+import { logger } from '../lib/logger.js';
+import { confirmDefault } from '../lib/prompt.js';
+import { openSshSession, waitForSshd } from '../lib/ssh.js';
+import { waitGuestIp } from './vmware-common.js';
+import { psExec } from './windows-guest.js';
+const WINLOGON_KEY = 'HKLM:\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Winlogon';
+/** @internal — escapes a value for a single-quoted PowerShell literal. */
+function escapePs(value) {
+    return value.replace(/'/g, "''");
+}
+/** @internal — the auto-logon state check ('enabled' | 'disabled' on
+ *  stdout): enabled only when AutoAdminLogon is set, targets the right
+ *  user and has a password (the image's LogonCount clears the flag).
+ *
+ * @param username - The expected auto-logon user.
+ * @returns The PowerShell script (ASCII).
+ */
+export function autologonCheckScript(username) {
+    return [
+        `$w = '${WINLOGON_KEY}'`,
+        '$prop = Get-ItemProperty -Path $w -ErrorAction SilentlyContinue',
+        `if ($prop.AutoAdminLogon -eq '1' -and $prop.DefaultUserName -eq '${escapePs(username)}' -and $prop.DefaultPassword) {`,
+        "  Write-Output 'enabled'",
+        '} else {',
+        "  Write-Output 'disabled'",
+        '}',
+    ].join('\n');
+}
+/** @internal — sets the auto-logon registry keys and reboots the guest.
+ *
+ * @param username - The user to log in as.
+ * @param password - The user's password (the Winlogon DefaultPassword).
+ * @returns The PowerShell script (ASCII).
+ */
+export function autologonEnableScript(username, password) {
+    return [
+        `$w = '${WINLOGON_KEY}'`,
+        'New-Item -Path $w -Force | Out-Null',
+        "Set-ItemProperty -Path $w -Name AutoAdminLogon -Value '1'",
+        `Set-ItemProperty -Path $w -Name DefaultUserName -Value '${escapePs(username)}'`,
+        `Set-ItemProperty -Path $w -Name DefaultPassword -Value '${escapePs(password)}'`,
+        'shutdown /r /t 0',
+    ].join('\n');
+}
+/** The auto-logon check/enable core (shared by the VMware and QEMU
+ *  Windows backends): probe the registry, offer the enable+reboot and
+ *  apply it. Returns true when a reboot was initiated — the caller
+ *  waits for sshd (the wait differs per backend: the VMware IP can
+ *  change, the QEMU hostfwd target is fixed).
+ *
+ * @param context - The run context (yes flag).
+ * @param creds - The guest credentials.
+ * @returns True when the guest was told to reboot with auto-logon.
+ */
+export async function configureAutologon(context, creds) {
+    const session = await openSshSession(creds);
+    try {
+        const check = await psExec(session, autologonCheckScript(creds.username), 60_000);
+        if (/enabled/.test(check.stdout)) {
+            logger.ok('Guest auto-logon is enabled — OpenChamber starts at logon.');
+            return false;
+        }
+        logger.info('Guest auto-logon is disabled (the image allows one OOBE logon only).');
+        if (!(await confirmDefault('Enable auto-logon and reboot the guest so OpenChamber starts at boot?', { default: 'y', yes: context.options.yes }))) {
+            logger.info('OpenChamber will not start until someone logs in via RDP or the console.');
+            return false;
+        }
+        await psExec(session, autologonEnableScript(creds.username, creds.password), 60_000);
+        return true;
+    }
+    catch (err) {
+        logger.warn(`auto-logon setup failed: ${err.message}`);
+        return false;
+    }
+    finally {
+        session.end();
+    }
+}
+/** The VMware auto-logon flow: configure, then wait for the rebooted
+ *  guest (the auto-logon makes the OpenChamber ONLOGON task fire at
+ *  boot). The reboot can land on a new NAT address, so the sshd wait
+ *  targets the refreshed IP (the shell's wait_guest_ip re-set the
+ *  global).
+ *
+ * @param context - The run context (yes flag).
+ * @param state - The accumulated run state (vmIp refreshed after reboot).
+ * @param workVmx - The working VM vmx.
+ * @param creds - The guest credentials.
+ */
+export async function ensureAutologon(context, state, workVmx, creds) {
+    if (!(await configureAutologon(context, creds))) {
+        return;
+    }
+    logger.info('Rebooting the guest (a minute or two)...');
+    const ip = await waitGuestIp(workVmx);
+    state.vmIp = ip;
+    const rebooted = { ...creds, host: ip };
+    process.stdout.write('    Waiting for the guest to reboot (up to 10 min)');
+    if (await waitForSshd(rebooted)) {
+        process.stdout.write(` ${logger.color('green')}done${logger.reset()}\n`);
+        logger.ok('Guest rebooted with auto-logon enabled.');
+    }
+    else {
+        process.stdout.write(` ${logger.color('yellow')}failed${logger.reset()}\n`);
+        logger.die(`timed out waiting for the guest to reboot (no SSH on ${ip}:22).`);
+    }
+}

package/dist/runners/windows-bridges.js

@@ -0,0 +1,136 @@
+// runners/windows-bridges.ts — step 3 for the two Windows backends: the
+// host side of the SSH agent + Docker bridges. VMware (Fusion's NAT is
+// userspace — the guest gateway x.y.z.2 is vmnetd and does not forward to
+// the host loopback, so the bridges bind the host's x.y.z.1 like the
+// Ubuntu backend); QEMU (user-mode networking — the guest reaches the
+// host loopback at 10.0.2.2, so the listeners bind 127.0.0.1). The guest
+// side (upload/install/status/docker over the ssh2 PowerShell transport)
+// lives in windows-guest.ts.
+import { QEMU_HOST_ALIAS } from '../lib/qemu.js';
+import { logger } from '../lib/logger.js';
+import { findHostAlias } from '../lib/network.js';
+import { openSshSession } from '../lib/ssh.js';
+import { findHostAgentSocket, findHostDockerSocket, startHostBridge } from './bridges.js';
+import { ensureGuestAgent, findGuestNode, readGuestStatus, resolveGuestCredentials, verifyGuestDocker, } from './windows-guest.js';
+/** The Windows step 3: host alias → host bridges → guest agent → guest
+ *  bridges → docker verification. The guest-visible alias and the bind
+ *  address differ per backend (QEMU: 10.0.2.2 / 127.0.0.1; VMware: the
+ *  NAT-segment x.y.z.1 / itself), resolved once and reused.
+ */
+export async function windowsBridges(context, state) {
+    const ip = state.vmIp;
+    if (!ip) {
+        logger.warn('no guest IP — skipping the host bridges and guest setup.');
+        return;
+    }
+    const isQemu = context.platform === 'windows-qemu';
+    const guestAlias = isQemu ? QEMU_HOST_ALIAS : await findHostAlias(ip);
+    if (!guestAlias) {
+        logger.warn('could not determine the host NAT-segment address — skipping the bridges.');
+        return;
+    }
+    const bindHost = isQemu ? '127.0.0.1' : guestAlias;
+    const creds = resolveGuestCredentials(context.image, context.options.env, ip, context.options.sshPort);
+    const session = await openSshSession(creds);
+    try {
+        const node = await findGuestNode(session);
+        if (!node) {
+            logger.warn('node not found in the guest — skipping the guest bridges.');
+            return;
+        }
+        if (context.options.noAgent) {
+            logger.info('Skipping SSH agent bridge setup (--no-agent).');
+        }
+        else {
+            await setupSshAgent(context, state, bindHost, guestAlias);
+        }
+        if (context.options.noDocker) {
+            logger.info('Skipping Docker bridge setup (--no-docker).');
+        }
+        else {
+            await setupDockerBridge(context, state, bindHost, guestAlias);
+        }
+        const anyBridged = state.bridges.agent.bridged || state.bridges.docker.bridged;
+        if (anyBridged) {
+            await ensureGuestAgent(session, node, guestAlias, context);
+            await readGuestStatus(session, state, node);
+            reportBridgeState(context, state);
+            if (state.bridges.docker.bridged && state.bridges.docker.guestUp) {
+                await verifyGuestDocker(session, state);
+            }
+        }
+    }
+    finally {
+        session.end();
+    }
+}
+async function setupSshAgent(context, state, bindHost, guestAlias) {
+    const sock = findHostAgentSocket(context.options.env, context.options.home);
+    if (!sock) {
+        logger.info('No SSH agent override detected — using the default macOS agent.');
+        logger.info('To share a password manager\u2019s agent (Bitwarden, 1Password, ...), ' +
+            'enable its SSH agent on the host and re-run.');
+        return;
+    }
+    logger.ok(`Host SSH agent socket found: ${sock}`);
+    logger.info(`Bridging it into the guest on TCP port ${context.agentPort} (see docs/ssh-agent.md).`);
+    logger.ok(`Guest reaches the host at ${guestAlias}`);
+    if (!(await startBridge(context, state, 'ssh-agent', sock, bindHost))) {
+        return;
+    }
+}
+async function setupDockerBridge(context, state, bindHost, guestAlias) {
+    const sock = findHostDockerSocket(context.options.home);
+    if (!sock) {
+        logger.info('No Docker engine socket found on the host (Docker Desktop, Colima, OrbStack).');
+        logger.info('Start an engine on the host and re-run to bridge it into the guest.');
+        return;
+    }
+    logger.ok(`Host Docker engine socket found: ${sock}`);
+    logger.info(`Bridging it into the guest on TCP port ${context.dockerPort}.`);
+    logger.ok(`Guest reaches the host at ${guestAlias}`);
+    if (!(await startBridge(context, state, 'docker', sock, bindHost))) {
+        return;
+    }
+}
+/** The shared bridge start: the host spawn + state bookkeeping (the
+ *  shell's start_host_bridge; pidfile + detached bridge.js via
+ *  runners/bridges.ts — no socat). Returns false when skipped.
+ */
+async function startBridge(context, state, role, socket, bindHost) {
+    const result = await startHostBridge({
+        role,
+        bindHost,
+        port: role === 'ssh-agent' ? context.agentPort : context.dockerPort,
+        forwardSocket: socket,
+    });
+    if (result.state === 'failed') {
+        logger.warn(`skipping the ${role === 'ssh-agent' ? 'SSH agent' : 'Docker'} bridge.`);
+        return false;
+    }
+    const bridge = role === 'ssh-agent' ? state.bridges.agent : state.bridges.docker;
+    bridge.bridged = true;
+    bridge.socket = socket;
+    bridge.pid = result.state === 'started' ? result.pid : undefined;
+    return true;
+}
+function reportBridgeState(context, state) {
+    const agent = state.bridges.agent;
+    if (agent.bridged) {
+        if (agent.guestUp) {
+            logger.ok(`Guest bridge is up: \\\\.\\pipe\\openssh-ssh-agent -> host TCP ${context.agentPort}`);
+        }
+        else {
+            logger.warn('guest bridge did not start — run the guest commands from docs/ssh-agent.md manually.');
+        }
+    }
+    const docker = state.bridges.docker;
+    if (docker.bridged) {
+        if (docker.guestUp) {
+            logger.ok(`Guest Docker bridge is up: \\\\.\\pipe\\docker_engine -> host TCP ${context.dockerPort}`);
+        }
+        else {
+            logger.warn('guest Docker bridge did not start — check the guest agent install.');
+        }
+    }
+}