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

package/dist/lib/tart.js

@@ -0,0 +1,210 @@
+// tart.ts — tart invocation wrappers, the unified replacement for the
+// scattered `tart list`/`ip`/`clone`/`set`/`run`/`stop`/`exec`/`pull`
+// calls in the macOS runner/stop/delete/sync shell scripts (and the
+// parsing in commands/status.ts).
+//
+// The arg builders and parsers are pure and unit-tested; the wrappers
+// themselves stay thin (run + error translation). Throwing happens at
+// the caller boundary like the shell's `|| die` — the wrappers report
+// raw results, the runners turn them into the legacy messages.
+import { commandExists, run, sleep } from './exec.js';
+/** True when tart is on PATH (doctor/run preflight check). */
+export function tartAvailable() {
+    return commandExists('tart');
+}
+/** @internal — Parses `tart list` rows into a name → state map
+ *  (exported for the co-located unit tests; callers use listVms()).
+ *
+ * `tart list` prints one row per VM: `source name disk used … state` —
+ * the name is the second column, the state the last one. Header lines
+ * (starting with `Source`) and blank lines are skipped.
+ *
+ * @param output - The raw stdout of `tart list`.
+ * @returns Map of VM name → state (e.g. `running`, `stopped`).
+ */
+export function parseTartList(output) {
+    const vms = new Map();
+    for (const line of output.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || /^Source\s/.test(trimmed)) {
+            continue;
+        }
+        const fields = trimmed.split(/\s+/);
+        if (fields.length >= 2) {
+            vms.set(fields[1], fields[fields.length - 1]);
+        }
+    }
+    return vms;
+}
+/** Runs `tart list` and returns the parsed name → state map.
+ *
+ * @returns The parsed VM map (empty on failure — callers check).
+ */
+export async function listVms() {
+    const res = await run('tart', ['list']);
+    return res.code === 0 ? parseTartList(res.stdout) : new Map();
+}
+/** Whether a VM by this name exists in the tart store.
+ *
+ * @param name - The VM/image name.
+ * @returns True when present in `tart list`.
+ */
+export async function vmExists(name) {
+    return (await listVms()).has(name);
+}
+/** The VM's state from `tart list` (running/stopped/…).
+ *
+ * @param name - The VM/image name.
+ * @returns The state, or undefined when the VM does not exist.
+ */
+export async function vmState(name) {
+    return (await listVms()).get(name);
+}
+/** Polls `tart list` until the VM reaches the wanted state.
+ *
+ * @param name - The VM/image name.
+ * @param want - The state to wait for (`running`/`stopped`).
+ * @param tries - Poll attempts (60 = up to 2 min at 2 s apart).
+ * @param delayMs - Delay between attempts.
+ * @returns True when the state was reached.
+ */
+export async function waitForVmState(name, want, tries = 60, delayMs = 2000) {
+    for (let attempt = 0; attempt < tries; attempt += 1) {
+        if ((await vmState(name)) === want) {
+            return true;
+        }
+        await sleep(delayMs);
+    }
+    return false;
+}
+/** The VM's IP from `tart ip` (empty when not reachable yet).
+ *
+ * @param name - The VM name.
+ * @returns The IP, or undefined when tart cannot report one.
+ */
+export async function vmIp(name) {
+    const res = await run('tart', ['ip', name]);
+    return res.code === 0 && res.stdout.trim() ? res.stdout.trim() : undefined;
+}
+/** The host's address on Tart's VM network: always `.1` of the VM's /24.
+ *
+ * @param ip - The VM's IP (e.g. `192.168.64.34`).
+ * @returns The gateway IP, or undefined when the IP is not an IPv4 /24.
+ */
+export function gatewayFromVmIp(ip) {
+    const parts = ip.split('.');
+    if (parts.length !== 4) {
+        return undefined;
+    }
+    return `${parts[0]}.${parts[1]}.${parts[2]}.1`;
+}
+/** Args for `tart set` — the runner's recommended VM settings.
+ *
+ * @param vm - The VM name.
+ * @param cpuCount - CPUs for the freshly cloned VM.
+ * @param memoryMb - RAM for the freshly cloned VM, in MB.
+ * @returns The argv for `tart set`.
+ */
+export function tartSetArgs(vm, cpuCount, memoryMb) {
+    return [
+        'set',
+        vm,
+        '--cpu',
+        String(cpuCount),
+        '--memory',
+        String(memoryMb),
+        '--display',
+        '1280x800',
+        '--display-refit',
+    ];
+}
+/** Args for `tart run`: the VM's launch flags (legacy order preserved).
+ *
+ * @param vm - The VM name.
+ * @param options - headless vs GUI flags + the optional `--dir` share.
+ * @returns The argv for `tart run`.
+ */
+export function tartRunArgs(vm, options) {
+    const flags = options.headless
+        ? ['--no-graphics', '--no-audio']
+        : ['--capture-system-keys', '--no-audio'];
+    const dir = options.dirArg ? [options.dirArg] : [];
+    return ['run', ...flags, ...dir, vm];
+}
+/** The `--dir=<mount>:<hostDir>` argument for `tart run`.
+ *
+ * @param mountName - Mount name inside the guest.
+ * @param hostDir - Host directory to share.
+ * @returns The `--dir` argument value.
+ */
+export function dirArg(mountName, hostDir) {
+    return `--dir=${mountName}:${hostDir}`;
+}
+/** Runs `tart clone` — the working VM is always a clone of the image.
+ *
+ * @param source - The pristine image VM name.
+ * @param dest - The working VM name.
+ * @returns The raw result (non-zero on failure, caller decides).
+ */
+export function cloneVm(source, dest) {
+    return run('tart', ['clone', source, dest]);
+}
+/** Runs `tart set` with the given argv (tartSetArgs).
+ *
+ * @param args - Full argv from tartSetArgs.
+ * @returns The raw result.
+ */
+export function setVm(args) {
+    return run('tart', args);
+}
+/** Runs `tart pull` of a registry ref (GHCR).
+ *
+ * @param registryRef - e.g. `ghcr.io/<owner>/<image>:latest`.
+ * @param options - run() overrides (timeouts etc.).
+ * @returns The raw result.
+ */
+export function pullImage(registryRef, options = {}) {
+    return run('tart', ['pull', registryRef], options);
+}
+/** Runs `tart stop` (graceful; tart force-stops after its own timeout).
+ *
+ * @param vm - The VM name.
+ * @returns The raw result.
+ */
+export function stopVm(vm) {
+    return run('tart', ['stop', vm]);
+}
+/** Runs `tart delete` — removes the VM from the store, disk included.
+ *
+ * @param vm - The VM name.
+ * @returns The raw result.
+ */
+export function deleteVm(vm) {
+    return run('tart', ['delete', vm]);
+}
+/** Runs a command inside the guest via `tart exec` (stdin piping with
+ *  `-i`).
+ *
+ * @param vm - The VM name (must be running).
+ * @param argv - The command + args to run inside the guest.
+ * @param options - `input` (implies `-i`) + run() overrides.
+ * @returns The raw result.
+ */
+export function execVm(vm, argv, options = {}) {
+    const interactive = options.input !== undefined ? ['-i'] : [];
+    return run('tart', ['exec', ...interactive, vm, ...argv], options);
+}
+/** Reports the path of the node binary inside a running guest.
+ *
+ * Node is installed via nvm and aliased as the default, so it is only on
+ * PATH in login shells — resolve once per run and reuse the absolute path
+ * for the guest-agent invocations.
+ *
+ * @param vm - The running VM name.
+ * @returns The absolute node path, or undefined when not found.
+ */
+export async function findGuestNode(vm) {
+    const res = await execVm(vm, ['sh', '-lc', 'command -v node']);
+    const node = res.code === 0 ? res.stdout.trim() : '';
+    return node && node.startsWith('/') ? node : undefined;
+}

