@nanobpm/urban 0.21.0 → 0.22.0

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

@@ -0,0 +1,231 @@
+// dataops — the DB-manager op protocol behind `urban data`. A single JSON request is
+// dispatched against a manifest datasource and a single JSON result is returned; the CLI
+// (`urban data`, cli.ts) wraps it in the `{ ok, ... }` stdin/stdout envelope. This is the
+// runtime-agnostic core the Nano console re-points its **Data** panel (Tables / SQL /
+// Migrations) at, replacing the vendored `nano-generated/data-cli.ts` (host dry-out #576).
+//
+// Every op runs THROUGH the same datasource seam the app runtime uses (`openSqliteSource` +
+// `makeGateway`), so the panel browses exactly what the named source resolves to — never a
+// parallel path. Read/list ops open the source WITHOUT applying migrations (opening the DB
+// manager must not silently mutate the schema); `migrate` applies pending migrations on the
+// shared `_urban_migrations` ledger.
+//
+//   Request:  { op, source?, sql?, params?, statements? }
+//   op = "sources" | "schema" | "query" | "exec" | "script" | "migrations" | "migrate"
+//      | "domaintypes"
+//
+// `domaintypes` (live-schema reification + shape resolution) is a known protocol op but is
+// intentionally NOT handled here yet — it is ported to `urban data` in a follow-up (PR 2 of
+// #576) and errors clearly for now.
+import { isRecord } from "../guards.js";
+import { loadManifest } from "../manifest.js";
+import { validateManifest } from "../validate.js";
+import { makeGateway } from "./gateway.js";
+import { applyMigrations, MIGRATIONS_TABLE, openSqliteSource, resolveAppPath } from "./datasource.js";
+const DEFAULT_MIGRATIONS_DIR = "db/migrations";
+/** 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 function jsonSafe(v) {
+    if (typeof v === "bigint") {
+        return v >= BigInt(Number.MIN_SAFE_INTEGER) && v <= BigInt(Number.MAX_SAFE_INTEGER)
+            ? Number(v)
+            : v.toString();
+    }
+    if (Array.isArray(v))
+        return v.map(jsonSafe);
+    if (v && typeof v === "object") {
+        const out = {};
+        for (const [k, val] of Object.entries(v))
+            out[k] = jsonSafe(val);
+        return out;
+    }
+    return v;
+}
+/** Column order across a row set: first-seen order, unioned over every row (rows may be ragged). */
+function columnsOf(rows) {
+    const seen = new Set();
+    const cols = [];
+    for (const r of rows) {
+        for (const k of Object.keys(r)) {
+            if (!seen.has(k)) {
+                seen.add(k);
+                cols.push(k);
+            }
+        }
+    }
+    return cols;
+}
+/** Split a script on `;` boundaries, dropping blank and comment-only fragments. Minimal DDL
+ * splitter (ADR 0024 "minimal dialect stance"); does not parse semicolons inside string literals. */
+function splitStatements(sql) {
+    return sql
+        .split(";")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0 && !s.split("\n").every((l) => l.trim().startsWith("--")));
+}
+/** List every declared datasource plus the default's name (no connection opened). */
+export function listSources(manifest) {
+    const data = manifest.data;
+    const sources = Object.entries(data?.sources ?? {}).map(([name, raw]) => ({
+        name,
+        driver: String(raw.driver),
+        url: raw.url,
+        migrations: raw.migrations,
+    }));
+    return { default: data?.default, sources };
+}
+/** Resolve the source a request names (the default, or the sole source, when unnamed). */
+function pickSource(manifest, name) {
+    const data = manifest.data;
+    const sources = data?.sources ?? {};
+    const chosen = name || data?.default || Object.keys(sources)[0];
+    if (!chosen)
+        throw new Error("no data source specified and none declared in the manifest");
+    const src = sources[chosen];
+    if (!src)
+        throw new Error(`no such data source "${chosen}"`);
+    return { name: chosen, src };
+}
+/** Open the requested source's gateway WITHOUT applying migrations (opening the DB manager must
+ * not mutate the schema). The caller closes the returned handle. */
+async function openGateway(host, root, manifest, name) {
+    const { name: chosen, src } = pickSource(manifest, name);
+    if (String(src.driver) !== "sqlite") {
+        throw new Error(`data source "${chosen}" uses driver "${String(src.driver)}"; only "sqlite" is implemented`);
+    }
+    let db;
+    try {
+        db = await openSqliteSource(host, root, src.url);
+    }
+    catch (err) {
+        // Prefix the source name onto openSqliteSource's runtime-agnostic message so the CLI/console
+        // error names which datasource failed (mirrors provisionSqlite).
+        throw new Error(`datasource "${chosen}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return { gw: makeGateway(db), db };
+}
+/**
+ * Resolve a `--manifest` argument against the app `root`. An absolute path (POSIX `/abs/…`, a
+ * Windows drive-letter `C:\…` or a UNC `\\host\share\…`) is honoured as-is; a relative path is
+ * joined onto `root`. Delegates to `resolveAppPath` so manifest and datasource path resolution
+ * share one cross-platform implementation and can't drift.
+ */
+function resolveManifestPath(root, manifestPath) {
+    return resolveAppPath(root, manifestPath);
+}
+/**
+ * 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 async function runDataOp(host, root, manifestPath, req) {
+    const manifest = validateManifest(await loadManifest(host, resolveManifestPath(root, manifestPath)));
+    switch (req.op) {
+        case "sources": {
+            const { sources, default: def } = listSources(manifest);
+            return { default: def, sources };
+        }
+        case "schema": {
+            const { gw, db } = await openGateway(host, root, manifest, req.source);
+            try {
+                return { tables: await gw.schema() };
+            }
+            finally {
+                db.close();
+            }
+        }
+        case "query": {
+            const { gw, db } = await openGateway(host, root, manifest, req.source);
+            try {
+                const rows = await gw.query(req.sql ?? "", req.params ?? []);
+                const safeRows = rows.map(jsonSafe);
+                return { columns: columnsOf(rows), rows: safeRows };
+            }
+            finally {
+                db.close();
+            }
+        }
+        case "exec": {
+            const { gw, db } = await openGateway(host, root, manifest, req.source);
+            try {
+                const result = jsonSafe(await gw.exec(req.sql ?? "", req.params ?? []));
+                return isRecord(result) ? result : {};
+            }
+            finally {
+                db.close();
+            }
+        }
+        case "script": {
+            // Run several statements atomically in one transaction — the console's structure editor
+            // uses this for the SQLite 12-step table rebuild (create → copy → drop → rename), so a
+            // mid-rebuild failure rolls back and leaves the table untouched. Statements come pre-split
+            // from the caller; `?`-params are not threaded (DDL needs none).
+            const { gw, db } = await openGateway(host, root, manifest, req.source);
+            try {
+                const statements = Array.isArray(req.statements)
+                    ? req.statements
+                    : splitStatements(req.sql ?? "");
+                let changed = 0;
+                await gw.tx(async (t) => {
+                    for (const stmt of statements) {
+                        if (stmt.trim())
+                            changed += (await t.exec(stmt)).changed;
+                    }
+                });
+                return { changed };
+            }
+            finally {
+                db.close();
+            }
+        }
+        case "migrations": {
+            const { name, src } = pickSource(manifest, req.source);
+            const relDir = src.migrations ?? DEFAULT_MIGRATIONS_DIR;
+            const absDir = resolveAppPath(root, relDir);
+            // `migrations` is a read/list op: treat a missing dir as no migrations (mirrors
+            // applyMigrations) instead of throwing on host.listDir.
+            const files = (await host.exists(absDir))
+                ? (await host.listDir(absDir)).filter((f) => f.endsWith(".sql")).sort()
+                : [];
+            const { gw, db } = await openGateway(host, root, manifest, name);
+            try {
+                // Do not create the ledger table here — listing migrations must not mutate the
+                // schema. If the ledger doesn't exist yet, nothing has been applied.
+                const ledgerExists = (await gw.query(`SELECT name FROM sqlite_master WHERE type='table' AND name='${MIGRATIONS_TABLE}'`)).length > 0;
+                const applied = ledgerExists
+                    ? new Map((await gw.query(`SELECT name, applied_at FROM ${MIGRATIONS_TABLE}`)).map((r) => [
+                        String(r.name),
+                        String(r.applied_at),
+                    ]))
+                    : new Map();
+                return {
+                    dir: relDir,
+                    entries: files.map((name) => ({
+                        name,
+                        applied: applied.has(name),
+                        appliedAt: applied.get(name) ?? null,
+                    })),
+                };
+            }
+            finally {
+                db.close();
+            }
+        }
+        case "migrate": {
+            const { name, src } = pickSource(manifest, req.source);
+            const { db } = await openGateway(host, root, manifest, name);
+            try {
+                const applied = await applyMigrations(host, db, root, src.migrations ?? DEFAULT_MIGRATIONS_DIR);
+                return { applied, pending: 0 };
+            }
+            finally {
+                db.close();
+            }
+        }
+        case "domaintypes": {
+            throw new Error("`domaintypes` is not yet implemented in `urban data` — the Nano console still serves it " +
+                "(tracked as PR 2 of nano-bpm#576)");
+        }
+        default:
+            throw new Error(`unknown op "${req.op}"`);
+    }
+}

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

@@ -1,7 +1,56 @@
 import type { RuntimeContext } from "../context.ts";
-import type { SqliteDb } from "../host.ts";
+import type { HostContext, SqliteDb } from "../host.ts";
 import type { DomainType } from "../manifest.ts";
 import { Table, type DataSource as GatewayDataSource } from "./gateway.ts";
+export declare function sqlitePathFromUrl(url: string): string;
+/** True when `p` is already an absolute path on any host `urban data` targets. `urban data` runs
+ * on a Node host that may be Windows, so absolute-path detection can't assume POSIX: this matches
+ * a POSIX root ("/…"), a Windows drive-letter root ("C:\…" or "C:/…"), a Windows drive-root path
+ * that starts with a single backslash ("\data\app.db") and a Windows UNC path
+ * ("\\\\server\\share"). A single leading backslash covers both the drive-root and UNC cases,
+ * matching Node's `path.win32.isAbsolute`. Used by `resolveAppPath` so a caller-supplied absolute
+ * path is never incorrectly prefixed with the app root. */
+export declare function isAbsolutePath(p: string): boolean;
+/** Resolve `p` against the app `root`: an absolute `p` (see `isAbsolutePath`) is returned as-is;
+ * a relative `p` is joined onto `root`. Trims a trailing separator of either kind off `root` so
+ * we never emit a doubled separator. The join separator matches the root's own style so we never
+ * emit a mixed-separator path (e.g. "C:\\srv\\app/app.db" or "\\\\server\\share/db\\migrations"),
+ * which Windows/UNC resolution and some tooling mishandle: a root that already uses backslashes is
+ * Windows-style and joins with "\\" — normalizing the relative segment's forward slashes to match —
+ * while everything else (POSIX, a "C:/…" forward-slash root, or a relative ".") joins with "/" —
+ * normalizing the relative segment's backslashes to match. Both `root` AND the relative segment are
+ * rewritten to the chosen separator, so the result is never mixed even when `root` itself is mixed
+ * (e.g. "C:/srv\\app") or `p` is. The single canonical implementation shared by `resolveSqlitePath`
+ * (datasource urls) and `resolveManifestPath` (`--manifest`) — and by `applyMigrations` to join each
+ * migration file onto its dir — so those path resolutions can never drift and all behave the same
+ * cross-platform. */
+export declare function resolveAppPath(root: string, p: string): string;
+/** Name of the SQLite ledger table that records applied migrations. The single source of truth
+ * for this identifier: `applyMigrations` writes it and `dataops`' `migrations` op reads it, so
+ * both import this constant and the ledger name can never drift between application and listing. */
+export declare const MIGRATIONS_TABLE = "_urban_migrations";
+/** Resolve a datasource `url` to its on-disk SQLite path against `root`. The result is absolute
+ * when the resolved path is absolute (either because `url` names an absolute path or `root` is
+ * absolute); if `root` is relative (e.g. "." as used by the CLI/tests) a relative `url` stays
+ * correspondingly relative. The single source of truth for this resolution, shared by
+ * `openSqliteSource` (to open the file) and `provisionSqlite` (to report where it provisioned),
+ * so the opened path and the logged path can never drift. */
+export declare function resolveSqlitePath(root: string, url: string): string;
+/**
+ * Open (creating if needed) the SQLite file a `file:`/`sqlite:` URL points at, resolved against
+ * `root`, with WAL journalling — but WITHOUT applying migrations. Provisioning (`provisionSqlite`)
+ * layers migrations on top; the `urban data` DB-manager gateway (dataops.ts) wants the raw handle
+ * so read/`migrations`-list ops don't silently mutate the schema on open.
+ */
+export declare function openSqliteSource(host: HostContext, root: string, url: string): Promise<SqliteDb>;
+/** The parent directory of `path`, or `""` when it has none (a bare filename or a filesystem
+ * root, for which the existence check in `openSqliteSource` is intentionally skipped). Splits on
+ * either separator so a Windows-style absolute path (e.g. "C:\data\app.db") yields a real parent
+ * dir rather than being treated as having none. Preserves the trailing separator on a Windows
+ * drive root so "C:\app.db" -> "C:\" (and "C:/app.db" -> "C:/"), not the bare volume "C:" — the
+ * latter is a drive-relative reference, not the drive root, and would make `openSqliteSource`
+ * fail fast against the wrong location. */
+export declare function parentDir(path: string): string;
 /** A typed accessor over a table declared in manifest `types`. */
 export declare class TypeRepo {
     private readonly db;
@@ -43,5 +92,6 @@ export declare class DataLayer {
     describe(): Record<string, unknown>;
     closeAll(): void;
 }
+export declare function applyMigrations(host: HostContext, db: SqliteDb, root: string, migrationsDir: string): Promise<string[]>;
 /** Provision every declared source and return the typed data layer. */
 export declare function provisionData(ctx: RuntimeContext): Promise<DataLayer>;

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

@@ -3,10 +3,74 @@
 // explicit seam (they are declared in the manifest but not yet provisioned). This is the
 // runtime side of ADR 0024 (datasource) + ADR 0040 (domain model), scoped to what an app needs.
 import { makeGateway } from "./gateway.js";
-function sqlitePathFromUrl(url) {
+export function sqlitePathFromUrl(url) {
     // Accept "file:./x.db", "file:x.db", "sqlite:./x.db" or a bare path.
     return url.replace(/^(file|sqlite):(\/\/)?/, "");
 }
+/** True when `p` is already an absolute path on any host `urban data` targets. `urban data` runs
+ * on a Node host that may be Windows, so absolute-path detection can't assume POSIX: this matches
+ * a POSIX root ("/…"), a Windows drive-letter root ("C:\…" or "C:/…"), a Windows drive-root path
+ * that starts with a single backslash ("\data\app.db") and a Windows UNC path
+ * ("\\\\server\\share"). A single leading backslash covers both the drive-root and UNC cases,
+ * matching Node's `path.win32.isAbsolute`. Used by `resolveAppPath` so a caller-supplied absolute
+ * path is never incorrectly prefixed with the app root. */
+export function isAbsolutePath(p) {
+    return /^(\/|\\|[A-Za-z]:[/\\])/.test(p);
+}
+/** Resolve `p` against the app `root`: an absolute `p` (see `isAbsolutePath`) is returned as-is;
+ * a relative `p` is joined onto `root`. Trims a trailing separator of either kind off `root` so
+ * we never emit a doubled separator. The join separator matches the root's own style so we never
+ * emit a mixed-separator path (e.g. "C:\\srv\\app/app.db" or "\\\\server\\share/db\\migrations"),
+ * which Windows/UNC resolution and some tooling mishandle: a root that already uses backslashes is
+ * Windows-style and joins with "\\" — normalizing the relative segment's forward slashes to match —
+ * while everything else (POSIX, a "C:/…" forward-slash root, or a relative ".") joins with "/" —
+ * normalizing the relative segment's backslashes to match. Both `root` AND the relative segment are
+ * rewritten to the chosen separator, so the result is never mixed even when `root` itself is mixed
+ * (e.g. "C:/srv\\app") or `p` is. The single canonical implementation shared by `resolveSqlitePath`
+ * (datasource urls) and `resolveManifestPath` (`--manifest`) — and by `applyMigrations` to join each
+ * migration file onto its dir — so those path resolutions can never drift and all behave the same
+ * cross-platform. */
+export function resolveAppPath(root, p) {
+    if (isAbsolutePath(p))
+        return p;
+    const sep = root.includes("\\") ? "\\" : "/";
+    const norm = (s) => (sep === "\\" ? s.replace(/\//g, "\\") : s.replace(/\\/g, "/"));
+    const base = norm(root).replace(/[/\\]+$/, "");
+    const rel = norm(p);
+    return `${base}${sep}${rel}`;
+}
+/** Name of the SQLite ledger table that records applied migrations. The single source of truth
+ * for this identifier: `applyMigrations` writes it and `dataops`' `migrations` op reads it, so
+ * both import this constant and the ledger name can never drift between application and listing. */
+export const MIGRATIONS_TABLE = "_urban_migrations";
+/** Resolve a datasource `url` to its on-disk SQLite path against `root`. The result is absolute
+ * when the resolved path is absolute (either because `url` names an absolute path or `root` is
+ * absolute); if `root` is relative (e.g. "." as used by the CLI/tests) a relative `url` stays
+ * correspondingly relative. The single source of truth for this resolution, shared by
+ * `openSqliteSource` (to open the file) and `provisionSqlite` (to report where it provisioned),
+ * so the opened path and the logged path can never drift. */
+export function resolveSqlitePath(root, url) {
+    return resolveAppPath(root, sqlitePathFromUrl(url));
+}
+/**
+ * Open (creating if needed) the SQLite file a `file:`/`sqlite:` URL points at, resolved against
+ * `root`, with WAL journalling — but WITHOUT applying migrations. Provisioning (`provisionSqlite`)
+ * layers migrations on top; the `urban data` DB-manager gateway (dataops.ts) wants the raw handle
+ * so read/`migrations`-list ops don't silently mutate the schema on open.
+ */
+export async function openSqliteSource(host, root, url) {
+    const abs = resolveSqlitePath(root, url);
+    const dir = parentDir(abs);
+    if (dir && !(await host.exists(dir))) {
+        // The host API doesn't expose mkdir and openSqlite won't create parent dirs,
+        // so fail fast with a clear, actionable message instead of a low-level
+        // "cannot open" error.
+        throw new Error(`directory "${dir}" does not exist — create it before running (the SQLite file cannot be opened otherwise)`);
+    }
+    const db = host.openSqlite(abs);
+    db.exec("PRAGMA journal_mode=WAL");
+    return db;
+}
 /** A safe unquoted SQL identifier. Table/column names are interpolated directly into SQL,
  * so reject anything that isn't a plain identifier to prevent invalid SQL / injection. */
 const SQL_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -16,9 +80,22 @@ function assertSqlIdent(kind, name) {
     }
     return name;
 }
-function parentDir(path) {
-    const i = path.lastIndexOf("/");
-    return i > 0 ? path.slice(0, i) : "";
+/** The parent directory of `path`, or `""` when it has none (a bare filename or a filesystem
+ * root, for which the existence check in `openSqliteSource` is intentionally skipped). Splits on
+ * either separator so a Windows-style absolute path (e.g. "C:\data\app.db") yields a real parent
+ * dir rather than being treated as having none. Preserves the trailing separator on a Windows
+ * drive root so "C:\app.db" -> "C:\" (and "C:/app.db" -> "C:/"), not the bare volume "C:" — the
+ * latter is a drive-relative reference, not the drive root, and would make `openSqliteSource`
+ * fail fast against the wrong location. */
+export function parentDir(path) {
+    const i = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+    if (i <= 0)
+        return "";
+    // A Windows drive root ("C:\…" / "C:/…"): the separator sits right after the "C:" volume, so
+    // keep it — dropping it would yield the drive-relative "C:" rather than the drive root.
+    if (i === 2 && /^[A-Za-z]:$/.test(path.slice(0, 2)))
+        return path.slice(0, i + 1);
+    return path.slice(0, i);
 }
 /** A typed accessor over a table declared in manifest `types`. */
 export class TypeRepo {
@@ -128,18 +205,21 @@ export class DataLayer {
             s.close();
     }
 }
-async function applyMigrations(host, db, root, migrationsDir) {
-    const dir = `${root.replace(/\/+$/, "")}/${migrationsDir.replace(/^\/+/, "")}`;
+export async function applyMigrations(host, db, root, migrationsDir) {
+    const dir = resolveAppPath(root, migrationsDir);
     if (!(await host.exists(dir)))
         return [];
     const files = (await host.listDir(dir)).filter((f) => f.endsWith(".sql")).sort();
-    db.exec("CREATE TABLE IF NOT EXISTS _urban_migrations (name TEXT PRIMARY KEY, applied_at TEXT NOT NULL)");
-    const applied = new Set(db.all("SELECT name FROM _urban_migrations").map((r) => r.name));
+    db.exec(`CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (name TEXT PRIMARY KEY, applied_at TEXT NOT NULL)`);
+    const applied = new Set(db.all(`SELECT name FROM ${MIGRATIONS_TABLE}`).map((r) => r.name));
     const newlyApplied = [];
     for (const file of files) {
         if (applied.has(file))
             continue;
-        const sql = await host.readTextFile(`${dir}/${file}`);
+        // Join via `resolveAppPath` (not a literal "/") so the migration file path adopts `dir`'s own
+        // separator style; a Windows/UNC-style `dir` (backslashes) would otherwise reintroduce a
+        // mixed-separator path (e.g. "C:\\app\\db\\migrations/001.sql") that breaks reads on Windows.
+        const sql = await host.readTextFile(resolveAppPath(dir, file));
         // Apply the migration and record it in the ledger atomically. SQLite DDL is
         // transactional, so wrapping both in one BEGIN/COMMIT makes a migration all-or-nothing:
         // either the schema change AND its `_urban_migrations` row commit together, or neither
@@ -150,7 +230,7 @@ async function applyMigrations(host, db, root, migrationsDir) {
         db.exec("BEGIN");
         try {
             db.exec(sql);
-            db.run("INSERT INTO _urban_migrations (name, applied_at) VALUES (?, ?)", [
+            db.run(`INSERT INTO ${MIGRATIONS_TABLE} (name, applied_at) VALUES (?, ?)`, [
                 file,
                 new Date(host.now()).toISOString(),
             ]);
@@ -165,23 +245,20 @@ async function applyMigrations(host, db, root, migrationsDir) {
     return newlyApplied;
 }
 async function provisionSqlite(ctx, name, src) {
-    const dbPath = sqlitePathFromUrl(src.url);
-    const abs = dbPath.startsWith("/") ? dbPath : `${ctx.root.replace(/\/+$/, "")}/${dbPath}`;
-    const dir = parentDir(abs);
-    if (dir && !(await ctx.host.exists(dir))) {
-        // The host API doesn't expose mkdir and openSqlite won't create parent dirs,
-        // so fail fast with a clear, actionable message instead of a low-level
-        // "cannot open" error.
-        throw new Error(`datasource "${name}": directory "${dir}" does not exist — create it before running (the SQLite file cannot be opened otherwise)`);
+    let db;
+    try {
+        db = await openSqliteSource(ctx.host, ctx.root, src.url);
+    }
+    catch (err) {
+        // Prefix the source name onto openSqliteSource's runtime-agnostic message.
+        throw new Error(`datasource "${name}": ${err instanceof Error ? err.message : String(err)}`);
     }
-    const db = ctx.host.openSqlite(abs);
-    db.exec("PRAGMA journal_mode=WAL");
     const migrationsApplied = src.migrations
         ? await applyMigrations(ctx.host, db, ctx.root, src.migrations)
         : [];
     ctx.host.log("info", `datasource: provisioned "${name}"`, {
         driver: "sqlite",
-        path: abs,
+        path: resolveSqlitePath(ctx.root, src.url),
         migrationsApplied,
     });
     return {

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

@@ -1,5 +1,7 @@
 import type { RuntimeContext } from "../context.ts";
-/** Deploy all processes, decisions and forms declared under `models`. */
+/** Deploy all processes, decisions and forms declared under `models`. Each resource has its
+ *  `{{name}}` placeholders substituted (manifest `models.templates`, then the programmatic
+ *  `ctx.templates`, the latter winning) before it is sent to the engine. */
 export declare function deployModels(ctx: RuntimeContext): Promise<{
     deployed: number;
     files: string[];

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

@@ -1,5 +1,7 @@
-// deploy — resolve the manifest `models` patterns and deploy the resources to the engine.
+// deploy — resolve the manifest `models` patterns and deploy the resources to the engine,
+// substituting any `{{name}}` templates into each resource first (see templates.ts).
 import { expandPatterns } from "../glob.js";
+import { applyTemplates, resolveTemplates } from "./templates.js";
 function contentTypeFor(path) {
     if (path.endsWith(".bpmn"))
         return "text/xml";
@@ -13,7 +15,9 @@ function baseName(path) {
     const i = path.lastIndexOf("/");
     return i >= 0 ? path.slice(i + 1) : path;
 }
-/** Deploy all processes, decisions and forms declared under `models`. */
+/** Deploy all processes, decisions and forms declared under `models`. Each resource has its
+ *  `{{name}}` placeholders substituted (manifest `models.templates`, then the programmatic
+ *  `ctx.templates`, the latter winning) before it is sent to the engine. */
 export async function deployModels(ctx) {
     const models = ctx.manifest.models ?? {};
     const patterns = [
@@ -26,11 +30,29 @@ export async function deployModels(ctx) {
         ctx.host.log("info", "deploy: no model files matched", { patterns });
         return { deployed: 0, files: [] };
     }
-    const resources = await Promise.all(files.map(async (path) => ({
-        name: baseName(path),
-        content: await ctx.host.readTextFile(path),
-        contentType: contentTypeFor(path),
-    })));
+    // Resolve templates once (manifest globs/dirs, then the programmatic deploy option). An empty
+    // map makes substitution a no-op, so apps that use no templates are unaffected.
+    const templates = await resolveTemplates(ctx.host, ctx.root, [models.templates, ctx.templates]);
+    const hasTemplates = Object.keys(templates).length > 0;
+    const resources = await Promise.all(files.map(async (path) => {
+        const contentType = contentTypeFor(path);
+        let content = await ctx.host.readTextFile(path);
+        // Only substitute into the model content types we know how to escape (XML for .bpmn/.dmn,
+        // JSON for .form). Unknown extensions map to application/octet-stream; running the default
+        // XML escaper over them could deterministically corrupt a non-XML/JSON resource that a
+        // manifest pattern matched by accident, so leave those files untouched.
+        if (hasTemplates && contentType !== "application/octet-stream") {
+            const applied = applyTemplates(content, contentType, templates);
+            content = applied.content;
+            if (applied.unresolved.length > 0) {
+                ctx.host.log("warn", "deploy: unresolved template placeholders", {
+                    file: path,
+                    unresolved: applied.unresolved,
+                });
+            }
+        }
+        return { name: baseName(path), content, contentType };
+    }));
     const { deployed } = await ctx.engine.deployResources(resources);
     ctx.host.log("info", "deploy: models deployed", { deployed, files });
     return { deployed, files };

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

@@ -35,7 +35,7 @@ export interface TableMeta {
  * interchangeable. */
 export interface DataSource {
     /** Run a SELECT (or any row-returning statement) and collect the rows. */
-    query(sql: string, params?: unknown[]): Promise<Row[]>;
+    query<T extends object = Row>(sql: string, params?: unknown[]): Promise<T[]>;
     /** Run a non-row statement (INSERT/UPDATE/DELETE/DDL). */
     exec(sql: string, params?: unknown[]): Promise<ExecResult>;
     /** Run `fn` inside a transaction, committing on success and rolling back on throw. The

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

@@ -19,12 +19,11 @@ export function quoteIdent(name) {
  * yields an empty clause (matches all rows). Takes `object` (not `Row`) so a `Partial<T>` for a
  * generated `interface` row type (which lacks a string index signature) is accepted. */
 function whereClause(where) {
-    const w = where;
-    const keys = Object.keys(w);
-    if (keys.length === 0)
+    const entries = Object.entries(where);
+    if (entries.length === 0)
         return { clause: "", params: [] };
-    const clause = " WHERE " + keys.map((k) => `${quoteIdent(k)} = ?`).join(" AND ");
-    return { clause, params: keys.map((k) => w[k]) };
+    const clause = " WHERE " + entries.map(([k]) => `${quoteIdent(k)} = ?`).join(" AND ");
+    return { clause, params: entries.map(([, v]) => v) };
 }
 /** A typed gateway over a single table — the record-oriented data object a handler binds to
  * instead of hand-writing SQL (the Delphi `TTable`/data-module idea, ADR 0029 §6). It builds
@@ -45,16 +44,16 @@ export class Table {
      * `DEFAULT`/`NULL` governs — `undefined` means "not provided, let the schema decide", never
      * a bound value. An explicit `null` is preserved (it stores `NULL`). */
     async insert(row) {
-        const provided = Object.keys(row);
-        const keys = provided.filter((k) => row[k] !== undefined);
-        if (keys.length === 0) {
+        const provided = Object.entries(row);
+        const entries = provided.filter(([, v]) => v !== undefined);
+        if (entries.length === 0) {
             throw new Error(provided.length === 0
                 ? `Table(${this.name}).insert: no columns to insert (empty row)`
                 : `Table(${this.name}).insert: no columns to insert (all values were undefined)`);
         }
-        const cols = keys.map(quoteIdent).join(", ");
-        const ph = keys.map(() => "?").join(", ");
-        const r = await this.#src.exec(`INSERT INTO ${quoteIdent(this.name)} (${cols}) VALUES (${ph})`, keys.map((k) => row[k]));
+        const cols = entries.map(([k]) => quoteIdent(k)).join(", ");
+        const ph = entries.map(() => "?").join(", ");
+        const r = await this.#src.exec(`INSERT INTO ${quoteIdent(this.name)} (${cols}) VALUES (${ph})`, entries.map(([, v]) => v));
         if (r.lastInsertId == null) {
             // The driver reported no rowid — treat as a failed/ambiguous insert rather than
             // silently returning 0, which a caller could mistake for a real primary key.
@@ -72,12 +71,12 @@ export class Table {
         const lim = typeof limit === "number" && Number.isFinite(limit)
             ? ` LIMIT ${Math.max(0, Math.floor(limit))}`
             : "";
-        return (await this.#src.query(`SELECT * FROM ${quoteIdent(this.name)}${lim}`));
+        return this.#src.query(`SELECT * FROM ${quoteIdent(this.name)}${lim}`);
     }
     /** Rows matching an equality filter (keys ANDed). An empty filter matches all rows. */
     async find(where = {}) {
         const { clause, params } = whereClause(where);
-        return (await this.#src.query(`SELECT * FROM ${quoteIdent(this.name)}${clause}`, params));
+        return this.#src.query(`SELECT * FROM ${quoteIdent(this.name)}${clause}`, params);
     }
     /** The first row matching an equality filter, or `undefined`. */
     async findOne(where = {}) {
@@ -89,11 +88,11 @@ export class Table {
      * `undefined` are skipped (that column is left unchanged); an explicit `null` clears the
      * column to `NULL`. A patch with no defined keys is a no-op. */
     async update(id, patch) {
-        const keys = Object.keys(patch).filter((k) => patch[k] !== undefined);
-        if (keys.length === 0)
+        const entries = Object.entries(patch).filter(([, v]) => v !== undefined);
+        if (entries.length === 0)
             return 0;
-        const set = keys.map((k) => `${quoteIdent(k)} = ?`).join(", ");
-        const r = await this.#src.exec(`UPDATE ${quoteIdent(this.name)} SET ${set} WHERE ${quoteIdent(this.pk)} = ?`, [...keys.map((k) => patch[k]), id]);
+        const set = entries.map(([k]) => `${quoteIdent(k)} = ?`).join(", ");
+        const r = await this.#src.exec(`UPDATE ${quoteIdent(this.name)} SET ${set} WHERE ${quoteIdent(this.pk)} = ?`, [...entries.map(([, v]) => v), id]);
         return r.changed;
     }
     /** Delete the row with the given primary key; returns rows changed. */