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

package/dist/runners/ubuntu-shared.js

@@ -0,0 +1,65 @@
+// runners/ubuntu-shared.ts — step 4 for the Ubuntu backend: the shared
+// host directory over HGFS (open-vm-tools' vmhgfs-fuse). Best-effort —
+// the sandbox works without it, failures warn only, like the shell's
+// setup_shared_folder. The vmrun side (tools gate + addSharedFolder with
+// the "Already exists" case) is here; the guest mount runs over the ssh2
+// session with the password piped into sudo -S.
+import { existsSync } from 'node:fs';
+import { logger } from '../lib/logger.js';
+import { openSshSession } from '../lib/ssh.js';
+import { enableSharedFolders, isVmRunning } from '../lib/vmrun.js';
+import { addSharedFolderRetry, waitForTools } from './vmware-common.js';
+/** The shared-folder step: register + enable the share with vmrun and
+ *  mount it in the guest (skipped silently when no --work-dir / missing
+ *  host dir / VM down — the shell's early-outs).
+ *
+ * @param context - The run context.
+ * @param workVmx - The working VM vmx.
+ * @param creds - The guest credentials (mount over ssh).
+ */
+export async function setupSharedFolder(context, workVmx, creds) {
+    if (!context.workDir) {
+        return;
+    }
+    if (!existsSync(context.workDir)) {
+        logger.warn(`work directory '${context.workDir}' does not exist — skipping the shared-directory share.`);
+        return;
+    }
+    if (!(await isVmRunning(workVmx))) {
+        logger.warn('shared folder skipped — the VM is not running.');
+        return;
+    }
+    logger.info(`Sharing ${context.workDir} into the guest as 'work' (/mnt/hgfs/work).`);
+    if (!(await waitForTools(workVmx))) {
+        logger.warn('VMware Tools did not report running — skipping the shared-directory share (re-run to retry).');
+        return;
+    }
+    await addSharedFolderRetry(workVmx, 'work', context.workDir);
+    await enableSharedFolders(workVmx);
+    await mountSharedFolder(creds);
+}
+/** Mounts the registered shares in the guest (vmhgfs-fuse needs root —
+ *  sudo -S reads the password from the session's stdin).
+ *
+ * @param creds - The guest credentials.
+ */
+async function mountSharedFolder(creds) {
+    const session = await openSshSession(creds);
+    try {
+        const command = 'mkdir -p /mnt/hgfs/work && sudo -S vmhgfs-fuse .host:/ /mnt/hgfs ' +
+            '-o allow_other,default_permissions,uid=$(id -u),gid=$(id -g)';
+        const res = await session.exec(command, { input: `${creds.password}\n`, timeoutMs: 60_000 });
+        if (res.code !== 0) {
+            logger.warn('could not mount the shared folder in the guest — is vmhgfs-fuse available (open-vm-tools)?');
+            logger.warn('try manually: sudo vmhgfs-fuse .host:/ /mnt/hgfs -o allow_other');
+            return;
+        }
+        logger.ok('Shared folder mounted at /mnt/hgfs/work.');
+    }
+    catch (err) {
+        logger.warn(`could not mount the shared folder in the guest: ${err.message}`);
+    }
+    finally {
+        session.end();
+    }
+}

package/dist/runners/ubuntu-summary.js

