@nodetool-ai/nodes-utils 0.8.1

package/README.md

@@ -0,0 +1,74 @@
+# @nodetool-ai/nodes-utils
+
+Shared helpers for node packages: platform tags and lazy Node-only module loaders for [NodeTool](https://nodetool.ai).
+
+A small utility crate every `*-nodes` package depends on instead of duplicating helpers or pulling the whole base-nodes barrel: platform-tagging helpers that stamp `static platforms` onto node arrays, lazy loaders for `node:` built-ins so non-portable paths don't block module init on non-Node runtimes, template variable substitution, Buffer-free base64, and the destination rules every `Save*File` node shares.
+
+## Install
+
+```bash
+npm install @nodetool-ai/nodes-utils
+```
+
+## Exported symbols
+
+| Symbol | Kind | Description |
+| --- | --- | --- |
+| `tagAsServer` | function | Mark a `_NODES` array as server-only |
+| `tagAsNode` | function | Mark nodes as requiring the Node runtime |
+| `tagAsHybrid` | function | Mark nodes as running on server or browser |
+| `tagAsBrowserGpu` | function | Mark nodes as needing browser WebGPU |
+| `tagAsUniversal` | function | Mark nodes as runnable on any platform |
+| `tagAsContentCard` | function | Tag nodes surfaced as content cards |
+| `loadNodeFsPromises` | function | Lazily import `node:fs/promises` |
+| `loadNodeFsSync` | function | Lazily import `node:fs` |
+| `loadNodePath` | function | Lazily import `node:path` |
+| `loadNodeOs` | function | Lazily import `node:os` |
+| `loadNodeUrl` | function | Lazily import `node:url` |
+| `renderTemplate` | function | Substitute `{{ variable }}` / `{variable}` placeholders |
+| `referencedVariables` | function | List variable names referenced in a template |
+| `base64ToBytes` | function | Decode base64 to `Uint8Array` (Node + browser) |
+| `bytesToBase64` | function | Encode bytes to base64 (Node + browser) |
+| `resolveSaveTarget` | function | Folder + filename → an absolute path, directory created, name numbered on collision |
+| `resolveSaveFolder` | function | Pick the workspace folder or the node's own `folder` property |
+| `uniqueFilePath` | function | `name.ext` → `name_1.ext`, `name_2.ext`, … past what is already there |
+| `folderPathOf` | function | Read a folder property (path, `file://` URI or folder ref) |
+| `SAVE_TO_WORKSPACE_TITLE` | const | Title every save node shows on the workspace toggle |
+| `SAVE_TO_WORKSPACE_DESCRIPTION` | const | Description every save node shows on the workspace toggle |
+| `VISIBLE_WHEN_NOT_SAVING_TO_WORKSPACE` | const | `json_schema_extra` (`visible_when`) that shows the folder field only while the toggle is off |
+
+## Usage
+
+```ts
+import {
+  tagAsServer,
+  renderTemplate,
+  loadNodePath
+} from "@nodetool-ai/nodes-utils";
+
+tagAsServer(_NODES);
+
+const text = renderTemplate("Hello {{ name }}", { name: "world" });
+
+// Only touches node:path when this path actually runs
+const path = await loadNodePath();
+const full = path.join(dir, "file.txt");
+```
+
+### Saving a file from a node
+
+```ts
+// Writes into the run's workspace folder while `save_to_workspace` is on, and
+// numbers the name (`out_1.png`) rather than overwriting what is there.
+const target = await resolveSaveTarget({
+  folder: this.folder,
+  filename: dateName(String(this.filename || "out.png")),
+  saveToWorkspace: this.save_to_workspace,
+  workspaceDir: context?.workspaceDir
+});
+```
+
+## Links
+
+- [NodeTool](https://nodetool.ai)
+- [GitHub](https://github.com/nodetool-ai/nodetool)

package/dist/.nodetool-build-stamp

@@ -0,0 +1 @@
+2026-09-28T09:19:08.910Z

package/dist/base64.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Buffer-free base64 helpers shared by the `*-nodes` packages.
+ *
+ * `atob`/`btoa` are global on Node ≥ 16 and in every browser, so these work
+ * in both environments without touching `node:buffer` (which the web bundle
+ * stubs out).
+ */
+/** Decode a base64 string to bytes without `Buffer` (works on Node and browser). */
+export declare function base64ToBytes(b64: string): Uint8Array;
+/** Encode bytes to a base64 string without `Buffer`. */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+//# sourceMappingURL=base64.d.ts.map

package/dist/base64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.d.ts","sourceRoot":"","sources":["../src/base64.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAKrD;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAOvD"}

package/dist/base64.js

@@ -0,0 +1,25 @@
+/**
+ * Buffer-free base64 helpers shared by the `*-nodes` packages.
+ *
+ * `atob`/`btoa` are global on Node ≥ 16 and in every browser, so these work
+ * in both environments without touching `node:buffer` (which the web bundle
+ * stubs out).
+ */
+/** Decode a base64 string to bytes without `Buffer` (works on Node and browser). */
+export function base64ToBytes(b64) {
+    const binary = atob(b64);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        out[i] = binary.charCodeAt(i);
+    return out;
+}
+/** Encode bytes to a base64 string without `Buffer`. */
+export function bytesToBase64(bytes) {
+    let binary = "";
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    }
+    return btoa(binary);
+}
+//# sourceMappingURL=base64.js.map

package/dist/base64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.js","sourceRoot":"","sources":["../src/base64.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,oFAAoF;AACpF,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACzB,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACtE,OAAO,GAAG,CAAC;AACb,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,aAAa,CAAC,KAAiB;IAC7C,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,MAAM,KAAK,GAAG,MAAM,CAAC;IACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC;QAC7C,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;AACtB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @nodetool-ai/nodes-utils — shared helpers for every `*-nodes` package.
+ *
+ * A few small concerns live here so each per-domain package can depend on
+ * a single utility crate instead of duplicating these helpers or pulling
+ * the entire base-nodes barrel just to access them:
+ *
+ *   - `platform-tags.ts` — `tagAsServer` / `tagAsHybrid` / `tagAsUniversal`
+ *     helpers that stamp `static platforms` on `_NODES` arrays.
+ *   - `node-only-modules.ts` — lazy loaders for `node:fs` / `node:path` /
+ *     etc. so non-portable code paths don't block module init on
+ *     non-Node runtimes.
+ *   - `template.ts` — `{{ variable }}` / `{variable}` substitution shared by
+ *     the Prompt, Format Text and Agent nodes.
+ *   - `base64.ts` — Buffer-free base64 encode/decode usable in Node and the
+ *     browser bundle alike.
+ *   - `save-target.ts` — the `save_to_workspace` toggle and the numbered
+ *     filenames every `Save*File` node shares.
+ */
+export { tagAsServer, tagAsNode, tagAsHybrid, tagAsBrowserGpu, tagAsUniversal, tagAsContentCard } from "./platform-tags.js";
+export { loadNodeFsPromises, loadNodeFsSync, loadNodePath, loadNodeOs, loadNodeUrl } from "./node-only-modules.js";
+export { renderTemplate, referencedVariables } from "./template.js";
+export type { TemplateValue, TemplateVars } from "./template.js";
+export { base64ToBytes, bytesToBase64 } from "./base64.js";
+export { resolveModelBytes } from "./model-bytes.js";
+export type { ModelBytesRefLike } from "./model-bytes.js";
+export { SAVE_TO_WORKSPACE_TITLE, SAVE_TO_WORKSPACE_DESCRIPTION, VISIBLE_WHEN_NOT_SAVING_TO_WORKSPACE, folderPathOf, resolveSaveFolder, saveFilename, uniqueFilePath, resolveSaveTarget, writeSavedFile } from "./save-target.js";
+export type { SaveFilenameOptions, SaveFolderOptions, SaveTargetOptions, SaveWorkspace } from "./save-target.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,WAAW,EACX,SAAS,EACT,WAAW,EACX,eAAe,EACf,cAAc,EACd,gBAAgB,EACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,UAAU,EACV,WAAW,EACZ,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,oCAAoC,EACpC,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,cAAc,EACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACd,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,26 @@
+/**
+ * @nodetool-ai/nodes-utils — shared helpers for every `*-nodes` package.
+ *
+ * A few small concerns live here so each per-domain package can depend on
+ * a single utility crate instead of duplicating these helpers or pulling
+ * the entire base-nodes barrel just to access them:
+ *
+ *   - `platform-tags.ts` — `tagAsServer` / `tagAsHybrid` / `tagAsUniversal`
+ *     helpers that stamp `static platforms` on `_NODES` arrays.
+ *   - `node-only-modules.ts` — lazy loaders for `node:fs` / `node:path` /
+ *     etc. so non-portable code paths don't block module init on
+ *     non-Node runtimes.
+ *   - `template.ts` — `{{ variable }}` / `{variable}` substitution shared by
+ *     the Prompt, Format Text and Agent nodes.
+ *   - `base64.ts` — Buffer-free base64 encode/decode usable in Node and the
+ *     browser bundle alike.
+ *   - `save-target.ts` — the `save_to_workspace` toggle and the numbered
+ *     filenames every `Save*File` node shares.
+ */
+export { tagAsServer, tagAsNode, tagAsHybrid, tagAsBrowserGpu, tagAsUniversal, tagAsContentCard } from "./platform-tags.js";
+export { loadNodeFsPromises, loadNodeFsSync, loadNodePath, loadNodeOs, loadNodeUrl } from "./node-only-modules.js";
+export { renderTemplate, referencedVariables } from "./template.js";
+export { base64ToBytes, bytesToBase64 } from "./base64.js";
+export { resolveModelBytes } from "./model-bytes.js";
+export { SAVE_TO_WORKSPACE_TITLE, SAVE_TO_WORKSPACE_DESCRIPTION, VISIBLE_WHEN_NOT_SAVING_TO_WORKSPACE, folderPathOf, resolveSaveFolder, saveFilename, uniqueFilePath, resolveSaveTarget, writeSavedFile } from "./save-target.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,WAAW,EACX,SAAS,EACT,WAAW,EACX,eAAe,EACf,cAAc,EACd,gBAAgB,EACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,UAAU,EACV,WAAW,EACZ,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAGpE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,oCAAoC,EACpC,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,cAAc,EACf,MAAM,kBAAkB,CAAC"}

package/dist/model-bytes.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Browser-safe model-bytes resolution (inline data → storage → uri fetch).
+ *
+ * Moved here from `packages/video-nodes/src/nodes/model3d/render.ts` so the
+ * Blender nodes and `RenderToImage` share it. Stays browser-safe: no
+ * `node:path` at module scope — the one Node-only read (`file://`) loads
+ * `node:fs/promises` and `node:url` through a dynamic import that only runs
+ * when `IS_NODE` is set.
+ */
+import type { ProcessingContext } from "@nodetool-ai/runtime";
+/**
+ * The fields of a model ref this resolution reads. Mirrors
+ * `Model3DRefLike` in video-nodes; node props arrive as `any`, so anything
+ * outside this shape is a runtime edge the null checks below absorb.
+ */
+export interface ModelBytesRefLike {
+    data?: Uint8Array | string;
+    uri?: string;
+}
+/** Browser-safe model-bytes resolution (inline data → storage → uri fetch). */
+export declare function resolveModelBytes(model: ModelBytesRefLike | null | undefined, context?: ProcessingContext): Promise<Uint8Array>;
+//# sourceMappingURL=model-bytes.d.ts.map

package/dist/model-bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-bytes.d.ts","sourceRoot":"","sources":["../src/model-bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAI9D;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,+EAA+E;AAC/E,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,EAC3C,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,UAAU,CAAC,CAyCrB"}

package/dist/model-bytes.js

@@ -0,0 +1,54 @@
+/**
+ * Browser-safe model-bytes resolution (inline data → storage → uri fetch).
+ *
+ * Moved here from `packages/video-nodes/src/nodes/model3d/render.ts` so the
+ * Blender nodes and `RenderToImage` share it. Stays browser-safe: no
+ * `node:path` at module scope — the one Node-only read (`file://`) loads
+ * `node:fs/promises` and `node:url` through a dynamic import that only runs
+ * when `IS_NODE` is set.
+ */
+import { IS_NODE } from "@nodetool-ai/config";
+import { isNonEmptyString } from "@nodetool-ai/protocol";
+import { fetchExternalMedia } from "@nodetool-ai/runtime";
+import { base64ToBytes } from "./base64.js";
+/** Browser-safe model-bytes resolution (inline data → storage → uri fetch). */
+export async function resolveModelBytes(model, context) {
+    if (model === null || model === undefined)
+        return new Uint8Array();
+    const ref = model;
+    if (ref.data instanceof Uint8Array && ref.data.length > 0) {
+        return ref.data;
+    }
+    if (ref.data !== undefined && isNonEmptyString(ref.data)) {
+        return base64ToBytes(ref.data);
+    }
+    const uri = ref.uri ?? "";
+    if (uri === "")
+        return new Uint8Array();
+    if (uri.startsWith("data:")) {
+        const comma = uri.indexOf(",");
+        if (comma === -1)
+            throw new Error(`Malformed data URI: ${uri.slice(0, 32)}…`);
+        return base64ToBytes(uri.slice(comma + 1));
+    }
+    if (context?.storage) {
+        const stored = await context.storage.retrieve(uri);
+        if (stored && stored.length > 0)
+            return new Uint8Array(stored);
+    }
+    if (uri.startsWith("file://") && IS_NODE) {
+        const { readFile } = await import("node:fs/promises");
+        const { fileURLToPath } = await import("node:url");
+        return new Uint8Array(await readFile(fileURLToPath(uri)));
+    }
+    if (uri.startsWith("http://") || uri.startsWith("https://")) {
+        // Caller-supplied media uri — the media-ref egress policy decides.
+        const res = await fetchExternalMedia(uri);
+        if (!res.ok) {
+            throw new Error(`Failed to fetch model (${res.status}): ${uri}`);
+        }
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    return new Uint8Array();
+}
+//# sourceMappingURL=model-bytes.js.map

package/dist/model-bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-bytes.js","sourceRoot":"","sources":["../src/model-bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAY5C,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAA2C,EAC3C,OAA2B;IAE3B,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,UAAU,EAAE,CAAC;IACnE,MAAM,GAAG,GAAG,KAAK,CAAC;IAElB,IAAI,GAAG,CAAC,IAAI,YAAY,UAAU,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1D,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACzD,OAAO,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC;IAC1B,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,IAAI,UAAU,EAAE,CAAC;IAExC,IAAI,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;QAC9E,OAAO,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED,IAAI,OAAO,EAAE,OAAO,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACnD,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IACjE,CAAC;IAED,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,OAAO,EAAE,CAAC;QACzC,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;QACtD,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;QACnD,OAAO,IAAI,UAAU,CAAC,MAAM,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5D,mEAAmE;QACnE,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,CAAC,MAAM,MAAM,GAAG,EAAE,CAAC,CAAC;QACnE,CAAC;QACD,OAAO,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,OAAO,IAAI,UAAU,EAAE,CAAC;AAC1B,CAAC"}

package/dist/node-only-modules.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Lazy loaders for Node.js built-in modules that block static portability.
+ *
+ * Nodes that call into these should declare `static platforms = ["node"]`
+ * — the module remains loadable on every runtime (the dynamic import is
+ * never evaluated at module-init time), but the specific node fails at
+ * call time if invoked off-Node. The platform filter prevents that from
+ * happening in normal use.
+ *
+ * Centralised here so the classifier can attribute the dynamic-import
+ * blocker to a single source path; per-module imports of these helpers
+ * are relative and don't appear in the external-import set.
+ */
+export declare function loadNodeFsPromises(): Promise<typeof import("node:fs").promises>;
+export declare function loadNodeFsSync(): Promise<typeof import("node:fs")>;
+export declare function loadNodePath(): Promise<typeof import("node:path")>;
+export declare function loadNodeOs(): Promise<typeof import("node:os")>;
+export declare function loadNodeUrl(): Promise<typeof import("node:url")>;
+//# sourceMappingURL=node-only-modules.d.ts.map

package/dist/node-only-modules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-only-modules.d.ts","sourceRoot":"","sources":["../src/node-only-modules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,wBAAsB,kBAAkB,IAAI,OAAO,CACjD,cAAc,SAAS,EAAE,QAAQ,CAClC,CAGA;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,cAAc,SAAS,CAAC,CAAC,CAExE;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,cAAc,WAAW,CAAC,CAAC,CAExE;AAED,wBAAsB,UAAU,IAAI,OAAO,CAAC,cAAc,SAAS,CAAC,CAAC,CAEpE;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,cAAc,UAAU,CAAC,CAAC,CAEtE"}

package/dist/node-only-modules.js

@@ -0,0 +1,30 @@
+/**
+ * Lazy loaders for Node.js built-in modules that block static portability.
+ *
+ * Nodes that call into these should declare `static platforms = ["node"]`
+ * — the module remains loadable on every runtime (the dynamic import is
+ * never evaluated at module-init time), but the specific node fails at
+ * call time if invoked off-Node. The platform filter prevents that from
+ * happening in normal use.
+ *
+ * Centralised here so the classifier can attribute the dynamic-import
+ * blocker to a single source path; per-module imports of these helpers
+ * are relative and don't appear in the external-import set.
+ */
+export async function loadNodeFsPromises() {
+    const mod = await import("node:fs");
+    return mod.promises;
+}
+export async function loadNodeFsSync() {
+    return import("node:fs");
+}
+export async function loadNodePath() {
+    return import("node:path");
+}
+export async function loadNodeOs() {
+    return import("node:os");
+}
+export async function loadNodeUrl() {
+    return import("node:url");
+}
+//# sourceMappingURL=node-only-modules.js.map

package/dist/node-only-modules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-only-modules.js","sourceRoot":"","sources":["../src/node-only-modules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,KAAK,UAAU,kBAAkB;IAGtC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;IACpC,OAAO,GAAG,CAAC,QAAQ,CAAC;AACtB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC;AAC3B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,OAAO,MAAM,CAAC,WAAW,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC;AAC3B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,OAAO,MAAM,CAAC,UAAU,CAAC,CAAC;AAC5B,CAAC"}

package/dist/platform-tags.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Platform tagging helpers for base-nodes.
+ *
+ * `tagAsServer(classes)` stamps `static platforms = SERVER_PLATFORMS` on
+ * every class in a registration array — declaring support for `node`,
+ * `workers`, and `edge` but **not** `browser`. This is the right default
+ * for nodes that make outbound HTTP calls or read env secrets (most LLM,
+ * HTTP, search, and integration nodes) — they can't be safely shipped to
+ * a browser tab without a separate CORS/secrets story.
+ *
+ * `tagAsHybrid(classes)` stamps `["node", "browser"]` — for nodes with a
+ * Node execution path AND a browser one but no V8-isolate path, typical
+ * of WebGPU shader nodes (Workers and Edge runtimes lack WebGPU).
+ *
+ * `tagAsUniversal(classes)` stamps `ALL_PLATFORMS` — for nodes that
+ * genuinely work on every runtime including the browser. Use sparingly:
+ * the node must handle CORS / secret-exposure / bundle-size implications
+ * itself.
+ *
+ * All three helpers leave alone any class that already declares its own
+ * `static platforms` — per-class overrides always win. The mutation is a
+ * one-time `Object.defineProperty` at module load.
+ */
+import type { NodeClass } from "@nodetool-ai/node-sdk";
+/** Tag every class in `classes` as supporting node + workers + edge. */
+export declare function tagAsServer<T extends readonly NodeClass[]>(classes: T): T;
+/**
+ * Tag every class in `classes` as supporting **only** the node tier — the
+ * (otherwise implicit) most-restrictive default. Use for nodes that spawn a
+ * subprocess (ffmpeg, ffprobe, yt-dlp, …) or write os.tmpdir() temp files:
+ * the workers (Cloudflare V8) and edge (Vercel/Deno) tiers have no subprocess
+ * and no filesystem, so offering them there is a guaranteed runtime failure.
+ * Stamping it explicitly documents the intent rather than relying on the
+ * unset default. Leaves any class with its own `static platforms` alone.
+ */
+export declare function tagAsNode<T extends readonly NodeClass[]>(classes: T): T;
+/**
+ * Tag every class in `classes` as supporting node + browser (no V8 server
+ * isolates). Use for WebGPU / Canvas / DOM-backed nodes that have both a
+ * Node fallback and a browser-native execution path.
+ */
+export declare function tagAsHybrid<T extends readonly NodeClass[]>(classes: T): T;
+/**
+ * Tag every class in `classes` as supporting every defined platform.
+ * Reserve for pure-JS nodes with no network calls, no secrets, and no
+ * platform-specific side effects (e.g. text/data transforms).
+ */
+export declare function tagAsUniversal<T extends readonly NodeClass[]>(classes: T): T;
+/**
+ * Like {@link tagAsHybrid} (node + browser) but additionally marks the classes
+ * as requiring a WebGPU device in the browser. WebGPU shader nodes use this so
+ * the in-browser runner routes graphs containing them to the server — where a
+ * GPU is always available via Dawn — when `navigator.gpu` is missing, instead
+ * of failing the run. Server execution is unchanged.
+ *
+ * `requiresGpu` is stamped only on classes that end up browser-capable: a class
+ * already tagged server keeps its platforms and is left unmarked (it can't run
+ * in the browser anyway). Per-class `static requiresGpu` overrides win.
+ */
+export declare function tagAsBrowserGpu<T extends readonly NodeClass[]>(classes: T): T;
+/**
+ * Stamp `static body = "content_card"` on every class in `classes` so the
+ * editor renders them as a media content card (the image/video/audio preview
+ * body) instead of the generic input/output layout. Leaves any class that
+ * already declares its own `static body` alone — per-class overrides win.
+ *
+ * Apply to media-output node groups, composing with a platform tagger:
+ * `tagAsHybrid(tagAsContentCard([...]))`.
+ */
+export declare function tagAsContentCard<T extends readonly NodeClass[]>(classes: T): T;
+//# sourceMappingURL=platform-tags.d.ts.map

package/dist/platform-tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-tags.d.ts","sourceRoot":"","sources":["../src/platform-tags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAyBvD,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,SAAS,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAEzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,SAAS,SAAS,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAEvE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,SAAS,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,SAAS,SAAS,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAE5E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,SAAS,SAAS,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAc7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,SAAS,SAAS,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAW9E"}

package/dist/platform-tags.js

@@ -0,0 +1,120 @@
+/**
+ * Platform tagging helpers for base-nodes.
+ *
+ * `tagAsServer(classes)` stamps `static platforms = SERVER_PLATFORMS` on
+ * every class in a registration array — declaring support for `node`,
+ * `workers`, and `edge` but **not** `browser`. This is the right default
+ * for nodes that make outbound HTTP calls or read env secrets (most LLM,
+ * HTTP, search, and integration nodes) — they can't be safely shipped to
+ * a browser tab without a separate CORS/secrets story.
+ *
+ * `tagAsHybrid(classes)` stamps `["node", "browser"]` — for nodes with a
+ * Node execution path AND a browser one but no V8-isolate path, typical
+ * of WebGPU shader nodes (Workers and Edge runtimes lack WebGPU).
+ *
+ * `tagAsUniversal(classes)` stamps `ALL_PLATFORMS` — for nodes that
+ * genuinely work on every runtime including the browser. Use sparingly:
+ * the node must handle CORS / secret-exposure / bundle-size implications
+ * itself.
+ *
+ * All three helpers leave alone any class that already declares its own
+ * `static platforms` — per-class overrides always win. The mutation is a
+ * one-time `Object.defineProperty` at module load.
+ */
+import { ALL_PLATFORMS, DEFAULT_PLATFORMS, NODE_AND_BROWSER_PLATFORMS, SERVER_PLATFORMS } from "@nodetool-ai/protocol";
+function tagWith(classes, platforms) {
+    for (const cls of classes) {
+        if (cls.platforms !== undefined)
+            continue;
+        Object.defineProperty(cls, "platforms", {
+            value: platforms,
+            writable: false,
+            configurable: true,
+            enumerable: true
+        });
+    }
+    return classes;
+}
+/** Tag every class in `classes` as supporting node + workers + edge. */
+export function tagAsServer(classes) {
+    return tagWith(classes, SERVER_PLATFORMS);
+}
+/**
+ * Tag every class in `classes` as supporting **only** the node tier — the
+ * (otherwise implicit) most-restrictive default. Use for nodes that spawn a
+ * subprocess (ffmpeg, ffprobe, yt-dlp, …) or write os.tmpdir() temp files:
+ * the workers (Cloudflare V8) and edge (Vercel/Deno) tiers have no subprocess
+ * and no filesystem, so offering them there is a guaranteed runtime failure.
+ * Stamping it explicitly documents the intent rather than relying on the
+ * unset default. Leaves any class with its own `static platforms` alone.
+ */
+export function tagAsNode(classes) {
+    return tagWith(classes, DEFAULT_PLATFORMS);
+}
+/**
+ * Tag every class in `classes` as supporting node + browser (no V8 server
+ * isolates). Use for WebGPU / Canvas / DOM-backed nodes that have both a
+ * Node fallback and a browser-native execution path.
+ */
+export function tagAsHybrid(classes) {
+    return tagWith(classes, NODE_AND_BROWSER_PLATFORMS);
+}
+/**
+ * Tag every class in `classes` as supporting every defined platform.
+ * Reserve for pure-JS nodes with no network calls, no secrets, and no
+ * platform-specific side effects (e.g. text/data transforms).
+ */
+export function tagAsUniversal(classes) {
+    return tagWith(classes, ALL_PLATFORMS);
+}
+/**
+ * Like {@link tagAsHybrid} (node + browser) but additionally marks the classes
+ * as requiring a WebGPU device in the browser. WebGPU shader nodes use this so
+ * the in-browser runner routes graphs containing them to the server — where a
+ * GPU is always available via Dawn — when `navigator.gpu` is missing, instead
+ * of failing the run. Server execution is unchanged.
+ *
+ * `requiresGpu` is stamped only on classes that end up browser-capable: a class
+ * already tagged server keeps its platforms and is left unmarked (it can't run
+ * in the browser anyway). Per-class `static requiresGpu` overrides win.
+ */
+export function tagAsBrowserGpu(classes) {
+    const tagged = tagWith(classes, NODE_AND_BROWSER_PLATFORMS);
+    for (const cls of tagged) {
+        const platforms = cls.platforms;
+        if (!platforms?.includes("browser"))
+            continue;
+        if (cls.requiresGpu !== undefined)
+            continue;
+        Object.defineProperty(cls, "requiresGpu", {
+            value: true,
+            writable: false,
+            configurable: true,
+            enumerable: true
+        });
+    }
+    return tagged;
+}
+/**
+ * Stamp `static body = "content_card"` on every class in `classes` so the
+ * editor renders them as a media content card (the image/video/audio preview
+ * body) instead of the generic input/output layout. Leaves any class that
+ * already declares its own `static body` alone — per-class overrides win.
+ *
+ * Apply to media-output node groups, composing with a platform tagger:
+ * `tagAsHybrid(tagAsContentCard([...]))`.
+ */
+export function tagAsContentCard(classes) {
+    for (const cls of classes) {
+        if (cls.body !== undefined)
+            continue;
+        Object.defineProperty(cls, "body", {
+            value: "content_card",
+            writable: false,
+            configurable: true,
+            enumerable: true
+        });
+    }
+    return classes;
+}
+//# sourceMappingURL=platform-tags.js.map

package/dist/platform-tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-tags.js","sourceRoot":"","sources":["../src/platform-tags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,0BAA0B,EAC1B,gBAAgB,EAEjB,MAAM,uBAAuB,CAAC;AAE/B,SAAS,OAAO,CACd,OAAU,EACV,SAA8B;IAE9B,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS;YAAE,SAAS;QAC1C,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,WAAW,EAAE;YACtC,KAAK,EAAE,SAAS;YAChB,QAAQ,EAAE,KAAK;YACf,YAAY,EAAE,IAAI;YAClB,UAAU,EAAE,IAAI;SACjB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAiC,OAAU;IACpE,OAAO,OAAO,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAiC,OAAU;IAClE,OAAO,OAAO,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAiC,OAAU;IACpE,OAAO,OAAO,CAAC,OAAO,EAAE,0BAA0B,CAAC,CAAC;AACtD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAiC,OAAU;IACvE,OAAO,OAAO,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAiC,OAAU;IACxE,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,0BAA0B,CAAC,CAAC;IAC5D,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,SAAS,CAAC;YAAE,SAAS;QAC9C,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS;YAAE,SAAS;QAC5C,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,aAAa,EAAE;YACxC,KAAK,EAAE,IAAI;YACX,QAAQ,EAAE,KAAK;YACf,YAAY,EAAE,IAAI;YAClB,UAAU,EAAE,IAAI;SACjB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAiC,OAAU;IACzE,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS;YAAE,SAAS;QACrC,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE;YACjC,KAAK,EAAE,cAAc;YACrB,QAAQ,EAAE,KAAK;YACf,YAAY,EAAE,IAAI;YAClB,UAAU,EAAE,IAAI;SACjB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/save-target.d.ts

@@ -0,0 +1,115 @@
+/** Title every save node shows on the workspace toggle. */
+export declare const SAVE_TO_WORKSPACE_TITLE = "Save to workspace";
+/** Description every save node shows on the workspace toggle. */
+export declare const SAVE_TO_WORKSPACE_DESCRIPTION = "Write the file into this workflow's workspace folder and number it (name_1, name_2, \u2026) instead of overwriting. Turn this off to choose a folder yourself.";
+/**
+ * `json_schema_extra` for a folder property that only applies while the
+ * workspace toggle is off. The editor hides the field rather than showing a
+ * path that has no effect.
+ */
+export declare const VISIBLE_WHEN_NOT_SAVING_TO_WORKSPACE: {
+    readonly visible_when: {
+        readonly property: "save_to_workspace";
+        readonly equals: false;
+    };
+};
+/** A folder ref — what a `folder`-typed property carries. */
+interface FolderRefValue {
+    uri?: string;
+}
+/** Every shape a node's `folder` property arrives in. */
+export type FolderValue = string | FolderRefValue | null | undefined;
+/**
+ * Read a folder property, which may be a plain path, a `file://` URI or a
+ * folder ref object. Returns "" when nothing usable is set.
+ */
+export declare function folderPathOf(raw: FolderValue): string;
+/**
+ * The slice of the run's workspace a save node needs.
+ *
+ * Structural rather than imported: `@nodetool-ai/nodes-utils` sits below
+ * `@nodetool-ai/runtime` in the dependency order, and a `ProcessingContext`'s
+ * `workspace` satisfies this shape.
+ */
+export interface SaveWorkspace {
+    localDir: string | null;
+    exists(path: string): Promise<boolean>;
+    write(path: string, data: Uint8Array | string, contentType?: string): Promise<void>;
+}
+export interface SaveFolderOptions {
+    /** The node's `folder` property, whatever shape it arrived in. */
+    folder: FolderValue;
+    /** The node's `save_to_workspace` property. */
+    saveToWorkspace: boolean | undefined;
+    /** `context.workspace` — null when the run has no workspace. */
+    workspace?: SaveWorkspace | null;
+    /**
+     * `context.workspaceDir`. Only meaningful for a workspace that is a real
+     * folder; a cloud run has none and saves through `workspace` instead.
+     */
+    workspaceDir?: string | null;
+}
+/**
+ * Pick the destination folder.
+ *
+ * With the toggle on, the workspace folder wins over the `folder` property —
+ * the editor hides that field while the toggle is on, so a value left there is
+ * a leftover, not a choice. A run with no workspace assigned has nowhere to put
+ * the file, so it falls back to the folder and finally to the working
+ * directory rather than failing the run.
+ */
+export declare function resolveSaveFolder(opts: SaveFolderOptions): string;
+/** What a save node calls its file when the user leaves the name empty. */
+export interface SaveFilenameOptions {
+    /** The node's filename property, with date tokens already expanded. */
+    filename: string;
+    /** The name to use when `filename` is blank. Carries its own extension. */
+    fallback: string;
+    /** Extension (with the dot) to append when the name carries none. */
+    extension?: string;
+}
+/**
+ * The name a save node writes under.
+ *
+ * A blank name used to reach `path.resolve(folder, "")`, which is the folder
+ * itself: the file landed *beside* the workspace, named after it, with no
+ * extension. And a name typed without one ("render") produced a file no image
+ * viewer would open. Both are answered here rather than in each node.
+ */
+export declare function saveFilename(opts: SaveFilenameOptions): string;
+/**
+ * Return a path nothing occupies: `target` itself when free, otherwise
+ * `name_1.ext`, `name_2.ext`, … in the same directory.
+ */
+export declare function uniqueFilePath(target: string): Promise<string>;
+export interface SaveTargetOptions extends SaveFolderOptions {
+    /** The node's filename property, with date tokens already expanded. */
+    filename: string;
+    /** Skip the numbered suffix and write over an existing file. */
+    overwrite?: boolean;
+}
+/**
+ * Resolve folder + filename into an absolute path ready to write to: the
+ * directory exists when this returns, and the name does not collide unless the
+ * caller asked to overwrite.
+ */
+export declare function resolveSaveTarget(opts: SaveTargetOptions): Promise<string>;
+/**
+ * Write a saved file where the node's properties say it goes, and report the
+ * path it landed on.
+ *
+ * With the workspace toggle on this writes through the workspace, so the same
+ * node produces a file in the user's folder locally and an object in their
+ * workspace prefix in the cloud. The name is deduplicated the same way in both
+ * cases — a run that saves twice in one second must not silently overwrite its
+ * first output.
+ *
+ * With the toggle off the node is naming a host folder, which only exists on a
+ * local install; a cloud run has no such folder and says so rather than writing
+ * somewhere the user will never find.
+ */
+export declare function writeSavedFile(opts: SaveTargetOptions & {
+    bytes: Uint8Array | string;
+}): Promise<string>;
+export {};
+//# sourceMappingURL=save-target.d.ts.map

package/dist/save-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"save-target.d.ts","sourceRoot":"","sources":["../src/save-target.ts"],"names":[],"mappings":"AAiBA,2DAA2D;AAC3D,eAAO,MAAM,uBAAuB,sBAAsB,CAAC;AAE3D,iEAAiE;AACjE,eAAO,MAAM,6BAA6B,mKACmH,CAAC;AAE9J;;;;GAIG;AACH,eAAO,MAAM,oCAAoC;aAC/C,YAAY;iBAAI,QAAQ,EAAE,mBAAmB;iBAAE,MAAM;;CAC7C,CAAC;AAaX,6DAA6D;AAC7D,UAAU,cAAc;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,yDAAyD;AACzD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,cAAc,GAAG,IAAI,GAAG,SAAS,CAAC;AAcrE;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAIrD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrF;AAED,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,MAAM,EAAE,WAAW,CAAC;IACpB,+CAA+C;IAC/C,eAAe,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,gEAAgE;IAChE,SAAS,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IACjC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAOjE;AAED,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAO9D;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBpE;AAoBD,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,MAAM,CAAC,CAOjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,iBAAiB,GAAG;IAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAAA;CAAE,GACvD,OAAO,CAAC,MAAM,CAAC,CA4BjB"}

package/dist/save-target.js

@@ -0,0 +1,202 @@
+/**
+ * Destination resolution shared by every node that writes a file to disk
+ * (`nodetool.image.SaveImageFile`, `SaveAudioFile`, `SaveTextFile`,
+ * `SaveVideoFile`, `SaveDocumentFile`, `SaveModel3DFile`).
+ *
+ * Two things every one of them needs and each used to solve on its own:
+ *
+ *  - **Where to write.** Without a folder they fell back to `.` — the server
+ *    process working directory, which is almost never where a user wants
+ *    output. The `save_to_workspace` toggle points them at the run's workspace
+ *    folder instead.
+ *  - **What to call it.** Filenames carry second-granularity date tokens, so
+ *    two saves in the same second collided and one silently overwrote the
+ *    other. `uniqueFilePath` numbers them `name_1.ext`, `name_2.ext`, …
+ */
+import { loadNodeFsPromises, loadNodePath } from "./node-only-modules.js";
+/** Title every save node shows on the workspace toggle. */
+export const SAVE_TO_WORKSPACE_TITLE = "Save to workspace";
+/** Description every save node shows on the workspace toggle. */
+export const SAVE_TO_WORKSPACE_DESCRIPTION = "Write the file into this workflow's workspace folder and number it (name_1, name_2, …) instead of overwriting. Turn this off to choose a folder yourself.";
+/**
+ * `json_schema_extra` for a folder property that only applies while the
+ * workspace toggle is off. The editor hides the field rather than showing a
+ * path that has no effect.
+ */
+export const VISIBLE_WHEN_NOT_SAVING_TO_WORKSPACE = {
+    visible_when: { property: "save_to_workspace", equals: false }
+};
+/** Turn a `file://` URI into a plain path; leave a plain path alone. */
+function toPath(value) {
+    if (!value.startsWith("file://"))
+        return value;
+    const rest = value.slice("file://".length);
+    try {
+        return decodeURIComponent(rest);
+    }
+    catch {
+        return rest;
+    }
+}
+function isPathString(value) {
+    return typeof value === "string";
+}
+function isFolderRef(value) {
+    return typeof value === "object" && value !== null;
+}
+function isSetString(value) {
+    return value !== undefined && value.trim() !== "";
+}
+/**
+ * Read a folder property, which may be a plain path, a `file://` URI or a
+ * folder ref object. Returns "" when nothing usable is set.
+ */
+export function folderPathOf(raw) {
+    if (isPathString(raw))
+        return toPath(raw.trim());
+    if (isFolderRef(raw) && isSetString(raw.uri))
+        return toPath(raw.uri.trim());
+    return "";
+}
+/**
+ * Pick the destination folder.
+ *
+ * With the toggle on, the workspace folder wins over the `folder` property —
+ * the editor hides that field while the toggle is on, so a value left there is
+ * a leftover, not a choice. A run with no workspace assigned has nowhere to put
+ * the file, so it falls back to the folder and finally to the working
+ * directory rather than failing the run.
+ */
+export function resolveSaveFolder(opts) {
+    const folder = folderPathOf(opts.folder);
+    const workspaceDir = opts.workspace?.localDir ?? opts.workspaceDir ?? null;
+    if (opts.saveToWorkspace === true && workspaceDir) {
+        return workspaceDir;
+    }
+    return folder || workspaceDir || ".";
+}
+/**
+ * The name a save node writes under.
+ *
+ * A blank name used to reach `path.resolve(folder, "")`, which is the folder
+ * itself: the file landed *beside* the workspace, named after it, with no
+ * extension. And a name typed without one ("render") produced a file no image
+ * viewer would open. Both are answered here rather than in each node.
+ */
+export function saveFilename(opts) {
+    const name = opts.filename.trim() || opts.fallback.trim();
+    const ext = opts.extension;
+    if (!ext)
+        return name;
+    const dot = name.lastIndexOf(".");
+    const hasExtension = dot > 0 && dot < name.length - 1;
+    return hasExtension ? name : `${name}${ext}`;
+}
+/**
+ * Return a path nothing occupies: `target` itself when free, otherwise
+ * `name_1.ext`, `name_2.ext`, … in the same directory.
+ */
+export async function uniqueFilePath(target) {
+    const fs = await loadNodeFsPromises();
+    const path = await loadNodePath();
+    const exists = async (p) => {
+        try {
+            await fs.access(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (!(await exists(target)))
+        return target;
+    const dir = path.dirname(target);
+    const ext = path.extname(target);
+    const base = path.basename(target, ext);
+    for (let i = 1;; i++) {
+        const candidate = path.join(dir, `${base}_${i}${ext}`);
+        if (!(await exists(candidate)))
+            return candidate;
+    }
+}
+/**
+ * Refuse a blank name instead of resolving it to the destination folder.
+ *
+ * Every save node supplies a fallback via {@link saveFilename}; one that
+ * forgets must fail loudly rather than write a file over the folder's own
+ * name, one level up from where the user asked for it.
+ */
+function requireFilename(filename) {
+    const name = filename.trim();
+    if (!name) {
+        throw new Error("This save node resolved to an empty filename. Set a filename on the " +
+            "node.");
+    }
+    return name;
+}
+/**
+ * Resolve folder + filename into an absolute path ready to write to: the
+ * directory exists when this returns, and the name does not collide unless the
+ * caller asked to overwrite.
+ */
+export async function resolveSaveTarget(opts) {
+    const fs = await loadNodeFsPromises();
+    const path = await loadNodePath();
+    const folder = resolveSaveFolder(opts);
+    const target = path.resolve(folder, requireFilename(opts.filename));
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    return opts.overwrite === true ? target : uniqueFilePath(target);
+}
+/**
+ * Write a saved file where the node's properties say it goes, and report the
+ * path it landed on.
+ *
+ * With the workspace toggle on this writes through the workspace, so the same
+ * node produces a file in the user's folder locally and an object in their
+ * workspace prefix in the cloud. The name is deduplicated the same way in both
+ * cases — a run that saves twice in one second must not silently overwrite its
+ * first output.
+ *
+ * With the toggle off the node is naming a host folder, which only exists on a
+ * local install; a cloud run has no such folder and says so rather than writing
+ * somewhere the user will never find.
+ */
+export async function writeSavedFile(opts) {
+    const workspace = opts.workspace ?? null;
+    const isVirtual = workspace !== null && workspace.localDir === null;
+    if (opts.saveToWorkspace === true && workspace) {
+        if (isVirtual) {
+            const filename = requireFilename(opts.filename);
+            const target = opts.overwrite === true
+                ? filename
+                : await uniqueWorkspacePath(workspace, filename);
+            await workspace.write(target, opts.bytes);
+            return target;
+        }
+        // A local workspace is a real folder, so the file goes there by path —
+        // which is what a user browsing their workspace on disk expects.
+    }
+    else if (isVirtual) {
+        throw new Error("This node writes to a folder on the machine running the workflow, and " +
+            "this run's workspace is cloud storage with no such folder. Turn on " +
+            '"Save to workspace" to write into the workspace instead.');
+    }
+    const fs = await loadNodeFsPromises();
+    const target = await resolveSaveTarget(opts);
+    await fs.writeFile(target, opts.bytes);
+    return target;
+}
+/** `name.ext`, `name_1.ext`, … — the first one the workspace does not hold. */
+async function uniqueWorkspacePath(workspace, filename) {
+    if (!(await workspace.exists(filename)))
+        return filename;
+    const dot = filename.lastIndexOf(".");
+    const base = dot > 0 ? filename.slice(0, dot) : filename;
+    const ext = dot > 0 ? filename.slice(dot) : "";
+    for (let i = 1;; i++) {
+        const candidate = `${base}_${i}${ext}`;
+        if (!(await workspace.exists(candidate)))
+            return candidate;
+    }
+}
+//# sourceMappingURL=save-target.js.map

package/dist/save-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"save-target.js","sourceRoot":"","sources":["../src/save-target.ts"],"names":[],"mappings":"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"}

package/dist/template.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared `{{ variable }}` / `{variable}` template substitution.
+ *
+ * Used by the Prompt and Format Text nodes and by the Agent node so they all
+ * resolve placeholders the same way:
+ *   - `{{ name }}` and `{name}` are replaced with the matching variable value.
+ *   - `{{ name|filter1|filter2 }}` applies Jinja-style filters in order
+ *     (upper, lower, capitalize, title, trim, truncate(n), default(val)).
+ *   - Placeholders whose variable is absent are left intact.
+ */
+/**
+ * Names of the variables a template references via `{{ name }}` /
+ * `{{ name|filter }}` / `{name}`. De-duplicated, in first-seen order. Used by
+ * the Prompt node to know which variable channels to await before rendering.
+ */
+export declare function referencedVariables(template: string): string[];
+/**
+ * One template variable's value. The renderer substitutes `String(value ?? "")`
+ * and then runs string filters over the result, so the contract is "a scalar
+ * with a meaningful string form"; `null` and `undefined` render as the empty
+ * string. Callers holding a richer value stringify it at their own boundary,
+ * where they know what its string form should be — the renderer's
+ * `[object Object]` is never that.
+ */
+export type TemplateValue = string | number | boolean | null | undefined;
+/** The variable bag `renderTemplate` substitutes from. */
+export type TemplateVars = Record<string, TemplateValue>;
+/**
+ * Substitute `{{ variable }}` / `{variable}` placeholders in `template` with
+ * values from `vars`. Unknown placeholders are left intact.
+ */
+export declare function renderTemplate(template: string, vars: TemplateVars): string;
+//# sourceMappingURL=template.d.ts.map

package/dist/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAoCH;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAe9D;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;AAEzE,0DAA0D;AAC1D,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,MAAM,CA6B3E"}

package/dist/template.js

@@ -0,0 +1,97 @@
+/**
+ * Shared `{{ variable }}` / `{variable}` template substitution.
+ *
+ * Used by the Prompt and Format Text nodes and by the Agent node so they all
+ * resolve placeholders the same way:
+ *   - `{{ name }}` and `{name}` are replaced with the matching variable value.
+ *   - `{{ name|filter1|filter2 }}` applies Jinja-style filters in order
+ *     (upper, lower, capitalize, title, trim, truncate(n), default(val)).
+ *   - Placeholders whose variable is absent are left intact.
+ */
+function toTitleCase(value) {
+    return value.replace(/\w\S*/g, (txt) => txt.charAt(0).toUpperCase() + txt.slice(1).toLowerCase());
+}
+function applyFilter(value, filter) {
+    const trimmed = filter.trim();
+    if (trimmed === "upper")
+        return value.toUpperCase();
+    if (trimmed === "lower")
+        return value.toLowerCase();
+    if (trimmed === "capitalize") {
+        return value.length === 0
+            ? ""
+            : value.charAt(0).toUpperCase() + value.slice(1).toLowerCase();
+    }
+    if (trimmed === "title")
+        return toTitleCase(value);
+    if (trimmed === "trim")
+        return value.trim();
+    const truncateMatch = trimmed.match(/^truncate\((\d+)\)$/);
+    if (truncateMatch) {
+        const n = Number(truncateMatch[1]);
+        return value.length <= n ? value : value.slice(0, n) + "...";
+    }
+    const defaultMatch = trimmed.match(/^default\((.+)\)$/);
+    if (defaultMatch) {
+        return value === "" ? defaultMatch[1].replace(/^['"]|['"]$/g, "") : value;
+    }
+    return value;
+}
+function applyFilters(value, filters) {
+    return filters.reduce((result, f) => applyFilter(result, f), value);
+}
+/**
+ * Names of the variables a template references via `{{ name }}` /
+ * `{{ name|filter }}` / `{name}`. De-duplicated, in first-seen order. Used by
+ * the Prompt node to know which variable channels to await before rendering.
+ */
+export function referencedVariables(template) {
+    const names = new Set();
+    // {{ name|filter... }} — leading identifier before any filter.
+    for (const match of template.matchAll(/\{\{([^{}]+?)\}\}/g)) {
+        const name = match[1].split("|")[0].trim();
+        if (name)
+            names.add(name);
+    }
+    // {name} — single brace, not adjacent to another brace.
+    for (const match of template.matchAll(/(?<!\{)\{([^{}]+?)\}(?!\})/g)) {
+        const name = match[1].trim();
+        // Skip anything that looks like a filter expression; single-brace refs are
+        // bare names only.
+        if (name && !name.includes("|"))
+            names.add(name);
+    }
+    return [...names];
+}
+/**
+ * Substitute `{{ variable }}` / `{variable}` placeholders in `template` with
+ * values from `vars`. Unknown placeholders are left intact.
+ */
+export function renderTemplate(template, vars) {
+    let result = template;
+    // {{ var|filter1|filter2 }}. The content class excludes both braces so the
+    // lazy repetition can't scan across `{`/`}` runs — without that, inputs like
+    // `{{{{{{...` give quadratic backtracking (CodeQL polynomial-ReDoS). A
+    // placeholder expression never legitimately contains a brace. Surrounding
+    // whitespace is handled by the per-part trim() below.
+    result = result.replace(/\{\{([^{}]+?)\}\}/g, (match, expr) => {
+        const parts = expr.split("|").map((p) => p.trim());
+        const varName = parts[0];
+        if (varName in vars) {
+            const strValue = String(vars[varName] ?? "");
+            return parts.length > 1
+                ? applyFilters(strValue, parts.slice(1))
+                : strValue;
+        }
+        return match;
+    });
+    // {var} (single brace, no filters)
+    for (const [key, value] of Object.entries(vars)) {
+        const strValue = String(value ?? "");
+        const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const single = new RegExp(`(?<!\\{)\\{${escapedKey}\\}(?!\\})`, "g");
+        result = result.replace(single, () => strValue);
+    }
+    return result;
+}
+//# sourceMappingURL=template.js.map

package/dist/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@nodetool-ai/nodes-utils",
+  "version": "0.8.1",
+  "description": "Shared helpers for node packages: platform tags and lazy Node-only module loaders",
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "node ../../scripts/build-typescript-workspace.mjs",
+    "test": "node ../../scripts/run-vitest.mjs run",
+    "test:watch": "node ../../scripts/run-vitest.mjs",
+    "lint": "node ../../scripts/run-tsc.mjs --noEmit"
+  },
+  "dependencies": {
+    "@nodetool-ai/config": "^0.8.1",
+    "@nodetool-ai/node-sdk": "^0.8.1",
+    "@nodetool-ai/protocol": "^0.8.1",
+    "@nodetool-ai/runtime": "^0.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "vitest": "^5.0.1"
+  },
+  "exports": {
+    ".": {
+      "nodetool-dev": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodetool-ai/nodetool.git",
+    "directory": "packages/nodes-utils"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "homepage": "https://nodetool.ai",
+  "bugs": {
+    "url": "https://github.com/nodetool-ai/nodetool/issues"
+  },
+  "keywords": [
+    "nodetool",
+    "ai",
+    "workflow",
+    "workflow-automation",
+    "typescript",
+    "utilities",
+    "helpers",
+    "platform"
+  ]
+}