@nanobpm/urban 0.48.0 → 0.49.0

package/src/runtime/engine/nanosdk.ts

@@ -14,12 +14,14 @@
 import type {
   EngineClient,
   EngineJob,
+  FormSchema,
   JobHandler,
   ProcessInstanceSnapshot,
   ProcessInstanceState,
+  UserTaskSummary,
   WorkerSubscription,
 } from "../core/host.ts";
-import { isBpmnError } from "../core/host.ts";
+import { isBpmnError, presentFormIdentifier } from "../core/host.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 import { isRecord } from "../core/guards.ts";
 
@@ -125,6 +127,11 @@ export interface NanoSdkClient {
     input: { userTaskKey: string; variables?: Record<string, unknown> },
     options?: unknown,
   ): Promise<unknown>;
+  getFormByKey(
+    input: { formKey: string },
+    consistency?: unknown,
+    options?: unknown,
+  ): Promise<Record<string, unknown>>;
   searchProcessInstances(
     input: { filter?: Record<string, unknown>; page?: Record<string, unknown> },
     consistency?: unknown,
@@ -214,7 +221,7 @@ export class SdkEngineClient implements EngineClient {
     processInstanceKey?: string;
     assignee?: string;
     candidateGroup?: string;
-  }): Promise<{ userTaskKey: string; elementId?: string; variables?: Record<string, unknown> }[]> {
+  }): Promise<UserTaskSummary[]> {
     // 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(
@@ -228,14 +235,77 @@ export class SdkEngineClient implements EngineClient {
         this.log("warn", "skipping user task with no key in engine response");
         return [];
       }
+      // The engine resolves a `formId="X"` linkage to the latest deployed form's key at
+      // task creation, so `formKey` (not a form id) is the linkage it reports on the task.
+      const formKey =
+        it.formKey != null && it.formKey !== "" ? String(it.formKey) : undefined;
+      const externalFormReference =
+        typeof it.externalFormReference === "string" && it.externalFormReference !== ""
+          ? it.externalFormReference
+          : undefined;
       return [{
         userTaskKey: String(userTaskKey),
         elementId: typeof it.elementId === "string" ? it.elementId : undefined,
         variables: isRecord(it.variables) ? it.variables : undefined,
+        ...(formKey ? { formKey } : {}),
+        ...(externalFormReference ? { externalFormReference } : {}),
       }];
     });
   }
 
+  async getForm(input: { formKey?: string; formId?: string }): Promise<FormSchema | null> {
+    // The engine addresses deployed forms by key (`GET /forms/{formKey}`). A user task's
+    // `formKey` is the engine's resolution of its `formId` linkage to the latest deployed
+    // form, so callers pass that key. `formId` is accepted as a fallback identifier for
+    // engines that address a form by its id; either way the engine returns the current
+    // form or 404s (→ null) when there is no such form.
+    //
+    // This is the single gate that resolves which identifier addresses the form: an
+    // empty/whitespace identifier is treated as *absent* (via `presentFormIdentifier`, the
+    // shared presence rule) so a blank `formKey` (e.g. a `?formKey=` query param) falls
+    // through to a valid `formId` instead of being taken as a present-but-unresolvable key
+    // that short-circuits to null.
+    const key = presentFormIdentifier(input.formKey) ?? presentFormIdentifier(input.formId);
+    if (key == null) return null;
+    let body: Record<string, unknown>;
+    try {
+      body = await this.client.getFormByKey(
+        { formKey: key },
+        { consistency: { waitUpToMs: 0 } },
+      );
+    } catch (err) {
+      this.log("warn", "getForm: engine form fetch failed", {
+        key,
+        formKey: input.formKey,
+        formId: input.formId,
+        err: err instanceof Error ? err.message : String(err),
+      });
+      return null;
+    }
+    if (!isRecord(body)) return null;
+    const rawSchema = body.schema;
+    // The engine serializes the form-js schema as a JSON string; parse it to the object
+    // the surface renders. Tolerate an already-parsed object (an in-memory/embedded engine).
+    let schema: Record<string, unknown> | undefined;
+    if (typeof rawSchema === "string") {
+      try {
+        const parsed: unknown = JSON.parse(rawSchema);
+        if (isRecord(parsed)) schema = parsed;
+      } catch {
+        this.log("warn", "getForm: form schema is not valid JSON", { key, formKey: input.formKey, formId: input.formId });
+      }
+    } else if (isRecord(rawSchema)) {
+      schema = rawSchema;
+    }
+    if (!schema) return null;
+    return {
+      schema,
+      ...(body.formKey != null && body.formKey !== "" ? { formKey: String(body.formKey) } : {}),
+      ...(typeof body.formId === "string" && body.formId !== "" ? { formId: body.formId } : {}),
+      ...(typeof body.version === "number" ? { version: body.version } : {}),
+    };
+  }
+
   async completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void> {
     await this.client.completeUserTask({ userTaskKey, variables: variables ?? {} });
   }

