@visualautomate/cli 0.4.1 → 0.5.1

package/README.md

@@ -4,14 +4,14 @@ Build and publish VisualAutomate plugins.
 
 ```bash
 npm install -g @visualautomate/cli
-visualautomate login
-visualautomate init my-step
+vsa login
+vsa init my-step
 cd my-step
-visualautomate dev      # run it on every save
-visualautomate push
+vsa dev                 # the sandbox, and a run again on every save
+vsa push
 ```
 
-`va` is the same command, shorter.
+`va` and `visualautomate` are the same command.
 
 That is the whole toolchain. There is nothing else to install: the CLI carries
 the SDK inside it, compiles your TypeScript itself, and writes the type
@@ -79,20 +79,25 @@ my-app/                       an app's repository
       …
 ```
 
-At the root of an app's repository every module runs, one after another;
-`--module send-message` runs one. `index.js` in a repository is run as written,
+At the root of an app's repository every module runs, one after another. Name one
+to run only that: `vsa test send-message`, or any short name that picks it out —
+`vsa test send`. `--module <name>` is the same thing. `index.js` in a repository is run as written,
 unbundled, because that is the file the sandbox loads.
 
 ## `dev`
 
-`test`, and again on every save. Only the module whose folder changed runs
-again; a change anywhere else runs them all. Ctrl+C stops it.
-
 ```bash
-va dev
-va dev --module send-message
+vsa dev                    # every module in modules/
+vsa dev send-message       # one of them; the shortest name that picks it will do
+vsa dev --tier boosted     # a bigger machine
+vsa dev --local            # on this machine's Node, without the sandbox
 ```
 
+Everything in one command: it starts Docker if it is not running, fetches the
+sandbox image the first time, runs every module, and runs them again on every
+save. Only the module whose folder changed runs again; a change anywhere else
+runs them all. Ctrl+C stops it.
+
 `context.connections` and `context.media` are **not** simulated. One is
 somebody's OAuth account and the other is an ffmpeg container; pretending to be
 either would produce a plugin that passes here and fails on a canvas. Asking for
@@ -140,14 +145,17 @@ Keeps storage and state between runs, in `.visualautomate/` next to the plugin:
 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
+## The sandbox on your machine
+
+`dev` uses it by default; `test` does with `--docker`:
 
 ```bash
