@visualautomate/cli 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WvB Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# @visualautomate/cli
+
+Build and publish VisualAutomate plugins.
+
+```bash
+npm install -g @visualautomate/cli
+visualautomate login
+visualautomate init my-step
+cd my-step
+visualautomate dev      # run it on every save
+visualautomate push
+```
+
+`va` is the same command, shorter.
+
+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
+declarations into the project. A plugin directory has no `node_modules`, no
+build step and no dependencies.
+
+## What `init` gives you
+
+```
+plugin.ts            your code
+manifest.json        what the canvas shows, with the rest of the options
+                     written out as commented examples
+plugin.json          name, version, description, category
+test.json            the input, config, storage and state `test` runs with
+visualautomate.d.ts  the types, written in rather than installed
+tsconfig.json        so your editor type-checks it
+```
+
+Templates: `blank`, `http-request`, `connection`, `file`. Pass one with
+`--template`. Each runs unmodified.
+
+## `test`
+
+Runs your plugin the way the platform would, in three steps:
+
+1. **The platform's code checks.** The same rules the upload applies: only
+   allowed packages in `require`, no dynamic `require`, none of the refused
+   patterns (`eval`, `process.env`, `import`, …). Code that fails here would be
+   refused on push, and says why.
+2. **The sandbox's `require`.** A step gets the allowed npm packages and nothing
+   else — no `fs`, no `http`. Those packages are installed in the sandbox; here
+   they come from your project, and a missing one prints the `npm install`
+   command for the version the sandbox has.
+3. **A context that behaves.** `storage` and `state` are real, in memory, and
+   the result shows what the step left behind:
+
+```
+✓ passed  success, 3ms
+output   success (expected success)
+data     { "path": "notes/hello-shouted.txt", "size": 17 }
+files    notes/hello.txt, notes/hello-shouted.txt
+state    {"runs":1}
+```
+
+A run passes when it succeeds and, if the test file names an `expectOutput`,
+leaves by that port — the same verdict as the GitHub check.
+
+### In a GitHub repository
+
+`test` works wherever the platform tests your code on a push:
+
+```
+my-plugin/                    a plugin's repository
+  manifest.json
+  index.js
+  visualautomate.test.json
+
+my-app/                       an app's repository
+  modules/
+    send-message/
+      manifest.json
+      index.js
+      visualautomate.test.json
+    list-channels/
+      …
+```
+
+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,
+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
+```
+
+`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
+one fails with a sentence saying so.
+
+`visualautomate.test.json` (or `test.json`, or `--input <file>`) seeds the run:
+
+```json
+{
+  "config": { "source": "notes/hello.txt" },
+  "input": {},
+  "storage": { "notes/hello.txt": "hello from a file" },
+  "state": { "runs": 0 },
+  "expectOutput": "success",
+  "timeoutMs": 30000
+}
+```
+
+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.
+
+## `push`
+
+Bundles the same code `test` ran, strips the comments out of `manifest.json`,
+and publishes. A version snapshot is saved, so you can roll back from the
+dashboard.
+
+Comments in `manifest.json` are a convenience of this tool: the file on your
+disk may have them, the bytes on the wire never do.
+
+## CI
+
+There is no browser on a build machine, so `login` is not available there. Set
+`VISUALAUTOMATE_API_TOKEN` instead — the same token `login` would have stored,
+which you can read out of `~/.visualautomate/config.json`.
+
+`VISUALAUTOMATE_API_URL` points the CLI at a different installation.
+
+## Where things are
+
+The runtime API your plugin is written against is documented in the types
+(`visualautomate.d.ts` in your project, `@visualautomate/plugin-sdk` if you
+prefer to install it) and on the platform's own docs page.