package/src/runtime/index.ts

@@ -10,20 +10,29 @@ export type {
 
 // Manifest
 export {
+  bindModeToHost,
   expandEnv,
   expandEnvString,
+  isBindMode,
   loadManifest,
   parseManifest,
+  resolveBindHost,
+  resolveBindMode,
   workerJobType,
+  ALL_INTERFACES_HOST,
+  BIND_ENV_VAR,
+  LOOPBACK_HOST,
 } from "./core/manifest.ts";
 export type {
   ActionDecl,
   AppManifest,
+  BindMode,
   ChatSurface,
   DataSource,
   DomainField,
   DomainType,
   LlmBinding,
+  NetworkConfig,
   PagesSurface,
   Surfaces,
   TaskInboxSurface,
@@ -119,10 +128,8 @@ export type {
 } from "./core/modules/llm.ts";
 export { evalCorrelation } from "./core/modules/triggers.ts";
 
-// Model deploy + `{{name}}` template substitution
-export { deployModels } from "./core/modules/deploy.ts";
-export { applyTemplates, resolveTemplates } from "./core/modules/templates.ts";
-export type { TemplateApplication, TemplateSource } from "./core/modules/templates.ts";
+// Model deploy (deploy-by-convention under `resources/`, ADR 0062)
+export { deployModels, RESOURCES_DIR } from "./core/modules/deploy.ts";
 export { defaultScheduler, MAX_TIMER_DELAY_MS } from "./core/modules/scheduler.ts";
 export type { SchedulerDeps } from "./core/modules/scheduler.ts";
 

package/src/runtime/run.ts

@@ -50,7 +50,6 @@ export async function runFromEnv(opts: RunOptions = {}): Promise<UrbanApp> {
     manifestPath: opts.manifestPath,
     port: opts.port,
     mount: opts.mount,
-    templates: opts.templates,
   });
   await app.start();
 

package/src/toolkit/fsio.ts

@@ -25,6 +25,14 @@ export function createNodeGenIO(): GenIO {
         return [];
       }
     },