package/dist/lib/template.js

@@ -0,0 +1,35 @@
+// template.ts — placeholder substitution shared by every piece of
+// scaffolding the runners render from templates.
+//
+// The shell scripts substituted with sed (`s|{{TOKEN}}|value|g`); this is
+// the unified replacement for all of them. Tokens are {{UPPER_SNAKE}}; an
+// unknown token is left untouched (sed only replaced the tokens it was
+// told about, too). The guest-side bridge assets migrated from `__X__`
+// placeholders to {{TOKEN}} in the same unification.
+import { escapeRegex } from './regex.js';
+const TOKEN_RE = /\{\{([A-Za-z0-9_]+)\}\}/g;
+/** Replaces every `{{TOKEN}}` occurrence with the substitution
+ *  value. Tokens not present in `substitutions` are left as-is.
+ * @param template - The template text.
+ * @param substitutions - Token → value map.
+ * @returns The rendered text.
+ */
+export function render(template, substitutions) {
+    return template.replace(TOKEN_RE, (match, key) => key in substitutions && substitutions[key] !== undefined ? String(substitutions[key]) : match);
+}
+/** Drops the given heading line and everything after it the
+ *  sed `/^<heading>$/,$d` the macOS/Ubuntu runners use to remove the SSH
+ *  agent section from the agent rules when no bridge is up. A heading
+ *  that is not present leaves the content unchanged.
+ * @param content - The document.
+ * @param headingLine - The heading to drop from (e.g. `## SSH agent bridge`).
+ * @returns The content up to (but excluding) the heading.
+ */
+export function dropSectionFrom(content, headingLine) {
+    const re = new RegExp(`^${escapeRegex(headingLine)}$`, 'm');
+    const idx = content.search(re);
+    if (idx === -1) {
+        return content;
+    }
+    return content.slice(0, idx);
+}