-va test --docker
-va dev --docker --tier boosted
+vsa dev
+vsa test --docker
+vsa dev --tier boosted
 ```
 
-Runs the test inside the plugin sandbox image,
+Your plugin runs 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
@@ -157,10 +165,12 @@ Runs the test inside the plugin sandbox image,
 - 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.
+A step that runs out of memory or time here does the same on the platform.
+
+Docker does not have to be running: `dev` starts Docker Desktop and waits for it,
+then fetches the image if this machine does not have it. `--image` uses a
+different image, for example one you built yourself. The watcher stays on your
+machine, and each run starts a fresh container.
 
 `context.media` is not available locally, in or out of Docker.
 

package/dist/index.js

@@ -1822,6 +1822,14 @@ var ENTRIES = ["plugin.ts", "plugin.js", "index.ts", "index.js"];
 function entryIn(dir) {
   return ENTRIES.map((file2) => join(dir, file2)).find((file2) => existsSync(file2)) ?? null;
 }
+function matchFolders(folders, name) {
+  const wanted = name.trim().toLowerCase();
+  const exact = folders.filter((folder) => folder.toLowerCase() === wanted);
+  if (exact.length > 0) return exact;
+  const prefix = folders.filter((folder) => folder.toLowerCase().startsWith(wanted));
+  if (prefix.length > 0) return prefix;
+  return folders.filter((folder) => folder.toLowerCase().includes(wanted));
+}
 function findTargets(cwd, only) {
   const dir = resolve(cwd);
   const modulesDir = join(dir, "modules");
@@ -1830,16 +1838,16 @@ function findTargets(cwd, only) {
     if (folders.length === 0) {
       throw new Error("There is a modules/ folder here, but none of its folders has a manifest.json.");
     }
-    const chosen = only ? folders.filter((f) => f === only) : folders;
+    const chosen = only ? matchFolders(folders, only) : folders;
     if (only && chosen.length === 0) {
-      throw new Error(`No module "${only}" in modules/. There is: ${folders.join(", ")}.`);
+      throw new Error(`No module matches "${only}". This repository has: ${folders.join(", ")}.`);
     }
     return chosen.map((folder) => targetIn(join(modulesDir, folder), `modules/${folder}`)).filter(Boolean);
   }
   const target = targetIn(dir, basename(dir));
   if (!target) {
     throw new Error(
-      "Nothing to test here: no plugin.ts, plugin.js or index.js, and no modules/ folder.\nRun this in a plugin's folder, at the root of its repository, or run `visualautomate init <name>`."
+      "Nothing to test here: no plugin.ts, plugin.js or index.js, and no modules/ folder.\nRun this in a module's folder, at the root of its repository, or run `vsa init <name>`."
     );
   }
   return [target];
@@ -2139,6 +2147,35 @@ function explainExit(code, tier) {
   if (code === 125) return "\u2717 Docker could not start the container. Is the image available? Try: docker pull " + IMAGE;
   return null;
 }
+function ensureDocker(say, waitMs = 12e4) {
+  const problem = dockerProblem();
+  if (!problem) return null;
+  if (problem.includes("not installed")) return problem;
+  say("Docker is not running. Starting Docker Desktop\u2026");
+  const started = spawnSync("docker", ["desktop", "start"], { encoding: "utf8" });
+  if (started.status !== 0) {
+    say("Could not start it from here \u2014 start Docker Desktop yourself; this will carry on when it is up.");
+  }
+  const until = Date.now() + waitMs;
+  while (Date.now() < until) {
+    spawnSync(process.execPath, ["-e", "setTimeout(() => {}, 1000)"]);
+    if (!dockerProblem()) {
+      say("Docker is ready.");
+      return null;
+    }
+  }
+  return "Docker did not come up in time. Start Docker Desktop and try again.";
+}
+function hasImage(image) {
+  return spawnSync("docker", ["image", "inspect", image], { stdio: "ignore" }).status === 0;
+}
+function pullImage(image, say) {
+  if (hasImage(image)) return null;
+  say(`Fetching ${image} \u2014 once, about 700 MB.`);
+  const pulled = spawnSync("docker", ["pull", image], { stdio: "inherit" });
+  if (pulled.status === 0) return null;
+  return `Could not fetch ${image}. Check your connection, or pass --image with one you have.`;
+}
 function runInDocker(run) {
   const result = spawnSync("docker", dockerArgs(run), { stdio: "inherit" });
   const code = result.status ?? 1;
@@ -2148,7 +2185,7 @@ function runInDocker(run) {
 }
 
 // src/index.ts
-var VERSION = true ? "0.4.1" : "0.0.0-dev";
+var VERSION = true ? "0.5.1" : "0.0.0-dev";
 var DEFAULT_API_URL = "https://visualautomate.com";
 function configPath() {
   return join3(homedir(), ".visualautomate", "config.json");
@@ -2472,9 +2509,16 @@ function packageLoader(dir) {
     }
   };
 }
+function imageFor(flags) {
+  return flags.image || `${IMAGE}:${VERSION}`;
+}
+function prepareSandbox(flags) {
+  const docker = ensureDocker(ok);
+  if (docker) fail(docker);
+  const image = pullImage(imageFor(flags), ok);
+  if (image) fail(image);
+}
 function dockerRunFor(flags, args) {
-  const problem = dockerProblem();
-  if (problem) fail(problem);
   let tier;
   try {
     tier = tierOf(flags.tier);
@@ -2483,7 +2527,7 @@ function dockerRunFor(flags, args) {
   }
   return {
     cwd: process.cwd(),
-    image: flags.image || `${IMAGE}:${VERSION}`,
+    image: imageFor(flags),
     tier,
     args,
     user: typeof process.getuid === "function" && typeof process.getgid === "function" ? { uid: process.getuid(), gid: process.getgid() } : void 0
@@ -2502,28 +2546,41 @@ function runTargetsInDocker(targets, all, flags) {
   }
   return passed;
 }
-function targetsOrFail(flags) {
+function targetsOrFail(args, flags) {
   try {
-    return findTargets(process.cwd(), flags.module);
+    return findTargets(process.cwd(), args[0] ?? flags.module);
   } catch (error) {
     fail(error instanceof Error ? error.message : String(error));
   }
 }
-async function cmdTest(flags) {
-  const targets = targetsOrFail(flags);
+function sayWhatRuns(targets, picked) {
+  if (targets.length === 1) {
+    ok(`Running ${targets[0].name}`);
+    return;
+  }
+  ok(`Running ${targets.length} modules: ${targets.map((t) => t.name.replace(/^modules\//, "")).join(", ")}`);
+  if (!picked) ok(`One of them: vsa dev ${targets[0].name.replace(/^modules\//, "")}`);
+}
+async function cmdTest(args, flags) {
+  const targets = targetsOrFail(args, flags);
+  if (flags.docker) prepareSandbox(flags);
   const passed = flags.docker ? runTargetsInDocker(targets, targets, flags) : await runTargets(targets, flags);
   if (!passed) process.exitCode = 1;
 }
-async function cmdDev(flags) {
+async function cmdDev(args, flags) {
   const root = process.cwd();
-  let targets = targetsOrFail(flags);
+  const picked = args[0] ?? flags.module;
+  let targets = targetsOrFail(args, flags);
+  const inSandbox = flags.local !== "true";
+  if (inSandbox) prepareSandbox(flags);
   const header = () => {
     process.stdout.write("\x1Bc");
-    ok(`visualautomate dev \u2014 ${(/* @__PURE__ */ new Date()).toLocaleTimeString()} \u2014 Ctrl+C to stop`);
+    ok(`vsa dev \u2014 ${(/* @__PURE__ */ new Date()).toLocaleTimeString()} \u2014 Ctrl+C to stop`);
   };
-  const run = async (chosen) => flags.docker ? runTargetsInDocker(chosen, targets, flags) : runTargets(chosen, flags);
+  const run = async (chosen) => inSandbox ? runTargetsInDocker(chosen, targets, flags) : runTargets(chosen, flags);
   header();
-  if (flags.docker) ok(`in ${flags.image || `${IMAGE}:${VERSION}`}, tier ${flags.tier || "standard"}`);
+  ok(inSandbox ? `in ${imageFor(flags)}, tier ${flags.tier || "standard"}` : "on this machine, not in the sandbox");
+  sayWhatRuns(targets, Boolean(picked));
   await run(targets);
   const ignored = [`${sep2}node_modules${sep2}`, `${sep2}.git${sep2}`, `${sep2}dist${sep2}`, `${sep2}.visualautomate${sep2}`];
   const pending = /* @__PURE__ */ new Set();
@@ -2538,7 +2595,7 @@ async function cmdDev(flags) {
     const changed = [...pending];
     pending.clear();
     try {
-      targets = findTargets(root, flags.module);
+      targets = findTargets(root, picked);
     } catch (error) {
       header();
       ok(`\u2717 ${error instanceof Error ? error.message : String(error)}`);
@@ -2656,29 +2713,33 @@ ${text.slice(0, 500)}`);
 }
 function printHelp() {
   console.log(`
-visualautomate \u2014 build and publish plugins
+vsa \u2014 build and publish VisualAutomate plugins
+
+  vsa login                    sign this machine in
+  vsa init <name> [--template] start a plugin
+  vsa dev [<module>]           the sandbox, and a run again on every save
+  vsa test [<module>]          run it once, as the platform's check does
+  vsa push                     publish it
+  vsa whoami                   which account this is
+  vsa logout                   forget the token
+  vsa --version                this CLI's version
 
-  visualautomate login                    sign this machine in
-  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
+\`va\` and \`visualautomate\` are the same command.
 
 Templates: ${Object.keys(TEMPLATES).join(", ")}
 
 \`test\` and \`dev\` work in a plugin made with \`init\`, at the root of a plugin's
 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
+in modules/ is run (or the one you name: vsa dev send-message). 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
+Options for \`dev\` and \`test\`:
+  --module <name>      the same as naming it: vsa dev send-message
+  --tier <name>        the sandbox's size: standard, boosted, high or max
+  --image <ref>        a different sandbox image
   --persist            keep storage and state in .visualautomate/ between runs
+  --local              \`dev\` without the sandbox, on this machine's Node
+  --docker             \`test\` inside the sandbox, as \`dev\` does
 
 Environment (for CI, where there is no browser):
   VISUALAUTOMATE_API_TOKEN   use instead of \`login\`
@@ -2718,17 +2779,17 @@ async function main() {
     case "new":
       return cmdInit(args, flags);
     case "test":
-      return cmdTest(flags);
+      return cmdTest(args, flags);
     case "dev":
     case "watch":
-      return cmdDev(flags);
+      return cmdDev(args, flags);
     case "push":
     case "publish":
       return cmdPush(flags);
     // `plugin test` and `plugin push` are accepted as aliases.
     case "plugin": {
       const sub = args.shift();
-      if (sub === "test") return cmdTest(flags);
+      if (sub === "test") return cmdTest(args, flags);
       if (sub === "push") return cmdPush(flags);
       printHelp();
       return;

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@visualautomate/cli",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Build and publish VisualAutomate plugins.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "visualautomate": "./dist/index.js",
-    "va": "./dist/index.js"
+    "visualautomate": "dist/index.js",
+    "va": "dist/index.js",
+    "vsa": "dist/index.js"
   },
   "files": [
     "dist",