agent-dev-env 0.1.0

package/dist/assets/images/windows-arm64-vmware/vars/sandbox-windows-11-arm64-vmware.pkrvars.hcl

@@ -0,0 +1,83 @@
+# Windows 11 (ARM64) sandbox image — VMware (Fusion) build.
+#
+# Built with the Packer vmware-iso plugin on Apple Silicon (the vmware-iso
+# builder drives VMware Fusion, which virtualizes ARM64 guests natively):
+# Windows 11 ARM64 ISO + Fusion's ARM64 boot drivers + VMware Tools. See
+# images/windows-arm64-vmware/README.md for the full build flow — the
+# Windows ISO is bring-your-own (Microsoft does not permit redistribution),
+# so it is not part of this repo.
+
+windows_version = "11"
+
+# SHA256 of the Windows 11 ARM64 ISO. Microsoft publishes the hash on the
+# download page (https://www.microsoft.com/software-download/windows11arm64);
+# paste it here to enable integrity verification. Set WINDOWS_ISO_PATH to
+# the local ISO path when building. Empty = skip verification.
+iso_sha256 = "638AA2C88E94385B00F4F178D071E3DF0B7D9E335577A83BD533B7F2EB65ADF0"
+
+# VMware Fusion installation that supplies the ARM64 boot drivers
+# (Contents/Library/isoimages/arm64/drivers-arm64.zip) and the ARM64 VMware
+# Tools ISO (Contents/Library/isoimages/arm64/windows.iso) during the build;
+# the sandbox runner needs the same Fusion to run the VM.
+# Fusion 13.6+ is required (the Packer vmware plugin's minimum).
+vmware_fusion_app_path = "/Applications/VMware Fusion.app"
+
+# Toolchain versions installed via Chocolatey (choco package versions —
+# must exist in the community repository).
+nodejs_version = "26.8.1"
+python_version = "3.13.15"
+github_cli_version = "2.97.0"
+ripgrep_version = "15.2.0"
+git_version = "2.55.0.4"
+jq_version = "1.8.1"
+open_code_review_version = "1.9.5"
+
+# C/C++ + cross-language toolchains (brought over from AdGuard's
+# build-agent-images windows2022-vs2022 / windows2022-go images).
+# VS2022 Build Tools (choco package version; the finalizer adds the .NET
+# SDKs + VC++ workload + Win11 SDK) and Rust (via rustup, not choco) are
+# installed by dedicated provisioners.
+go_version = "1.27.0"
+rust_version = "1.95"
+wixtoolset_version = "3.14.1.20250415"
+protoc_version = "36.0.0"
+nasm_version = "3.2.0"
+llvm_version = "22.1.7"
+vim_version = "9.2.995"
+nuget_version = "7.9.0"
+mingw_version = "16.1.0"
+make_version = "4.4.1"
+vs_buildtools_version = "117.14.37"
+
+# Google Chrome: installed from the Chrome for Testing (CfT) snapshot
+# archive instead of choco — choco's googlechrome package always downloads
+# the live dl.google.com MSI whose hash rotates on every Chrome release,
+# so the pinned package hash breaks between releases. CfT serves versioned
+# zips at storage.googleapis.com/chrome-for-testing-public/<version>/,
+# which stay downloadable and hash-stable. The x64 build runs under Windows
+# on ARM emulation, like the choco MSI did.
+chrome_version = "152.0.7977.54"
+chrome_sha256 = "91850065e6b80bba0c752e17a150fe1b9e39bba51ed705640c1273f565950dda"
+
+# VM resources
+disk_size = 100
+cpu_count = 4
+memory_gb = 8
+
+# WinRM credentials used for provisioning. They are baked into
+# images/windows-arm64-vmware/autounattend.xml (Administrator password) and
+# become the sandbox's login (SSH/RDP) — keep the two files in sync.
+winrm_username = "Administrator"
+winrm_password = "sandbox1"
+
+# OpenChamber web UI password + port. The runner advertises the UI at
+# http://<guest-ip>:4000 (password "sandbox" by default). OpenChamber
+# refuses to serve on the network without a password.
+openchamber_ui_password = "sandbox"
+openchamber_port = 4000
+
+# Semantic version this image is published under (also the GHCR push tag,
+# besides :latest). For every release: bump it, add a CHANGELOG.md entry,
+# and create the windows-arm64-vmware-v<version> git tag
+# (npx agent-dev-env tag <image>).
+image_version = "1.0.0"

