@nanobpm/urban 0.21.0 → 0.23.0

package/README.md

@@ -141,6 +141,41 @@ wiring; `WorkflowClient` deploys and starts, `Worker` hosts your `run` steps.
 inspectable in a modeller/Operate — `@nanobpm/urban` bundles `bpmn-auto-layout`
 so this works out of the box.
 
+### Deploy-time model templates (`{{name}}`)
+
+A model file can carry `{{name}}` placeholders that are substituted at deploy
+time — handy for inlining a large asset (e.g. an agent prompt authored as its own
+file) into a `zeebe:header` value instead of hand-pasting it into XML or shipping
+it as a bulky per-instance process variable. Declare the template sources under
+`models.templates` (globs, a bare directory that is scanned, or literal files); a
+template's name is its file **stem**, so `prompts/review.md` fills `{{review}}`:
+
+```jsonc
+{
+  "models": {
+    "processes": ["processes/*.bpmn"],
+    "templates": ["prompts/*.md"]
+  }
+}
+```
+
+```xml
+<!-- processes/agent.bpmn -->
+<zeebe:header key="io.nanobpm.agentTask.task.prompt" value="{{review}}" />
+```
+
+Content is escaped for the resource's type: XML for `.bpmn`/`.dmn` (newlines/tabs
+become character references so a multi-line prompt survives XML attribute-value
+normalization), JSON for `.form`. Substitution is single-pass (a template's own
+`{{…}}` is not re-expanded); an unknown placeholder is left verbatim and logged as
+a warning. Templates can also be supplied programmatically via the `templates`
+run option (globs or an explicit `name → content` map), which wins over the
+manifest on a name collision:
+
+```ts
+await runFromEnv({ templates: { review: await readPrompt("review.md") } });
+```
+
 ### Triggers — the inbound I/O edge
 
 Declare `triggers[]` in the app manifest to turn outside events into engine

package/dist/cli.d.ts

@@ -1 +1,27 @@
+interface Flags {
+    root: string;
+    manifest: string;
+    port?: number;
+    check: boolean;
+    write: boolean;
+    deno: boolean;
+    models: boolean;
+    stdout: boolean;
+    install: boolean;
+    style?: "model" | "code";
+    help: boolean;
+    version: boolean;
+    _: string[];
+}
+/**
+ * `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 declare function cmdData(f: Flags, readInput?: () => Promise<string>): Promise<number>;
 export declare function main(argv: string[]): Promise<number>;
+export {};

package/dist/cli.js

@@ -7,10 +7,13 @@
 //   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.
-import { collectManifestIssues, installSignalHandlers, loadManifest, runDev, runFromEnv, selectHost, } from "./runtime/index.js";
+import { collectManifestIssues, installSignalHandlers, loadManifest, runDataOp, runDev, runFromEnv, selectHost, } from "./runtime/index.js";
+import { denoGlobal, processGlobal } from "./runtime/adapters/globals.js";
+import { errorMessage, isRecord } from "./runtime/core/guards.js";
 import { scaffold, slugify } from "create-urban-app";
 import { addConnector, createNodeGenIO, previewModels, runGen, scaffoldWorkers } from "./toolkit/index.js";
 import { pathToFileURL } from "node:url";
@@ -21,7 +24,8 @@ import { spawnSync } from "node:child_process";
 function readVersion() {
     try {
         const url = new URL("../package.json", import.meta.url);
-        return JSON.parse(readFileSync(url, "utf8")).version ?? "0.0.0";
+        const pkg = JSON.parse(readFileSync(url, "utf8"));
+        return isRecord(pkg) && typeof pkg.version === "string" ? pkg.version : "0.0.0";
     }
     catch {
         return "0.0.0";
@@ -102,6 +106,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 ".")
@@ -257,6 +264,60 @@ async function cmdDeploy(f) {
     await app.stop();
     return 0;
 }
+/** Read all of stdin as UTF-8 text (Node or Deno). Returns "" if stdin is empty/closed. */
+async function readStdin() {
+    const deno = denoGlobal();
+    const proc = processGlobal();
+    const chunks = [];
+    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, readInput = readStdin) {
+    let req;
+    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) {
     const name = f._[1];
     if (!name) {
@@ -324,7 +385,7 @@ async function cmdAdd(f) {
         return 0;
     }
     catch (err) {
-        console.error(`✖ ${err.message}`);
+        console.error(`✖ ${errorMessage(err)}`);
         return 1;
     }
 }
@@ -334,7 +395,7 @@ export async function main(argv) {
         f = parse(argv);
     }
     catch (err) {
-        console.error(String(err.message));
+        console.error(errorMessage(err));
         return 1;
     }
     if (f.version) {
@@ -360,6 +421,8 @@ export async function main(argv) {
             return cmdStubs(f);
         case "add":
             return cmdAdd(f);
+        case "data":
+            return cmdData(f);
         case "run":
             return cmdRun(f);
         case "dev":
@@ -372,27 +435,28 @@ export async function main(argv) {
             return 1;
     }
 }
-const g = globalThis;
-const meta = import.meta;
-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 = 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) => {
-        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?.message ?? err));
+        console.error(errorMessage(err));
         exit(1);
     });
 }