package/dist/lib/vars.js

@@ -0,0 +1,99 @@
+// vars.ts — reading values out of Packer vars files (*.pkrvars.hcl).
+//
+// Port of the shell `read_var` sed pattern (scripts/build.sh, every runner):
+//
+//   ^[[:space:]]*NAME[[:space:]]*=[[:space:]]*"([^"]*)"[[:space:]]*$
+//
+// extended with number and boolean parsing (disk_size = 160, a flag =
+// true), and with port validation for the port-like vars. The vars files
+// are the single source of truth for versions and resources, so everything
+// that needs a value (image_version for deploy/tag/list, disk_size/ports
+// for doctor, guest passwords for the runners) reads them through here.
+import { escapeRegex } from './regex.js';
+/** Reads a quoted-string assignment: `name = "value"`.
+ *
+ * @param text - Vars file content.
+ * @param name - The variable name.
+ * @returns The value, or undefined when not present as a quoted string.
+ */
+export function readQuotedVar(text, name) {
+    const re = new RegExp(`^[ \\t]*${escapeRegex(name)}[ \\t]*=[ \\t]*"([^"]*)"[ \\t]*$`, 'm');
+    const m = text.match(re);
+    return m?.[1];
+}
+/** @internal — Integer assignment: `name = 160`.
+ * @param text - Vars file content.
+ * @param name - The variable name.
+ * @returns The value, or undefined when not present as an integer.
+ */
+export function readNumberVar(text, name) {
+    const re = new RegExp(`^[ \\t]*${escapeRegex(name)}[ \\t]*=[ \\t]*(\\d+)[ \\t]*$`, 'm');
+    const m = text.match(re);
+    return m ? Number(m[1]) : undefined;
+}
+/** @internal — Boolean assignment: `name = true|false`.
+ * @param text - Vars file content.
+ * @param name - The variable name.
+ * @returns The value, or undefined when not present as a boolean.
+ */
+export function readBoolVar(text, name) {
+    const re = new RegExp(`^[ \\t]*${escapeRegex(name)}[ \\t]*=[ \\t]*(true|false)[ \\t]*$`, 'm');
+    const m = text.match(re);
+    return m ? m[1] === 'true' : undefined;
+}
+/** @internal — Any assignment, string first (the shell only ever read
+ *  quoted strings).
+ * @param text - Vars file content.
+ * @param name - The variable name.
+ * @returns The string/number/boolean value, or undefined when absent.
+ */
+export function readVar(text, name) {
+    return readQuotedVar(text, name) ?? readNumberVar(text, name) ?? readBoolVar(text, name);
+}
+/** @internal — Port assignment (number 1-65535).
+ * @param text - Vars file content.
+ * @param name - The variable name.
+ * @returns The port, or undefined when absent.
+ * @throws RangeError when the port is out of range.
+ */
+export function readPortVar(text, name) {
+    const v = readNumberVar(text, name);
+    if (v !== undefined && (v < 1 || v > 65535)) {
+        throw new RangeError(`port '${name}' is out of range (1-65535): ${v}`);
+    }
+    return v;
+}
+/** @internal — Quoted string that must exist — the pattern
+ *  deploy.sh/tag.sh use for image_version, with the same error message
+ *  shape.
+ * @param text - Vars file content.
+ * @param name - The variable name.
+ * @param file - The source path, included in the error message.
+ * @returns The quoted value.
+ * @throws Error when the variable is missing.
+ */
+export function requireQuotedVar(text, name, file) {
+    const v = readQuotedVar(text, name);
+    if (v === undefined) {
+        throw new Error(`Could not read ${name} from ${file}`);
+    }
+    return v;
+}
+const ASSIGNMENT_RE = /^[ \t]*([A-Za-z_][A-Za-z0-9_]*)[ \t]*=[ \t]*(?:"([^"]*)"|(\d+)|(true|false))[ \t]*$/gm;
+/** Parses every assignment in a vars file (last value wins for duplicate
+ *  keys).
+ *
+ * @param text - Vars file content.
+ * @returns The name → value map.
+ */
+export function parseVars(text) {
+    const out = {};
+    for (const m of text.matchAll(ASSIGNMENT_RE)) {
+        const [, name, quoted, number, bool] = m;
+        if (name !== undefined) {
+            out[name] =
+                quoted !== undefined ? quoted : number !== undefined ? Number(number) : bool === 'true';
+        }
+    }
+    return out;
+}