package/dist/assets/rules/agent-rules-linux.md

@@ -0,0 +1,68 @@
+# Sandbox VM environment
+
+You are running inside an Ubuntu sandbox VM. Your code lives on the host Mac
+and is shared into the VM; the toolchain (Go, Rust, Node, Python, VS Code,
+opencode, ...) runs in the VM. The environment differs from a normal dev
+machine in a few ways that matter when you run commands or start services.
+
+## Paths
+
+- When the runner was started with `--work-dir`, the shared working
+  directory is mounted in the VM at `{{GUEST_MOUNT}}` and corresponds to
+  the host's `{{HOST_WORK_DIR}}`. Paths quoted from the host — in issues,
+  commits, or host-side terminal output — use the host form: map them to
+  the guest form when you open files, and back to the host form when you
+  return paths to the user.
+- The VM's user is `admin` (home `/home/admin`); your git identity comes
+  from the host's git config (the runner shares it into the guest).
+
+## Docker
+
+The VM ships the Docker CLI but **no container engine** — the runner
+bridges the *host's* engine into the VM instead:
+
+- Docker talks to the host engine through `unix:///tmp/docker.sock`
+  (`DOCKER_HOST` is exported; the `host` docker context is the default).
+- **Never try to install or start a local engine** (`dockerd`, Docker
+  Desktop, ...) — it cannot work here. If `docker info` fails, the bridge
+  or the host engine is down: tell the user to start the engine on the
+  host and/or re-run `agent-dev-env run ubuntu-vmware`, and continue with
+  work that does not need Docker.
+
+### Containers you launch
+
+- Containers run on the **host engine**, and the Docker daemon resolves
+  volume-mount paths on the **host's filesystem** — the guest mount
+  (`{{GUEST_MOUNT}}`) does not exist there. Bind mounts must use **host
+  paths**: mount `{{HOST_WORK_DIR}}/<project>/...` into the container, not
+  `{{GUEST_MOUNT}}/<project>/...`. This applies to `docker run -v` and to
+  compose `volumes:` entries alike; named volumes are unaffected.
+- Published ports are bound on the **host**. From inside the VM they are
+  reachable at `{{NAT_GATEWAY}}:<port>` — **not** at `localhost:<port>`.
+  Check a container you started with `curl http://{{NAT_GATEWAY}}:<port>`,
+  and tell the user the port is available as `http://localhost:<port>` on
+  the host itself.
+- Image builds run on the host engine: `docker build` and `docker buildx`
+  work as usual.
+
+## Services you start
+
+- A server you start inside the VM (e.g. a dev server) is reachable from
+  the host at `http://<vm-ip>:<port>` — the VM's IP is printed when the
+  sandbox starts. OpenChamber itself listens on port 4000.
+
+## Config changes
+
+- After editing opencode or Copilot settings in the VM, restart OpenChamber
+  with `systemctl --user restart agent-sandbox-openchamber` (the CLI
+  restarts it automatically when it brings the bridges up). To pull the
+  host's versions of the settings instead, the user runs
+  `agent-dev-env sync ubuntu-vmware`.
+
+## SSH agent bridge
+
+- The runner bridges the host's SSH agent into the VM, so `git push`, `git
+  fetch`, `gh`, `ssh` and `scp` work against any host the user's agent
+  knows, without keys on disk. `SSH_AUTH_SOCK` points at the bridged
+  socket (`/tmp/ssh-agent.sock`), and `~/.ssh/config` sets `IdentityAgent`
+  for tools that don't read the export.

package/dist/assets/rules/agent-rules.md

@@ -0,0 +1,71 @@
+# Sandbox VM environment
+
+You are running inside a macOS sandbox VM. Your code lives on the host Mac and
+is shared into the VM; the toolchain (Xcode, Homebrew, Node, Python, VS Code,
+opencode, ...) runs in the VM. The environment differs from a normal dev
+machine in a few ways that matter when you run commands or start services.
+
+## Paths
+
+- The shared working directory is mounted in the VM at `{{GUEST_MOUNT}}` and
+  corresponds to the host's `{{HOST_WORK_DIR}}`. Paths quoted from the host —
+  in issues, commits, or host-side terminal output — use the host form: map
+  them to the guest form when you open files, and back to the host form when
+  you return paths to the user.
+- The VM's user is `admin` (home `/Users/admin`); your git identity, aliases
+  and signing config come from `~/.gitconfig` (synced from the host with the
+  user settings).
+
+## Docker
+
+The VM ships the Docker CLI but **no container engine** — macOS guests cannot
+nest VMs, so Docker Desktop, Colima and OrbStack do not run inside the VM. The
+runner bridges the *host's* engine into the VM instead:
+
+- The `host` docker context is the default; `docker`, `docker compose` and
+  `docker buildx` talk to the host engine via `~/.docker/run/docker.sock`
+  (`DOCKER_HOST` and `TESTCONTAINERS_HOST_OVERRIDE` are exported for clients
+  that ignore contexts, e.g. testcontainers).
+- **Never try to install or start a local engine** (`colima start`, Docker
+  Desktop, ...) — it cannot work here. If `docker info` fails, the bridge or
+  the host engine is down: tell the user to start the engine on the host
+  and/or re-run `agent-dev-env run macos`, and continue with work that does
+  not need Docker.
+
+### Containers you launch
+
+- Containers run on the **host engine**, and the Docker daemon resolves
+  volume-mount paths on the **host's filesystem** — the guest mount
+  (`{{GUEST_MOUNT}}`) does not exist there. Bind mounts must use **host
+  paths**: mount `{{HOST_WORK_DIR}}/<project>/...` into the container, not
+  `{{GUEST_MOUNT}}/<project>/...`. This applies to `docker run -v` and to
+  compose `volumes:` entries alike (compose resolves relative mount paths in
+  the guest before the daemon sees them); named volumes are unaffected.
+- Published ports are bound on the **host**. From inside the VM they are
+  reachable at the NAT gateway — `192.168.64.1:<port>` (verify with `route -n
+  get default`) — **not** at `localhost:<port>`. Check a container you
+  started with `curl http://192.168.64.1:<port>`, and tell the user the port
+  is available as `http://localhost:<port>` on the host itself.
+- Image builds run on the host engine: `docker build` and `docker buildx`
+  work as usual.
+
+## Services you start
+
+- A server you start inside the VM (e.g. a dev server) is reachable from the
+  host at `http://<vm-ip>:<port>` — the VM's IP is printed when the sandbox
+  starts, or ask the user to run `tart ip <vm>`. OpenChamber itself listens
+  on port 4000.
+
+## Config changes
+
+- After editing opencode or Copilot settings in the VM, restart OpenChamber
+  with `openchamber restart`; to pull the host's versions of the settings
+  instead, the user runs `agent-dev-env sync macos`.
+
+## SSH agent bridge
+
+- The runner bridges the host's SSH agent into the VM, so `git push`, `git
+  fetch`, `gh`, `ssh` and `scp` work against any host the user's agent knows,
+  without keys on disk. `SSH_AUTH_SOCK` points at the bridged socket
+  (`/tmp/ssh-agent.sock`), and `~/.ssh/config` sets `IdentityAgent` for tools
+  that don't read the export.

package/dist/assets/watchdog/watch-build-ocr.swift

@@ -0,0 +1,40 @@
+// watch-build-ocr.swift — OCR helper for the Windows sandbox build watchdog.
+//
+// Compiled on first use by the CLI's `watch-build` command (swiftc -O)
+// into the watchdog outdir; the Python worker (watch-build.py) runs it on
+// each captured VNC frame. Uses Apple's Vision framework — no external OCR
+// dependency, and the Xcode command line tools are already a build
+// prerequisite on the host.
+//
+// Prints one line per recognized text:
+//   <text> | center=(<x>,<y>) box=(<x>,<y> <w>x<h>)
+// with pixel coordinates in the image's own resolution (top-left origin),
+// so the worker can click OCR'd buttons without assuming a framebuffer
+// size.
+
+import Vision
+import AppKit
+
+let url = URL(fileURLWithPath: CommandLine.arguments[1])
+guard let img = NSImage(contentsOf: url),
+      let cg = img.cgImage(forProposedRect: nil, context: nil, hints: nil) else {
+    FileHandle.standardError.write("cannot load image\n".data(using: .utf8)!)
+    exit(1)
+}
+let w = cg.width
+let h = cg.height
+let request = VNRecognizeTextRequest()
+request.recognitionLevel = .accurate
+request.usesLanguageCorrection = false
+let handler = VNImageRequestHandler(cgImage: cg, options: [:])
+try handler.perform([request])
+for obs in request.results ?? [] {
+    if let c = obs.topCandidates(1).first {
+        let bb = obs.boundingBox  // normalized, origin bottom-left
+        let x = Int(bb.origin.x * CGFloat(w))
+        let y = Int((1 - bb.origin.y - bb.size.height) * CGFloat(h))
+        let bw = Int(bb.size.width * CGFloat(w))
+        let bh = Int(bb.size.height * CGFloat(h))
+        print("\(c.string) | center=(\(x + bw/2),\(y + bh/2)) box=(\(x),\(y) \(bw)x\(bh))")
+    }
+}

package/dist/assets/watchdog/watch-build.py

@@ -0,0 +1,275 @@
+#!/usr/bin/env python3
+"""Watchdog for the headless sandbox builds (Windows + Ubuntu).
+
+Why it exists: the Packer build's boot_command types Enter 15 times to
+answer the firmware's boot prompts. The stray keys can hit "Cancel" on
+Windows Setup's "Installing Windows 11" screen — Setup then asks "Are you
+sure you want to quit?" and, headless, nothing dismisses it: the build
+stalls forever. Boot races can also land in the UEFI shell. This watchdog
+polls the build's VNC framebuffer, OCRs each frame (Apple Vision via
+watch-build-ocr.swift), and:
+
+  - clicks "No" on the quit-confirmation dialog (at the OCR'd button
+    position; falls back to measured coordinates for the 800x600 buffer),
+  - presses a key when "Press any key to boot from CD or DVD" is on screen,
+  - boots the ISO from the UEFI shell (fs0: + EFI\\BOOT\\BOOTAA64.EFI),
+  - logs loudly when Windows Setup's "Windows could not complete the
+    installation" dialog is on screen (the build then hangs at WinRM —
+    nothing to click; the root cause is in the guest's Panther logs),
+  - Ubuntu builds: types the autoinstall kernel command into grub when
+    the grub menu or shell appears (WATCH_BUILD_BOOT_CMD env var, one
+    grub command per line; the env var is read per frame, so it can be
+    filled in after the build started, e.g. once the HTTP port is known).
+    While the command is still untyped (no .boot-typed marker in the frame
+    directory), the supervisor polls every 3 s — grub's menu countdown is
+    ~20 s wide and the slow cadence (~2 min per frame) can miss it, which
+    makes the interactive Subiquity installer boot instead of autoinstall
+    and the build hang waiting for SSH. Once the command is typed (or the
+    fast-poll cap passes), the slow cadence resumes. The grub command is
+    typed only once per build (a marker file in the frame directory
+    records it; the build wrapper removes the marker when the watchdog
+    starts), and only after grub is actually on screen — the firmware's
+    (variable-length) No-Media/PXE probe cycle no longer races the Packer
+    boot_command typing.
+
+The supervisor runs every capture in a subprocess with a hard timeout, so a
+hung VNC/OCR cycle cannot stall the watch. See the CLI's `watch-build`
+command for the entry point and prerequisites (python3 + vncdotool +
+swiftc).
+
+Usage:
+  watch-build.py <vnc-port> <outdir> <ocr-binary>
+  watch-build.py       --worker <vnc-port> <outdir> <ocr-binary> <frame>
+"""
+
+import os
+import re
+import subprocess
+import sys
+import time
+
+# Fallback "No" button center for the 800x600 framebuffer (top-left origin),
+# used when the OCR did not return a position for the button.
+NO_BUTTON_FALLBACK = (487, 381)
+
+# --- poll pacing -----------------------------------------------------------
+#
+# Until the Ubuntu autoinstall command is typed (or the hard cap below
+# passes), the supervisor polls fast so at least one worker lands inside
+# grub's ~20 s menu countdown. The slow cadence (90 s worker + 20 s sleep)
+# scans a frame roughly every 2 minutes, so it can miss the menu entirely —
+# the default entry then boots the interactive Subiquity installer and the
+# build hangs waiting for SSH ("Timeout waiting for SSH" after the 60 m
+# ssh_timeout; observed in the Ubuntu 24.04 build on 2026-08-29).
+# Once .boot-typed exists the slow cadence resumes — the only screens left
+# are the installer / Windows dialogs, which change on the minute timescale.
+# The worker timeout stays at 90 s even in the fast phase: the worker's own
+# OCR timeout (50 s) and connect timeout (10 s) bound a slow worker, and a
+# kill mid-typing would corrupt the grub shell input line.
+FAST_POLL_INTERVAL = 3
+FAST_POLL_MAX_SECONDS = 240
+SLOW_POLL_INTERVAL = 20
+SLOW_POLL_WORKER_TIMEOUT = 90
+
+# Ubuntu autoinstall boot command (rendered by the build wrapper; see the
+# module docstring). Read per worker invocation, so the value can be
+# provided after the watchdog started.
+BOOT_CMD = os.environ.get('WATCH_BUILD_BOOT_CMD', '')
+
+
+def log(msg):
+    print(time.ctime(), msg, flush=True)
+
+
+# --- worker: capture one frame, act on what is on screen --------------------
+
+def type_colon(vnc):
+    """The VNC keymap mangles ':' (shift modifier dropped), so send
+    shift+';' explicitly."""
+    vnc.keyDown('lshift')
+    time.sleep(0.15)
+    vnc.keyPress(';')
+    time.sleep(0.15)
+    vnc.keyUp('lshift')
+    time.sleep(0.2)
+
+
+def type_string(vnc, text):
+    """Type a string character by character. ':' needs the shift trick
+    (see type_colon); everything else is a plain key. Per-character
+    try/except so an unmappable key never aborts the typing."""
+    for ch in text:
+        try:
+            if ch == ':':
+                type_colon(vnc)
+            else:
+                vnc.keyPress(ch)
+                time.sleep(0.08)
+        except Exception:  # noqa: BLE001 - keep typing the rest
+            log(f'WARN: could not type {ch!r}')
+
+    time.sleep(0.5)
+
+
+def type_boot_command(vnc, outdir, at_shell):
+    """Types the Ubuntu autoinstall grub command (BOOT_CMD, one grub
+    command per line). 'c' opens the grub shell from the menu; when the
+    shell prompt is already up (at_shell), the command lines are typed
+    directly."""
+    if not at_shell:
+        vnc.keyPress('c')
+        time.sleep(1.0)
+    for line in BOOT_CMD.split('\n'):
+        if not line.strip():
+            continue
+        type_string(vnc, line)
+        vnc.keyPress('return')
+        time.sleep(1.5)
+    # Snapshot the shell right after typing (before/while the kernel
+    # boots) — debugging aid: the frame shows the typed command line.
+    try:
+        vnc.captureScreen(os.path.join(outdir, 'boot-typed.png'))
+    except Exception:  # noqa: BLE001 - best effort
+        pass
+    # The marker: typed once per build (the wrapper removes it when the
+    # watchdog starts). The worker is re-exec-ed per frame, so state only
+    # survives via this file.
+    with open(os.path.join(outdir, '.boot-typed'), 'w') as f:
+        f.write(time.ctime())
+
+
+def click_no(vnc, position):
+    vnc.mouseMove(*position)
+    time.sleep(0.3)
+    vnc.mousePress(1)
+    time.sleep(0.2)
+    vnc.mouseUp(1)
+    time.sleep(0.5)
+
+
+def shell_rescue(vnc):
+    """Boot the Windows ISO from the UEFI shell."""
+    for ch in 'fs0':
+        vnc.keyPress(ch)
+        time.sleep(0.25)
+    type_colon(vnc)
+    vnc.keyPress('return')
+    time.sleep(2.5)
+    for ch in r'EFI\BOOT\BOOTAA64.EFI':
+        vnc.keyPress(ch)
+        time.sleep(0.25)
+    vnc.keyPress('return')
+    time.sleep(1.5)
+    vnc.keyPress('spacebar')
+    time.sleep(0.5)
+    vnc.keyPress('spacebar')
+
+
+def find_no_button(ocr_text):
+    """OCR lines look like 'No | center=(487,381) box=(...)' — return the
+    center of the last line whose text is exactly 'No' (buttons sit at the
+    bottom of the dialog), or None."""
+    found = None
+    for line in ocr_text.splitlines():
+        if '|' not in line:
+            continue
+        label, _, rest = line.partition('|')
+        if label.strip().lower() != 'no':
+            continue
+        m = re.search(r'center=\((\d+),(\d+)\)', rest)
+        if m:
+            found = (int(m.group(1)), int(m.group(2)))
+    return found
+
+
+def run_worker(port, outdir, ocr, frame):
+    from vncdotool import api
+
+    vnc = api.connect(f'127.0.0.1::{port}', timeout=10)
+    try:
+        vnc.captureScreen(frame)
+        text = subprocess.run([ocr, frame], capture_output=True,
+                              text=True, timeout=50).stdout
+        actions = []
+        if 'Are you sure you want to quit?' in text:
+            actions.append('NO_CLICK')
+            pos = find_no_button(text) or NO_BUTTON_FALLBACK
+            click_no(vnc, pos)
+        if 'Press any key to boot from CD' in text:
+            actions.append('CD_KEY')
+            vnc.keyPress('spacebar')
+        if 'startup.nsh' in text or 'Shell>' in text or 'Shel1>' in text:
+            actions.append('SHELL_RESCUE')
+            shell_rescue(vnc)
+        if 'could not complete the installation' in text:
+            # Windows Setup (Win11, VMware Fusion): the first-boot pass
+            # failed ("Windows could not complete the installation. To
+            # install Windows on this computer, restart the
+            # installation."). Clicking OK only restarts the broken
+            # install — do not press anything; shout loudly instead, so
+            # the build log shows the real state instead of Packer
+            # spinning on "Waiting for WinRM" for 90 min. Diagnose from
+            # C:\Windows\Panther\setuperr.log / setupact.log on the disk.
+            actions.append('SETUP_FAILED')
+            log('WINDOWS SETUP FAILED: "Windows could not complete the '
+                'installation" dialog on screen — the build will hang at '
+                'WinRM. Check C:\\Windows\\Panther\\setuperr.log.')
+        if (BOOT_CMD and 'grub>' not in text
+                and 'Try or Install Ubuntu Server' not in text):
+            # keep silent: grub is not on screen yet
+            pass
+        elif BOOT_CMD and not os.path.exists(
+                os.path.join(outdir, '.boot-typed')):
+            # grub menu or shell is up: type the autoinstall command.
+            actions.append('AUTOINSTALL_BOOT')
+            type_boot_command(vnc, outdir, at_shell='grub>' in text)
+        log('actions: ' + (','.join(actions) if actions else 'none'))
+    finally:
+        vnc.disconnect()
+
+
+# --- supervisor: run the worker per frame with a hard timeout ---------------
+
+def main():
+    args = sys.argv[1:]
+    if args and args[0] in ('-h', '--help'):
+        print(__doc__)
+        return
+    if args and args[0] == '--worker':
+        # Re-exec'd by the supervisor: one capture cycle.
+        _, port, outdir, ocr, frame = args
+        run_worker(port, outdir, ocr, frame)
+        return
+
+    port, outdir, ocr = args
+    os.makedirs(outdir, exist_ok=True)
+    log(f'watching VNC port {port} (frames in {outdir})')
+    i = 0
+    fast_until = time.time() + FAST_POLL_MAX_SECONDS
+    try:
+        while True:
+            frame = os.path.join(outdir, f'w{i:04d}.png')
+            # Fast-poll while the Ubuntu autoinstall command still has to be
+            # typed (grub's menu countdown is only ~20 s wide); relax once
+            # typed or when a boot never reaches grub (hard cap, so a stuck
+            # interactive installer is watched at the gentle cadence).
+            boot_marker = os.path.join(outdir, '.boot-typed')
+            fast = bool(BOOT_CMD) and not os.path.exists(boot_marker) \
+                and time.time() < fast_until
+            try:
+                subprocess.run(
+                    [sys.executable, os.path.abspath(__file__), '--worker',
+                     port, outdir, ocr, frame],
+                    timeout=SLOW_POLL_WORKER_TIMEOUT)
+            except subprocess.TimeoutExpired:
+                log('worker timed out — skipping this frame')
+            except Exception as e:  # noqa: BLE001 - keep watching
+                log(f'error: {e}')
+            i += 1
+            time.sleep(FAST_POLL_INTERVAL if fast else SLOW_POLL_INTERVAL)
+    except KeyboardInterrupt:
+        log('stopping')
+
+
+if __name__ == '__main__':
+    main()

package/dist/cli.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+//
+// cli.ts — the agent-dev-env CLI entry point (commander).
+//
+// The surface is registered in commands/register.ts (small register
+// functions, one per group): the lifecycle commands (build/deploy/tag),
+// the diagnostic commands (list/status/doctor), and the VM commands
+// (run/stop/delete/sync/watch-build) — all implemented for every
+// platform; `sync` is limited to the tart/ssh2 transports (macos,
+// ubuntu-vmware).
+import { Command, CommanderError } from 'commander';
+import { createRequire } from 'node:module';
+import { registerDoctorCommands, registerLifecycleCommands, registerStatusCommands, registerVmCommands, } from './commands/register.js';
+import { logger } from './lib/logger.js';
+// dist/cli.js -> ../package.json is the package root; src/cli.ts ->
+// ../package.json is the repo root. Both work because package.json and
+// dist/ sit next to each other in the published npm package.
+const pkg = createRequire(import.meta.url)('../package.json');
+function buildProgram() {
+    const program = new Command();
+    program
+        .name('agent-dev-env')
+        .description('Sandbox VM runner and image lifecycle CLI. Builds, runs, and wires ' +
+        'up sandbox VMs (macOS via Tart, Windows via QEMU/VMware, Ubuntu via ' +
+        'VMware) and manages their image releases on GHCR.')
+        .version(pkg.version)
+        .showSuggestionAfterError();
+    registerVmCommands(program);
+    registerStatusCommands(program);
+    registerLifecycleCommands(program);
+    registerDoctorCommands(program);
+    // Errors: commander messages are printed by commander itself; our own
+    // throws go through die().
+    program.exitOverride();
+    return program;
+}
+async function main() {
+    const program = buildProgram();
+    try {
+        await program.parseAsync(process.argv);
+    }
+    catch (err) {
+        if (err instanceof CommanderError) {
+            process.exit(err.exitCode);
+        }
+        if (err instanceof Error) {
+            logger.die(err.message);
+        }
+        process.exit(1);
+    }
+}
+void main();