package/dist/runtime/adapters/deno.js

@@ -13,6 +13,20 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { DatabaseSync } from "node:sqlite";
+function sqliteParams(params) {
+    return params.map((param) => {
+        if (param === null ||
+            typeof param === "string" ||
+            typeof param === "number" ||
+            typeof param === "bigint" ||
+            param instanceof Uint8Array) {
+            return param;
+        }
+        if (typeof param === "boolean")
+            return param ? 1 : 0;
+        throw new TypeError(`unsupported SQLite parameter type: ${typeof param}`);
+    });
+}
 export function createDenoHost(opts = {}) {
     const cwd = opts.cwd ?? Deno.cwd();
     const abs = (p) => (isAbsolute(p) ? p : resolve(cwd, p));
@@ -53,7 +67,8 @@ export function createDenoHost(opts = {}) {
         },
         importModule: (p) => {
             const href = pathToFileURL(abs(p)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
-            return import(__rewriteRelativeImportExtension(href));
+            const mod = import(__rewriteRelativeImportExtension(href));
+            return mod;
         },
         async serveHttp(port, handler) {
             return startDenoServer(port, handler);
@@ -96,12 +111,13 @@ function wrapSqlite(db) {
         exec: (sql) => db.exec(sql),
         run: (sql, params = []) => {
             const stmt = db.prepare(sql);
-            const r = stmt.run(...params);
+            const r = stmt.run(...sqliteParams(params));
             return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid };
         },
         all: (sql, params = []) => {
             const stmt = db.prepare(sql);
-            return stmt.all(...params);
+            // biome-ignore lint/plugin: Deno sqlite returns untyped row objects; SqliteDb.all<T> is the host adapter boundary.
+            return stmt.all(...sqliteParams(params));
         },
         close: () => db.close(),
     };

package/dist/runtime/adapters/detect.js

@@ -2,10 +2,10 @@
 // modules is safe — neither touches its runtime's globals at module top level.
 import { createNodeHost } from "./node.js";
 import { createDenoHost } from "./deno.js";
+import { denoGlobal } from "./globals.js";
 /** True when running under Deno. */
 export function isDeno() {
-    const g = globalThis;
-    return typeof g.Deno !== "undefined" && typeof g.Deno.version !== "undefined";
+    return denoGlobal()?.version !== undefined;
 }
 /** Select and construct the host for the current runtime. */
 export function selectHost(opts = {}) {

package/dist/runtime/adapters/globals.d.ts

@@ -0,0 +1,19 @@
+export interface DenoRuntimeGlobal {
+    version?: unknown;
+    stdin?: {
+        readable?: ReadableStream<Uint8Array>;
+    };
+    args?: string[];
+    exit?: (code: number) => void;
+    addSignalListener?: (sig: string, cb: () => void) => void;
+}
+export interface ProcessRuntimeGlobal {
+    argv?: string[];
+    exit?: (code: number) => void;
+    stdin?: AsyncIterable<Uint8Array | string> & {
+        setEncoding?(encoding: string): void;
+    };
+    on?: (sig: string, cb: () => void) => void;
+}
+export declare function denoGlobal(): DenoRuntimeGlobal | undefined;
+export declare function processGlobal(): ProcessRuntimeGlobal | undefined;

package/dist/runtime/adapters/globals.js

@@ -0,0 +1,9 @@
+import { isRecord } from "../core/guards.js";
+export function denoGlobal() {
+    const value = Reflect.get(globalThis, "Deno");
+    return isRecord(value) ? value : undefined;
+}
+export function processGlobal() {
+    const value = Reflect.get(globalThis, "process");
+    return isRecord(value) ? value : undefined;
+}

package/dist/runtime/adapters/node.js

@@ -16,6 +16,20 @@ import { register } from "node:module";
 import { isAbsolute, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { DatabaseSync } from "node:sqlite";
+function sqliteParams(params) {
+    return params.map((param) => {
+        if (param === null ||
+            typeof param === "string" ||
+            typeof param === "number" ||
+            typeof param === "bigint" ||
+            param instanceof Uint8Array) {
+            return param;
+        }
+        if (typeof param === "boolean")
+            return param ? 1 : 0;
+        throw new TypeError(`unsupported SQLite parameter type: ${typeof param}`);
+    });
+}
 /** Resolve the in-process `@nanobpm/worker` shim URL relative to this adapter,
  *  tolerating both the compiled package (`.js`, the published/`urban run` path)
  *  and a from-source run (`.ts`). */
@@ -101,7 +115,8 @@ export function createNodeHost(opts = {}) {
         },
         importModule: (p) => {
             const href = pathToFileURL(abs(p)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
-            return import(__rewriteRelativeImportExtension(href));
+            const mod = import(__rewriteRelativeImportExtension(href));
+            return mod;
         },
         async importConnectorModule(entry) {
             ensureConnectorHooks();
@@ -147,12 +162,13 @@ function wrapNodeSqlite(db) {
         exec: (sql) => db.exec(sql),
         run: (sql, params = []) => {
             const stmt = db.prepare(sql);
-            const r = stmt.run(...params);
+            const r = stmt.run(...sqliteParams(params));
             return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid };
         },
         all: (sql, params = []) => {
             const stmt = db.prepare(sql);
-            return stmt.all(...params);
+            // biome-ignore lint/plugin: Node sqlite returns untyped row objects; SqliteDb.all<T> is the host adapter boundary.
+            return stmt.all(...sqliteParams(params));
         },
         close: () => db.close(),
     };
@@ -160,8 +176,12 @@ function wrapNodeSqlite(db) {
 async function startNodeServer(port, handler) {
     const server = createServer(async (nreq, nres) => {
         const chunks = [];
-        for await (const c of nreq)
-            chunks.push(c);
+        for await (const c of nreq) {
+            if (Buffer.isBuffer(c))
+                chunks.push(c);
+            else
+                chunks.push(Buffer.from(c));
+        }
         const bodyText = Buffer.concat(chunks).toString("utf8");
         const url = new URL(nreq.url ?? "/", "http://localhost");
         const headers = new Headers();

package/dist/runtime/core/context.d.ts

@@ -1,6 +1,7 @@
 import type { AppManifest } from "./manifest.ts";
 import type { EngineClient, HostContext } from "./host.ts";
 import type { EngineSdkClient } from "../engine/sdk.ts";
+import type { TemplateSource } from "./modules/templates.ts";
 /** Everything a runtime module needs. Passed to each module's mount function. */
 export interface RuntimeContext {
     manifest: AppManifest;
@@ -8,6 +9,9 @@ export interface RuntimeContext {
     engine: EngineClient;
     /** App root directory (paths in the manifest are relative to this). */
     root: string;
+    /** Programmatic `{{name}}` template source for deploy-time substitution (globs or a
+     *  `name → content` map), merged over the manifest's `models.templates`. See `deployModels`. */
+    templates?: TemplateSource;
 }
 /** A mounted module returns a disposer so the runtime can tear it down cleanly. */
 export interface Mounted {

package/dist/runtime/core/guards.d.ts

@@ -0,0 +1,2 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function errorMessage(error: unknown): string;

package/dist/runtime/core/guards.js

@@ -0,0 +1,10 @@
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (isRecord(error) && typeof error.message === "string")
+        return error.message;
+    return String(error);
+}

package/dist/runtime/core/host.js

@@ -23,8 +23,9 @@ export class BpmnError extends Error {
  *  BpmnError constructed against a different copy of this module still routes as
  *  a BPMN error rather than a generic failure). */
 export function isBpmnError(err) {
-    return (typeof err === "object" &&
-        err !== null &&
-        typeof err.errorCode === "string" &&
-        err.errorCode.length > 0);
+    if (typeof err !== "object" || err === null)
+        return false;
+    const errorCode = "errorCode" in err ? err.errorCode : undefined;
+    return (typeof errorCode === "string" &&
+        errorCode.length > 0);
 }

package/dist/runtime/core/manifest.d.ts

@@ -1,6 +1,14 @@
 import type { HostContext } from "./host.ts";
 import type { AppManifest, Worker } from "@nanobpm/nano-app-schema";
 export type { ActionDecl, AppManifest, ChatSurface, Connection, Data, DataSource, DomainField, DomainType, LlmBinding, Models, PagesSurface, Runtime, Security, Surfaces, TaskInboxSurface, Trigger, TriggerAction, Worker, } from "@nanobpm/nano-app-schema";
+declare module "@nanobpm/nano-app-schema" {
+    interface Models {
+        /** `{{name}}` template sources substituted into model resources at deploy time: globs, a bare
+         *  directory (scanned), or literal files. A template's name is its file stem
+         *  (`prompts/review-round.md` → `{{review-round}}`). See `deployModels`. */
+        templates?: string[];
+    }
+}
 /** The job type a worker subscribes to (schema key: `taskType`). */
 export declare function workerJobType(w: Worker): string | undefined;
 /**

package/dist/runtime/core/manifest.js

@@ -24,7 +24,6 @@ export function expandEnvString(input, lookup) {
         return dflt ?? "";
     });
 }
-/** Recursively expand env placeholders across every string in a JSON-ish value. */
 export function expandEnv(value, lookup) {
     if (typeof value === "string")
         return expandEnvString(value, lookup);

package/dist/runtime/core/modules/actions.js

@@ -9,16 +9,20 @@
 // Precedence: action routes are mounted BEFORE the generic pages action routes (the router
 // is first-match-wins), so an override at `/app/actions/cancel` shadows the generic one,
 // while an unmatched process still falls through to the generic `/app/actions/start/` route.
+import { errorMessage } from "../guards.js";
 import { json, normalizeRoutePath } from "../router.js";
+function isActionHandler(value) {
+    return typeof value === "function";
+}
 /**
  * Resolve an action handler from a loaded module, in priority order:
  *   1. `default` (when it is a function — the common one-handler-per-file case)
  *   2. a named export `handler`
  */
 export function resolveActionHandler(mod) {
-    if (typeof mod.default === "function")
+    if (isActionHandler(mod.default))
         return mod.default;
-    if (typeof mod.handler === "function")
+    if (isActionHandler(mod.handler))
         return mod.handler;
     return undefined;
 }
@@ -28,7 +32,7 @@ export function resolveActionHandler(mod) {
  * surfaces as a clear `500` on that route rather than failing the whole boot.
  */
 export function mountActions(ctx, app) {
-    const decls = (ctx.manifest.actions ?? []);
+    const decls = ctx.manifest.actions ?? [];
     const routes = [];
     const mounted = [];
     const joinRoot = (p) => p.startsWith("/") ? p : `${ctx.root.replace(/\/+$/, "")}/${p.replace(/^\/+/, "")}`;
@@ -85,7 +89,7 @@ export function mountActions(ctx, app) {
                     ctx.host.log("error", "action handler module failed to load", {
                         path,
                         module: decl.module,
-                        error: String(e?.message ?? e),
+                        error: errorMessage(e),
                     });
                     return json({ error: `action handler ${decl.module} failed to load` }, 500);
                 }
@@ -103,7 +107,7 @@ export function mountActions(ctx, app) {
                     };
                 }
                 catch (e) {
-                    return json({ error: String(e?.message ?? e) }, 500);
+                    return json({ error: errorMessage(e) }, 500);
                 }
             },
         });

package/dist/runtime/core/modules/connectors.js

@@ -14,6 +14,7 @@
 //
 // This file is runtime-agnostic (core purity): the Node/Deno specifics of aliasing
 // the pack's `@nanobpm/worker` import live behind `host.importConnectorModule`.
+import { errorMessage, isRecord } from "../guards.js";
 import { BpmnError } from "../host.js";
 import { workerJobType } from "../manifest.js";
 import { drainDefinedWorkers, } from "../../connector-worker-sdk.js";
@@ -40,11 +41,12 @@ async function readJson(ctx, relPath, opts) {
     if (!(await ctx.host.exists(path)))
         return undefined;
     try {
-        return JSON.parse(await ctx.host.readTextFile(path));
+        const parsed = JSON.parse(await ctx.host.readTextFile(path));
+        return parsed;
     }
     catch (err) {
         if (opts?.strict) {
-            throw new Error(`failed to parse ${relPath}: ${err.message}`);
+            throw new Error(`failed to parse ${relPath}: ${errorMessage(err)}`);
         }
         return undefined;
     }
@@ -107,7 +109,7 @@ export function adaptConnectorHandler(worker) {
         if (outcome?.kind === "complete")
             return outcome.vars ?? {};
         // No explicit outcome: fall back to the handle's return value (SDK-style).
-        return ret && typeof ret === "object" ? ret : {};
+        return isRecord(ret) ? ret : {};
     };
 }
 /**
@@ -118,7 +120,7 @@ export function adaptConnectorHandler(worker) {
  * the host cannot host connector workers (`importConnectorModule` absent).
  */
 export async function mountConnectors(ctx, app) {
-    const decls = (ctx.manifest.workers ?? []).filter((w) => w.connector);
+    const decls = (ctx.manifest.workers ?? []).filter((w) => Boolean(w.connector));
     const subs = [];
     const jobTypes = [];
     if (decls.length === 0)

package/dist/runtime/core/modules/dataops.d.ts

@@ -0,0 +1,36 @@
+import type { HostContext } from "../host.ts";
+import type { AppManifest } from "../manifest.ts";
+/** The DB-manager op protocol's known op set. `domaintypes` is part of the protocol but is not
+ * yet handled here (it errors clearly — see the file header); every other op is dispatched by
+ * `runDataOp`. Typing `op` as this union (instead of `string`) gives SDK/console callers
+ * type-safety and catches typos at compile time. */
+export type DataOp = "sources" | "schema" | "query" | "exec" | "script" | "migrations" | "migrate" | "domaintypes";
+export interface DataRequest {
+    op: DataOp;
+    source?: string;
+    sql?: string;
+    params?: unknown[];
+    statements?: string[];
+}
+/** One datasource the manifest declares, resolved against the environment (env templates in
+ * `driver`/`url` are already expanded by `loadManifest`). Mirrors the console's `ResolvedSource`
+ * so the panel's datasource picker is unchanged. */
+export interface ResolvedSource {
+    name: string;
+    driver: string;
+    url: string;
+    migrations?: string;
+}
+/** JSON-safe a value: BigInt → number (when lossless) or string, recursing objects/arrays. SQLite
+ * reports `lastInsertRowid` (and INTEGER columns) as BigInt, which `JSON.stringify` cannot encode. */
+export declare function jsonSafe(v: unknown): unknown;
+/** List every declared datasource plus the default's name (no connection opened). */
+export declare function listSources(manifest: AppManifest): {
+    default?: string;
+    sources: ResolvedSource[];
+};
+/**
+ * Dispatch one DB-manager op against the app at `root`. Returns the op's result object (the CLI
+ * wraps it as `{ ok: true, ...result }`); throws on a handled error (wrapped as `{ ok: false }`).
+ */
+export declare function runDataOp(host: HostContext, root: string, manifestPath: string, req: DataRequest): Promise<Record<string, unknown>>;