@visualautomate/cli 0.3.1 → 0.4.1

package/README.md

@@ -107,13 +107,62 @@ one fails with a sentence saying so.
   "storage": { "notes/hello.txt": "hello from a file" },
   "state": { "runs": 0 },
   "expectOutput": "success",
-  "timeoutMs": 30000
+  "timeoutMs": 30000,
+  "allowedDomains": ["api.example.com"]
 }
 ```
 
 The platform's push check reads `config`, `input`, `expectOutput` and
-`timeoutMs`; `storage`, `state` and `secrets` are for running locally. A file that is not valid JSON
-stops the run rather than running with nothing.
+`timeoutMs`; `storage`, `state`, `secrets` and `allowedDomains` are for running
+locally. A file that is not valid JSON stops the run rather than running with
+nothing.
+
+## Where `fetch` may go
+
+On the platform a step may contact the domains its plugin declares, plus any
+host in the configuration filled in for that step. A declared domain covers its
+subdomains; localhost, private networks and metadata addresses are never
+allowed.
+
+Put the domains in `allowedDomains` and `test` applies the same rule: a request
+anywhere else fails. Without `allowedDomains` nothing is blocked, but every host
+the platform would refuse is listed after the run.
+
+## `--persist`
+
+Keeps storage and state between runs, in `.visualautomate/` next to the plugin:
+
+```
+.visualautomate/storage/<path>   files the step wrote
+.visualautomate/state.json       the workflow state
+```
+
+Once that folder exists it is used without the flag. Delete it to start over,
+and add it to `.gitignore`.
+
+## `--docker`: the sandbox on your machine
+
+```bash
+va test --docker
+va dev --docker --tier boosted
+```
+
+Runs the test inside the plugin sandbox image,
+`ghcr.io/visualautomate/plugin-sandbox`, at the version of this CLI:
+
+- the Node version the platform runs plugins on, with every allowed npm
+  package installed — no `npm install` needed;
+- the CPU and memory of the sandbox tier: `standard` (¼ vCPU, 1 GB, the
+  default), `boosted` (½ vCPU, 4 GB), `high` (1 vCPU, 6 GB), `max` (2 vCPU, 8 GB);
+- no Linux capabilities, a read-only filesystem apart from your project and a
+  small `/tmp`, and nothing else from your machine.
+
+A step that runs out of memory or time here does the same on the platform. Docker
+must be running. `--image` uses a different image, for example one you built
+yourself. With `dev`, the watcher stays on your machine and each run starts a
+fresh container.
+
+`context.media` is not available locally, in or out of Docker.
 
 ## `push`
 

package/dist/index.js

@@ -2,10 +2,10 @@
 
 // src/index.ts
 import { createServer } from "node:http";
-import { mkdir, readFile as readFile2, writeFile } from "node:fs/promises";
-import { existsSync as existsSync2, watch } from "node:fs";
+import { mkdir as mkdir2, readFile as readFile3, writeFile as writeFile2 } from "node:fs/promises";
+import { existsSync as existsSync3, watch } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join as join2, relative as relative2, resolve as resolve2, sep } from "node:path";
+import { dirname as dirname2, join as join3, relative as relative3, resolve as resolve3, sep as sep2 } from "node:path";
 import { randomBytes } from "node:crypto";
 import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
@@ -1882,8 +1882,12 @@ async function readTestFile(dir, override) {
   if (raw.timeoutMs !== void 0 && (typeof raw.timeoutMs !== "number" || raw.timeoutMs <= 0 || raw.timeoutMs > 6e4)) {
     throw new Error(`${path}: "timeoutMs" must be a number of milliseconds up to 60000.`);
   }
+  if (raw.allowedDomains !== void 0 && (!Array.isArray(raw.allowedDomains) || !raw.allowedDomains.every((d) => typeof d === "string" && d.trim() !== ""))) {
+    throw new Error(`${path}: "allowedDomains" must be a list of hosts, like ["api.example.com"], or ["*"].`);
+  }
   return {
     path,
+    allowedDomains: raw.allowedDomains,
     config: raw.config ?? {},
     input: raw.input ?? {},
     storage: raw.storage,
@@ -1940,22 +1944,226 @@ if (${fallback} && typeof ${fallback}.execute === "function") module.exports.exe
   return code.replace(/^\n+/, "");
 }
 
+// src/egress.ts
+var ALWAYS_DENIED = [
+  /^localhost$/i,
+  /^127\./,
+  /^0\./,
+  /^10\./,
+  /^192\.168\./,
+  /^172\.(1[6-9]|2\d|3[01])\./,
+  /^169\.254\./,
+  /^\[?::1\]?$/,
+  /^\[?f[cd][0-9a-f]{2}:/i,
+  /\.internal$/i,
+  /\.local$/i
+];
+function hostOf(value) {
+  if (typeof value !== "string" || value.trim() === "") return null;
+  const trimmed = value.trim();
+  try {
+    const host = new URL(trimmed.includes("://") ? trimmed : `https://${trimmed}`).hostname.toLowerCase();
+    return host || null;
+  } catch {
+    return null;
+  }
+}
+function isAlwaysDenied(host) {
+  return ALWAYS_DENIED.some((pattern) => pattern.test(host));
+}
+function hostsInConfig(config, depth = 0) {
+  if (depth > 6 || config === null || config === void 0) return [];
+  if (typeof config === "string") {
+    const host = hostOf(config);
+    return host && (config.includes("://") || /^[a-z0-9.-]+\.[a-z]{2,}(:\d+)?$/i.test(config.trim())) ? [host] : [];
+  }
+  if (Array.isArray(config)) return config.flatMap((entry) => hostsInConfig(entry, depth + 1));
+  if (typeof config === "object") {
+    return Object.entries(config).filter(([key]) => !key.startsWith("_")).flatMap(([, value]) => hostsInConfig(value, depth + 1));
+  }
+  return [];
+}
+function policyFor(allowedDomains, config) {
+  const declared = (allowedDomains ?? []).map((d) => d.trim().toLowerCase()).filter(Boolean);
+  const wildcard = declared.includes("*");
+  const hosts = [
+    .../* @__PURE__ */ new Set([
+      ...declared.filter((d) => d !== "*").map((d) => hostOf(d.replace(/^\*\./, "")) ?? d),
+      ...hostsInConfig(config)
+    ])
+  ].filter((host) => !isAlwaysDenied(host));
+  return { hosts, wildcard, enforce: allowedDomains !== void 0 };
+}
+function permits(policy, host) {
+  if (policy.wildcard) return true;
+  return policy.hosts.some((allowed) => host === allowed || host.endsWith(`.${allowed}`));
+}
+function guardFetch(policy, base, onDenied) {
+  return ((resource, init) => {
+    const raw = typeof resource === "string" ? resource : resource instanceof URL ? resource.href : resource.url;
+    const host = hostOf(raw);
+    if (host && !permits(policy, host)) {
+      onDenied(host, policy.enforce);
+      if (policy.enforce) {
+        return Promise.reject(
+          new Error(`This step is not allowed to contact ${host}. Add it to the plugin's allowed domains.`)
+        );
+      }
+    }
+    return base(resource, init);
+  });
+}
+
+// src/persist.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { mkdir, readdir, readFile as readFile2, rm, writeFile } from "node:fs/promises";
+import { dirname, join as join2, relative as relative2, resolve as resolve2, sep } from "node:path";
+var PERSIST_DIR = ".visualautomate";
+function persistEnabled(dir, flag) {
+  return flag === "true" || existsSync2(join2(dir, PERSIST_DIR));
+}
+function diskPathFor(storageRoot, path) {
+  if (!path || path.includes("\0")) return null;
+  const target = resolve2(storageRoot, path);
+  const rel = relative2(storageRoot, target);
+  if (!rel || rel.startsWith("..") || rel.split(sep).includes("..") || resolve2(rel) === rel) return null;
+  return target;
+}
+async function walk(root, dir = root) {
+  if (!existsSync2(dir)) return [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  const nested = await Promise.all(
+    entries.map((entry) => entry.isDirectory() ? walk(root, join2(dir, entry.name)) : Promise.resolve([join2(dir, entry.name)]))
+  );
+  return nested.flat();
+}
+async function loadPersisted(dir) {
+  const storageRoot = join2(dir, PERSIST_DIR, "storage");
+  const storage = {};
+  for (const file2 of await walk(storageRoot)) {
+    storage[relative2(storageRoot, file2).split(sep).join("/")] = new Uint8Array(await readFile2(file2));
+  }
+  let state = {};
+  const statePath = join2(dir, PERSIST_DIR, "state.json");
+  if (existsSync2(statePath)) {
+    try {
+      const parsed = JSON.parse(await readFile2(statePath, "utf8"));
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) state = parsed;
+    } catch {
+      throw new Error(`${statePath} is not valid JSON. Fix it, or delete it to start from empty state.`);
+    }
+  }
+  return { storage, state };
+}
+async function savePersisted(dir, files, state) {
+  const storageRoot = join2(dir, PERSIST_DIR, "storage");
+  const refused = [];
+  const keep = /* @__PURE__ */ new Set();
+  for (const [path, file2] of files) {
+    const target = diskPathFor(storageRoot, path);
+    if (!target) {
+      refused.push(path);
+      continue;
+    }
+    keep.add(target);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, file2.bytes);
+  }
+  for (const existing of await walk(storageRoot)) {
+    if (!keep.has(existing)) await rm(existing);
+  }
+  await mkdir(join2(dir, PERSIST_DIR), { recursive: true });
+  await writeFile(join2(dir, PERSIST_DIR, "state.json"), JSON.stringify(Object.fromEntries(state), null, 2) + "\n");
+  return refused;
+}
+
+// src/docker.ts
+import { spawnSync } from "node:child_process";
+var IMAGE = "ghcr.io/visualautomate/plugin-sandbox";
+var TIERS = {
+  standard: { cpus: "0.25", memory: "1g" },
+  boosted: { cpus: "0.5", memory: "4g" },
+  high: { cpus: "1", memory: "6g" },
+  max: { cpus: "2", memory: "8g" }
+};
+function dockerArgs(run) {
+  const tier = TIERS[run.tier];
+  return [
+    "run",
+    "--rm",
+    "--init",
+    "--volume",
+    `${run.cwd}:/work`,
+    "--workdir",
+    "/work",
+    "--cpus",
+    tier.cpus,
+    "--memory",
+    tier.memory,
+    "--memory-swap",
+    tier.memory,
+    "--pids-limit",
+    "256",
+    "--read-only",
+    "--tmpfs",
+    "/tmp:rw,size=64m",
+    "--cap-drop",
+    "ALL",
+    "--security-opt",
+    "no-new-privileges",
+    ...run.user ? ["--user", `${run.user.uid}:${run.user.gid}`] : [],
+    run.image,
+    ...run.args
+  ];
+}
+function forwardedFlags(flags) {
+  const local = /* @__PURE__ */ new Set(["docker", "image", "tier"]);
+  return Object.entries(flags).filter(([key]) => !local.has(key)).flatMap(([key, value]) => value === "true" ? [`--${key}`] : [`--${key}`, value]);
+}
+function tierOf(value) {
+  if (!value) return "standard";
+  if (value in TIERS) return value;
+  throw new Error(`Unknown tier "${value}". Available: ${Object.keys(TIERS).join(", ")}.`);
+}
+function dockerProblem() {
+  const probe = spawnSync("docker", ["version", "--format", "{{.Server.Version}}"], { encoding: "utf8" });
+  if (probe.error) return "Docker is not installed, or not on PATH. Install Docker Desktop, or run without --docker.";
+  if (probe.status !== 0) return "Docker is installed but not running. Start Docker Desktop and try again.";
+  return null;
+}
+function explainExit(code, tier) {
+  if (code === 137) {
+    const next = Object.keys(TIERS)[Object.keys(TIERS).indexOf(tier) + 1];
+    return `\u2717 stopped   the step used more than the ${TIERS[tier].memory.replace("g", " GB")} of memory the ${tier} tier has, and the container was killed. On the platform it would stop the same way.` + (next ? ` To check it fits a bigger machine: --tier ${next}` : "");
+  }
+  if (code === 125) return "\u2717 Docker could not start the container. Is the image available? Try: docker pull " + IMAGE;
+  return null;
+}
+function runInDocker(run) {
+  const result = spawnSync("docker", dockerArgs(run), { stdio: "inherit" });
+  const code = result.status ?? 1;
+  const explained = explainExit(code, run.tier);
+  if (explained) console.error(explained);
+  return code;
+}
+
 // src/index.ts
