@nanobpm/urban 0.20.0 → 0.22.0

package/src/runtime/core/modules/datasource.test.ts

@@ -0,0 +1,129 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { applyMigrations, isAbsolutePath, MIGRATIONS_TABLE, parentDir, resolveAppPath, resolveSqlitePath, sqlitePathFromUrl } from "./datasource.ts";
+import type { HostContext, SqliteDb } from "../host.ts";
+
+// `resolveSqlitePath` is the single source of truth for turning a datasource `url` into its
+// on-disk SQLite path (absolute when `root` is absolute, relative when `root` is relative, e.g.
+// `root === "."`), shared by `openSqliteSource` (which opens the file) and `provisionSqlite`
+// (which logs `path`). These guard that the two can never drift: the logged path must be exactly
+// the path that was opened.
+test("resolveSqlitePath joins a relative url verbatim against root", () => {
+  assert.equal(resolveSqlitePath("/srv/app", "file:./db/app.db"), "/srv/app/./db/app.db");
+  assert.equal(resolveSqlitePath("/srv/app", "sqlite:db/app.db"), "/srv/app/db/app.db");
+  assert.equal(resolveSqlitePath(".", "sqlite:db/app.db"), "./db/app.db");
+});
+
+test("resolveSqlitePath passes an absolute path through unchanged", () => {
+  assert.equal(resolveSqlitePath("/srv/app", "file:/var/data/app.db"), "/var/data/app.db");
+});
+
+test("resolveSqlitePath honours Windows absolute paths (drive-letter + UNC) as-is", () => {
+  // A Node host on Windows can hand us a drive-letter or UNC absolute path; it must NOT be
+  // treated as relative and prefixed with `root`.
+  assert.equal(resolveSqlitePath("/srv/app", "file:C:\\data\\app.db"), "C:\\data\\app.db");
+  assert.equal(resolveSqlitePath("/srv/app", "sqlite:C:/data/app.db"), "C:/data/app.db");
+  assert.equal(
+    resolveSqlitePath("/srv/app", "file:\\\\server\\share\\app.db"),
+    "\\\\server\\share\\app.db",
+  );
+});
+
+test("isAbsolutePath recognises POSIX, drive-letter and UNC roots (and rejects relative)", () => {
+  assert.equal(isAbsolutePath("/var/data/app.db"), true);
+  assert.equal(isAbsolutePath("C:\\data\\app.db"), true);
+  assert.equal(isAbsolutePath("c:/data/app.db"), true);
+  assert.equal(isAbsolutePath("\\\\server\\share\\app.db"), true);
+  assert.equal(isAbsolutePath("\\data\\app.db"), true); // Windows drive-root, single leading backslash
+  assert.equal(isAbsolutePath("db/app.db"), false);
+  assert.equal(isAbsolutePath("./db/app.db"), false);
+  assert.equal(isAbsolutePath("C:relative.db"), false); // drive-relative, no root separator
+});
+
+test("resolveAppPath trims a trailing separator of either kind off root before joining", () => {
+  assert.equal(resolveAppPath("/srv/app/", "app.db"), "/srv/app/app.db");
+  // A Windows-style root (uses backslashes) joins with "\\" and normalizes the relative segment's
+  // separators to match, so the result is never mixed-separator ("C:\\srv\\app/app.db").
+  assert.equal(resolveAppPath("C:\\srv\\app\\", "app.db"), "C:\\srv\\app\\app.db");
+  assert.equal(resolveAppPath("C:\\srv\\app", "db/app.db"), "C:\\srv\\app\\db\\app.db");
+  assert.equal(resolveAppPath("\\\\server\\share", "db/migrations"), "\\\\server\\share\\db\\migrations");
+  // A drive-letter root that already uses forward slashes stays forward-slash (also non-mixed).
+  assert.equal(resolveAppPath("C:/srv/app/", "app.db"), "C:/srv/app/app.db");
+  // A forward-slash root joined with a backslash-containing relative segment normalizes the
+  // segment to "/", so the result is never mixed-separator ("C:/srv/app/db\\migrations").
+  assert.equal(resolveAppPath("C:/srv/app", "db\\migrations"), "C:/srv/app/db/migrations");
+  assert.equal(resolveAppPath(".", "db\\migrations"), "./db/migrations");
+  // A mixed-separator root is normalized to the chosen style too (it contains a backslash, so the
+  // whole path becomes backslash-style), so the result is never mixed even when `root` itself is.
+  assert.equal(resolveAppPath("C:/srv\\app", "db/app.db"), "C:\\srv\\app\\db\\app.db");
+  assert.equal(resolveAppPath("C:/srv\\app\\", "db/app.db"), "C:\\srv\\app\\db\\app.db");
+});
+
+test("parentDir keeps the trailing separator on a Windows drive root", () => {
+  // A file directly under a drive root must yield the drive root itself, not the bare volume:
+  // "C:" is a drive-relative reference, "C:\\" / "C:/" is the actual directory.
+  assert.equal(parentDir("C:\\app.db"), "C:\\");
+  assert.equal(parentDir("C:/app.db"), "C:/");
+  // Nested paths and the no-parent cases keep working.
+  assert.equal(parentDir("C:\\data\\app.db"), "C:\\data");
+  assert.equal(parentDir("/var/data/app.db"), "/var/data");
+  assert.equal(parentDir("app.db"), "");
+});
+
+test("resolveSqlitePath strips a trailing slash on root before joining", () => {
+  assert.equal(resolveSqlitePath("/srv/app/", "sqlite:app.db"), "/srv/app/app.db");
+});
+
+test("resolveSqlitePath resolves the same path openSqliteSource would open", () => {
+  const root = "/srv/app";
+  const url = "file:./db/app.db";
+  const bare = sqlitePathFromUrl(url);
+  assert.equal(resolveSqlitePath(root, url), `${root}/${bare}`);
+});
+
+test("MIGRATIONS_TABLE is the single canonical ledger name shared by application and listing", () => {
+  // `applyMigrations` (datasource) writes this ledger and dataops' `migrations` op reads it; both
+  // import this constant so the name can never drift between the two sites.
+  assert.equal(MIGRATIONS_TABLE, "_urban_migrations");
+});
+
+test("applyMigrations joins each migration file onto its dir without reintroducing mixed separators", async () => {
+  // When the resolved migrations dir is Windows/UNC-style (backslashes), the per-file read path
+  // must adopt that separator too — a literal "/" join would emit e.g.
+  // "C:\\app\\db\\migrations/001.sql", which breaks reads on Windows. `applyMigrations` routes the
+  // join through `resolveAppPath`, so we assert the exact path handed to `readTextFile`.
+  const readPaths: string[] = [];
+  const host: HostContext = {
+    runtime: "node",
+    env: () => undefined,
+    now: () => 0,
+    exists: async () => true,
+    listDir: async () => ["002_b.sql", "001_a.sql"],
+    readTextFile: async (path: string) => {
+      readPaths.push(path);
+      return "";
+    },
+    openSqlite: () => {
+      throw new Error("sqlite not used in this test");
+    },
+    importModule: async () => ({}),
+    serveHttp: async () => ({ port: 0, stop: async () => {} }),
+    log: () => {},
+  };
+  const db: SqliteDb = {
+    exec: () => {},
+    run: () => ({ changes: 0, lastInsertRowid: 0 }),
+    all: <T>() => {
+      const rows: T[] = [];
+      return rows;
+    },
+    close: () => {},
+  };
+  // A backslash root makes `resolveAppPath` pick "\\", so the migrations dir is backslash-style.
+  const applied = await applyMigrations(host, db, "C:\\srv\\app", "db\\migrations");
+  assert.deepEqual(applied, ["001_a.sql", "002_b.sql"]);
+  assert.deepEqual(readPaths, [
+    "C:\\srv\\app\\db\\migrations\\001_a.sql",
+    "C:\\srv\\app\\db\\migrations\\002_b.sql",
+  ]);
+});