@@ -0,0 +1,141 @@
+// runners/ubuntu-summary.ts — the Ubuntu "Sandbox is ready" block (port
+// of the shell's print_summary in run-ubuntu-vmware-sandbox.sh: same
+// labels, same wording, same color scheme — with the CLI's 12-char label
+// column, like the macOS summary).
+import { existsSync } from 'node:fs';
+import { logger } from '../lib/logger.js';
+import { imageRootDir, workingVmxPath } from '../lib/paths.js';
+import { resolveGuestCredentials } from './ubuntu-guest.js';
+/** Prints the Ubuntu summary block (image/VM/IP/SSH/shared dir/bridges/
+ *  rules/settings/OpenChamber/state/stop hints).
+ *
+ * @param context - The run context.
+ * @param state - The accumulated run state.
+ */
+export async function printUbuntuSummary(context, state) {
+    const workVmx = workingVmxPath(context.platform, context.image);
+    const stateDir = imageRootDir(context.platform, context.image);
+    logger.step('Sandbox is ready');
+    summaryLine('Image:', state.imageArchive ?? 'not available');
+    summaryLine('VM:', workVmx);
+    summaryLine('Guest IP:', state.vmIp ? `${state.vmIp} (Fusion NAT, vmnet8)` : 'unavailable');
+    const creds = state.vmIp
+        ? resolveGuestCredentials(context.image, context.options.env, state.vmIp)
+        : undefined;
+    summaryLine('SSH:', `ssh ${creds?.username ?? 'admin'}@${state.vmIp ?? '?'} (password: ${creds?.password ?? 'sandbox'})`);
+    if (context.workDir && existsSync(context.workDir)) {
+        summaryLine('Shared:', `/mnt/hgfs/work -> ${context.workDir}`);
+    }
+    else {
+        summaryLine('Shared:', 'not shared');
+    }
+    printBridgeLines(context, state);
+    printRulesLine(state.rules);
+    printSettingsLine(state.settings);
+    printOpenchamberLine(context, state);
+    summaryLine('State:', `${stateDir} (extracted base + working clone; --reset re-clones)`);
+    printStopLines(context, state);
+}
+/** One `    LABEL........  VALUE` line. */
+function summaryLine(label, value) {
+    logger.out(`    ${label.padEnd(12)}${value}`);
+}
+function printBridgeLines(context, state) {
+    const agent = state.bridges.agent;
+    if (agent.bridged) {
+        const value = agent.guestUp
+            ? `host agent -> TCP ${context.agentPort} -> guest (/tmp/ssh-agent.sock)`
+            : `host bridge up (TCP ${context.agentPort}), guest bridge not running`;
+        summaryLine('SSH agent:', agent.guestUp ? loggerOk(value) : loggerWarn(value));
+    }
+    else {
+        summaryLine('SSH agent:', 'not bridged');
+    }
+    const docker = state.bridges.docker;
+    if (docker.bridged) {
+        if (docker.engineUp) {
+            summaryLine('Docker:', loggerOk(`host engine (v${docker.serverVersion}) -> TCP ${context.dockerPort} -> guest (context 'host')`));
+        }
+        else if (docker.guestUp) {
+            summaryLine('Docker:', loggerWarn('bridge up, engine not reachable in the guest — is Docker running on the host?'));
+        }
+        else {
+            summaryLine('Docker:', loggerWarn(`host bridge up (TCP ${context.dockerPort}), guest bridge not running`));
+        }
+    }
+    else {
+        summaryLine('Docker:', 'not bridged');
+    }
+}
+function printRulesLine(rules) {
+    switch (rules) {
+        case 'installed':
+            summaryLine('Rules:', loggerOk('installed for opencode + Copilot'));
+            break;
+        case 'updated':
+        case 'overwritten':
+            summaryLine('Rules:', loggerOk('updated for opencode + Copilot'));
+            break;
+        case 'uptodate':
+            summaryLine('Rules:', 'up to date in the guest');
+            break;
+        case 'kept':
+            summaryLine('Rules:', 'guest rules kept (not overwritten)');
+            break;
+        case 'failed':
+            summaryLine('Rules:', loggerWarn('could not be installed'));
+            break;
+        default:
+            summaryLine('Rules:', 'not installed');
+    }
+}
+function printSettingsLine(settings) {
+    switch (settings) {
+        case 'copied':
+            summaryLine('Settings:', loggerOk('host user settings copied into the guest'));
+            break;
+        case 'uptodate':
+            summaryLine('Settings:', 'already in the guest');
+            break;
+        case 'skipped':
+            summaryLine('Settings:', 'not copied (--no-settings)');
+            break;
+        case 'declined':
+            summaryLine('Settings:', 'not copied (declined)');
+            break;
+        case 'none':
+            summaryLine('Settings:', 'no host settings found');
+            break;
+        case 'failed':
+            summaryLine('Settings:', loggerWarn('copy failed — re-run to retry'));
+            break;
+        default:
+            summaryLine('Settings:', 'not copied');
+    }
+}
+function printOpenchamberLine(context, state) {
+    if (state.openchamberUp && state.openchamberUrl) {
+        summaryLine('OpenChamber:', loggerOk(`${state.openchamberUrl} (password: sandbox)`));
+    }
+    else {
+        summaryLine('OpenChamber:', loggerWarn(`not responding on http://${state.vmIp ?? '?'}:${context.openchamberPort}`));
+    }
+}
+function printStopLines(context, state) {
+    summaryLine('Stop:', 'run "agent-dev-env stop ubuntu-vmware"');
+    if (!context.options.foreground) {
+        if (state.bridges.agent.bridged) {
+            summaryLine('Bridge:', `host listener on TCP ${context.agentPort} stays up — stop it with: agent-dev-env stop ubuntu-vmware`);
+        }
+        if (state.bridges.docker.bridged) {
+            summaryLine('Bridge:', `host Docker listener on TCP ${context.dockerPort} stays up — stop it with: agent-dev-env stop ubuntu-vmware`);
+        }
+    }
+}
+// color helpers — the shell's ${c_green}/${c_yellow} inline.
+function loggerOk(text) {
+    return logger.color('green') + text + logger.reset();
+}
+function loggerWarn(text) {
+    return logger.color('yellow') + text + logger.reset();
+}

