vmsan 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/_chunks/create.mjs

@@ -1,19 +1,16 @@
-import { n as vmsanPaths } from "./paths.mjs";
-import { t as handleCommandError, z as mutuallyExclusiveFlagsError } from "./errors.mjs";
+import "./paths.mjs";
+import { t as handleCommandError } from "./errors.mjs";
 import { i as initVmsanLogger, n as createScopedLogger, t as createCommandLogger } from "./logger.mjs";
-import { t as FirecrackerClient } from "./firecracker.mjs";
-import { n as generateVmId, t as FileVmStateStore } from "./vm-state.mjs";
-import { a as getVmPid, c as NetworkManager, n as findKernel, o as validateEnvironment, r as findRootfs, s as waitForSocket } from "./environment.mjs";
-import { a as Jailer, i as markVmAsError, n as cleanupNetwork, r as killOrphanVmProcess, t as cleanupChroot } from "./cleanup.mjs";
+import "./vm-state.mjs";
+import { t as createVmsan } from "./context.mjs";
+import "./firecracker.mjs";
+import "./timeout-killer.mjs";
+import { n as waitForAgent } from "./vm-context.mjs";
 import { t as ShellSession } from "./shell.mjs";
 import { a as parseImageReference, t as parseBandwidth } from "./validation.mjs";
-import { a as buildInitialVmState, i as buildCreateSummaryLines, o as parseCreateInput, r as ensureSeccompFilter, t as resolveImageRootfs } from "./image-rootfs.mjs";
-import { t as waitForAgent } from "./connect.mjs";
+import { n as parseCreateInput, t as buildCreateSummaryLines } from "./summary.mjs";
 import { join } from "node:path";
-import { spawn } from "node:child_process";
 import { consola } from "consola";