package/dist/lib/vmrun.js

@@ -0,0 +1,334 @@
+// vmrun.ts — vmrun resolution + the VMware helpers the runners, stop and
+// delete flows share. Phase 1 landed the binary resolution + `list`;
+// Phase 4 adds the hardware-upgrade/guest-IP/tools-state/shared-folder
+// helpers for the VMware backends (the port of scripts/lib/vmware.sh).
+//
+// The pure parsers stay unit-testable (vmrun writes plain text); the IO
+// wrappers stay thin. Hangs are bounded with withTimeout — vmrun's
+// getGuestIPAddress/checkToolsState can hang past their own timeouts, and
+// upgradevm never exits by design (it blocks after doing the work).
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isExecutable, run, sleep, which, withTimeout } from './exec.js';
+const DEFAULT_FUSION_APP = '/Applications/VMware Fusion.app';
+/** Resolves the vmrun binary: PATH first, then the Fusion app bundle —
+ *  the same order as scripts/lib/vmware.sh.
+ *
+ * @param env - Environment (FUSION_APP_PATH override).
+ * @returns The vmrun path, or undefined when not found.
+ */
+export function findVmrun(env = process.env) {
+    const onPath = which('vmrun', env);
+    if (onPath) {
+        return onPath;
+    }
+    const fusionApp = env.FUSION_APP_PATH ?? DEFAULT_FUSION_APP;
+    const candidate = join(fusionApp, 'Contents', 'Public', 'vmrun');
+    return isExecutable(candidate) ? candidate : undefined;
+}
+/** `vmrun -T fusion <args>`, resolving the binary when not given. */
+function vmrunCommand(args, options = {}) {
+    const vmrun = options.vmrun ?? findVmrun(options.env);
+    if (!vmrun) {
+        throw new Error('vmrun not found — install VMware Fusion (free for personal use) or set FUSION_APP_PATH.');
+    }
+    return { cmd: vmrun, argv: ['-T', 'fusion', ...args] };
+}
+/** Lists the paths of the running VMs, from `vmrun -T fusion list`.
+ *
+ * @param options - vmrun path / env overrides.
+ * @returns The running VMs' vmx paths.
+ * @throws Error when vmrun is missing or the list fails.
+ */
+export async function listRunningVms(options = {}) {
+    const { cmd, argv } = vmrunCommand(['list'], options);
+    const res = await run(cmd, argv);
+    if (res.code !== 0) {
+        throw new Error(`vmrun list failed:\n${res.stderr.trim()}`);
+    }
+    return res.stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line && !/^Total running VMs:/i.test(line));
+}
+/** Normalizes a vmx path for comparison (vmrun list output vs our
+ *  derived path — whitespace/case aside, the path itself must match).
+ *
+ * @param path - The path to normalize.
+ * @returns The path with duplicate slashes collapsed.
+ */
+function normalizeVmxPath(path) {
+    return path.replace(/\/+/g, '/');
+}
+/** Whether the working VM is in Fusion's running-VM list.
+ *
+ * @param vmx - The vmx path to look up.
+ * @param options - vmrun path / env overrides.
+ * @returns True when the VM is running.
+ */
+export async function isVmRunning(vmx, options = {}) {
+    try {
+        const running = await listRunningVms(options);
+        return running.some((path) => normalizeVmxPath(path) === normalizeVmxPath(vmx));
+    }
+    catch {
+        return false;
+    }
+}
+/** Waits until the VM disappears from the running list.
+ *
+ * @param vmx - The working VM vmx.
+ * @param tries - Poll attempts (30 = up to 1 min at 2 s apart).
+ * @param delayMs - Delay between attempts.
+ * @returns True when the VM stopped within the window.
+ */
+export async function waitForVmNotRunning(vmx, tries = 30, delayMs = 2000) {
+    for (let attempt = 0; attempt < tries; attempt += 1) {
+        if (!(await isVmRunning(vmx))) {
+            return true;
+        }
+        await sleep(delayMs);
+    }
+    return false;
+}
+/** @internal — the strict last-line extraction of a vmrun answer
+ *  (handles a trailing newline like the shell's `tail -n1`).
+ *
+ * @param output - The raw vmrun output.
+ * @returns The last non-empty trimmed line, or undefined.
+ */
+function lastOutputLine(output) {
+    const lines = output
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line !== '');
+    return lines.length > 0 ? lines[lines.length - 1] : undefined;
+}
+/** @internal — the `virtualhw.version` line from a vmx text. */
+export function parseVmwareHwVersion(content) {
+    const match = /^[ \t]*virtualhw\.version[ \t]*=[ \t]*"([0-9]+)"/m.exec(content);
+    return match?.[1];
+}
+/** The working VM's hardware version (sed port; reads the vmx).
+ *
+ * @param vmx - The vmx path.
+ * @returns The version string, or undefined when absent.
+ */
+export function vmwareHwVersion(vmx) {
+    try {
+        return parseVmwareHwVersion(readFileSync(vmx, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** @internal — rewrites the displayname key of a vmx (case-insensitive:
+ *  replaces every `displayname =` / `displayName =` line with the new
+ *  name, appends one at the end when the vmx has none — the awk port).
+ *  A second, case-variant key would make Fusion refuse the VM.
+ *
+ * @param content - The vmx text.
+ * @param name - The VM's display name.
+ * @returns The rewritten text.
+ */
+export function rewriteVmxDisplayName(content, name) {
+    const hasTrailingNewline = content.endsWith('\n');
+    const lines = content.split('\n');
+    if (hasTrailingNewline) {
+        lines.pop(); // the split artifact of the trailing newline
+    }
+    let seen = false;
+    const out = [];
+    for (const line of lines) {
+        if (/^[ \t]*displayname[ \t]*=/i.test(line)) {
+            out.push(`displayname = "${name}"`);
+            seen = true;
+            continue;
+        }
+        out.push(line);
+    }
+    if (!seen) {
+        out.push(`displayname = "${name}"`);
+    }
+    return out.join('\n') + (hasTrailingNewline ? '\n' : '');
+}
+/** Sets the vmx displayName (the name Fusion's library shows) —
+ *  `vmrun clone` inherits the base's name, so the working clone would
+ *  otherwise be indistinguishable from the pristine image.
+ *
+ * @param vmx - The vmx path.
+ * @param name - The display name.
+ * @returns True when the file was rewritten.
+ */
+export function setVmDisplayName(vmx, name) {
+    try {
+        writeFileSync(vmx, rewriteVmxDisplayName(readFileSync(vmx, 'utf8'), name));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function vmrunRaw(args, options = {}) {
+    const { cmd, argv } = vmrunCommand(args, options);
+    return run(cmd, argv);
+}
+/** Copies the base VM into the working VM (`vmrun clone <src> <dst>
+ *  full`).
+ *
+ * @param sourceVmx - The pristine (base) vmx.
+ * @param destinationVmx - The working vmx.
+ * @param options - vmrun path / env overrides.
+ * @returns The raw result.
+ */
+export function cloneVm(sourceVmx, destinationVmx, options = {}) {
+    return vmrunRaw(['clone', sourceVmx, destinationVmx, 'full'], options);
+}
+/** Starts the VM (`vmrun start <vmx> gui|nogui`).
+ *
+ * @param vmx - The working vmx.
+ * @param mode - gui (Fusion window) or nogui (headless).
+ * @param options - vmrun path / env overrides.
+ * @returns The raw result.
+ */
+export function startVm(vmx, mode = 'gui', options = {}) {
+    return vmrunRaw(['start', vmx, mode], options);
+}
+/** Stops the VM (`vmrun stop <vmx> [soft]`; soft = graceful via VMware
+ *  Tools).
+ *
+ * @param vmx - The working vmx.
+ * @param mode - soft (default) or a hard power-off.
+ * @param options - vmrun path / env overrides.
+ * @returns The raw result.
+ */
+export function stopVm(vmx, mode = 'soft', options = {}) {
+    const args = mode === 'soft' ? ['stop', vmx, 'soft'] : ['stop', vmx];
+    return vmrunRaw(args, options);
+}
+/** The stop flow of the legacy stop script: graceful `soft` stop, hard
+ *  power-off after a minute, both with the wait-for-stopped poll.
+ *
+ * @param vmx - The working vmx.
+ * @param options - vmrun path / env overrides.
+ * @returns True when the VM was (or already is) stopped.
+ */
+export async function stopVmGraceful(vmx, options = {}) {
+    if (!(await isVmRunning(vmx, options))) {
+        return true;
+    }
+    await stopVm(vmx, 'soft', options);
+    if (await waitForVmNotRunning(vmx, 30, 2000)) {
+        return true;
+    }
+    await stopVm(vmx, 'hard', options);
+    return waitForVmNotRunning(vmx, 30, 2000);
+}
+/** @internal — strict dotted-quad parse of `getGuestIPAddress` output
+ *  (the error text "The VMware Tools are not running…" must never become
+ *  the guest IP).
+ *
+ * @param output - The raw vmrun output (last line is the answer).
+ * @returns The IP, or undefined when not a valid dotted quad.
+ */
+export function parseGuestIpAddress(output) {
+    const ip = lastOutputLine(output) ?? '';
+    return /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.test(ip) && ip !== '0.0.0.0'
+        ? ip
+        : undefined;
+}
+/** The guest IP as reported by open-vm-tools, bounded (vmrun has no
+ *  timeout of its own — the perl alarm wrapper port).
+ *
+ * @param vmx - The working vmx.
+ * @param options - vmrun path / env overrides.
+ * @returns The dotted-quad IP, or undefined before the tools answer.
+ */
+export async function getGuestIpAddress(vmx, options = {}) {
+    const { cmd, argv } = vmrunCommand(['getGuestIPAddress', vmx], options);
+    try {
+        const res = await withTimeout(run(cmd, argv), 30_000, 'vmrun getGuestIPAddress timed out');
+        return res.code === 0 ? parseGuestIpAddress(res.stdout) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** @internal — the last non-empty vmrun line (checkToolsState's answer).
+ *
+ * @param output - The raw vmrun output.
+ * @returns The trimmed last line, or undefined when empty.
+ */
+export function parseToolsState(output) {
+    return lastOutputLine(output);
+}
+/** The VMware Tools state vmrun reports (`running`/`notrunning`),
+ *  bounded like the IP fetch.
+ *
+ * @param vmx - The working vmx.
+ * @param options - vmrun path / env overrides.
+ * @returns The state string, or undefined on failure/timeout.
+ */
+export async function checkToolsState(vmx, options = {}) {
+    const { cmd, argv } = vmrunCommand(['checkToolsState', vmx], options);
+    try {
+        const res = await withTimeout(run(cmd, argv), 30_000, 'vmrun checkToolsState timed out');
+        return res.code === 0 ? parseToolsState(res.stdout) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The "Already exists" case from addSharedFolder (a share registered by
+ *  a previous run is fine).
+ *
+ * @param err - The command's combined output.
+ * @returns True when the share is already registered.
+ */
+export function sharedFolderAlreadyExists(err) {
+    return /already exists/i.test(err);
+}
+/** Registers a shared folder with vmrun (`addSharedFolder <vmx> <name>
+ *  <path>`); the caller retries — the tools state can flip back right
+ *  after checkToolsState reports running.
+ *
+ * @param vmx - The working vmx.
+ * @param name - Share name inside the guest.
+ * @param path - Host directory to share.
+ * @param options - vmrun path / env overrides.
+ * @returns The raw result.
+ */
+export function addSharedFolder(vmx, name, path, options = {}) {
+    return vmrunRaw(['addSharedFolder', vmx, name, path], options);
+}
+/** Enables the registered shares for the running VM (best effort —
+ *  `enableSharedFolders <vmx> runtime`), like the shell's `|| true`.
+ *
+ * @param vmx - The working vmx.
+ * @param options - vmrun path / env overrides.
+ */
+export async function enableSharedFolders(vmx, options = {}) {
+    const { cmd, argv } = vmrunCommand(['enableSharedFolders', vmx, 'runtime'], options);
+    await run(cmd, argv);
+}
+/** Upgrades the VM to the hardware version the installed Fusion supports
+ *  (vmrun upgradevm — which never exits, hence the 180 s cap; the work
+ *  finishes before it blocks). The caller records .hw-version so it runs
+ *  once per VM version.
+ *
+ * @param vmx - The working vmx.
+ * @param options - vmrun path / env overrides.
+ * @returns The resulting hardware version (or undefined when unreadable).
+ */
+export async function upgradeVmHardware(vmx, options = {}) {
+    const before = vmwareHwVersion(vmx);
+    const { cmd, argv } = vmrunCommand(['upgradevm', vmx], options);
+    try {
+        await withTimeout(run(cmd, argv), 180_000, 'vmrun upgradevm timed out');
+    }
+    catch {
+        // upgradevm never exits — the timeout is expected; the vmx is
+        // written before it blocks.
+    }
+    return vmwareHwVersion(vmx) ?? before;
+}