+    async listSubdirs(path: string): Promise<string[]> {
+      try {
+        const entries = await readdir(path, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+      } catch {
+        return [];
+      }
+    },
     async exists(path: string): Promise<boolean> {
       try {
         await stat(path);

package/src/toolkit/gen.test.ts

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { runGen, collectArtifacts, type GenIO } from "./gen.ts";
+import { runGen, collectArtifacts, readModels, type GenIO } from "./gen.ts";
 import { defineFlow, envelope } from "@nanobpm/workflow";
 import { MODEL_PROVENANCE } from "./models.ts";
 
@@ -29,6 +29,18 @@ function memIO(
       }
       return [...names];
     },
+    async listSubdirs(p) {
+      const prefix = p.replace(/\/+$/, "") + "/";
+      const names = new Set<string>();
+      for (const f of Object.keys(files)) {
+        if (f.startsWith(prefix)) {
+          const rest = f.slice(prefix.length);
+          const slash = rest.indexOf("/");
+          if (slash > 0) names.add(rest.slice(0, slash));
+        }
+      }
+      return [...names];
+    },
     async exists(p) {
       return p in files;
     },
@@ -181,11 +193,11 @@ function codeFirstIO() {
   );
 }
 
-test("runGen derives processes/<id>.bpmn from workflows/*.ts and feeds worker-io off it", async () => {
+test("runGen derives resources/processes/<id>.bpmn from workflows/*.ts and feeds worker-io off it", async () => {
   const io = codeFirstIO();
   const res = await runGen({ root: "/cf", io });
-  const bpmn = io.files["/cf/processes/greet.bpmn"];
-  assert.ok(bpmn, "expected a derived processes/greet.bpmn");
+  const bpmn = io.files["/cf/resources/processes/greet.bpmn"];
+  assert.ok(bpmn, "expected a derived resources/processes/greet.bpmn");
   assert.ok(bpmn.includes(MODEL_PROVENANCE), "derived .bpmn must be provenance-stamped");
   assert.ok(bpmn.includes('type="greet:hello"'), "derived .bpmn carries the task type");
   // worker-io is derived FROM the in-memory model, not from any on-disk file.
@@ -197,7 +209,7 @@ test("runGen derives processes/<id>.bpmn from workflows/*.ts and feeds worker-io
 test("gen --no-models derives in-memory for worker-io but writes no .bpmn", async () => {
   const io = codeFirstIO();
   const res = await runGen({ root: "/cf", io, emitModels: false });
-  assert.equal(io.files["/cf/processes/greet.bpmn"], undefined, "must not write .bpmn");
+  assert.equal(io.files["/cf/resources/processes/greet.bpmn"], undefined, "must not write .bpmn");
   // still derives the model in-memory so worker-io is populated.
   assert.ok(io.files["/cf/nano-generated/worker-io.d.ts"].includes("greet:hello"));
   assert.equal(res.incomplete, false);
@@ -206,17 +218,17 @@ test("gen --no-models derives in-memory for worker-io but writes no .bpmn", asyn
 test("the provenance sweep removes a stale derived .bpmn no longer backed by a workflow", async () => {
   const io = codeFirstIO();
   // a leftover derived model from a since-deleted flow, provenance-stamped.
-  io.files["/cf/processes/stale.bpmn"] = `<?xml version="1.0"?>\n${MODEL_PROVENANCE}\n<bpmn:x/>`;
+  io.files["/cf/resources/processes/stale.bpmn"] = `<?xml version="1.0"?>\n${MODEL_PROVENANCE}\n<bpmn:x/>`;
   await runGen({ root: "/cf", io });
-  assert.ok(io.files["/cf/processes/greet.bpmn"], "keeps the live derived model");
-  assert.equal(io.files["/cf/processes/stale.bpmn"], undefined, "sweeps the stale derived model");
+  assert.ok(io.files["/cf/resources/processes/greet.bpmn"], "keeps the live derived model");
+  assert.equal(io.files["/cf/resources/processes/stale.bpmn"], undefined, "sweeps the stale derived model");
 });
 
 test("the sweep never touches an authored (un-stamped) .bpmn", async () => {
   const io = codeFirstIO();
-  io.files["/cf/processes/authored.bpmn"] = `<?xml version="1.0"?>\n<bpmn:authored/>`;
+  io.files["/cf/resources/processes/authored.bpmn"] = `<?xml version="1.0"?>\n<bpmn:authored/>`;
   await runGen({ root: "/cf", io });
-  assert.ok(io.files["/cf/processes/authored.bpmn"], "authored .bpmn must survive the sweep");
+  assert.ok(io.files["/cf/resources/processes/authored.bpmn"], "authored .bpmn must survive the sweep");
 });
 
 test("collectArtifacts trims api.spec whitespace so gen matches the runtime (no gen/runtime drift)", async () => {
@@ -324,3 +336,27 @@ test("gen fuses a model-authored nano:shape envelope into the worker-io contract
   assert.ok(domain, "domain-rows.d.ts is emitted from the fused registry");
   assert.match(domain!.content, /"ReviewIn":/);
 });
+
+// Guards the gen/runtime drift class: gen's readModels must key the `resources/` convention off the
+// *absence* of the whole `models` block (mirroring the runtime deploy, ADR 0062), NOT off a missing
+// `models.processes`. A `models` block present for other overrides (e.g. forms) must suppress the
+// convention scan, so gen never derives process models the runtime deploy would never deploy.
+test("readModels: a models block without processes suppresses the resources/ convention (no gen/runtime drift)", async () => {
+  const io = memIO({
+    "/app/resources/a.bpmn": "<bpmn:definitions/>",
+    "/app/resources/sub/b.bpmn": "<bpmn:definitions/>",
+  });
+  // No models block at all → convention scans resources/ (shallow, one level deep).
+  const byConvention = await readModels("/app", io, {});
+  assert.deepEqual(
+    byConvention.map((m) => m.path).sort(),
+    ["resources/a.bpmn", "resources/sub/b.bpmn"],
+    "with no models block, gen discovers under resources/ by convention",
+  );
+  // A declared models block (even one that resolves to zero process files) is an explicit override:
+  // the convention scan must be skipped entirely, matching runtime deployModels.
+  const withEmptyModels = await readModels("/app", io, { models: {} });
+  assert.deepEqual(withEmptyModels, [], "a declared models block suppresses the resources/ convention");
+  const withOnlyProcesses = await readModels("/app", io, { models: { processes: [] } });
+  assert.deepEqual(withOnlyProcesses, [], "an explicitly empty models.processes yields no models, not a convention fallback");
+});

package/src/toolkit/gen.ts

@@ -21,6 +21,12 @@ export interface GenIO {
   writeText(path: string, content: string): Promise<void>;
   /** File names (not paths) in a directory; empty if it does not exist. */
   listDir(path: string): Promise<string[]>;
+  /**
+   * Sub-directory names (not files) in a directory; empty if it does not exist. Optional: the
+   * deploy-by-convention model scan uses it to descend one level into `resources/<subdir>/`. When
+   * absent, only files directly under `resources/` are scanned.
+   */
+  listSubdirs?(path: string): Promise<string[]>;
   exists(path: string): Promise<boolean>;
   /**
    * Import an app module and return its exports. Optional: only present when the caller runs on
@@ -99,19 +105,66 @@ export async function expandPattern(root: string, io: GenIO, pattern: string): P
     .sort();
 }
 
-/** Read + resolve the app's process models from the manifest's `models.processes` patterns. */
+/** The deploy-by-convention directory (ADR 0062): when the manifest declares no `models`, both the
+ *  runtime deploy and this codegen scan discover deployables/models under it — shallow, one level
+ *  deep (`resources/*` and `resources/<subdir>/*`). Deploy-only by convention. */
+export const RESOURCES_DIR = "resources";
+
+/** Model file extensions the `nano:shape`/code-first scan reads by convention (BPMN + DMN). */
+const MODEL_EXTS = [".bpmn", ".dmn"];
+
+/**
+ * Discover model files under `resources/` by convention — shallow, one level deep (`resources/*`
+ * and `resources/<subdir>/*`), never deeper — mirroring the runtime deploy walk so the codegen scan
+ * and the deploy see the same set. Returns root-relative paths, sorted. Descending one level needs
+ * `io.listSubdirs`; without it only the files directly under `resources/` are scanned.
+ */
+export async function discoverResourceModels(root: string, io: GenIO): Promise<string[]> {
+  const isModel = (n: string): boolean => MODEL_EXTS.some((e) => n.endsWith(e));
+  const out: string[] = [];
+  for (const n of await io.listDir(join(root, RESOURCES_DIR))) {
+    if (isModel(n)) out.push(`${RESOURCES_DIR}/${n}`);
+  }
+  const subdirs = io.listSubdirs ? await io.listSubdirs(join(root, RESOURCES_DIR)) : [];
+  for (const sub of subdirs.slice().sort()) {
+    for (const n of await io.listDir(join(root, `${RESOURCES_DIR}/${sub}`))) {
+      if (isModel(n)) out.push(`${RESOURCES_DIR}/${sub}/${n}`);
+    }
+  }
+  return out.sort();
+}
+
+/**
+ * Read + resolve the app's process models. Convention is keyed off the *absence* of the entire
+ * `models` block — mirroring the runtime deploy (ADR 0062): with no `models` block, models are
+ * discovered by convention under `resources/`; with a `models` block declared, `models.processes`
+ * is the explicit override (used verbatim, possibly empty). Keying off a missing `models.processes`
+ * alone would fall back to convention even when a `models` block is present for other overrides
+ * (e.g. forms), letting gen scan/derive process models the runtime deploy will never deploy —
+ * gen/runtime drift.
+ */
 export async function readModels(
   root: string,
   io: GenIO,
   manifest: { models?: { processes?: string[] } },
 ): Promise<ModelSource[]> {
-  const procPatterns = manifest.models?.processes ?? [];
-  const models: ModelSource[] = [];
-  for (const pat of procPatterns) {
-    for (const rel of await expandPattern(root, io, pat)) {
-      models.push({ path: rel, xml: await io.readText(join(root, rel)) });
+  const byConvention = manifest.models === undefined;
+  let rels: string[];
+  if (byConvention) {
+    rels = await discoverResourceModels(root, io);
+  } else {
+    rels = [];
+    for (const pat of manifest.models?.processes ?? []) {
+      rels.push(...(await expandPattern(root, io, pat)));
     }
   }
+  const models: ModelSource[] = [];
+  const seen = new Set<string>();
+  for (const rel of rels) {
+    if (seen.has(rel)) continue;
+    seen.add(rel);
+    models.push({ path: rel, xml: await io.readText(join(root, rel)) });
+  }
   return models;
 }
 

package/src/toolkit/models.test.ts

@@ -64,13 +64,13 @@ test("bpmnFilename sanitizes ids into safe .bpmn filenames", () => {
   assert.equal(bpmnFilename("a b:c"), "a-b-c.bpmn");
 });
 
-test("processesOutDir defaults to processes/, or the dir of a models.processes glob", () => {
-  assert.equal(processesOutDir({}), "processes");
+test("processesOutDir defaults to resources/processes/, or the dir of a models.processes glob", () => {
+  assert.equal(processesOutDir({}), "resources/processes");
   assert.equal(processesOutDir({ models: { processes: ["resources/processes/*.bpmn"] } }), "resources/processes");
   assert.equal(processesOutDir({ models: { processes: ["src/models/*.bpmn"] } }), "src/models");
 });
 
-test("deriveModels turns workflows/*.ts into a provenance-stamped processes/<id>.bpmn", async () => {
+test("deriveModels turns workflows/*.ts into a provenance-stamped resources/processes/<id>.bpmn", async () => {
   const io = memIO(
     { "/app/workflows/greet.ts": "// source" },
     { "workflows/greet.ts": { greet } },
@@ -81,12 +81,12 @@ test("deriveModels turns workflows/*.ts into a provenance-stamped processes/<id>
   assert.equal(d.incomplete, false);
   assert.deepEqual(d.ids, ["greet"]);
   assert.equal(d.artifacts.length, 1);
-  assert.equal(d.artifacts[0].path, "processes/greet.bpmn");
+  assert.equal(d.artifacts[0].path, "resources/processes/greet.bpmn");
   assert.match(d.artifacts[0].content, /<!--.*@nanobpm\/urban/);
   assert.ok(d.artifacts[0].content.includes(MODEL_PROVENANCE));
   assert.match(d.artifacts[0].content, /greet/);
   // the in-memory ModelSource is fed to the type-contract derivers
-  assert.deepEqual(d.models.map((m) => m.path), ["processes/greet.bpmn"]);
+  assert.deepEqual(d.models.map((m) => m.path), ["resources/processes/greet.bpmn"]);
   assert.equal(d.list[0].id, "greet");
   assert.equal(d.list[0].kind, "declarative");
 });

package/src/toolkit/models.ts

@@ -2,7 +2,8 @@
 //
 // Unlike the pure derivers (migrations, domain, worker I/O), which transform strings, this
 // imports the app's `workflows/*.ts`, turns each `defineFlow` into executable BPMN via
-// `@nanobpm/workflow` (`toBpmn` + `bpmn-auto-layout` DI), and writes `processes/<id>.bpmn`.
+// `@nanobpm/workflow` (`toBpmn` + `bpmn-auto-layout` DI), and writes `resources/processes/<id>.bpmn`
+// (the deploy-by-convention `resources/` tree, ADR 0062 — see `PROCESSES_DIR`).
 // Executing the app's TypeScript needs a runtime module loader, so this is gated on the
 // optional `GenIO.importModule` (present on Node with type-stripping, and on Deno). When the
 // loader is absent — or the app authors its models directly (model-first) — derivation is a
@@ -19,9 +20,11 @@ import { isRecord } from "../runtime/core/guards.ts";
 /** 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
- * model is ejectable to model-first and picked up by `models.processes: ["processes/*.bpmn"]`). */
-export const PROCESSES_DIR = "processes";
+/** Default output dir for derived models when the manifest declares no `models.processes`: under
+ * the deploy-by-convention `resources/` tree (ADR 0062), one level deep, so a derived model lands
+ * exactly where the convention deploy + codegen scan look for it. When `models.processes` IS set,
+ * `processesOutDir` derives the dir from that glob instead (the model-first override). */
+export const PROCESSES_DIR = "resources/processes";
 
 /** Marker stamped into every derived `.bpmn` (an XML comment) so re-gen overwrites and the
  * stale sweep deletes ONLY derived output — never an authored, human-owned model. */
@@ -68,7 +71,7 @@ export interface ModelError {
 }
 
 export interface DerivedModels {
-  /** `processes/<id>.bpmn` artifacts (path + provenance-stamped content). */
+  /** `resources/processes/<id>.bpmn` artifacts (path + provenance-stamped content). */
   artifacts: DerivedArtifact[];
   /** The same models, in-memory, for feeding the type-contract derivers (worker I/O, meta, messages). */
   models: ModelSource[];

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

@@ -1,18 +0,0 @@
-import type { HostContext } from "../host.ts";
-/** A template source: a list of globs/directories/files (name = file stem), or an explicit
- *  `name → content` map. */
-export type TemplateSource = string[] | Record<string, string>;
-/** Build the `name → content` template map from the given sources in order (later sources win on
- *  a name collision). Array sources are resolved to files (stem = name) and read; map sources are
- *  merged verbatim. */
-export declare function resolveTemplates(host: HostContext, root: string, sources: ReadonlyArray<TemplateSource | undefined>): Promise<Record<string, string>>;
-export interface TemplateApplication {
-    content: string;
-    /** Distinct placeholder names with no matching template (left in place, surfaced by the caller). */
-    unresolved: string[];
-}
-/** Replace every `{{ name }}` placeholder in `content` with the named template's content, escaped
- *  for `contentType`. Single-pass and non-recursive: a template that itself contains `{{…}}` is
- *  not re-expanded. Unknown placeholders are left verbatim (so the miss is visible, not silently
- *  dropped) and reported in `unresolved`. */
-export declare function applyTemplates(content: string, contentType: string, templates: Record<string, string>): TemplateApplication;

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

@@ -1,133 +0,0 @@
-// Template substitution for deployed model resources. A model file (`.bpmn`/`.dmn`/`.form`) may
-// carry `{{ name }}` placeholders — e.g. an agent service task whose prompt lives in a
-// `zeebe:header` value. Before deploy we replace each placeholder with the named template's
-// content, escaped for the resource's content-type, so a large asset (a prompt) is authored once
-// in a file and inlined into the model at deploy time rather than hand-pasted into XML or shipped
-// as a bulky per-instance process variable.
-//
-// Templates come from two sources, merged in order (later wins on a name collision):
-//   1. the manifest `models.templates` (globs, or a bare directory that is scanned), and
-//   2. a programmatic `templates` deploy option (globs, or an explicit `name → content` map).
-// A template's name is its file's stem (basename without extension): `prompts/review-round.md`
-// resolves the placeholder `{{review-round}}`.
-import { expandPatterns } from "../glob.js";
-/** A file's stem: basename without its final extension (`a/b/review-round.md` → `review-round`). */
-function stem(path) {
-    const base = path.slice(path.lastIndexOf("/") + 1);
-    const dot = base.lastIndexOf(".");
-    return dot > 0 ? base.slice(0, dot) : base;
-}
-// A template name is referenceable only if it matches the placeholder charset (`[\w.-]`, see
-// `PLACEHOLDER`). A file stem outside that set (e.g. containing spaces) could be loaded but never
-// referenced, and its `{{…}}` would not even be detected as unresolved — so we reject it loudly.
-const VALID_NAME = /^[\w.-]+$/;
-/** Files contributed by one entry: a glob (`prompts/*.md`), a bare directory (scanned, non-glob),
- *  or a literal file. Returns root-prefixed paths, matching `expandPatterns`. */
-async function filesFor(host, root, entry) {
-    if (entry.includes("*"))
-        return expandPatterns(host, root, [entry]);
-    const trimmed = entry.replace(/\/+$/, "");
-    // A non-glob entry is either a directory (scan it) or a literal file. Scan as a directory first;
-    // a non-empty directory resolves here.
-    const scanned = await expandPatterns(host, root, [`${trimmed}/*`]);
-    if (scanned.length > 0)
-        return scanned;
-    // No children matched: the entry is an empty (or subdir-only) directory, a literal file, or
-    // missing. A directory never appears in its parent's `listDir` (which yields file names only),
-    // so if the parent lists this basename it is a real file to read; otherwise treat the entry as an
-    // empty template directory that contributes nothing — and, crucially, emit no misleading
-    // "unreadable entry" warning for a valid-but-empty directory (readTextFile on it would EISDIR).
-    const slash = trimmed.lastIndexOf("/");
-    const base = trimmed.slice(slash + 1);
-    const parent = slash > 0 ? trimmed.slice(0, slash) : "";
-    const parentDir = parent ? `${root.replace(/\/+$/, "")}/${parent}` : root;
-    const siblings = await host.listDir(parentDir);
-    return siblings.includes(base) ? expandPatterns(host, root, [trimmed]) : [];
-}
-/** Build the `name → content` template map from the given sources in order (later sources win on
- *  a name collision). Array sources are resolved to files (stem = name) and read; map sources are
- *  merged verbatim. */
-export async function resolveTemplates(host, root, sources) {
-    // A null-prototype dictionary: template names (file stems or caller-supplied map keys) are
-    // untrusted, so a name like `__proto__` must set a plain own property rather than trip the
-    // magic prototype setter that a normal `{}` inherits from `Object.prototype`.
-    const map = Object.create(null);
-    for (const source of sources) {
-        if (!source)
-            continue;
-        if (Array.isArray(source)) {
-            const seen = new Set();
-            for (const entry of source) {
-                for (const file of await filesFor(host, root, entry)) {
-                    if (seen.has(file))
-                        continue;
-                    seen.add(file);
-                    const name = stem(file);
-                    if (!VALID_NAME.test(name)) {
-                        // Loud failure for a misnamed template file rather than a silently unreferenceable entry.
-                        host.log("warn", "template: skipped unsupported name", { file, name });
-                        continue;
-                    }
-                    try {
-                        map[name] = await host.readTextFile(file);
-                    }
-                    catch (err) {
-                        // A directory path that slipped through the file fallback, or an unreadable file.
-                        host.log("warn", "template: skipped unreadable entry", { file, error: String(err) });
-                    }
-                }
-            }
-        }
-        else {
-            Object.assign(map, source);
-        }
-    }
-    return map;
-}
-// `{{ name }}` — a double-brace placeholder around a template name. Double braces avoid clashing
-// with FEEL's single-brace context syntax used elsewhere in BPMN.
-const PLACEHOLDER = /\{\{\s*([\w.-]+)\s*\}\}/g;
-/** Escape template content for an XML attribute value (e.g. a `zeebe:header` `value="…"`). Beyond
- *  the markup-significant characters, newlines and tabs MUST become character references:
- *  XML attribute-value normalization collapses literal newlines/tabs to spaces, which would
- *  destroy a multi-line prompt. Character references are exempt from that normalization, so
- *  `
` round-trips as a newline. This escaping is also valid for XML element text, so it is
- *  the safe default for any `.bpmn`/`.dmn` placeholder position. */
-function xmlAttrEscape(s) {
-    return s
-        .replace(/&/g, "&")
-        .replace(/</g, "&lt;")
-        .replace(/>/g, "&gt;")
-        .replace(/"/g, "&quot;")
-        .replace(/'/g, "&apos;")
-        .replace(/\r/g, "&#13;")
-        .replace(/\n/g, "&#10;")
-        .replace(/\t/g, "&#9;");
-}
-/** Escape template content for embedding inside a JSON string literal (a `.form` value). */
-function jsonStringEscape(s) {
-    // Stringify to a valid JSON string, then drop the surrounding quotes → an inner-string fragment.
-    const quoted = JSON.stringify(s);
-    return quoted.slice(1, quoted.length - 1);
-}
-function escaperFor(contentType) {
-    if (contentType === "application/json")
-        return jsonStringEscape;
-    return xmlAttrEscape; // text/xml (.bpmn/.dmn) and any other markup
-}
-/** Replace every `{{ name }}` placeholder in `content` with the named template's content, escaped
- *  for `contentType`. Single-pass and non-recursive: a template that itself contains `{{…}}` is
- *  not re-expanded. Unknown placeholders are left verbatim (so the miss is visible, not silently
- *  dropped) and reported in `unresolved`. */
-export function applyTemplates(content, contentType, templates) {
-    const escape = escaperFor(contentType);
-    const unresolved = [];
-    const out = content.replace(PLACEHOLDER, (whole, name) => {
-        if (Object.prototype.hasOwnProperty.call(templates, name))
-            return escape(templates[name]);
-        if (!unresolved.includes(name))
-            unresolved.push(name);
-        return whole;
-    });
-    return { content: out, unresolved };
-}