-import { existsSync } from "node:fs";
-import { randomBytes } from "node:crypto";
 import { defineCommand } from "citty";
 const createCommandArgs = {
 	vcpus: {
@@ -118,13 +115,6 @@ const createCommandArgs = {
 	}
 };
 const RUNTIME_DEFAULT_IMAGES = { "node22-demo": "node:22" };
-function createLifecycleState() {
-	return {
-		networkConfig: void 0,
-		vmId: void 0,
-		chrootDir: void 0
-	};
-}
 const createCommand = defineCommand({
 	meta: {
 		name: "create",
@@ -135,161 +125,45 @@ const createCommand = defineCommand({
 		const commandArgs = args;
 		if (commandArgs.silent) initVmsanLogger("silent");
 		const cmdLog = createCommandLogger("create");
-		const lifecycle = createLifecycleState();
-		const paths = vmsanPaths();
-		const store = new FileVmStateStore(paths.vmsDir);
 		try {
-			const baseDir = paths.baseDir;
-			validateEnvironment(baseDir);
-			if (commandArgs["from-image"] && commandArgs.rootfs) throw mutuallyExclusiveFlagsError("--from-image", "--rootfs");
-			const parsedInput = parseCreateInput(commandArgs, paths);
+			const vmsan = await createVmsan();
+			const parsedInput = parseCreateInput(commandArgs, vmsan.paths);
 			const defaultImage = RUNTIME_DEFAULT_IMAGES[parsedInput.runtime];
 			if (defaultImage && !commandArgs["from-image"] && !commandArgs.rootfs) {
 				commandArgs["from-image"] = defaultImage;
 				consola.info(`Runtime "${parsedInput.runtime}" auto-selected image: ${defaultImage}`);
 			}
 			if (parsedInput.runtime === "node22-demo" && parsedInput.ports.length === 0) consola.warn("Runtime node22-demo serves a welcome page, but no --publish-port was specified. The page won't be accessible externally.");
-			const kernelPath = typeof commandArgs.kernel === "string" ? commandArgs.kernel : findKernel(baseDir);
-			consola.debug(`Kernel resolved: ${kernelPath}`);
-			let rootfsPath;
-			if (typeof commandArgs["from-image"] === "string") rootfsPath = resolveImageRootfs(parseImageReference(commandArgs["from-image"]), paths.registryDir);
-			else rootfsPath = typeof commandArgs.rootfs === "string" ? commandArgs.rootfs : findRootfs(baseDir);
-			consola.debug(`Rootfs resolved: ${rootfsPath}`);
 			if (parsedInput.domains.length > 0) consola.warn("Domain filtering is DNS-based best effort. Direct-IP and DoH traffic may bypass allow-lists.");
 			const bandwidthMbit = parseBandwidth(commandArgs.bandwidth);
-			lifecycle.vmId = generateVmId();
-			const log = createScopedLogger(lifecycle.vmId);
-			const slot = store.allocateNetworkSlot();
-			consola.debug(`Network slot allocated: ${slot}`);
-			const netnsName = commandArgs["no-netns"] ? void 0 : `vmsan-${lifecycle.vmId}`;
-			const net = new NetworkManager(slot, parsedInput.networkPolicy, parsedInput.domains, parsedInput.allowedCidrs, parsedInput.deniedCidrs, parsedInput.ports, bandwidthMbit, netnsName);
-			lifecycle.networkConfig = net.config;
-			log.start(`Creating VM ${lifecycle.vmId}...`);
-			const agentToken = existsSync(paths.agentBin) ? randomBytes(32).toString("hex") : null;
-			const state = buildInitialVmState({
-				vmId: lifecycle.vmId,
-				project: commandArgs.project || "",
-				runtime: parsedInput.runtime,
-				diskSizeGb: parsedInput.diskSizeGb,
-				kernelPath,
-				rootfsPath,
+			const fromImage = commandArgs["from-image"] ? parseImageReference(commandArgs["from-image"]) : void 0;
+			const result = await vmsan.create({
 				vcpus: parsedInput.vcpus,
 				memMib: parsedInput.memMib,
+				diskSizeGb: parsedInput.diskSizeGb,
+				kernelPath: typeof commandArgs.kernel === "string" ? commandArgs.kernel : void 0,
+				rootfsPath: typeof commandArgs.rootfs === "string" ? commandArgs.rootfs : void 0,
+				fromImage,
+				project: commandArgs.project || "",
+				runtime: parsedInput.runtime,
 				networkPolicy: parsedInput.networkPolicy,
 				domains: parsedInput.domains,
 				allowedCidrs: parsedInput.allowedCidrs,
 				deniedCidrs: parsedInput.deniedCidrs,
 				ports: parsedInput.ports,
-				tapDevice: lifecycle.networkConfig.tapDevice,
-				hostIp: lifecycle.networkConfig.hostIp,
-				guestIp: lifecycle.networkConfig.guestIp,
-				subnetMask: lifecycle.networkConfig.subnetMask,
-				macAddress: lifecycle.networkConfig.macAddress,
-				snapshotId: parsedInput.snapshotId,
-				timeoutMs: parsedInput.timeoutMs,
-				agentToken,
-				agentPort: paths.agentPort,
 				bandwidthMbit,
-				netnsName
+				disableNetns: commandArgs["no-netns"],
+				disableSeccomp: commandArgs["no-seccomp"],
+				disablePidNs: commandArgs["no-pid-ns"],
+				disableCgroup: commandArgs["no-cgroup"],
+				timeoutMs: parsedInput.timeoutMs ?? void 0,
+				snapshotId: parsedInput.snapshotId ?? void 0
 			});
-			store.save(state);
-			log.start("Setting up networking...");
-			await net.setup();
-			log.success(`Network: TAP ${lifecycle.networkConfig.tapDevice}, Host ${lifecycle.networkConfig.hostIp}, Guest ${lifecycle.networkConfig.guestIp}`);
-			log.start("Preparing chroot...");
-			const snapshotConfig = parsedInput.snapshotId ? {
-				snapshotFile: join(paths.snapshotsDir, parsedInput.snapshotId, "snapshot_file"),
-				memFile: join(paths.snapshotsDir, parsedInput.snapshotId, "mem_file")
-			} : void 0;
-			const jailer = new Jailer(lifecycle.vmId, paths.jailerBaseDir);
-			const welcomePage = parsedInput.runtime === "node22-demo" && parsedInput.ports.length > 0 ? {
-				vmId: lifecycle.vmId,
-				ports: parsedInput.ports
-			} : void 0;
-			const agentConfig = agentToken ? {
-				binaryPath: paths.agentBin,
-				token: agentToken,
-				port: paths.agentPort,
-				vmId: lifecycle.vmId
-			} : void 0;
-			const jailerPaths = jailer.prepare({
-				kernelSrc: kernelPath,
-				rootfsSrc: rootfsPath,
-				diskSizeGb: parsedInput.diskSizeGb,
-				snapshot: snapshotConfig,
-				welcomePage,
-				agent: agentConfig
-			});
-			lifecycle.chrootDir = jailerPaths.chrootDir;
-			store.update(lifecycle.vmId, {
-				chrootDir: jailerPaths.chrootDir,
-				apiSocket: jailerPaths.socketPath
-			});
-			consola.debug(`Jailer chroot: ${jailerPaths.chrootDir}`);
-			consola.debug(`API socket path: ${jailerPaths.socketPath}`);
-			log.start("Spawning Firecracker via jailer...");
-			const firecrackerBin = join(baseDir, "bin", "firecracker");
-			const jailerBin = join(baseDir, "bin", "jailer");
-			const seccompFilter = commandArgs["no-seccomp"] ? void 0 : ensureSeccompFilter(paths);
-			if (seccompFilter) consola.debug(`Seccomp filter: ${seccompFilter}`);
-			const cgroup = commandArgs["no-cgroup"] ? void 0 : {
-				cpuQuotaUs: parsedInput.vcpus * 1e5,
-				cpuPeriodUs: 1e5,
-				memoryBytes: parsedInput.memMib * 1024 * 1024
-			};
-			jailer.spawn({
-				firecrackerBin,
-				jailerBin,
-				chrootBase: jailerPaths.chrootBase,
-				seccompFilter: seccompFilter ?? void 0,
-				newPidNs: !commandArgs["no-pid-ns"],
-				cgroup,
-				netns: netnsName
-			});
-			log.start("Waiting for API socket...");
-			await waitForSocket(jailerPaths.socketPath, 5e3);
-			log.success("API socket ready");
-			const vm = new FirecrackerClient(jailerPaths.socketPath);
-			if (parsedInput.snapshotId) {
-				log.start("Restoring from snapshot...");
-				await vm.loadSnapshot("snapshot/snapshot_file", "snapshot/mem_file");
-				await vm.resume();
-				log.success("Snapshot restored and VM resumed");
-			} else {
-				const bootArgs = NetworkManager.bootArgs(slot);
-				consola.debug(`Boot args: ${bootArgs}`);
-				await vm.boot("kernel/vmlinux", bootArgs);
-				await vm.addDrive("rootfs", "rootfs/rootfs.ext4", true, false);
-				await vm.configure(parsedInput.vcpus, parsedInput.memMib);
-				await vm.addNetwork("eth0", lifecycle.networkConfig.tapDevice, lifecycle.networkConfig.macAddress);
-				log.start("Starting VM...");
-				await vm.start();
-			}
-			const pid = getVmPid(lifecycle.vmId);
-			consola.debug(`Firecracker PID: ${pid ?? "unknown"}`);
-			store.update(lifecycle.vmId, {
-				status: "running",
-				pid
-			});
-			log.success(`VM ${lifecycle.vmId} is running (PID: ${pid || "unknown"})`);
-			if (parsedInput.timeoutMs && pid) {
-				const stateFile = join(paths.vmsDir, `${lifecycle.vmId}.json`);
-				spawn("bash", ["-c", [
-					`sleep ${Math.ceil(parsedInput.timeoutMs / 1e3)}`,
-					`STATE=$(cat "${stateFile}" 2>/dev/null) || exit 0`,
-					`echo "$STATE" | grep -q '"status":"running"' || exit 0`,
-					`echo "$STATE" | grep -q '"pid":${pid}' || exit 0`,
-					`[ -d /proc/${pid} ] || exit 0`,
-					`grep -q "${lifecycle.vmId}" /proc/${pid}/cmdline 2>/dev/null || exit 0`,
-					`kill ${pid} 2>/dev/null`
-				].join(" && ")], {
-					detached: true,
-					stdio: "ignore"
-				}).unref();
-			}
+			const log = createScopedLogger(result.vmId);
+			const state = result.state;
 			const summaryLines = buildCreateSummaryLines({
-				vmId: lifecycle.vmId,
-				pid,
+				vmId: result.vmId,
+				pid: result.pid,
 				vcpus: parsedInput.vcpus,
 				memMib: parsedInput.memMib,
 				runtime: parsedInput.runtime,
@@ -300,50 +174,44 @@ const createCommand = defineCommand({
 				allowedCidrs: parsedInput.allowedCidrs,
 				deniedCidrs: parsedInput.deniedCidrs,
 				ports: parsedInput.ports,
-				kernelPath,
-				rootfsPath,
+				kernelPath: state.kernel,
+				rootfsPath: state.rootfs,
 				snapshotId: parsedInput.snapshotId,
 				timeout: commandArgs.timeout,
-				socketPath: jailerPaths.socketPath,
-				chrootDir: jailerPaths.chrootDir,
-				tapDevice: lifecycle.networkConfig.tapDevice,
-				hostIp: lifecycle.networkConfig.hostIp,
-				guestIp: lifecycle.networkConfig.guestIp,
-				macAddress: lifecycle.networkConfig.macAddress,
-				stateFilePath: join(paths.vmsDir, `${lifecycle.vmId}.json`)
+				socketPath: state.apiSocket,
+				chrootDir: state.chrootDir,
+				tapDevice: state.network.tapDevice,
+				hostIp: state.network.hostIp,
+				guestIp: state.network.guestIp,
+				macAddress: state.network.macAddress,
+				stateFilePath: join(vmsan.paths.vmsDir, `${result.vmId}.json`)
 			});
 			log.box(summaryLines.join("\n"));
 			cmdLog.set({
-				vmId: lifecycle.vmId,
+				vmId: result.vmId,
 				vcpus: parsedInput.vcpus,
 				memMib: parsedInput.memMib,
 				runtime: parsedInput.runtime,
 				networkPolicy: parsedInput.networkPolicy,
-				guestIp: lifecycle.networkConfig.guestIp,
-				pid,
-				kernel: kernelPath,
-				rootfs: rootfsPath,
+				guestIp: state.network.guestIp,
+				pid: result.pid,
+				kernel: state.kernel,
+				rootfs: state.rootfs,
 				diskSizeGb: parsedInput.diskSizeGb
 			});
 			cmdLog.emit();
-			if (commandArgs.connect && lifecycle.networkConfig && agentToken) {
+			if (commandArgs.connect && state.agentToken) {
 				log.start("Waiting for agent to become ready...");
-				await waitForAgent(lifecycle.networkConfig.guestIp, paths.agentPort);
+				await waitForAgent(state.network.guestIp, vmsan.paths.agentPort);
 				log.success("Agent is ready. Connecting via PTY shell...");
 				const shell = new ShellSession({
-					host: lifecycle.networkConfig.guestIp,
-					port: paths.agentPort,
-					token: agentToken
+					host: state.network.guestIp,
+					port: vmsan.paths.agentPort,
+					token: state.agentToken
 				});
-				if (!(await shell.connect()).sessionDestroyed && shell.sessionId) process.stderr.write(`\nResume this session with:\n  vmsan connect ${lifecycle.vmId} --session ${shell.sessionId}\n`);
+				if (!(await shell.connect()).sessionDestroyed && shell.sessionId) process.stderr.write(`\nResume this session with:\n  vmsan connect ${result.vmId} --session ${shell.sessionId}\n`);
 			}
 		} catch (error) {
-			if (lifecycle.vmId) {
-				killOrphanVmProcess(lifecycle.vmId);
-				markVmAsError(lifecycle.vmId, error, paths);
-			}
-			cleanupNetwork(lifecycle.networkConfig);
-			cleanupChroot(lifecycle.chrootDir);
 			handleCommandError(error, cmdLog);
 			process.exitCode = 1;
 		}

package/dist/_chunks/download.mjs

@@ -1,12 +1,12 @@
 import { n as vmsanPaths } from "./paths.mjs";
-import { b as vmNotFoundError, t as handleCommandError } from "./errors.mjs";
+import { t as handleCommandError } from "./errors.mjs";
 import { t as createCommandLogger } from "./logger.mjs";
+import "./vm-state.mjs";
 import { t as AgentClient } from "./agent.mjs";
-import { t as FileVmStateStore } from "./vm-state.mjs";
-import { t as waitForAgent } from "./connect.mjs";
-import { basename, resolve } from "node:path";
+import { n as waitForAgent, t as resolveVmState } from "./vm-context.mjs";
+import { basename, join, resolve } from "node:path";
+import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
 import { consola } from "consola";
-import { writeFileSync } from "node:fs";
 import { defineCommand } from "citty";
 const downloadCommand = defineCommand({
 	meta: {
@@ -29,23 +29,8 @@ const downloadCommand = defineCommand({
 		const cmdLog = createCommandLogger("download");
 		const paths = vmsanPaths();
 		try {
-			const state = new FileVmStateStore(paths.vmsDir).load(args.vmId);
-			if (!state) throw vmNotFoundError(args.vmId);
-			if (state.status !== "running") {
-				consola.error(`VM ${args.vmId} is not running (status: ${state.status})`);
-				cmdLog.emit();
-				process.exitCode = 1;
-				return;
-			}
-			if (!state.agentToken) {
-				consola.error("VM has no agent token. Cannot download files without the agent.");
-				cmdLog.emit();
-				process.exitCode = 1;
-				return;
-			}
+			const { state, guestIp, port } = resolveVmState(args.vmId, paths);
 			const log = consola.withTag(args.vmId);
-			const guestIp = state.network.guestIp;
-			const port = state.agentPort || paths.agentPort;
 			consola.debug(`Agent endpoint: ${guestIp}:${port}`);
 			log.start("Waiting for agent...");
 			await waitForAgent(guestIp, port);
@@ -66,7 +51,14 @@ const downloadCommand = defineCommand({
 				process.exitCode = 1;
 				return;
 			}
-			const localPath = args.dest ? resolve(args.dest) : resolve(basename(remotePath));
+			let localPath;
+			if (args.dest) {
+				const resolved = resolve(args.dest);
+				if (args.dest.endsWith("/") || existsSync(resolved) && statSync(resolved).isDirectory()) {
+					mkdirSync(resolved, { recursive: true });
+					localPath = join(resolved, basename(remotePath));
+				} else localPath = resolved;
+			} else localPath = resolve(basename(remotePath));
 			writeFileSync(localPath, data);
 			log.success(`Downloaded to ${localPath} (${data.length} bytes)`);
 			cmdLog.set({

package/dist/_chunks/errors.mjs

@@ -122,10 +122,16 @@ const chrootNotFoundError = (vmId) => new VmError("ERR_VM_CHROOT_NOT_FOUND", {
 	fix: "The VM must be recreated with 'vmsan create'."
 });
 const networkSlotsExhaustedError = () => new VmError("ERR_VM_NETWORK_SLOTS_EXHAUSTED", { message: "No available network slots (max 255 VMs)" });
-const vmNotRunningError = (vmId) => new VmError("ERR_VM_NOT_RUNNING", {
+const vmNotRunningError = (vmId, currentStatus) => new VmError("ERR_VM_NOT_RUNNING", {
 	vmId,
-	message: `VM ${vmId} is not running`,
-	fix: "The VM must be running to update its network policy. Start it with 'vmsan start <vm-id>'."
+	message: currentStatus ? `VM ${vmId} is not running (current status: ${currentStatus})` : `VM ${vmId} is not running`,
+	fix: "The VM must be running. Start it with 'vmsan start <vm-id>'."
+});
+const vmNoAgentTokenError = (vmId) => new VmError("ERR_VM_NO_AGENT_TOKEN", {
+	vmId,
+	message: `VM ${vmId} has no agent token`,
+	why: "The vmsan-agent binary was not found at ~/.vmsan/bin/vmsan-agent when this VM was created.",
+	fix: "Install the agent binary into ~/.vmsan/bin/vmsan-agent and recreate the VM with 'vmsan create'."
 });
 const snapshotNotFoundError = (snapshotId) => new VmError("ERR_VM_SNAPSHOT_NOT_FOUND", { message: `Snapshot not found: ${snapshotId}` });
 var FirecrackerApiError = class extends VmsanError {
@@ -197,7 +203,7 @@ var SetupError = class extends VmsanError {
 		this.name = "SetupError";
 	}
 };
-const INSTALL_FIX = `Run the install script to set up all dependencies:\n\ncurl -fsSL https://raw.githubusercontent.com/angelorc/vmsan/main/install.sh | bash`;
+const INSTALL_FIX = `Run the install script to set up all dependencies:\n\ncurl -fsSL https://vmsan.dev/install | bash`;
 const missingBinaryError = (binary, path) => new SetupError("ERR_SETUP_MISSING_BINARY", {
 	message: `${binary} not found at ${path}`,
 	fix: INSTALL_FIX
@@ -229,4 +235,4 @@ function handleCommandError(error, cmdLog) {
 		if (error.link) consola.log(`  More: ${error.link}`);
 	} else consola.error(error instanceof Error ? error.message : String(error));
 }
-export { invalidDomainError as A, policyConflictError as B, vmStateNotFoundError as C, invalidCidrPrefixError as D, invalidCidrOctetError as E, invalidIntegerFlagError as F, VmsanError as H, invalidNetworkPolicyError as I, invalidPortError as L, invalidDurationError as M, invalidImageRefEmptyError as N, invalidDiskSizeFormatError as O, invalidImageRefTagError as P, invalidRuntimeError as R, vmNotStoppedError as S, invalidCidrFormatError as T, portConflictError as V, chrootNotFoundError as _, noKernelDirError as a, vmNotFoundError as b, TimeoutError as c, socketTimeoutError as d, NetworkError as f, VmError as g, firecrackerApiError as h, noExt4RootfsError as i, invalidDomainPatternError as j, invalidDiskSizeRangeError as k, agentTimeoutError as l, FirecrackerApiError as m, SetupError as n, noKernelError as o, defaultInterfaceNotFoundError as p, missingBinaryError as r, noRootfsDirError as s, handleCommandError as t, lockTimeoutError as u, networkSlotsExhaustedError as v, ValidationError as w, vmNotRunningError as x, snapshotNotFoundError as y, mutuallyExclusiveFlagsError as z };
+export { invalidDiskSizeRangeError as A, mutuallyExclusiveFlagsError as B, vmNotStoppedError as C, invalidCidrOctetError as D, invalidCidrFormatError as E, invalidImageRefTagError as F, portConflictError as H, invalidIntegerFlagError as I, invalidNetworkPolicyError as L, invalidDomainPatternError as M, invalidDurationError as N, invalidCidrPrefixError as O, invalidImageRefEmptyError as P, invalidPortError as R, vmNotRunningError as S, ValidationError as T, VmsanError as U, policyConflictError as V, chrootNotFoundError as _, noKernelDirError as a, vmNoAgentTokenError as b, TimeoutError as c, socketTimeoutError as d, NetworkError as f, VmError as g, firecrackerApiError as h, noExt4RootfsError as i, invalidDomainError as j, invalidDiskSizeFormatError as k, agentTimeoutError as l, FirecrackerApiError as m, SetupError as n, noKernelError as o, defaultInterfaceNotFoundError as p, missingBinaryError as r, noRootfsDirError as s, handleCommandError as t, lockTimeoutError as u, networkSlotsExhaustedError as v, vmStateNotFoundError as w, vmNotFoundError as x, snapshotNotFoundError as y, invalidRuntimeError as z };

package/dist/_chunks/exec.mjs

@@ -0,0 +1,190 @@
+import { n as vmsanPaths } from "./paths.mjs";
+import { t as handleCommandError } from "./errors.mjs";
+import { t as createCommandLogger } from "./logger.mjs";
+import "./vm-state.mjs";
+import "./timeout-killer.mjs";
+import { t as AgentClient } from "./agent.mjs";
+import { t as TimeoutExtender } from "./timeout-extender.mjs";
+import { n as waitForAgent, t as resolveVmState } from "./vm-context.mjs";
+import { t as ShellSession } from "./shell.mjs";
+import { consola } from "consola";
+import { defineCommand } from "citty";
+import { isatty } from "node:tty";
+function shellEscape(s) {
+	if (/^[a-zA-Z0-9._\-/=:@]+$/.test(s)) return s;
+	return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+function parseEnvFlags(targetCommand) {
+	const env = {};
+	const argv = process.argv;
+	let positionalCount = 0;
+	for (let i = 2; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === "--") break;
+		if (!arg.startsWith("-")) {
+			positionalCount++;
+			if (positionalCount >= 3) break;
+			continue;
+		}
+		let value;
+		if (arg === "--env" || arg === "-e") {
+			value = argv[i + 1];
+			if (value !== void 0) i++;
+		} else if (arg.startsWith("--env=")) value = arg.slice(6);
+		else if (arg.startsWith("-e=")) value = arg.slice(3);
+		if (value !== void 0) {
+			const eqIdx = value.indexOf("=");
+			if (eqIdx > 0) env[value.slice(0, eqIdx)] = value.slice(eqIdx + 1);
+		}
+	}
+	return env;
+}
+function buildVmsanPrompt(vmId) {
+	return `\\[\\033[1;32m\\]vmsan:${vmId.slice(0, 8)}\\[\\033[0m\\]:\\[\\033[1;34m\\]\\w\\[\\033[0m\\]\\$ `;
+}
+const execCommand = defineCommand({
+	meta: {
+		name: "exec",
+		description: "Execute a command inside a running VM"
+	},
+	args: {
+		vmId: {
+			type: "positional",
+			description: "VM ID, followed by command and arguments",
+			required: true
+		},
+		sudo: {
+			type: "boolean",
+			default: false,
+			description: "Run with extended privileges (sudo)"
+		},
+		interactive: {
+			type: "boolean",
+			alias: "i",
+			default: false,
+			description: "Interactive shell mode (PTY)"
+		},
+		"no-extend-timeout": {
+			type: "boolean",
+			default: false,
+			description: "Skip timeout extension (interactive only)"
+		},
+		tty: {
+			type: "boolean",
+			alias: "t",
+			default: false,
+			description: "Allocate a pseudo-TTY (accepted for compatibility)"
+		},
+		workdir: {
+			type: "string",
+			alias: "w",
+			description: "Working directory inside the VM"
+		},
+		env: {
+			type: "string",
+			alias: "e",
+			description: "Environment variable (KEY=VAL), repeatable"
+		}
+	},
+	async run({ args }) {
+		const cmdLog = createCommandLogger("exec");
+		const paths = vmsanPaths();
+		try {
+			const command = args._[1];
+			const commandArgs = args._.slice(2);
+			if (!command) {
+				consola.error("No command provided. Usage: vmsan exec <vm_id> <command> [...args]");
+				cmdLog.emit();
+				process.exitCode = 1;
+				return;
+			}
+			if (args.interactive && !isatty(1)) {
+				consola.error("--interactive requires a terminal (TTY).");
+				process.exitCode = 1;
+				return;
+			}
+			const envVars = parseEnvFlags(command);
+			const { state, guestIp, port, store } = resolveVmState(args.vmId, paths);
+			consola.debug(`Agent endpoint: ${guestIp}:${port}`);
+			consola.debug(`Waiting for agent on ${guestIp}:${port}...`);
+			await waitForAgent(guestIp, port);
+			if (args.interactive) {
+				const parts = [];
+				parts.push(`export PS1=${shellEscape(buildVmsanPrompt(args.vmId))} TERM=xterm-256color &&`);
+				if (args.workdir) parts.push(`cd ${shellEscape(args.workdir)} &&`);
+				for (const [key, val] of Object.entries(envVars)) parts.push(`${key}=${shellEscape(val)}`);
+				parts.push(shellEscape(command));
+				for (const a of commandArgs) parts.push(shellEscape(a));
+				const injectedCmd = "clear; " + parts.join(" ") + "; exit $?\n";
+				let extender = null;
+				if (!args["no-extend-timeout"] && state.timeoutMs) {
+					extender = new TimeoutExtender({
+						vmId: args.vmId,
+						store,
+						paths
+					});
+					extender.start();
+				}
+				try {
+					await new ShellSession({
+						host: guestIp,
+						port,
+						token: state.agentToken,
+						initialCommand: injectedCmd,
+						user: args.sudo ? "root" : void 0
+					}).connect();
+				} finally {
+					extender?.stop();
+				}
+				cmdLog.set({
+					vmId: args.vmId,
+					mode: "interactive",
+					command,
+					args: commandArgs,
+					...args["no-extend-timeout"] && { noExtendTimeout: true }
+				});
+				cmdLog.emit();
+			} else {
+				consola.debug(`exec: ${command} ${commandArgs.join(" ")}`);
+				const agent = new AgentClient(`http://${guestIp}:${port}`, state.agentToken);
+				const params = {
+					cmd: command,
+					args: commandArgs.length > 0 ? commandArgs : void 0,
+					cwd: args.workdir || void 0,
+					env: Object.keys(envVars).length > 0 ? envVars : void 0,
+					user: args.sudo ? "root" : void 0
+				};
+				const ac = new AbortController();
+				const onSignal = () => ac.abort();
+				process.on("SIGINT", onSignal);
+				process.on("SIGTERM", onSignal);
+				try {
+					const result = await (await agent.exec(params, {
+						signal: ac.signal,
+						onStdout: (line) => process.stdout.write(line + "\n"),
+						onStderr: (line) => process.stderr.write(line + "\n")
+					})).wait();
+					process.exitCode = result.exitCode;
+					if (result.timedOut) consola.error("Command timed out.");
+				} catch (err) {
+					if (!ac.signal.aborted) throw err;
+					process.exitCode = 130;
+				} finally {
+					process.removeListener("SIGINT", onSignal);
+					process.removeListener("SIGTERM", onSignal);
+				}
+				cmdLog.set({
+					vmId: args.vmId,
+					mode: "non-interactive",
+					command,
+					args: commandArgs
+				});
+				cmdLog.emit();
+			}
+		} catch (error) {
+			handleCommandError(error, cmdLog);
+			process.exitCode = 1;
+		}
+	}
+});
+export { execCommand as default };