@visualautomate/plugin-sdk 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,110 @@
+# @visualautomate/plugin-sdk
+
+The types a VisualAutomate plugin is written against, and a way to run one on
+your own machine.
+
+Most people do not need to install this. `@visualautomate/cli` carries it and
+writes the types into your project, so a scaffolded plugin has no dependencies
+at all. Install it directly if you want the simulator in your own test suite.
+
+```bash
+npm install --save-dev @visualautomate/plugin-sdk
+```
+
+## A plugin
+
+```ts
+import type { PluginModule } from "@visualautomate/plugin-sdk"
+
+const plugin: PluginModule = {
+    async execute(input, config, context) {
+        const bytes = await context.storage.get(config.path as string)
+        if (!bytes) return { output: "error", data: { error: "No such file." } }
+
+        return {
+            output: "success",
+            data: { size: bytes.length },
+        }
+    },
+}
+
+export default plugin
+```
+
+`output` names which port the run leaves by, and has to be one of the `outputs`
+in your manifest. `data` is what the next steps read.
+
+## What `context` has
+
+| | |
+|---|---|
+| `storage` | the account's files — `put`, `get`, `delete`, `list`, `head`, `signedUrl`, `download` |
+| `state` | values that outlive one run, scoped to the workflow — `get`, `set`, `delete`, `list` |
+| `media` | ffmpeg, by operation name. Absent when the server has no sandbox configured |
+| `connections` | the accounts this step was configured with. Absent when it declares none |
+| `workflowId`, `nodeId`, `userId`, `executionId`, `startedAt`, `secrets` | about the run |
+
+You never see a credential and you never name a host. `connections.get("account")`
+takes the name of one of *your* properties, and the platform attaches the token
+on the way past — which is what stops a plugin pointing somebody's account
+somewhere it chose.
+
+## `simulate`
+
+```ts
+import { simulate } from "@visualautomate/plugin-sdk"
+import plugin from "./plugin"
+
+const result = await simulate(plugin, {
+    config: { path: "notes/a.txt" },
+    storage: { "notes/a.txt": "hello" },
+    state: { runs: 0 },
+})
+
+result.status        // "success" | "error" | "timeout" | ...
+result.output?.data
+result.files         // what storage holds now
+result.state         // what state holds now
+```
+
+Storage and state are real, in memory, with the same edge cases the platform's
+have — `get` on a missing key is `null`, `put` takes a string or bytes, `list`
+is prefix-filtered.
+
+`connections` and `media` are not simulated. Pass a stub if you want to test the
+code around them:
+
+```ts
+await simulate(plugin, {
+    connections: {
+        async get() {
+            return { id: "test", async request() { return { ok: true, status: 200, body: {} } } }
+        },
+    },
+})
+```
+
+Asserting on what your plugin *asked* the provider for is a better test than any
+imitation of the provider would be.
+
+## The platform's code checks
+
+The rules the platform applies to a plugin's code on upload, so a test can
+refuse what the platform would refuse:
+
+```ts
+import { validatePluginCode, ALLOWED_PACKAGES } from "@visualautomate/plugin-sdk"
+
+const check = validatePluginCode(code)
+if (!check.valid) throw new Error(check.error)
+check.packages // the allowed packages this code requires
+```
+
+`ALLOWED_PACKAGES` lists every npm package a plugin may `require`, with the
+version the sandbox has installed. Nothing else is available: no `fs`, no
+`http`, and no subpaths like `lodash/get`.
+
+`sandboxRequire(load)` and `loadPluginCode(code, require)` load code the way
+the sandbox does, as the body of a function given `module`, `exports` and a
+`require` that only hands out allowed packages. `visualautomate test` uses
+them; they are here for your own test runner.

package/dist/context-api.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The runtime API, as data.
+ *
+ * The same things types.ts describes, in a form a tool can read without a
+ * TypeScript compiler: an editor's autocomplete, a documentation page, a lint
+ * rule. Each entry is a name an author types, what it is, and a one-line
+ * description.
+ *
+ * Plain data with no imports, so it can go into a browser bundle without the
+ * rest of the SDK.
+ */
+export interface ContextApiEntry {
+    /** What an author types, e.g. `context.storage.put`. */
+    path: string;
+    /** `property` for a value, `method` for something you call. */
+    kind: "variable" | "property" | "method";
+    /** The signature, for a method. Shown beside the name. */
+    signature?: string;
+    /** One line, in the hover card. */
+    info: string;
+    /**
+     * Set when the helper is not always there.
+     *
+     * The editor says so, because the alternative is an author writing
+     * `context.media.run(...)` against a completion that promised it existed
+     * and meeting `undefined` on somebody's canvas.
+     */
+    conditional?: string;
+}
+/** Everything a plugin is called with, and everything it can reach. */
+export declare const CONTEXT_API: ContextApiEntry[];
+/**
+ * The globals a plugin does NOT get, and what to reach for instead.
+ *
+ * Worth offering in an editor as much as the API is: an author who types
+ * `require('fs')` should be told at the keystroke rather than at the push.
+ */
+export declare const BLOCKED_GLOBALS: Array<{
+    name: string;
+    instead: string;
+}>;

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @visualautomate/plugin-sdk
+ *
+ * Three things: the types a plugin is written against, a way to run one on
+ * your own machine before it goes anywhere near a canvas, and the checks the
+ * platform applies to a plugin's code before it will accept it.
+ *
+ * Nothing here runs inside the sandbox. Plugin code is plain JavaScript that
+ * the platform loads; this package exists so an editor can tell you what
+ * `context` has on it, and so `visualautomate test` can call your execute with
+ * a context that behaves like the real one.
+ */
+export * from "./types";
+export * from "./simulate";
+export * from "./validate";
+export { CONTEXT_API, BLOCKED_GLOBALS, type ContextApiEntry } from "./context-api";