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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrey Meshkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# agent-dev-env
+
+[![CI](https://github.com/ameshkov/agent-dev-env/actions/workflows/ci.yml/badge.svg)](https://github.com/ameshkov/agent-dev-env/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/agent-dev-env)](https://www.npmjs.com/package/agent-dev-env)
+[![GitHub release](https://img.shields.io/github/v/release/ameshkov/agent-dev-env)](https://github.com/ameshkov/agent-dev-env/releases)
+
+Local sandbox virtual machines for AI coding agents. A pre-built image with
+the full toolchain (macOS with Xcode/Homebrew, Windows 11 ARM64 with
+VS2022/toolchains, or Ubuntu 24.04 with the open-source toolchain; OpenCode,
+OpenCodeReview, OpenChamber, Docker CLI bridged to the host) runs on your
+Mac. Your code stays on the host — you share a working directory into the VM
+and let a coding agent work on it in an isolated sandbox. The
+[`agent-dev-env`](https://www.npmjs.com/package/agent-dev-env) CLI builds,
+runs, and wires up the sandboxes, and manages their image releases.
+
+**Currently supported:** macOS host on Apple Silicon → macOS (Tart),
+Windows 11 ARM64 (QEMU, VMware Fusion) and Ubuntu 24.04 LTS ARM64 (VMware
+Fusion) guests. Linux hosts are coming soon.
+
+## Quick start
+
+Try it without installing:
+
+```bash
+npx agent-dev-env doctor            # host + tooling check for every platform
+npx agent-dev-env run macos         # pull, boot, and wire up the macOS sandbox
+```
+
+Or install the CLI globally:
+
+```bash
+npm install -g agent-dev-env
+agent-dev-env run macos
+```
+
+Want the latest build from the `master` branch? The CI publishes a canary
+build on every push to npm under the `canary` dist-tag:
+
+```bash
+npm install -g agent-dev-env@canary
+```
+
+On first use the CLI asks before pulling the image (one-time, ~50 GB for
+macOS) and creating the working VM, then starts it with the recommended
+settings. Every guest gets the host's SSH agent and Docker engine bridged
+in; the macOS and Ubuntu guests additionally share your work directory and
+copy your user settings in. What works where differs per guest — see the
+[macOS guide](docs/macos.md), [Ubuntu guide](docs/ubuntu-vmware.md),
+[Windows QEMU guide](docs/windows-qemu.md) or
+[Windows VMware guide](docs/windows-vmware.md) for your OS, and the
+[CLI reference](docs/cli.md) for every command and option.
+
+> Tip: `agent-dev-env doctor` checks Tart/QEMU/Fusion/oras and free disk
+> before you start; the per-platform guides list the official install
+> commands.
+
+## Guides
+
+Pick the guide for your operating system:
+
+| Operating system | Guide |
+| --- | --- |
+| macOS (Apple Silicon) | [Set up your macOS sandbox](docs/macos.md) |
+| Ubuntu (VMware) | [Set up your Ubuntu sandbox](docs/ubuntu-vmware.md) |
+| Windows (QEMU) | [Set up your Windows sandbox](docs/windows-qemu.md) |
+| Windows (VMware) | [Set up your Windows VMware sandbox](docs/windows-vmware.md) |
+
+Each guide starts with a short quick setup — macOS takes four steps, the
+others three — and is all you need to have a sandbox with a coding agent
+running.
+
+## Documentation
+
+User guides and reference:
+
+- [docs/cli.md](docs/cli.md) — the `agent-dev-env` CLI reference: commands,
+  options, environment variables, paths.
+- [docs/macos.md](docs/macos.md) — user guide: pull, run, share code, run
+  the agent (macOS guest).
+- [docs/ubuntu-vmware.md](docs/ubuntu-vmware.md) — Ubuntu 24.04 (ARM64)
+  guest under VMware Fusion.
+- [docs/windows-qemu.md](docs/windows-qemu.md) — Windows 11 (ARM64) guest
+  under QEMU.
+- [docs/windows-vmware.md](docs/windows-vmware.md) — Windows 11 (ARM64)
+  guest under VMware Fusion.
+- [docs/ssh-agent.md](docs/ssh-agent.md) — how the SSH agent bridge shares
+  the host's passwords manager (Bitwarden, 1Password, ...) with the
+  sandbox.
+
+Image recipes — per-platform build/publish commands:
+
+- [images/mac/README.md](images/mac/README.md) — macOS images.
+- [images/windows-arm64-qemu/README.md](images/windows-arm64-qemu/README.md)
+  — Windows 11 ARM64 under QEMU.
+- [images/windows-arm64-vmware/README.md](images/windows-arm64-vmware/README.md)
+  — Windows 11 ARM64 under VMware.
+- [images/ubuntu-arm64-vmware/README.md](images/ubuntu-arm64-vmware/README.md)
+  — Ubuntu 24.04 ARM64 under VMware.
+
+For maintainers and contributors:
+
+- [AGENTS.md](AGENTS.md) — project map, how to build and use the CLI and
+  the images, releases/tags/changelogs, code guidelines.
+- [DEVELOPMENT.md](DEVELOPMENT.md) — prerequisites and how to build and
+  debug the CLI and the recipes.
+- [CHANGELOG.md](CHANGELOG.md) — the repo changelog.

package/dist/assets/bridge/bridge.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+
+// packages/bridge-core/src/bin.ts
+import { fileURLToPath } from "node:url";
+
+// packages/bridge-core/src/index.ts
+import { rmSync, writeFileSync } from "node:fs";
+
+// packages/bridge-core/src/endpoints.ts
+var PIPE_PREFIX = "\\\\.\\pipe\\";
+function parseEndpoint(spec) {
+  const sep = spec.indexOf(":");
+  if (sep <= 0) {
+    throw new Error(`invalid endpoint '${spec}' (expected unix:|pipe:|tcp:)`);
+  }
+  const scheme = spec.slice(0, sep);
+  const rest = spec.slice(sep + 1);
+  switch (scheme) {
+    case "unix": {
+      if (!rest) {
+        throw new Error(`invalid unix endpoint '${spec}': missing path`);
+      }
+      return { kind: "unix", path: rest };
+    }
+    case "pipe": {
+      if (!rest) {
+        throw new Error(`invalid pipe endpoint '${spec}': missing name`);
+      }
+      const name = rest.startsWith(PIPE_PREFIX) ? rest : `${PIPE_PREFIX}${rest}`;
+      return { kind: "pipe", name };
+    }
+    case "tcp": {
+      const m = /^([^:]+):(\d+)$/.exec(rest);
+      const port = m ? Number(m[2]) : NaN;
+      if (!m || !Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`invalid tcp endpoint '${spec}' (expected tcp:host:port, port 1-65535)`);
+      }
+      return { kind: "tcp", host: m[1], port };
+    }
+    default:
+      throw new Error(
+        `unknown endpoint scheme '${scheme}' in '${spec}' (expected unix:|pipe:|tcp:)`
+      );
+  }
+}
+function formatEndpoint(endpoint) {
+  switch (endpoint.kind) {
+    case "unix":
+      return `unix:${endpoint.path}`;
+    case "pipe":
+      return `pipe:${endpoint.name}`;
+    case "tcp":
+      return `tcp:${endpoint.host}:${endpoint.port}`;
+  }
+}
+
+// packages/bridge-core/src/forwarder.ts
+import net from "node:net";
+import { existsSync, unlinkSync } from "node:fs";
+function startForwarder(options) {
+  const sockets = /* @__PURE__ */ new Set();
+  const server = net.createServer((client) => {
+    sockets.add(client);
+    client.on("close", () => sockets.delete(client));
+    forwardConnection(client, options.forward, sockets);
+  });
+  return bind(server, options.listen).then(() => {
+    options.log?.(
+      `listening on ${formatEndpoint(options.listen)} \u2192 ${formatEndpoint(options.forward)}`
+    );
+    return {
+      close: () => closeForwarder(server, sockets, options.listen, options.log)
+    };
+  });
+}
+function forwardConnection(client, target, sockets) {
+  const upstream = connectTo(target);
+  sockets.add(upstream);
+  upstream.on("close", () => sockets.delete(upstream));
+  upstream.once("connect", () => {
+    client.pipe(upstream);
+    upstream.pipe(client);
+  });
+  const tearDown = () => {
+    client.destroy();
+    upstream.destroy();
+  };
+  upstream.once("error", tearDown);
+  client.once("error", () => {
+    upstream.destroy();
+  });
+}
+async function bind(server, endpoint) {
+  switch (endpoint.kind) {
+    case "unix":
+      if (existsSync(endpoint.path)) {
+        unlinkSync(endpoint.path);
+      }
+      await listen(server, endpoint.path);
+      break;
+    case "pipe":
+      await listen(server, endpoint.name);
+      break;
+    case "tcp":
+      await listen(server, { port: endpoint.port, host: endpoint.host });
+      break;
+  }
+}
+function listen(server, spec) {
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(spec, () => {
+      server.removeListener("error", reject);
+      resolve();
+    });
+  });
+}
+function connectTo(endpoint) {
+  switch (endpoint.kind) {
+    case "unix":
+      return net.connect({ path: endpoint.path });
+    case "pipe":
+      return net.connect({ path: endpoint.name });
+    case "tcp":
+      return net.connect({ port: endpoint.port, host: endpoint.host });
+  }
+}
+function closeForwarder(server, sockets, listen2, log) {
+  return new Promise((resolve) => {
+    for (const socket of sockets) {
+      socket.destroy();
+    }
+    server.close(() => {
+      if (listen2.kind === "unix" && existsSync(listen2.path)) {
+        unlinkSync(listen2.path);
+      }
+      log?.("closed");
+      resolve();
+    });
+  });
+}
+
+// packages/bridge-core/src/index.ts
+function parseBridgeArgs(argv) {
+  const values = /* @__PURE__ */ new Map();
+  for (let i = 0; i < argv.length; i += 2) {
+    const flag = argv[i];
+    if (flag === "--listen" || flag === "--forward" || flag === "--pidfile") {
+      values.set(flag, argv[i + 1] ?? "");
+    } else {
+      throw new Error(`unknown argument: ${flag}`);
+    }
+  }
+  const listenSpec = values.get("--listen");
+  const forwardSpec = values.get("--forward");
+  if (!listenSpec || !forwardSpec) {
+    throw new Error("usage: bridge --listen <endpoint> --forward <endpoint> [--pidfile PATH]");
+  }
+  const pidfile = values.get("--pidfile");
+  return {
+    listen: parseEndpoint(listenSpec),
+    forward: parseEndpoint(forwardSpec),
+    pidfile: pidfile || void 0
+  };
+}
+async function runBridge(options) {
+  const running = await startForwarder(options);
+  if (options.pidfile) {
+    writeFileSync(options.pidfile, `${process.pid}
+`);
+  }
+  await new Promise((resolve) => {
+    const stop = () => {
+      void running.close().then(() => {
+        if (options.pidfile) {
+          rmSync(options.pidfile, { force: true });
+        }
+        resolve();
+      });
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+  });
+  return 0;
+}
+async function main(argv) {
+  const args = parseBridgeArgs(argv);
+  return runBridge({
+    listen: args.listen,
+    forward: args.forward,
+    pidfile: args.pidfile,
+    log: (message) => process.stderr.write(`${message}
+`)
+  });
+}
+
+// packages/bridge-core/src/bin.ts
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  void main(process.argv.slice(2)).then((code) => {
+    process.exit(code);
+  });
+}