+var VERSION = true ? "0.4.1" : "0.0.0-dev";
 var DEFAULT_API_URL = "https://visualautomate.com";
 function configPath() {
-  return join2(homedir(), ".visualautomate", "config.json");
+  return join3(homedir(), ".visualautomate", "config.json");
 }
 async function readConfig() {
   try {
-    return JSON.parse(await readFile2(configPath(), "utf8"));
+    return JSON.parse(await readFile3(configPath(), "utf8"));
   } catch {
     return {};
   }
 }
 async function writeConfig(next) {
   const path = configPath();
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, JSON.stringify(next, null, 2) + "\n", { mode: 384 });
+  await mkdir2(dirname2(path), { recursive: true });
+  await writeFile2(path, JSON.stringify(next, null, 2) + "\n", { mode: 384 });
 }
 async function tokenFor(flags) {
   const stored = await readConfig();
@@ -2078,23 +2286,23 @@ async function cmdInit(args, flags) {
   if (!template) {
     fail(`Unknown template "${templateName}". Available: ${Object.keys(TEMPLATES).join(", ")}`);
   }
-  const target = resolve2(process.cwd(), name);
-  if (existsSync2(target)) fail(`"${name}" already exists here.`);
+  const target = resolve3(process.cwd(), name);
+  if (existsSync3(target)) fail(`"${name}" already exists here.`);
   const slug = name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
-  await mkdir(target, { recursive: true });
-  await writeFile(join2(target, "plugin.ts"), template.code);
-  await writeFile(join2(target, "manifest.json"), template.manifest);
-  await writeFile(
-    join2(target, "plugin.json"),
+  await mkdir2(target, { recursive: true });
+  await writeFile2(join3(target, "plugin.ts"), template.code);
+  await writeFile2(join3(target, "manifest.json"), template.manifest);
+  await writeFile2(
+    join3(target, "plugin.json"),
     JSON.stringify(
       { name: slug, version: "1.0.0", description: template.description, category: template.category },
       null,
       2
     ) + "\n"
   );
-  await writeFile(join2(target, "visualautomate.d.ts"), TYPE_DECLARATIONS);
-  await writeFile(
-    join2(target, "tsconfig.json"),
+  await writeFile2(join3(target, "visualautomate.d.ts"), TYPE_DECLARATIONS);
+  await writeFile2(
+    join3(target, "tsconfig.json"),
     JSON.stringify(
       {
         compilerOptions: {
@@ -2112,12 +2320,12 @@ async function cmdInit(args, flags) {
       2
     ) + "\n"
   );
-  await writeFile(
-    join2(target, "test.json"),
+  await writeFile2(
+    join3(target, "test.json"),
     JSON.stringify(template.testInput, null, 2) + "\n"
   );
-  await writeFile(
-    join2(target, "README.md"),
+  await writeFile2(
+    join3(target, "README.md"),
     `# ${name}
 
 ${template.description}
@@ -2159,7 +2367,7 @@ ${message}`);
   }
 }
 async function codeFor(target) {
-  return target.raw ? readFile2(target.entry, "utf8") : bundlePlugin(target.entry);
+  return target.raw ? readFile3(target.entry, "utf8") : bundlePlugin(target.entry);
 }
 function line(indent, text) {
   ok(indent ? "  " + text.replace(/\n/g, "\n  ") : text);
@@ -2177,28 +2385,38 @@ async function runTarget(target, flags, several) {
     }
     const settings = await readTestFile(target.dir, flags.input);
     if (!settings.path) say("No visualautomate.test.json \u2014 running with empty input and config.");
-    const load = createRequire(join2(target.dir, "noop.js"));
-    const exported = loadPluginCode(code, sandboxRequire(load));
+    const exported = loadPluginCode(code, sandboxRequire(packageLoader(target.dir)));
     const plugin = typeof exported === "function" ? exported : typeof exported?.execute === "function" ? exported : exported?.default;
     let outputs = [];
-    const manifestPath = join2(target.dir, "manifest.json");
-    if (existsSync2(manifestPath)) {
+    const manifestPath = join3(target.dir, "manifest.json");
+    if (existsSync3(manifestPath)) {
       try {
-        const manifest = parseJsonc(await readFile2(manifestPath, "utf8")).value;
+        const manifest = parseJsonc(await readFile3(manifestPath, "utf8")).value;
         outputs = manifest.outputs ?? [];
       } catch (error) {
         say(`\u2717 manifest.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
         return false;
       }
     }
-    const result = await simulate(plugin, {
-      input: settings.input,
-      config: settings.config,
-      storage: settings.storage,
-      state: settings.state,
-      secrets: settings.secrets,
-      timeoutMs: settings.timeoutMs
-    });
+    const persist = persistEnabled(target.dir, flags.persist);
+    const kept = persist ? await loadPersisted(target.dir) : { storage: {}, state: {} };
+    const policy = policyFor(settings.allowedDomains, settings.config);
+    const denied = /* @__PURE__ */ new Map();
+    const baseFetch = globalThis.fetch;
+    globalThis.fetch = guardFetch(policy, baseFetch, (host, enforced) => denied.set(host, enforced));
+    let result;
+    try {
+      result = await simulate(plugin, {
+        input: settings.input,
+        config: settings.config,
+        storage: { ...settings.storage, ...kept.storage },
+        state: { ...settings.state, ...kept.state },
+        secrets: settings.secrets,
+        timeoutMs: settings.timeoutMs
+      });
+    } finally {
+      globalThis.fetch = baseFetch;
+    }
     const port = result.output?.output ?? null;
     const expected = settings.expectOutput;
     const passed = result.status === "success" && (!expected || port === expected);
@@ -2211,6 +2429,16 @@ async function runTarget(target, flags, several) {
     if (result.files.size > 0) say(`files    ${[...result.files.keys()].join(", ")}`);
     if (result.state.size > 0) say(`state    ${JSON.stringify(Object.fromEntries(result.state))}`);
     for (const entry of result.logs ?? []) say(`log      ${entry}`);
+    for (const [host, enforced] of denied) {
+      say(
+        enforced ? `egress   blocked ${host} \u2014 not in allowedDomains` : `! egress ${host} is not allowed on the platform unless the plugin declares it. Add "allowedDomains": ["${host}"] to the test file to check with the same rule.`
+      );
+    }
+    if (persist) {
+      const refused = await savePersisted(target.dir, result.files, result.state);
+      say(`kept     storage and state in ${relative3(process.cwd(), join3(target.dir, ".visualautomate")) || ".visualautomate"}`);
+      for (const path of refused) say(`! storage path "${path}" points outside the storage folder and was not written`);
+    }
     if (port && outputs.length > 0 && !outputs.includes(port)) {
       say(
         `! This returned output "${port}", which manifest.json does not list (it has ${outputs.map((o) => `"${o}"`).join(", ")}). On a canvas nothing would follow it.`
@@ -2231,6 +2459,49 @@ async function runTargets(targets, flags) {
 ${passed} of ${targets.length} passed`);
   return passed === targets.length;
 }
+function packageLoader(dir) {
+  const fromProject = createRequire(join3(dir, "noop.js"));
+  const imageDir = process.env.VISUALAUTOMATE_PACKAGES;
+  const fromImage = imageDir ? createRequire(join3(imageDir, "noop.js")) : null;
+  return (name) => {
+    try {
+      return fromProject(name);
+    } catch (error) {
+      if (fromImage) return fromImage(name);
+      throw error;
+    }
+  };
+}
+function dockerRunFor(flags, args) {
+  const problem = dockerProblem();
+  if (problem) fail(problem);
+  let tier;
+  try {
+    tier = tierOf(flags.tier);
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+  return {
+    cwd: process.cwd(),
+    image: flags.image || `${IMAGE}:${VERSION}`,
+    tier,
+    args,
+    user: typeof process.getuid === "function" && typeof process.getgid === "function" ? { uid: process.getuid(), gid: process.getgid() } : void 0
+  };
+}
+function runTargetsInDocker(targets, all, flags) {
+  const base = forwardedFlags(flags).filter((f, i, list) => f !== "--module" && list[i - 1] !== "--module");
+  if (targets.length === all.length) {
+    const extra = flags.module ? ["--module", flags.module] : [];
+    return runInDocker(dockerRunFor(flags, ["test", ...base, ...extra])) === 0;
+  }
+  let passed = true;
+  for (const target of targets) {
+    const module = target.name.replace(/^modules\//, "");
+    if (runInDocker(dockerRunFor(flags, ["test", ...base, "--module", module])) !== 0) passed = false;
+  }
+  return passed;
+}
 function targetsOrFail(flags) {
   try {
     return findTargets(process.cwd(), flags.module);
@@ -2240,7 +2511,8 @@ function targetsOrFail(flags) {
 }
 async function cmdTest(flags) {
   const targets = targetsOrFail(flags);
-  if (!await runTargets(targets, flags)) process.exitCode = 1;
+  const passed = flags.docker ? runTargetsInDocker(targets, targets, flags) : await runTargets(targets, flags);
+  if (!passed) process.exitCode = 1;
 }
 async function cmdDev(flags) {
   const root = process.cwd();
@@ -2249,9 +2521,11 @@ async function cmdDev(flags) {
     process.stdout.write("\x1Bc");
     ok(`visualautomate dev \u2014 ${(/* @__PURE__ */ new Date()).toLocaleTimeString()} \u2014 Ctrl+C to stop`);
   };
+  const run = async (chosen) => flags.docker ? runTargetsInDocker(chosen, targets, flags) : runTargets(chosen, flags);
   header();
-  await runTargets(targets, flags);
-  const ignored = [`${sep}node_modules${sep}`, `${sep}.git${sep}`, `${sep}dist${sep}`, `${sep}.visualautomate${sep}`];
+  if (flags.docker) ok(`in ${flags.image || `${IMAGE}:${VERSION}`}, tier ${flags.tier || "standard"}`);
+  await run(targets);
+  const ignored = [`${sep2}node_modules${sep2}`, `${sep2}.git${sep2}`, `${sep2}dist${sep2}`, `${sep2}.visualautomate${sep2}`];
   const pending = /* @__PURE__ */ new Set();
   let timer;
   let running = false;
@@ -2274,14 +2548,14 @@ async function cmdDev(flags) {
     const hit = changed.map((path) => targetForPath(targets, path));
     const chosen = hit.some((t) => t === null) ? targets : [...new Set(hit)];
     header();
-    ok(`changed: ${changed.map((p) => relative2(root, p)).join(", ")}`);
-    await runTargets(chosen, flags);
+    ok(`changed: ${changed.map((p) => relative3(root, p)).join(", ")}`);
+    await run(chosen);
     running = false;
   };
   const watcher = watch(root, { recursive: true }, (_event, name) => {
     if (!name) return;
-    const path = join2(root, name.toString());
-    if (ignored.some((part) => `${sep}${relative2(root, path)}${sep}`.includes(part))) return;
+    const path = join3(root, name.toString());
+    if (ignored.some((part) => `${sep2}${relative3(root, path)}${sep2}`.includes(part))) return;
     pending.add(path);
     if (timer) clearTimeout(timer);
     timer = setTimeout(flush, 150);
@@ -2296,30 +2570,30 @@ async function cmdDev(flags) {
 async function cmdPush(flags) {
   const dir = process.cwd();
   const { token, apiUrl } = await tokenFor(flags);
-  const metaPath = join2(dir, "plugin.json");
-  const pkgPath = join2(dir, "package.json");
-  const metaFile = existsSync2(metaPath) ? metaPath : existsSync2(pkgPath) ? pkgPath : null;
+  const metaPath = join3(dir, "plugin.json");
+  const pkgPath = join3(dir, "package.json");
+  const metaFile = existsSync3(metaPath) ? metaPath : existsSync3(pkgPath) ? pkgPath : null;
   if (!metaFile) {
     fail("No plugin.json here. Run `visualautomate init <name>` to start a plugin.");
   }
-  const meta = JSON.parse(await readFile2(metaFile, "utf8"));
+  const meta = JSON.parse(await readFile3(metaFile, "utf8"));
   if (!meta.name) fail(`${metaFile} has no "name".`);
   if (!meta.version || !/^\d+\.\d+\.\d+$/.test(meta.version)) {
     fail(`${metaFile} needs a "version" like 1.0.0.`);
   }
-  const manifestPath = resolve2(process.cwd(), "manifest.json");
+  const manifestPath = resolve3(process.cwd(), "manifest.json");
   let parsed = {};
   let manifest = null;
-  if (existsSync2(manifestPath)) {
+  if (existsSync3(manifestPath)) {
     try {
-      const result = parseJsonc(await readFile2(manifestPath, "utf8"));
+      const result = parseJsonc(await readFile3(manifestPath, "utf8"));
       parsed = result.value;
       manifest = result.json;
     } catch (error) {
       fail(`manifest.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
-  const entry = ["plugin.ts", "plugin.js", "index.ts", "index.js"].map((f) => join2(dir, f)).find((f) => existsSync2(f));
+  const entry = ["plugin.ts", "plugin.js", "index.ts", "index.js"].map((f) => join3(dir, f)).find((f) => existsSync3(f));
   if (!entry) {
     fail("No plugin.ts or plugin.js here. Run `visualautomate init <name>` to start one.");
   }
@@ -2331,7 +2605,7 @@ async function cmdPush(flags) {
   }
   let schemaJson = null;
   if (!manifest) {
-    const source = await readFile2(entry, "utf8");
+    const source = await readFile3(entry, "utf8");
     const match = source.match(/@schema\s*\n([\s\S]*?)(?:\*\s*\/|\*\/)/);
     if (match) {
       schemaJson = match[1].replace(/^\s*\*\s?/gm, "").trim();
@@ -2388,6 +2662,7 @@ visualautomate \u2014 build and publish plugins
   visualautomate init <name> [--template] start a plugin
   visualautomate test [--module <name>]   run it here, as the platform's check does
   visualautomate dev [--module <name>]    run it again on every save
+  visualautomate --version                this CLI's version
   visualautomate push                     publish it
   visualautomate whoami                   which account this is
   visualautomate logout                   forget the token
@@ -2399,6 +2674,12 @@ GitHub repository, and at the root of an app's repository, where every folder
 in modules/ is run (or the one named with --module). The run's settings come
 from visualautomate.test.json, test.json, or --input <file>.
 
+Options for \`test\` and \`dev\`:
+  --docker             run inside the plugin sandbox image (Docker must be running)
+  --tier <name>        with --docker: standard, boosted, high or max
+  --image <ref>        with --docker: a different image
+  --persist            keep storage and state in .visualautomate/ between runs
+
 Environment (for CI, where there is no browser):
   VISUALAUTOMATE_API_TOKEN   use instead of \`login\`
   VISUALAUTOMATE_API_URL     a different installation
@@ -2422,6 +2703,10 @@ function parse(argv) {
 async function main() {
   const { args, flags } = parse(process.argv.slice(2));
   const command = args.shift();
+  if (flags.version || command === "version") {
+    ok(VERSION);
+    return;
+  }
   switch (command) {
     case "login":
       return cmdLogin(flags);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visualautomate/cli",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Build and publish VisualAutomate plugins.",
   "license": "MIT",
   "type": "module",
@@ -23,10 +23,10 @@
     "deploy"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=20"
   },
   "dependencies": {
-    "esbuild": "^0.23.0"
+    "esbuild": "^0.28.2"
   },
   "devDependencies": {
     "@types/node": "^22",