@nanobpm/urban 0.20.0 → 0.22.0

package/dist/runtime/core/validate.js

@@ -8,7 +8,7 @@
 // schema JSON means the envelope check tracks the published schema and can't drift from it
 // silently — the whole point of consuming the package rather than vendoring a copy.
 import schema from "@nanobpm/nano-app-schema/schema" with { type: "json" };
-import { workerJobType } from "./manifest.js";
+import { isRecord } from "./guards.js";
 export class ManifestValidationError extends Error {
     issues;
     constructor(issues) {
@@ -22,7 +22,7 @@ const S = schema;
 /** Validate a parsed manifest. Returns the list of issues (empty === valid). */
 export function collectManifestIssues(m) {
     const issues = [];
-    if (m === null || typeof m !== "object" || Array.isArray(m)) {
+    if (!isRecord(m)) {
         return [{ path: "$", message: "manifest must be a JSON object" }];
     }
     const obj = m;
@@ -50,10 +50,11 @@ export function collectManifestIssues(m) {
         issues.push({ path: "name", message: "must be a non-empty string" });
     }
     // — Runtime binding rules —
-    const man = obj;
-    if (Array.isArray(man.workers)) {
-        man.workers.forEach((w, i) => {
-            if (!workerJobType(w)) {
+    const workers = Array.isArray(obj.workers) ? obj.workers : undefined;
+    if (workers) {
+        workers.forEach((w, i) => {
+            const worker = isRecord(w) ? w : undefined;
+            if (typeof worker?.taskType !== "string" || worker.taskType.length === 0) {
                 issues.push({ path: `workers[${i}]`, message: "missing taskType" });
             }
             // A worker is backed by exactly one of: a `handler` file, an `llm` binding,
@@ -62,11 +63,11 @@ export function collectManifestIssues(m) {
             // `connector` actually resolves to an installed pack is a runtime seam check
             // (mountConnectors), not something this static manifest check can see.
             const backings = [];
-            if (typeof w?.handler === "string" && w.handler.length > 0)
+            if (typeof worker?.handler === "string" && worker.handler.length > 0)
                 backings.push("handler");
-            if (typeof w?.llm === "string" && w.llm.length > 0)
+            if (typeof worker?.llm === "string" && worker.llm.length > 0)
                 backings.push("llm");
-            if (typeof w?.connector === "string" && w.connector.length > 0)
+            if (typeof worker?.connector === "string" && worker.connector.length > 0)
                 backings.push("connector");
             if (backings.length === 0) {
                 issues.push({
@@ -81,34 +82,38 @@ export function collectManifestIssues(m) {
                 });
             }
             // A `connection` must reference a declared top-level `connections` entry.
-            if (typeof w?.connection === "string" && w.connection.length > 0) {
-                const conns = man.connections && typeof man.connections === "object" && !Array.isArray(man.connections)
-                    ? man.connections
+            if (typeof worker?.connection === "string" && worker.connection.length > 0) {
+                const conns = isRecord(obj.connections)
+                    ? obj.connections
                     : undefined;
-                if (!conns || !(w.connection in conns)) {
+                if (!conns || !(worker.connection in conns)) {
                     issues.push({
                         path: `workers[${i}].connection`,
-                        message: `no such connection "${w.connection}" (add it to connections)`,
+                        message: `no such connection "${worker.connection}" (add it to connections)`,
                     });
                 }
             }
         });
     }
-    if (man.data?.sources) {
-        for (const [name, src] of Object.entries(man.data.sources)) {
-            if (!src || typeof src.driver !== "string") {
+    const data = isRecord(obj.data) ? obj.data : undefined;
+    const sources = isRecord(data?.sources) ? data.sources : undefined;
+    if (sources) {
+        for (const [name, src] of Object.entries(sources)) {
+            const source = isRecord(src) ? src : undefined;
+            if (!source || typeof source.driver !== "string") {
                 issues.push({ path: `data.sources.${name}.driver`, message: "missing driver" });
             }
-            if (!src || typeof src.url !== "string") {
+            if (!source || typeof source.url !== "string") {
                 issues.push({ path: `data.sources.${name}.url`, message: "missing url" });
             }
         }
-        if (man.data.default && !man.data.sources[man.data.default]) {
-            issues.push({ path: "data.default", message: `no such source "${man.data.default}"` });
+        if (typeof data?.default === "string" && !sources[data.default]) {
+            issues.push({ path: "data.default", message: `no such source "${data.default}"` });
         }
     }
-    if (man.types) {
-        for (const [name, t] of Object.entries(man.types)) {
+    const types = isRecord(obj.types) ? obj.types : undefined;
+    if (types) {
+        for (const [name, t] of Object.entries(types)) {
             // `table` is optional in the schema: a type may declare `fields` without a
             // `table` (a transient / non-persisted domain type). Don't require it.
             if (t && typeof t !== "object") {
@@ -116,20 +121,25 @@ export function collectManifestIssues(m) {
             }
         }
     }
-    if (Array.isArray(man.triggers)) {
-        man.triggers.forEach((t, i) => {
-            if (!t?.id)
+    const triggers = Array.isArray(obj.triggers) ? obj.triggers : undefined;
+    if (triggers) {
+        triggers.forEach((t, i) => {
+            const trigger = isRecord(t) ? t : undefined;
+            if (!trigger?.id)
                 issues.push({ path: `triggers[${i}].id`, message: "missing id" });
-            if (!t?.type)
+            if (!trigger?.type)
                 issues.push({ path: `triggers[${i}].type`, message: "missing type" });
         });
     }
     return issues;
 }
-/** Throw ManifestValidationError if the manifest is invalid; otherwise return it typed. */
-export function validateManifest(m) {
+export function assertValidManifest(m) {
     const issues = collectManifestIssues(m);
     if (issues.length > 0)
         throw new ManifestValidationError(issues);
+}
+/** Throw ManifestValidationError if the manifest is invalid; otherwise return it typed. */
+export function validateManifest(m) {
+    assertValidManifest(m);
     return m;
 }

package/dist/runtime/devserver.js

@@ -12,6 +12,7 @@
 // live-reload can layer on later behind this same seam.
 import { runFromEnv } from "./run.js";
 import { selectHost } from "./adapters/detect.js";
+import { errorMessage } from "./core/guards.js";
 import { createNodeGenIO, runGen } from "../toolkit/index.js";
 const SOURCE_EXT = [".bpmn", ".dmn", ".form", ".ts", ".js", ".mjs", ".sql"];
 // Directories whose churn must never trigger a reload: generated output (gen writes here —
@@ -109,7 +110,7 @@ export async function runDev(opts = {}, deps) {
         }
         catch (err) {
             // Keep the dev server alive on a bad edit; the next save will retry.
-            log(`✖ reload failed: ${String(err?.message ?? err)}`);
+            log(`✖ reload failed: ${errorMessage(err)}`);
         }
         finally {
             reloading = false;

package/dist/runtime/engine/nanosdk.d.ts

@@ -6,7 +6,7 @@ export declare function requireProcessInstanceKey(key: string | number | null |
 /** A job as delivered to a nano-sdk job handler: the frame fields plus the
  *  acknowledgement actions the handler must call. */
 export interface NanoSdkActivatedJob {
-    jobKey: string;
+    jobKey: string | number;
     type?: string;
     processInstanceKey?: string | number;
     elementId?: string;

package/dist/runtime/engine/nanosdk.js

@@ -19,6 +19,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { isBpmnError } from "../core/host.js";
+import { isRecord } from "../core/guards.js";
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
 export function requireProcessInstanceKey(key) {
@@ -47,6 +48,7 @@ export class SdkEngineClient {
      * the same connection. Surfaced to handlers as `AppApi.sdk`.
      */
     get sdk() {
+        // biome-ignore lint/plugin: `this.client` is the same `@nanobpm/nano-sdk` client at runtime; exposing its full EngineSdkClient surface is the adapter boundary (see EngineSdkClient in ./sdk.ts).
         return this.client;
     }
     async deployResources(resources) {
@@ -60,11 +62,12 @@ export class SdkEngineClient {
             variables: input.variables ?? {},
             awaitCompletion: input.awaitCompletion ?? false,
         });
-        const key = body.processInstanceKey ??
-            body.key;
+        const rawKey = body.processInstanceKey ?? body.key;
+        const key = typeof rawKey === "string" || typeof rawKey === "number" ? rawKey : undefined;
+        const variables = isRecord(body.variables) ? body.variables : undefined;
         return {
             processInstanceKey: requireProcessInstanceKey(key),
-            variables: body.variables ?? undefined,
+            variables,
         };
     }
     async cancelInstance(input) {
@@ -80,8 +83,8 @@ export class SdkEngineClient {
     async searchUserTasks(filter) {
         // User tasks are an eventually consistent read; ask for zero-wait consistency so
         // the search reflects what is currently visible without blocking.
-        const body = await this.client.searchUserTasks({ filter: (filter ?? {}) }, { consistency: { waitUpToMs: 0 } });
-        const items = body.items ?? [];
+        const body = await this.client.searchUserTasks({ filter: { ...(filter ?? {}) } }, { consistency: { waitUpToMs: 0 } });
+        const items = Array.isArray(body.items) ? body.items.filter(isRecord) : [];
         return items.flatMap((it) => {
             const userTaskKey = it.userTaskKey ?? it.key;
             if (userTaskKey == null || userTaskKey === "") {
@@ -90,8 +93,8 @@ export class SdkEngineClient {
             }
             return [{
                     userTaskKey: String(userTaskKey),
-                    elementId: it.elementId,
-                    variables: it.variables,
+                    elementId: typeof it.elementId === "string" ? it.elementId : undefined,
+                    variables: isRecord(it.variables) ? it.variables : undefined,
                 }];
         });
     }
@@ -210,12 +213,15 @@ async function importNanoSdk() {
     // Indirect the specifier so the (lazily loaded) module is not resolved at
     // typecheck time and stays out of the import graph for injected-client paths.
     const spec = "@nanobpm/nano-sdk";
-    const mod = (await import(__rewriteRelativeImportExtension(spec)));
-    if (typeof mod.createCamundaClient !== "function") {
+    const mod = await import(__rewriteRelativeImportExtension(spec));
+    if (!isNanoSdkModule(mod)) {
         throw new Error("@nanobpm/nano-sdk does not export createCamundaClient");
     }
     return mod.createCamundaClient;
 }
+function isNanoSdkModule(value) {
+    return isRecord(value) && typeof value.createCamundaClient === "function";
+}
 /**
  * Build the Urban runtime's `EngineClient`, backed by a single `@nanobpm/nano-sdk`
  * client. Provide a `client`/`createClient` seam to inject a fake (tests, embedded

package/dist/runtime/index.d.ts

@@ -11,6 +11,8 @@ export { adaptConnectorHandler, mountConnectors, resolveInstalledConnectors, } f
 export type { ConnectorsHandle } from "./core/modules/connectors.ts";
 export { DataLayer, TypeRepo } from "./core/modules/datasource.ts";
 export type { ProvisionedSource } from "./core/modules/datasource.ts";
+export { runDataOp } from "./core/modules/dataops.ts";
+export type { DataOp, DataRequest, ResolvedSource } from "./core/modules/dataops.ts";
 export { makeGateway, Table } from "./core/modules/gateway.ts";
 export type { ColumnMeta, DataSource as GatewayDataSource, ExecResult, ForeignKeyMeta, Row, TableMeta, } from "./core/modules/gateway.ts";
 export { createPagesRoutes, mountPages } from "./core/modules/pages.ts";
@@ -22,6 +24,9 @@ export { resolveHandler, sdkDecisionEvaluator } from "./core/modules/workers.ts"
 export { buildMessages, callLlm, resolveProvider, runLlmJob, } from "./core/modules/llm.ts";
 export type { ChatMessage, DecisionEvaluator, EnvLookup, LlmRuntime, LlmVars, ProviderConfig, } from "./core/modules/llm.ts";
 export { evalCorrelation } from "./core/modules/triggers.ts";
+export { deployModels } from "./core/modules/deploy.ts";
+export { applyTemplates, resolveTemplates } from "./core/modules/templates.ts";
+export type { TemplateApplication, TemplateSource } from "./core/modules/templates.ts";
 export { createNodeHost } from "./adapters/node.ts";
 export { createDenoHost } from "./adapters/deno.ts";
 export { isDeno, selectHost } from "./adapters/detect.ts";

package/dist/runtime/index.js

@@ -12,12 +12,16 @@ export { BpmnError, isBpmnError } from "./core/host.js";
 export { adaptConnectorHandler, mountConnectors, resolveInstalledConnectors, } from "./core/modules/connectors.js";
 // Data layer
 export { DataLayer, TypeRepo } from "./core/modules/datasource.js";
+export { runDataOp } from "./core/modules/dataops.js";
 export { makeGateway, Table } from "./core/modules/gateway.js";
 export { createPagesRoutes, mountPages } from "./core/modules/pages.js";
 export { mountActions, resolveActionHandler } from "./core/modules/actions.js";
 export { resolveHandler, sdkDecisionEvaluator } from "./core/modules/workers.js";
 export { buildMessages, callLlm, resolveProvider, runLlmJob, } from "./core/modules/llm.js";
 export { evalCorrelation } from "./core/modules/triggers.js";
+// Model deploy + `{{name}}` template substitution
+export { deployModels } from "./core/modules/deploy.js";
+export { applyTemplates, resolveTemplates } from "./core/modules/templates.js";
 // Adapters + engine + run entrypoint
 export { createNodeHost } from "./adapters/node.js";
 export { createDenoHost } from "./adapters/deno.js";

package/dist/runtime/run.js

@@ -3,6 +3,7 @@
 // create the Urban app, start it, and install a graceful-shutdown handler.
 import { createUrbanApp } from "./core/runtime.js";
 import { selectHost } from "./adapters/detect.js";
+import { denoGlobal, processGlobal } from "./adapters/globals.js";
 import { createNanoSdkEngineClient } from "./engine/nanosdk.js";
 export async function runFromEnv(opts = {}) {
     const host = opts.host ?? selectHost({ cwd: opts.root });
@@ -26,6 +27,7 @@ export async function runFromEnv(opts = {}) {
         manifestPath: opts.manifestPath,
         port: opts.port,
         mount: opts.mount,
+        templates: opts.templates,
     });
     await app.start();
     if (opts.handleSignals !== false)
@@ -52,18 +54,19 @@ export function installSignalHandlers(stop) {
             }
         });
     };
-    const g = globalThis;
-    if (g.Deno) {
+    const deno = denoGlobal();
+    const proc = processGlobal();
+    if (deno?.addSignalListener) {
         try {
-            g.Deno.addSignalListener("SIGINT", onSignal);
-            g.Deno.addSignalListener("SIGTERM", onSignal);
+            deno.addSignalListener("SIGINT", onSignal);
+            deno.addSignalListener("SIGTERM", onSignal);
         }
         catch {
             /* signal listeners may be unavailable (e.g. Windows) */
         }
     }
-    else if (g.process) {
-        g.process.on("SIGINT", onSignal);
-        g.process.on("SIGTERM", onSignal);
+    else if (proc?.on) {
+        proc.on("SIGINT", onSignal);
+        proc.on("SIGTERM", onSignal);
     }
 }

package/dist/toolkit/addConnector.js

@@ -11,6 +11,7 @@
 // This module only reads/writes files through the GenIO port — installing the
 // package (a subprocess) is the CLI's job, so this stays runtime-agnostic and
 // unit-testable.
+import { errorMessage, isRecord } from "../runtime/core/guards.js";
 const MANIFEST_FILE = "nano-ide.ext.json";
 function joinPath(a, b) {
     // Trim both slash styles (as toolkit/gen.ts joinPath does) so a Windows-style
@@ -40,7 +41,7 @@ export async function addConnector(opts) {
         pack = JSON.parse(await io.readText(packManifestPath));
     }
     catch (err) {
-        throw new Error(`failed to parse ${packManifestPath}: ${err.message}`);
+        throw new Error(`failed to parse ${packManifestPath}: ${errorMessage(err)}`);
     }
     if (typeof pack.id !== "string" || !pack.id) {
         throw new Error(`${packManifestPath} has no string "id" (a pack must declare its id).`);
@@ -65,7 +66,7 @@ export async function addConnector(opts) {
         app = JSON.parse(await io.readText(appManifestPath));
     }
     catch (err) {
-        throw new Error(`failed to parse ${appManifestPath}: ${err.message}`);
+        throw new Error(`failed to parse ${appManifestPath}: ${errorMessage(err)}`);
     }
     if (app === null || typeof app !== "object" || Array.isArray(app)) {
         throw new Error(`${appManifestPath} is not a JSON object.`);
@@ -109,7 +110,7 @@ export async function addConnector(opts) {
             // A pre-existing connection of this name must be a compatible object of the
             // same pack `type`; otherwise wiring workers to it would produce an invalid
             // or misleading manifest. Fail loudly instead of silently reusing it.
-            if (existing === null || typeof existing !== "object" || Array.isArray(existing)) {
+            if (!isRecord(existing)) {
                 throw new Error(`connection "${connection}" already exists and is not an object.`);
             }
             const conn = existing;

package/dist/toolkit/fsio.js

@@ -58,7 +58,8 @@ export function createNodeGenIO() {
                 // stat failed (e.g. a virtual path); fall back to no cache key and let import() surface it.
             }
             const href = `${pathToFileURL(abs).href}${version}`;
-            return import(__rewriteRelativeImportExtension(href));
+            const mod = import(__rewriteRelativeImportExtension(href));
+            return mod;
         },
     };
 }

package/dist/toolkit/models.js

@@ -9,6 +9,7 @@
 // no-op and the rest of `urban gen` proceeds on the authored/derived models unchanged.
 import { toDeployableBpmn } from "@nanobpm/workflow";
 import { expandPattern, joinPath } from "./gen.js";
+import { isRecord } from "../runtime/core/guards.js";
 /** Default source glob for code-first flows (matches the code-first scaffold layout). */
 export const DEFAULT_WORKFLOW_PATTERNS = ["workflows/*.ts"];
 /** Default output dir for derived models (matches the model-first scaffold, so a derived
@@ -19,10 +20,7 @@ export const PROCESSES_DIR = "processes";
 export const MODEL_PROVENANCE = "Generated by @nanobpm/urban from workflows/*.ts — do not edit; edit the flow and re-run `urban gen`.";
 /** A `defineFlow` export: has a string `id` and an `imperative`/`declarative` `kind`. */
 export function isWorkflow(v) {
-    if (!v || typeof v !== "object")
-        return false;
-    const o = v;
-    return typeof o.id === "string" && (o.kind === "imperative" || o.kind === "declarative");
+    return isRecord(v) && typeof v.id === "string" && (v.kind === "imperative" || v.kind === "declarative");
 }
 /** Sanitize a flow id into a safe `.bpmn` filename (mirrors the host generator). */
 export function bpmnFilename(id) {
@@ -65,7 +63,7 @@ function messageOf(e) {
 /** Append an actionable hint when a `.ts` import fails because the runtime can't strip types. */
 function importHint(rel, e) {
     const base = messageOf(e);
-    const code = e?.code ?? "";
+    const code = isRecord(e) && typeof e.code === "string" ? e.code : "";
     const looksLikeNoTsLoader = rel.endsWith(".ts") &&
         (code === "ERR_UNKNOWN_FILE_EXTENSION" || /Unknown file extension "\.ts"/.test(base));
     if (!looksLikeNoTsLoader)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
   "license": "Apache-2.0",
   "type": "module",

package/src/cli.test.ts

@@ -0,0 +1,44 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { cmdData } from "./cli.ts";
+import { isRecord } from "./runtime/core/guards.ts";
+
+// The `urban data` gateway's contract (see cmdData's docstring): *every* reply — including an
+// unreadable request — is a parseable `{ ok: false, error }` envelope on stdout AND the process
+// exits 0, so the Nano console can always parse the reply off stdout and never mistakes a
+// malformed request for a subprocess crash. This guards the unreadable-request path, which used
+// to exit non-zero and could make a caller that keys off the exit code discard the (parseable)
+// error payload.
+test("urban data exits 0 with a parseable envelope on an unreadable request", async () => {
+  const flags: Parameters<typeof cmdData>[0] = {
+    root: ".",
+    manifest: "nano.app.json",
+    check: false,
+    write: false,
+    deno: false,
+    models: true,
+    stdout: false,
+    install: true,
+    help: false,
+    version: false,
+    _: ["data"],
+  };
+  const lines: string[] = [];
+  const orig = console.log;
+  console.log = (...args: unknown[]) => {
+    lines.push(args.map(String).join(" "));
+  };
+  let code: number;
+  try {
+    code = await cmdData(flags, async () => "this is not json {");
+  } finally {
+    console.log = orig;
+  }
+  assert.equal(code, 0);
+  assert.equal(lines.length, 1);
+  const reply: unknown = JSON.parse(lines[0]);
+  assert.ok(isRecord(reply));
+  assert.equal(reply.ok, false);
+  if (typeof reply.error !== "string") throw new TypeError("expected string error");
+  assert.match(reply.error, /^bad request: /);
+});

package/src/cli.ts

@@ -7,6 +7,7 @@
 //   urban run            materialize + serve the app (deploy, data, workers, surfaces, triggers)
 //   urban dev            like run, plus watch sources and hot-reload on change
 //   urban deploy         deploy models only, then exit
+//   urban data           DB-manager op gateway (stdin JSON → stdout JSON)
 //
 // Global flags: --root <dir> (default "."), --manifest <file> (default nano.app.json),
 //               --port <n>, -h/--help, -v/--version.
@@ -15,11 +16,15 @@ import {
   collectManifestIssues,
   installSignalHandlers,
   loadManifest,
+  runDataOp,
   runDev,
   runFromEnv,
   selectHost,
 } from "./runtime/index.ts";
+import { denoGlobal, processGlobal } from "./runtime/adapters/globals.ts";
+import { errorMessage, isRecord } from "./runtime/core/guards.ts";
 import { scaffold, slugify } from "create-urban-app";
+import type { DataRequest } from "./runtime/index.ts";
 import { addConnector, createNodeGenIO, previewModels, runGen, scaffoldWorkers } from "./toolkit/index.ts";
 import { pathToFileURL } from "node:url";
 import { readFileSync } from "node:fs";
@@ -30,7 +35,8 @@ import { spawnSync } from "node:child_process";
 function readVersion(): string {
   try {
     const url = new URL("../package.json", import.meta.url);
-    return (JSON.parse(readFileSync(url, "utf8")) as { version?: string }).version ?? "0.0.0";
+    const pkg: unknown = JSON.parse(readFileSync(url, "utf8"));
+    return isRecord(pkg) && typeof pkg.version === "string" ? pkg.version : "0.0.0";
   } catch {
     return "0.0.0";
   }
@@ -111,6 +117,9 @@ Usage:
   urban run                         materialize + serve the app
   urban dev                         run + watch sources, hot-reload on change
   urban deploy                      deploy models only, then exit
+  urban data                        DB-manager op gateway: read a JSON request on stdin
+                                    ({op:sources|schema|query|exec|script|migrations|migrate,…}),
+                                    write a JSON result on stdout
 
 Global flags:
   --root <dir>        app root (default ".")
@@ -270,6 +279,63 @@ async function cmdDeploy(f: Flags): Promise<number> {
   return 0;
 }
 
+/** Read all of stdin as UTF-8 text (Node or Deno). Returns "" if stdin is empty/closed. */
+async function readStdin(): Promise<string> {
+  const deno = denoGlobal();
+  const proc = processGlobal();
+  const chunks: string[] = [];
+  const dec = new TextDecoder();
+  if (deno?.stdin?.readable) {
+    for await (const chunk of deno.stdin.readable) chunks.push(dec.decode(chunk, { stream: true }));
+    chunks.push(dec.decode());
+    return chunks.join("");
+  }
+  if (proc?.stdin) {
+    for await (const chunk of proc.stdin) {
+      chunks.push(typeof chunk === "string" ? chunk : dec.decode(chunk, { stream: true }));
+    }
+    chunks.push(dec.decode());
+    return chunks.join("");
+  }
+  return "";
+}
+
+/**
+ * `urban data` — the DB-manager op gateway. Reads a single JSON request from stdin
+ * (`{ op, source?, sql?, params?, statements? }`) and writes a single JSON response to stdout
+ * (`{ ok: true, ...result }` or `{ ok: false, error }`). Every response — a handled op error *or*
+ * an unreadable request — is a parseable `{ ok: false, error }` envelope and still exits 0, so the
+ * caller can always parse the reply off stdout and never has to treat a non-zero exit as a lost
+ * error; the process only exits non-zero on an unexpected crash. This is the seam the Nano console
+ * re-points its Data panel at (host dry-out nano-bpm#576), replacing the vendored data-cli.ts.
+ */
+export async function cmdData(f: Flags, readInput: () => Promise<string> = readStdin): Promise<number> {
+  let req: DataRequest;
+  try {
+    req = JSON.parse(await readInput());
+  } catch (err) {
+    console.log(
+      JSON.stringify({
+        ok: false,
+        error: `bad request: ${err instanceof Error ? err.message : String(err)}`,
+      }),
+    );
+    return 0;
+  }
+  const host = selectHost({ cwd: f.root });
+  try {
+    // Mirror runFromEnv: the host is anchored at f.root, so pass root "." to avoid
+    // double-prefixing every manifest/db path (host.abs already resolves against f.root).
+    const result = await runDataOp(host, ".", f.manifest, req);
+    console.log(JSON.stringify({ ok: true, ...result }));
+  } catch (err) {
+    console.log(
+      JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) }),
+    );
+  }
+  return 0;
+}
+
 async function cmdNew(f: Flags): Promise<number> {
   const name = f._[1];
   if (!name) {
@@ -332,7 +398,7 @@ async function cmdAdd(f: Flags): Promise<number> {
     }
     return 0;
   } catch (err) {
-    console.error(`✖ ${(err as Error).message}`);
+    console.error(`✖ ${errorMessage(err)}`);
     return 1;
   }
 }
@@ -342,7 +408,7 @@ export async function main(argv: string[]): Promise<number> {
   try {
     f = parse(argv);
   } catch (err) {
-    console.error(String((err as Error).message));
+    console.error(errorMessage(err));
     return 1;
   }
   if (f.version) {
@@ -368,6 +434,8 @@ export async function main(argv: string[]): Promise<number> {
       return cmdStubs(f);
     case "add":
       return cmdAdd(f);
+    case "data":
+      return cmdData(f);
     case "run":
       return cmdRun(f);
     case "dev":
@@ -381,29 +449,27 @@ export async function main(argv: string[]): Promise<number> {
   }
 }
 
-const g = globalThis as {
-  process?: { argv: string[]; exit(code: number): void };
-  Deno?: { args?: string[]; exit?: (code: number) => void };
-};
-const meta = import.meta as unknown as { main?: boolean; url: string };
-const argv1 = g.process?.argv?.[1];
-const nodeMain = argv1 ? meta.url === pathToFileURL(argv1).href : false;
-if (meta.main === true || nodeMain) {
+const proc = processGlobal();
+const deno = denoGlobal();
+const importMetaMain: unknown = Reflect.get(import.meta, "main");
+const argv1 = proc?.argv?.[1];
+const nodeMain = argv1 ? import.meta.url === pathToFileURL(argv1).href : false;
+if (importMetaMain === true || nodeMain) {
   // Node passes args via process.argv (slice off exec+script); Deno (run directly)
   // exposes them on Deno.args. Prefer whichever actually carries args.
-  const fromNode = g.process?.argv?.slice(2);
-  const fromDeno = g.Deno?.args;
+  const fromNode = proc?.argv?.slice(2);
+  const fromDeno = deno?.args;
   const argv = (fromNode && fromNode.length ? fromNode : fromDeno) ?? fromNode ?? [];
   const exit = (code: number) => {
-    if (g.process?.exit) g.process.exit(code);
-    else if (g.Deno?.exit) g.Deno.exit(code);
+    if (proc?.exit) proc.exit(code);
+    else if (deno?.exit) deno.exit(code);
   };
   main(argv).then(
     (code) => {
       if (code >= 0) exit(code);
     },
     (err) => {
-      console.error(String((err as Error)?.message ?? err));
+      console.error(errorMessage(err));
       exit(1);
     },
   );