package/dist/runners/ubuntu.js

@@ -0,0 +1,117 @@
+// runners/ubuntu.ts — the Ubuntu 24.04 (ARM64) VMware backend (Phase 4 of
+// the port): vmrun-driven image/base/clone (ubuntu-image.ts), boot with
+// the guest-IP + sshd waits and the HGFS share (ubuntu-shared.ts), the
+// NAT-segment bridges + guest agent over ssh2 (ubuntu-bridges.ts), the
+// settings copy over ssh2 (settings/ubuntu-copy.ts) and the summary.
+// Port of run-ubuntu-vmware-sandbox.sh §steps 0-8.
+import { rmSync } from 'node:fs';
+import { logger } from '../lib/logger.js';
+import { imageRootDir } from '../lib/paths.js';
+import { openSshSession, waitForSshd } from '../lib/ssh.js';
+import { startVm } from '../lib/vmrun.js';
+import { ensureUserSettings, restartOpenchamber } from '../settings/ubuntu-copy.js';
+import { ensureBridgeDir } from './bridges.js';
+import { offerOpenInBrowser, waitForOpenchamber } from './openchamber.js';
+import { ensureUbuntuImage, ubuntuWorkingVmx } from './ubuntu-image.js';
+import { ubuntuBridges } from './ubuntu-bridges.js';
+import { resolveGuestCredentials } from './ubuntu-guest.js';
+import { setupSharedFolder } from './ubuntu-shared.js';
+import { printUbuntuSummary } from './ubuntu-summary.js';
+import { cleanupRunBridge, requireVmrun, stopRunningVm, waitForForegroundVmStop, waitGuestIp, } from './vmware-common.js';
+const PLATFORM = 'ubuntu-vmware';
+/** The Ubuntu backend — vmrun + ssh2 (no Tart; the state lives under the
+ *  CLI's data dir, unlike the macOS backend's no-footprint design).
+ */
+export const ubuntuBackend = {
+    preflight: (context) => preflight(context),
+    ensureImageAndVm: (context, state) => ensureUbuntuImage(context, state),
+    boot: boot,
+    setupBridges: (context, state) => ubuntuBridges(context, state),
+    setupSettings: (context, state) => setupSettings(context, state),
+    verifyOpenchamber: (context, state) => verifyOpenchamber(context, state),
+    summarize: (context, state) => printUbuntuSummary(context, state),
+    finish: finish,
+};
+async function preflight(context) {
+    requireVmrun();
+    ensureBridgeDir();
+    if (context.options.reset) {
+        const root = imageRootDir(PLATFORM, context.image);
+        logger.info(`Resetting the working VM (--reset) — deleting the extracted base and the working clone.`);
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+// --- step 2: boot -----------------------------------------------------------
+async function boot(context, state) {
+    const workVmx = ubuntuWorkingVmx(context.image);
+    await stopRunningVm(context, workVmx, PLATFORM);
+    logger.cmd(`vmrun -T fusion start ${workVmx} ${context.options.headless ? 'nogui' : 'gui'}`);
+    const start = await startVm(workVmx, context.options.headless ? 'nogui' : 'gui');
+    if (start.code !== 0) {
+        throw new Error(`vmrun start failed:\n${start.stderr.trim()}`);
+    }
+    logger.ok('VM started.');
+    state.vmIp = await waitGuestIp(workVmx);
+    logger.ok(`Guest IP: ${state.vmIp}`);
+    const creds = resolveGuestCredentials(context.image, context.options.env, state.vmIp);
+    process.stdout.write('    Waiting for the guest to boot (up to 10 min)');
+    if (await waitForSshd(creds)) {
+        process.stdout.write(` ${logger.color('green')}done${logger.reset()}\n`);
+        logger.ok(`VM is up: ssh ${creds.username}@${state.vmIp}`);
+    }
+    else {
+        process.stdout.write(` ${logger.color('yellow')}failed${logger.reset()}\n`);
+        logger.die(`timed out waiting for the guest to boot (no SSH on ${state.vmIp}:22).`);
+    }
+    await setupSharedFolder(context, workVmx, creds);
+}
+// --- step 4/5 hooks ---------------------------------------------------------
+async function setupSettings(context, state) {
+    if (context.options.noSettings) {
+        logger.info('Skipping user settings copy (--no-settings).');
+        state.settings = 'skipped';
+        return;
+    }
+    if (!state.vmIp) {
+        logger.warn('no guest IP — skipping the user settings copy.');
+        state.settings = 'failed';
+        return;
+    }
+    const creds = resolveGuestCredentials(context.image, context.options.env, state.vmIp);
+    const session = await openSshSession(creds);
+    try {
+        state.settings = await ensureUserSettings(session, context.options.home, context.options.yes, creds.password);
+        if (state.settings === 'copied') {
+            await restartOpenchamber(session);
+        }
+    }
+    catch (err) {
+        state.settings = 'failed';
+        logger.warn(`settings copy failed: ${err.message}`);
+    }
+    finally {
+        session.end();
+    }
+}
+async function verifyOpenchamber(context, state) {
+    if (!state.vmIp) {
+        logger.warn('OpenChamber: guest IP unavailable — cannot probe.');
+        return;
+    }
+    state.openchamberUrl = `http://${state.vmIp}:${context.openchamberPort}`;
+    state.openchamberUp = await waitForOpenchamber(state.openchamberUrl);
+    if (state.openchamberUp) {
+        await offerOpenInBrowser(state.openchamberUrl, context.options.yes);
+    }
+}
+// --- finish: foreground wait + bridge cleanup --------------------------------
+async function finish(context, state) {
+    if (!context.options.foreground) {
+        return;
+    }
+    await waitForForegroundVmStop(ubuntuWorkingVmx(context.image));
+    // The VM stopped (or Cmd+C was pressed) — kill the bridges this run
+    // started; in background mode they stay up, outliving the CLI by design.
+    await cleanupRunBridge(state.bridges.agent.pid, 'agent bridge');
+    await cleanupRunBridge(state.bridges.docker.pid, 'Docker bridge');
+}

package/dist/runners/vmware-common.js

@@ -0,0 +1,158 @@
+// runners/vmware-common.ts — the run-time helpers the two VMware backends
+// (ubuntu-vmware and windows-vmware) share: the vmrun prereq, the
+// stop-running-VM restart flow, the bounded guest-IP wait, the
+// VMware-Tools wait and the bridge cleanup. Extracted from the ubuntu
+// backend when the windows backend landed (Phase 5) — one implementation
+// for both, with the platform label for the runners' messages.
+import { killTree, sleep } from '../lib/exec.js';
+import { logger } from '../lib/logger.js';
+import { confirmDefault } from '../lib/prompt.js';
+import { addSharedFolder, checkToolsState, findVmrun, getGuestIpAddress, isVmRunning, sharedFolderAlreadyExists, stopVm, waitForVmNotRunning, } from '../lib/vmrun.js';
+/** vmrun prereq (same message as doctor/status).
+ *
+ * @returns The resolved vmrun path.
+ */
+export function requireVmrun() {
+    if (!findVmrun()) {
+        logger.die('vmrun not found — install VMware Fusion (free for personal use) or set FUSION_APP_PATH.');
+    }
+}
+/** Stops a VM left running by a previous run before the boot (the old
+ *  VM holds the clone's disks; the legacy stop_running_vm — restart
+ *  confirm defaults to no).
+ *
+ * @param context - The run context.
+ * @param workVmx - The working VM vmx.
+ * @param platform - The platform id (stop-hint message).
+ */
+export async function stopRunningVm(context, workVmx, platform) {
+    if (!(await isVmRunning(workVmx))) {
+        return;
+    }
+    if (!(await confirmDefault('The sandbox VM is already running — restart it?', {
+        default: 'n',
+        yes: context.options.yes,
+    }))) {
+        logger.die(`aborted — the VM is already running. Stop it with: agent-dev-env stop ${platform}`);
+    }
+    logger.cmd(`vmrun -T fusion stop ${workVmx}`);
+    await stopVm(workVmx);
+    process.stdout.write('    Waiting for the VM to stop');
+    if (await waitForVmNotRunning(workVmx, 60, 2000)) {
+        process.stdout.write(` ${logger.color('green')}stopped${logger.reset()}\n`);
+    }
+    else {
+        process.stdout.write(` ${logger.color('yellow')}failed${logger.reset()}\n`);
+        logger.warn(`'${workVmx}' is still running — stop it manually with 'vmrun -T fusion stop'.`);
+    }
+    await sleep(1000);
+}
+/** Polls vmrun getGuestIPAddress (bounded per call; strictly a dotted
+ *  quad — the "Tools not running" error text must never become the IP).
+ *
+ * @param workVmx - The working VM vmx.
+ * @returns The guest IP.
+ */
+export async function waitGuestIp(workVmx) {
+    process.stdout.write('    Waiting for the guest IP (open-vm-tools; up to 15 min)');
+    for (let attempt = 0; attempt < 180; attempt += 1) {
+        const ip = await getGuestIpAddress(workVmx);
+        if (ip) {
+            process.stdout.write(` ${logger.color('green')}done${logger.reset()}\n`);
+            return ip;
+        }
+        process.stdout.write('.');
+        await sleep(5000);
+    }
+    process.stdout.write(` ${logger.color('yellow')}failed${logger.reset()}\n`);
+    return logger.die('timed out waiting for the guest IP — are open-vm-tools running in the guest?');
+}
+/** Polls checkToolsState until vmrun reports "running" (the tools can
+ *  still be starting when the IP and sshd already answer — vmrun
+ *  addSharedFolder then fails).
+ *
+ * @param workVmx - The working VM vmx.
+ * @returns True when the tools report running within the window.
+ */
+export async function waitForTools(workVmx) {
+    process.stdout.write('    Waiting for VMware Tools to be running');
+    for (let attempt = 0; attempt < 60; attempt += 1) {
+        if ((await checkToolsState(workVmx)) === 'running') {
+            process.stdout.write(` ${logger.color('green')}done${logger.reset()}\n`);
+            return true;
+        }
+        process.stdout.write('.');
+        await sleep(5000);
+    }
+    process.stdout.write(` ${logger.color('yellow')}failed${logger.reset()}\n`);
+    return false;
+}
+/** Registers the share (4 x 10 s retries — the tools state can flip back
+ *  after waitForTools; "Already exists" from a previous run is ok).
+ *
+ * @param workVmx - The working VM vmx.
+ * @param name - The share name.
+ * @param path - The host directory.
+ */
+export async function addSharedFolderRetry(workVmx, name, path) {
+    for (let attempt = 1; attempt <= 4; attempt += 1) {
+        const res = await addSharedFolder(workVmx, name, path);
+        if (res.code === 0) {
+            return;
+        }
+        if (sharedFolderAlreadyExists(`${res.stdout}${res.stderr}`)) {
+            logger.ok('Shared folder already registered (from a previous run — the share persists in the vmx).');
+            return;
+        }
+        if (attempt < 4) {
+            logger.warn(`addSharedFolder failed (${res.stderr.trim()}) — retrying in 10 s (attempt ${attempt}/4).`);
+            await sleep(10_000);
+        }
+    }
+    logger.warn('addSharedFolder failed after 4 attempts — is VMware Tools up? Continuing.');
+}
+/** The foreground wait: poll vmrun list until the VM stops; a Cmd+C stops
+ *  it through the same vmrun path as the shell's EXIT trap. The VM must
+ *  already be up (the working vmx exists).
+ *
+ * @param workVmx - The working VM vmx.
+ */
+export async function waitForForegroundVmStop(workVmx) {
+    let stopping = false;
+    const onSignal = () => {
+        if (stopping) {
+            return;
+        }
+        stopping = true;
+        logger.info('Stopping the VM (Cmd+C)...');
+        // Plain `vmrun stop` — the shell's EXIT trap parity (hard power-off;
+        // the poll loop waits for the running list to clear).
+        void stopVm(workVmx, 'hard');
+    };
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+    logger.info('Waiting for the VM to stop (Cmd+C to stop it now)...');
+    try {
+        while (await isVmRunning(workVmx)) {
+            await sleep(3000);
+        }
+    }
+    finally {
+        process.removeListener('SIGINT', onSignal);
+        process.removeListener('SIGTERM', onSignal);
+    }
+    logger.info('VM stopped.');
+}
+/** Kills one of this run's bridges (the foreground-mode teardown; in
+ *  background mode the bridges stay up, outliving the CLI by design).
+ *
+ * @param pid - The bridge pid this run started (undefined = not ours).
+ * @param label - The bridge label (agent bridge / Docker bridge).
+ */
+export async function cleanupRunBridge(pid, label) {
+    if (pid === undefined) {
+        return;
+    }
+    await killTree(pid);
+    logger.info(`Stopped the host ${label} (pid ${pid}).`);
+}