package/src/runtime/core/modules/datasource.ts

@@ -8,11 +8,85 @@ import type { HostContext, SqliteDb } from "../host.ts";
 import type { AppManifest, DataSource, DomainType } from "../manifest.ts";
 import { makeGateway, Table, type DataSource as GatewayDataSource } from "./gateway.ts";
 
-function sqlitePathFromUrl(url: string): string {
+export function sqlitePathFromUrl(url: string): string {
   // 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: string): boolean {
+  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: string, p: string): string {
+  if (isAbsolutePath(p)) return p;
+  const sep = root.includes("\\") ? "\\" : "/";
+  const norm = (s: string): string => (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: string, url: string): string {
+  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: HostContext,
+  root: string,
+  url: string,
+): Promise<SqliteDb> {
+  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_]*$/;
@@ -23,9 +97,20 @@ function assertSqlIdent(kind: string, name: string): string {
   return name;
 }
 
-function parentDir(path: string): string {
-  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: string): string {
+  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`. */
@@ -169,25 +254,28 @@ export class DataLayer {
   }
 }
 
-async function applyMigrations(
+export async function applyMigrations(
   host: HostContext,
   db: SqliteDb,
   root: string,
   migrationsDir: string,
 ): Promise<string[]> {
-  const dir = `${root.replace(/\/+$/, "")}/${migrationsDir.replace(/^\/+/, "")}`;
+  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)",
+    `CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (name TEXT PRIMARY KEY, applied_at TEXT NOT NULL)`,
   );
   const applied = new Set(
-    db.all<{ name: string }>("SELECT name FROM _urban_migrations").map((r) => r.name),
+    db.all<{ name: string }>(`SELECT name FROM ${MIGRATIONS_TABLE}`).map((r) => r.name),
   );
   const newlyApplied: string[] = [];
   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
@@ -198,7 +286,7 @@ async function applyMigrations(
     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(),
       ]);
@@ -222,25 +310,19 @@ async function provisionSqlite(
   name: string,
   src: DataSource,
 ): Promise<ProvisionedSource> {
-  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: SqliteDb;
+  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/src/runtime/core/modules/deploy.test.ts

@@ -0,0 +1,258 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import type { RuntimeContext } from "../context.ts";
+import type { HostContext } from "../host.ts";
+import type { AppManifest } from "../manifest.ts";
+import { deployModels } from "./deploy.ts";
+import { applyTemplates, resolveTemplates, type TemplateSource } from "./templates.ts";
+
+const ROOT = "/app";
+
+function dirname(p: string): string {
+  const i = p.lastIndexOf("/");
+  return i > 0 ? p.slice(0, i) : "/";
+}
+
+interface DeployedResource {
+  name: string;
+  content: string;
+  contentType: string;
+}
+
+interface Harness {
+  ctx: RuntimeContext;
+  logs: Array<{ level: string; msg: string; fields?: Record<string, unknown> }>;
+  deployed: DeployedResource[];
+}
+
+/** A virtual-filesystem host over `files` (keyed by absolute path) plus a recording engine. */
+function makeHarness(
+  files: Record<string, string>,
+  manifest: Partial<AppManifest>,
+  templates?: TemplateSource,
+): Harness {
+  const logs: Harness["logs"] = [];
+  const deployed: DeployedResource[] = [];
+  // biome-ignore lint/plugin: HostContext test double implementing only the fs/log members deployModels exercises; the rest are intentionally absent.
+  const host: HostContext = {
+    runtime: "node",
+    log: (level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>) =>
+      logs.push({ level, msg, fields }),
+    exists: async (p: string) =>
+      p in files || Object.keys(files).some((f) => f.startsWith(`${p}/`)),
+    readTextFile: async (p: string) => {
+      if (!(p in files)) throw new Error(`ENOENT ${p}`);
+      return files[p];
+    },
+    listDir: async (dir: string) =>
+      Object.keys(files)
+        .filter((f) => dirname(f) === dir)
+        .map((f) => f.slice(f.lastIndexOf("/") + 1)),
+  } as unknown as HostContext;
+  const engine = {
+    deployResources: async (resources: DeployedResource[]) => {
+      deployed.push(...resources);
+      return { deployed: resources.length };
+    },
+  };
+  // biome-ignore lint/plugin: RuntimeContext test double assembled from the mock host/engine/manifest below for deployModels.
+  const ctx = {
+    root: ROOT,
+    // biome-ignore lint/plugin: inline AppManifest fixture — a Partial<AppManifest> spread over the required base fields.
+    manifest: { schemaVersion: 1, id: "t", name: "T", ...manifest } as AppManifest,
+    // biome-ignore lint/plugin: EngineClient test double implementing only deployResources (the sole method deployModels calls).
+    engine: engine as unknown as RuntimeContext["engine"],
+    host,
+    templates,
+  } as unknown as RuntimeContext;
+  return { ctx, logs, deployed };
+}
+
+// ── applyTemplates ─────────────────────────────────────────────────────────
+
+test("applyTemplates substitutes a named placeholder", () => {
+  const { content, unresolved } = applyTemplates("<a>{{greet}}</a>", "text/xml", {
+    greet: "hello",
+  });
+  assert.equal(content, "<a>hello</a>");
+  assert.deepEqual(unresolved, []);
+});
+
+test("applyTemplates tolerates inner whitespace in the placeholder", () => {
+  const { content } = applyTemplates("{{  greet  }}", "text/xml", { greet: "hi" });
+  assert.equal(content, "hi");
+});
+
+test("applyTemplates encodes newlines/tabs as XML character references (survives attr normalization)", () => {
+  const { content } = applyTemplates('value="{{p}}"', "text/xml", {
+    p: "line1\nline2\twith <b> & 'q'",
+  });
+  assert.equal(content, 'value="line1&#10;line2&#9;with &lt;b&gt; &amp; &apos;q&apos;"');
+  // Critically, no literal newline/tab remains (those would collapse to spaces in an attribute).
+  assert.ok(!/[\n\t]/.test(content));
+});
+
+test("applyTemplates escapes JSON-string content for .form resources", () => {
+  const { content } = applyTemplates('{"q":"{{p}}"}', "application/json", {
+    p: 'a\nb"c',
+  });
+  assert.equal(content, '{"q":"a\\nb\\"c"}');
+  assert.deepEqual(JSON.parse(content), { q: 'a\nb"c' });
+});
+
+test("applyTemplates leaves unknown placeholders verbatim and reports them once", () => {
+  const { content, unresolved } = applyTemplates("{{x}} {{y}} {{x}}", "text/xml", {});
+  assert.equal(content, "{{x}} {{y}} {{x}}");
+  assert.deepEqual(unresolved, ["x", "y"]);
+});
+
+test("applyTemplates is non-recursive: a template's own braces are not re-expanded", () => {
+  const { content, unresolved } = applyTemplates("{{a}}", "text/xml", {
+    a: "{{b}}",
+    b: "SHOULD-NOT-APPEAR",
+  });
+  assert.equal(content, "{{b}}");
+  assert.deepEqual(unresolved, []);
+});
+
+// ── resolveTemplates ─────────────────────────────────────────────────────────
+
+test("resolveTemplates reads a glob source, keying by file stem", async () => {
+  const { ctx } = makeHarness(
+    { "/app/prompts/review.md": "REVIEW", "/app/prompts/fix-ci.md": "FIXCI" },
+    {},
+  );
+  const map = await resolveTemplates(ctx.host, ROOT, [["prompts/*.md"]]);
+  assert.deepEqual({ ...map }, { review: "REVIEW", "fix-ci": "FIXCI" });
+});
+
+test("resolveTemplates scans a bare directory entry", async () => {
+  const { ctx } = makeHarness(
+    { "/app/prompts/a.md": "A", "/app/prompts/b.md": "B" },
+    {},
+  );
+  const map = await resolveTemplates(ctx.host, ROOT, [["prompts"]]);
+  assert.deepEqual({ ...map }, { a: "A", b: "B" });
+});
+
+test("resolveTemplates resolves a literal file entry", async () => {
+  const { ctx } = makeHarness({ "/app/prompts/one.md": "ONE" }, {});
+  const map = await resolveTemplates(ctx.host, ROOT, [["prompts/one.md"]]);
+  assert.deepEqual({ ...map }, { one: "ONE" });
+});
+
+test("resolveTemplates ignores a directory with no readable files without warning", async () => {
+  // A directory that exists (has nested content) but no files directly under it: previously the
+  // non-glob fallback treated it as a literal file and logged a misleading "unreadable entry" warn.
+  const { ctx, logs } = makeHarness({ "/app/prompts/nested/x.md": "X" }, {});
+  const map = await resolveTemplates(ctx.host, ROOT, [["prompts"]]);
+  assert.deepEqual({ ...map }, {});
+  assert.equal(logs.filter((l) => l.level === "warn").length, 0);
+});
+
+test("resolveTemplates merges a programmatic map, letting later sources win", async () => {
+  const { ctx } = makeHarness({ "/app/prompts/review.md": "FROM-FILE" }, {});
+  const map = await resolveTemplates(ctx.host, ROOT, [
+    ["prompts/*.md"],
+    { review: "FROM-MAP", extra: "X" },
+  ]);
+  assert.deepEqual({ ...map }, { review: "FROM-MAP", extra: "X" });
+});
+
+test("resolveTemplates returns a null-prototype map so `__proto__` keys can't pollute", async () => {
+  // A template file literally named `__proto__.md`, or a programmatic map keyed by `__proto__`,
+  // must set a plain own property rather than trip the magic prototype setter on `{}`.
+  const { ctx } = makeHarness({ "/app/prompts/__proto__.md": "PWN" }, {});
+  const map = await resolveTemplates(ctx.host, ROOT, [
+    ["prompts/__proto__.md"],
+    { extra: "X" },
+  ]);
+  assert.equal(Object.getPrototypeOf(map), null);
+  assert.equal(Object.getPrototypeOf({}), Object.prototype, "global prototype untouched");
+  assert.equal(map.extra, "X");
+  assert.equal(Object.prototype.hasOwnProperty.call(map, "__proto__"), true);
+});
+
+test("resolveTemplates skips a file whose stem is not a valid placeholder name, with a warning", async () => {
+  // `spaced name.md` yields the stem `spaced name`, which the `{{…}}` placeholder charset (`[\w.-]`)
+  // can never match — so it would be unreferenceable and silently ignored. Fail loudly instead.
+  const { ctx, logs } = makeHarness(
+    { "/app/prompts/spaced name.md": "NOPE", "/app/prompts/ok.md": "YES" },
+    {},
+  );
+  const map = await resolveTemplates(ctx.host, ROOT, [["prompts/*.md"]]);
+  assert.deepEqual({ ...map }, { ok: "YES" });
+  const warn = logs.find((l) => l.level === "warn" && l.msg === "template: skipped unsupported name");
+  assert.ok(warn, "expected an unsupported-name warning");
+  assert.equal(warn?.fields?.name, "spaced name");
+});
+
+// ── deployModels integration ─────────────────────────────────────────────────
+
+test("deployModels substitutes manifest templates into deployed model content", async () => {
+  const { ctx, deployed } = makeHarness(
+    {
+      "/app/processes/agent.bpmn": '<x value="{{review}}" />',
+      "/app/prompts/review.md": "Do the review",
+    },
+    { models: { processes: ["processes/*.bpmn"], templates: ["prompts/*.md"] } },
+  );
+  const res = await deployModels(ctx);
+  assert.equal(res.deployed, 1);
+  assert.equal(deployed[0].name, "agent.bpmn");
+  assert.equal(deployed[0].content, '<x value="Do the review" />');
+});
+
+test("deployModels lets the programmatic templates option win over the manifest", async () => {
+  const { ctx, deployed } = makeHarness(
+    {
+      "/app/processes/agent.bpmn": '<x value="{{review}}" />',
+      "/app/prompts/review.md": "FROM-MANIFEST",
+    },
+    { models: { processes: ["processes/*.bpmn"], templates: ["prompts/*.md"] } },
+    { review: "FROM-OPTION" },
+  );
+  await deployModels(ctx);
+  assert.equal(deployed[0].content, '<x value="FROM-OPTION" />');
+});
+
+test("deployModels warns on an unresolved placeholder but still deploys", async () => {
+  const { ctx, deployed, logs } = makeHarness(
+    {
+      "/app/processes/agent.bpmn": '<x a="{{present}}" b="{{missing}}" />',
+      "/app/prompts/present.md": "HERE",
+    },
+    { models: { processes: ["processes/*.bpmn"], templates: ["prompts/*.md"] } },
+  );
+  const res = await deployModels(ctx);
+  assert.equal(res.deployed, 1);
+  assert.equal(deployed[0].content, '<x a="HERE" b="{{missing}}" />');
+  const warn = logs.find((l) => l.msg.includes("unresolved template placeholders"));
+  assert.ok(warn, "expected an unresolved-placeholder warning");
+  assert.deepEqual(warn?.fields?.unresolved, ["missing"]);
+});
+
+test("deployModels leaves unknown-extension resources untouched (no XML escaping)", async () => {
+  // Unknown extensions (application/octet-stream) have no safe escaper, so substitution must be
+  // skipped rather than run the default XML escaper and risk corrupting the resource.
+  const { ctx, deployed } = makeHarness(
+    {
+      "/app/models/notes.txt": "raw {{review}} & <stuff>",
+      "/app/prompts/review.md": "R",
+    },
+    { models: { processes: ["models/*.txt"], templates: ["prompts/*.md"] } },
+  );
+  await deployModels(ctx);
+  assert.equal(deployed[0].contentType, "application/octet-stream");
+  assert.equal(deployed[0].content, "raw {{review}} & <stuff>");
+});
+
+test("deployModels is a no-op on content when no templates are configured", async () => {
+  const { ctx, deployed } = makeHarness(
+    { "/app/processes/agent.bpmn": '<x value="{{review}}" />' },
+    { models: { processes: ["processes/*.bpmn"] } },
+  );
+  await deployModels(ctx);
+  // With no templates, placeholders are left untouched (no substitution pass runs).
+  assert.equal(deployed[0].content, '<x value="{{review}}" />');
+});

package/src/runtime/core/modules/deploy.ts

@@ -1,7 +1,9 @@
-// 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 type { RuntimeContext } from "../context.ts";
 import { expandPatterns } from "../glob.ts";
+import { applyTemplates, resolveTemplates } from "./templates.ts";
 
 function contentTypeFor(path: string): string {
   if (path.endsWith(".bpmn")) return "text/xml";
@@ -15,7 +17,9 @@ function baseName(path: string): string {
   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: RuntimeContext): Promise<{ deployed: number; files: string[] }> {
   const models = ctx.manifest.models ?? {};
   const patterns = [
@@ -28,12 +32,30 @@ export async function deployModels(ctx: RuntimeContext): Promise<{ deployed: num
     ctx.host.log("info", "deploy: no model files matched", { patterns });
     return { deployed: 0, files: [] };
   }
+  // 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) => ({
-      name: baseName(path),
-      content: await ctx.host.readTextFile(path),
-      contentType: contentTypeFor(path),
-    })),
+    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 });