Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ VM (Ubuntu 24.04; XFCE desktop unless --headless)
| Component | Runs on | Role |
|---|---|---|
| `core/boxery-tools.mjs` | agent machine (or host, for HTTP MCP) | **The `vm_*` tool table**: name, description, JSON Schema and runner for every tool, plus `vm_manage`/`vm_info`/`vm_lease` action logic (hosts included) over front-end session hooks, and `runTool()`, which resolves each call's host and VM. MCP and pi are both built from it and run tools through it, so they can't drift (`test/frontends.test.mjs`: a tool only one front-end has must say why). `test/parity.test.mjs` maps every tool and action to its `boxery` command (or why it has none) and every command back, so the CLI can't silently fall behind either |
| `core/boxery-core.mjs`, `core/copy-stream.mjs`, `core/atomic-edit.mjs`, `core/shell.mjs` | same | Transport and tool implementation: `sshRun`/`execRemote` (remote process-group kill on cancel), path mapping, read/write/edit (atomic, detects concurrent changes), streaming tar `vm_copy` (local⇄VM⇄VM, across hosts), computer use via xdotool, Playwright over CDP, `LeaseKeeper`, host-profile resolution with `AsyncLocalStorage` |
| `core/boxery-core.mjs`, `core/copy-stream.mjs`, `core/sync.mjs` + `core/sync-guest.sh`, `core/atomic-edit.mjs`, `core/shell.mjs` | same | Transport and tool implementation: `sshRun`/`execRemote` (remote process-group kill on cancel), path mapping, read/write/edit (atomic, detects concurrent changes), streaming tar `vm_copy` (local⇄VM⇄VM, across hosts), `vm_sync` (a local git checkout → VM: `git push` over the VM's ssh connection, then a staged swap in the VM), computer use via xdotool, Playwright over CDP, `LeaseKeeper`, host-profile resolution with `AsyncLocalStorage` |
| `core/grants.mjs`, `core/grant-operations.mjs`, `core/grant-approval.mjs`, `core/grants-guest.sh` | agent machine | Shared spec/deny-directory validation and prompt text; grant store locking/edits, edge-route application and tmpfs reconciliation. Agent front-ends approve through elicitation/pi dialogs, then call operations in-process, without spawning the CLI. The guest script is a single reconciliation template with values inserted at apply time |
| `core/boxery-jobs.ts`, `core/boxery-job-runner.sh` | piped into the VM per call | Background jobs (`run --bg`, `jobs`, `logs`, `wait`, `kill`; `vm_jobs`). The helper is erasable TypeScript run by the VM's Node (type stripping, ≥ 22.18), never installed, so a VM always runs the caller's version; it answers in JSON. The runner is plain bash, sent with each start: it runs the command in its own process group, independent of tmux, and records the real exit code. |
| `backends/index.mjs` | agent machine and host | What each backend declares: supported and tested boxery-host platforms, runtimes, prerequisites and capabilities, as data (no probes). `host/capabilities.mjs` checks against it, `boxery-host backends`/`capabilities` print it, and `vm_info` lists it; it imports nothing. A backend without a declaration (one added as a `.sh` file) runs unchecked ([backends](docs/backends.md)) |
Expand Down
31 changes: 31 additions & 0 deletions controller/cli.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -262,6 +262,23 @@ async function cmdCp(s, args) {
await copy(s.host, args);
}

/** sync NAME [--from DIR] [--to PATH] [--json]: vm_sync's own code. Needs only the profile's ssh_config. @param {Selected} s @param {string[]} args @returns {Promise<void>} */
async function cmdSync(s, args) {
let name = "", from, to, json = false;
for (let i = 0; i < args.length; i++) {
const a = args[i], v = args[i + 1];
if (a === "--from") { if (v == null) die("--from needs a directory"); from = v; i++; }
else if (a === "--to") { if (v == null) die("--to needs a path"); to = v; i++; }
else if (a === "--json") json = true;
else if (a.startsWith("-")) die(`unknown flag ${a}`);
else if (name) usage("sync");
else name = a;
}
needVm(name);
const { sync } = await import("./sync.mjs");
await sync(s.host, name, { from, to, json });
}

/** version [--json] @param {Selected | null} s @param {string[]} args */
async function cmdVersion(s, args) {
const json = args[0] === "--json";
Expand Down Expand Up @@ -523,6 +540,20 @@ export const COMMANDS = {
status: {},
run: cmdCp,
},
sync: {
help: {
group: "use", summary: "push a local git checkout into a VM, so its tree matches exactly", usage: ["sync NAME [--from DIR] [--to PATH] [--json]"],
details: [
"git pushes the commits the VM lacks over its ssh connection, checks out the same commit (detached) and applies staged, unstaged and untracked changes, deletions included. Ignored files in the VM (node_modules, builds) stay. No git remote or GitHub access is needed on either side.",
"Refuses, changing nothing, when the VM checkout has changes the last sync didn't make, or the checkout holds a credential file (.env, .npmrc, auth files).",
],
flags: [["--from DIR", "Local checkout (default: the current directory)"], ["--to PATH", "VM directory (default ~/project; relative paths are under it)"], ["--json", "Print the result as JSON"]],
examples: [["This checkout into demo's ~/project", "boxery sync demo"], ["Another checkout, into ~/api (not inside ~/project, which is a checkout itself)", "boxery sync demo --from ../api --to ~/api"]],
seeAlso: ["cp"], docs: "sync.md",
},
status: { vm: true },
run: cmdSync,
},
desktop: {
help: { group: "use", summary: "open a VM's desktop in your browser (noVNC over ssh)", usage: ["desktop NAME [--no-open]"], flags: [["--no-open", "Print the URL instead of opening it"]], docs: "cli.md#desktop-and-ports" },
run: async (s, args) => { needHost(s); await cmdDesktop(s, args); },
Expand Down
31 changes: 31 additions & 0 deletions controller/sync.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
// boxery sync NAME: the CLI front-end of vm_sync. It runs the same TOOLS entry as the MCP server and the
// pi extension, so the transfer, refusals and result cannot drift (docs/sync.md).
import { constants } from "node:os";
import * as core from "../core/boxery-core.mjs";
import { TOOLS } from "../core/boxery-tools.mjs";
import { die, quit, say } from "./lib.mjs";
/** @import { Tool } from "../core/boxery-tools.mjs" */
/** @import { HostProfile } from "../core/boxery-core.mjs" */

/** @param {HostProfile} host @param {string} vm @param {{ from?: string, to?: string, json?: boolean }} opts */
export async function sync(host, vm, { from, to, json = false }) {
// Ctrl-C cancels like an MCP cancellation: before the VM applies anything, nothing changes there.
const abort = new AbortController();
let interrupted = 0;
// Once the VM has started applying, the sync finishes (or rolls back) there regardless; wait for its result.
const handlers = /** @type {const} */ (["SIGINT", "SIGTERM", "SIGHUP"]).map((sig) => /** @type {[NodeJS.Signals, () => void]} */ ([sig, () => {
if (!interrupted) process.stderr.write("boxery: stopping; if the VM is already applying the sync, it finishes or rolls back first\n");
interrupted = 128 + constants.signals[sig]; abort.abort();
}]));
for (const [sig, h] of handlers) process.on(sig, h);
const tool = /** @type {Tool} */ (TOOLS.find((t) => t.name === "vm_sync"));
try {
const r = await core.withHost(host, () => tool.run(vm, { from, to }, /** @type {any} */ ({ localCwd: process.cwd(), signal: abort.signal }) /* no session: vm_sync needs none */));
say(json ? JSON.stringify(r.structured) : r.text);
if (r.isError) quit(1);
} catch (/** @type {any} */ e) {
if (e?.exitCode !== undefined) throw e;
if (interrupted) { process.stderr.write(`boxery: ${e.message}\n`); quit(interrupted); }
die(e.message);
} finally { for (const [sig, h] of handlers) process.off(sig, h); }
}
7 changes: 4 additions & 3 deletions core/boxery-core.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,8 @@ export { q } from "./shell.mjs";
/** @typedef {{ name: string, dir: string, default: boolean, destination: string | null, backend: string | null, same_as: string[] }} HostDescription */
/** @typedef {{ host?: HostProfile, vm: string | null, path: string }} Loc */
/** env: ssh's environment (default: this process's); batch: false lets ssh ask (a terminal's passphrase).
* @typedef {{ input?: string | Buffer, signal?: AbortSignal, timeoutMs?: number, onData?: (d: Buffer) => void, maxBytes?: number, closePipes?: boolean, env?: NodeJS.ProcessEnv, batch?: boolean }} SshRunOpts */
* detached: ssh in its own process group, so a terminal's Ctrl-C doesn't cut off a remote step that must finish.
* @typedef {{ input?: string | Buffer, signal?: AbortSignal, timeoutMs?: number, onData?: (d: Buffer) => void, maxBytes?: number, closePipes?: boolean, env?: NodeJS.ProcessEnv, batch?: boolean, detached?: boolean }} SshRunOpts */
/** @typedef {{ code: number | null, stdout: Buffer, stderr: string }} SshResult */
/** @typedef {{ onData?: (d: Buffer) => void, signal?: AbortSignal, timeout?: number }} ExecRemoteOpts */
/** @typedef {{ exitCode: number | null }} ExecResult */
Expand Down Expand Up @@ -352,7 +353,7 @@ export function sshRun(vm, script, opts = {}) {
if (!existsSync(sshConf)) return reject(new Error(`boxery not set up (${sshConf} missing); run: boxery setup user@host`));
// stdin is a pipe whenever it is used (opts.input != null).
const child = /** @type {ChildProcessWithoutNullStreams} */ (spawn("ssh", ["-F", sshConf, ...(opts.batch === false ? [] : ["-o", "BatchMode=yes"]), `${vm}.boxery`, `bash -c ${q(script)}`], {
stdio: [opts.input != null ? "pipe" : "ignore", "pipe", "pipe"], ...(opts.env ? { env: opts.env } : {}),
stdio: [opts.input != null ? "pipe" : "ignore", "pipe", "pipe"], ...(opts.env ? { env: opts.env } : {}), ...(opts.detached ? { detached: true } : {}),
}));
/** @type {Buffer[]} */
const out = [];
Expand Down Expand Up @@ -890,7 +891,7 @@ export function copyRoot(dir, { deny = [] } = {}) {
* unless it is inside the root and neither inside nor containing a denied path.
* @param {LocalConfinement} confinement
*/
function confineLocal({ root, deny = [] }) {
export function confineLocal({ root, deny = [] }) {
const denied = copyDenied(deny);
const check = (/** @type {string} */ real, shown = real) => {
if (!isWithin(real, root)) throw new Error(`local:${shown} is outside the copy root ${root}`);
Expand Down
18 changes: 17 additions & 1 deletion core/boxery-tools.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
// Front-ends call runTool(), which resolves the call's host and VM against their Session and runs the
// tool on that host. ctx: { signal, session, host, current, localCwd, localCopy?, progress?, approve? }.
// progress(message) reports a status line while the tool runs (MCP progress notifications); front-ends
// without it pass nothing. localCopy limits vm_copy's local: endpoints (see copyTool); front-ends that run
// without it pass nothing. localCopy limits vm_copy's local: endpoints (see copyTool) and vm_sync's local checkout; front-ends that run
// on the user's own machine pass nothing.
// engine: pi runs this tool with its own built-in engine (same rendering/truncation as bash, read, …)
// noVm: the front-end does not resolve a VM; the tool gets every argument, `vm` included
Expand All @@ -16,6 +16,7 @@
// them only through the Session hooks.
import * as core from "./boxery-core.mjs";
import { BACKENDS as BACKEND_DECLARATIONS } from "../backends/index.mjs";
import { SYNC_OUTPUT, syncTool } from "./sync.mjs";
/** @import { Approve, HostProfile, LocalConfinement, ManageArgs, Progress, ToolResult } from "./boxery-core.mjs" */
/** A JSON Schema fragment. @typedef {{ type?: string | string[], description?: string, enum?: readonly string[], properties?: Record<string, JsonSchema>, items?: JsonSchema, required?: string[], anyOf?: JsonSchema[], minimum?: number, maximum?: number }} JsonSchema */
/** A tool's input schema: always an object with named properties. @typedef {JsonSchema & { type: "object", properties: Record<string, JsonSchema>, required: string[] }} ObjectSchema */
Expand Down Expand Up @@ -179,6 +180,21 @@ export const TOOLS = [
annotations: { destructiveHint: true, openWorldHint: false },
run: (_vm, a, x) => core.copyTool(a, { current: a.vm ?? x.current, localCwd: x.localCwd, local: x.localCopy, signal: x.signal }),
},
{
name: "vm_sync",
title: "VM sync",
description:
"Push a local git checkout into a VM so the VM's tree matches it exactly: same commit (detached HEAD), plus staged, unstaged and untracked changes, deletions included; the VM's ignored files (node_modules, builds) stay. " +
"Use it instead of vm_copy for a repository: it sends only what changed, needs no git remote or GitHub access, refuses VM-side edits it would overwrite, and reports whether lockfiles changed. " +
"It never syncs credentials: it refuses .env, .npmrc and other auth files (ask with vm_grant).",
parameters: obj({
from: { type: "string", description: "Local checkout (default: this agent's working directory)" },
to: { type: "string", description: `VM directory (default ${core.PROJECT}; relative paths are under it)` },
}),
annotations: { destructiveHint: true, idempotentHint: true, openWorldHint: false },
outputSchema: SYNC_OUTPUT,
run: (vm, a, x) => syncTool(vm, a, { localCwd: x.localCwd, local: x.localCopy, signal: x.signal }),
},
{
name: "vm_screenshot",
title: "VM screenshot",
Expand Down
Loading
Loading