@nanobpm/urban 0.32.2 → 0.33.0

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

@@ -6,10 +6,9 @@ import { type Route } from "../router.ts";
 export interface ApiBinding {
     spec: string;
     dir?: string;
-    base?: string;
     validateResponses?: "dev" | "always" | "never";
     eject?: boolean;
-    /** Human API docs (Swagger UI). `true`/omitted → on at `${base}-docs` (ADR 0058); `false` →
+    /** Human API docs (Swagger UI). `true`/omitted → on at `/app/api-docs` (ADR 0058); `false` →
      *  off; a string → a custom absolute route to mount the UI under. Spec-first apps get docs
      *  for free — the UI reads the SAME OpenAPI document the runtime routes + validates from. */
     docs?: boolean | string;

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

@@ -2,7 +2,7 @@
 // instead of hand-rolled imperative handlers, an author declares `api: { spec }` in the manifest and
 // writes one delegate module per `operationId`. This runtime reads the SAME OpenAPI document the
 // toolkit deriver turns into types (via the shared `openapi/spec.ts`), mounts one dispatcher over the
-// `api.base` namespace, and for each request: parses → validates params/query/body against the spec →
+// fixed `/app/api` namespace, and for each request: parses → validates params/query/body against the spec →
 // 400 with a structured error → resolves + calls the operationId delegate (validated, typed input +
 // the injected AppApi, exactly like a worker/action handler) → serializes the result.
 //
@@ -15,6 +15,10 @@ import { errorMessage } from "../guards.js";
 import { html, json, normalizeRoutePath } from "../router.js";
 import { resolveAppPath } from "./datasource.js";
 import { collectOperations, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, resolveSchema, toRouteMatcher, undeclaredPathParams, validateValue, } from "../../../openapi/spec.js";
+/** The canonical, non-configurable mount prefix for an app's OpenAPI operations. Operations always
+ *  live under `/app/api` so page actions, links, and any `callRoute` can name an operation path as a
+ *  stable framework constant (`/app/api/<op path>`) — there is no per-app `base` knob to drift. */
+const API_BASE = "/app/api";
 /** Pinned Swagger UI dist served from a CDN, so the docs UI adds zero bundle/runtime deps to an
  *  Urban app (matching the deps-free spirit of the rest of the surface — validators are standalone,
  *  ADR 0058 Consequences). Pinned (not `latest`) for reproducibility. */
@@ -76,7 +80,6 @@ function readApiBinding(manifest) {
     if (typeof spec !== "string" || spec.trim().length === 0)
         return undefined;
     const dir = Reflect.get(raw, "dir");
-    const base = Reflect.get(raw, "base");
     const validateResponses = Reflect.get(raw, "validateResponses");
     const eject = Reflect.get(raw, "eject");
     const docs = Reflect.get(raw, "docs");
@@ -84,7 +87,6 @@ function readApiBinding(manifest) {
     return {
         spec: spec.trim(),
         dir: typeof dir === "string" && dir.trim().length > 0 ? dir.trim() : undefined,
-        base: typeof base === "string" && base.trim().length > 0 ? base.trim() : undefined,
         validateResponses: validateResponses === "dev" || validateResponses === "always" || validateResponses === "never"
             ? validateResponses
             : undefined,
@@ -94,14 +96,15 @@ function readApiBinding(manifest) {
         docs: docs === false ? false : typeof docs === "string" && docs.trim().length > 0 ? docs.trim() : true,
     };
 }
-/** Resolve the api `base` + docs routing from a binding, in ONE place, so `mountApi` (which
- *  serves the docs) and `apiDocsPath` (which the pages surface links to) can never drift. */
+/** Resolve the api `base` + docs routing, in ONE place, so `mountApi` (which serves the docs) and
+ *  `apiDocsPath` (which the pages surface links to) can never drift. The operation base is the fixed
+ *  `/app/api` constant; only the docs route remains manifest-configurable. */
 function resolveApiRoutes(binding) {
-    const base = normalizeRoutePath(binding.base, "/app/api");
+    const base = API_BASE;
     const docsEnabled = binding.docs !== false;
-    // Swagger UI at a SIBLING of the base (`${base}-docs`, e.g. /app/api-docs), never a subpath
-    // of it — so the docs routes can't collide with, or be shadowed by, the operation dispatcher
-    // that owns the `${base}/` prefix (a string `docs` overrides the whole route).
+    // Swagger UI at a SIBLING of the base (`/app/api-docs`), never a subpath of it — so the docs
+    // routes can't collide with, or be shadowed by, the operation dispatcher that owns the
+    // `${base}/` prefix (a string `docs` overrides the whole route).
     const docsBase = normalizeRoutePath(typeof binding.docs === "string" ? binding.docs : `${base}-docs`, `${base}-docs`);
     return { base, docsEnabled, docsBase };
 }
@@ -143,15 +146,11 @@ export function mountApi(ctx, app) {
     const binding = readApiBinding(ctx.manifest);
     if (!binding)
         return { name: "api", routes: [], describe: () => ({ api: "disabled" }) };
-    // Normalize the manifest base the same way actions[] routes do (shared normalizeRoutePath):
-    // ensure a leading "/", strip trailing slashes, and fall back when empty — otherwise a base
-    // like "app/api" would never match request paths, which always start with "/".
-    //
-    // The api `base` and the docs routing are derived TOGETHER by the shared helper (ADR 0058) so
-    // this module (which serves the docs) and `apiDocsPath` (which links to them from the pages
-    // shell) stay in lockstep with a single normalization of `binding.base` — no second, drifting
-    // copy of that logic here. The spec JSON is served under the docs path so the operations
-    // namespace stays purely operations.
+    // The api `base` is the fixed `/app/api` constant; only the docs routing is derived here. Both
+    // come from the shared helper (ADR 0058) so this module (which serves the docs) and `apiDocsPath`
+    // (which links to them from the pages shell) stay in lockstep — no second, drifting copy of that
+    // logic here. The spec JSON is served under the docs path so the operations namespace stays
+    // purely operations.
     const { base, docsEnabled, docsBase } = resolveApiRoutes(binding);
     const dir = binding.dir ?? "operations";
     const surfaceEject = binding.eject === true;

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

@@ -14,6 +14,13 @@
 //   POST /app/actions/start/<process>               → engine.createInstance
 //   POST /app/actions/cancel                        → engine.cancelInstance
 //   POST /app/actions/message                       → engine.publishMessage
+//
+// Page actions are ROUTE-DRIVEN: an `actionForm`/rowAction/detail-form `action` is just
+// `{ path, method?, body?, successLabel? }`. The client POSTs the resolved body (default
+// `{ variables: <form> }`) to `path`, templating `{{form.KEY}}` / `{{row.KEY}}` (and the
+// whole-object `{{form}}` / `{{row}}`) tokens. There are NO bespoke action kinds — a form
+// reaches start/cancel/message above, an OpenAPI operation under /app/api, or any app route
+// uniformly by naming its path.
 import { errorMessage, isRecord } from "../guards.js";
 import { html, json } from "../router.js";
 import { cancelInstanceReconciling } from "./cancel.js";
@@ -586,6 +593,59 @@ async function getJSON(url, opts) {
   return body;
 }
 
+// ── route-driven actions ────────────────────────────────────────────────
+// Every page action is a single primitive: POST (or any method) the resolved
+// body to an app route path. There are NO bespoke action kinds — a form/row
+// reaches process start, message publish, cancel, an OpenAPI operation, a
+// webhook, or any app route uniformly by naming its path. Path + body may
+// interpolate the current form fields and (for grid rows/detail forms) the row
+// via {{form.KEY}} / {{row.KEY}} tokens; the whole-string tokens {{form}} and
+// {{row}} splice the object itself (type-preserving), so a body of
+// "variables": "{{form}}" sends the form object as the variable map.
+function lookupToken(path, ctx) {
+  const segs = String(path).split(".");
+  const head = segs[0];
+  let base = head === "form" ? (ctx.form || {}) : head === "row" ? (ctx.row || {}) : undefined;
+  for (let i = 1; i < segs.length; i++) base = base == null ? undefined : base[segs[i]];
+  return base;
+}
+function resolveTemplate(node, ctx) {
+  if (typeof node === "string") {
+    const whole = node.match(/^\{\{\s*([\w.]+)\s*\}\}$/);
+    if (whole) return lookupToken(whole[1], ctx);
+    return node.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, k) => {
+      const v = lookupToken(k, ctx);
+      return v == null ? "" : String(v);
+    });
+  }
+  if (Array.isArray(node)) return node.map((n) => resolveTemplate(n, ctx));
+  if (node && typeof node === "object") {
+    // Null-proto target so a template key like "__proto__" can't trigger prototype
+    // mutation (prototype-pollution class) when copied into the resolved object.
+    const out = Object.create(null);
+    for (const [k, v] of Object.entries(node)) out[k] = resolveTemplate(v, ctx);
+    return out;
+  }
+  return node;
+}
+async function runRoute(action, ctx) {
+  if (!action || typeof action.path !== "string" || action.path === "") {
+    throw new Error("This action has no route configured (action.path is missing or blank)");
+  }
+  const path = action.path.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, k) => {
+    const v = lookupToken(k, ctx);
+    return v == null ? "" : encodeURIComponent(String(v));
+  });
+  const method = String(action.method || "POST").toUpperCase();
+  let body;
+  if (action.body !== undefined) body = resolveTemplate(action.body, ctx);
+  else if (ctx.form) body = { variables: ctx.form };
+  else body = {};
+  const opts = { method, headers: { "content-type": "application/json" } };
+  if (method !== "GET" && method !== "HEAD") opts.body = JSON.stringify(body);
+  return getJSON(path, opts);
+}
+
 function el(tag, attrs = {}, ...kids) {
   const n = document.createElement(tag);
   for (const [k, v] of Object.entries(attrs)) {
@@ -686,37 +746,14 @@ function renderActionForm(node) {
     }
     btn.disabled = true; msg.className = "pc-msg"; msg.textContent = "Submitting…";
     try {
-      // Two action kinds: startProcess (default, back-compat) -> engine.createInstance; and
-      // publishMessage -> engine.publishMessage, which correlates a message to a message start
-      // (or intermediate catch) event. correlationKeyField names the form field that carries
-      // the correlation key; the whole form becomes the message variables.
-      if (p.action && p.action.kind === "publishMessage") {
-        const correlationKey = String(variables[p.action.correlationKeyField] ?? "").trim();
-        if (!correlationKey) {
-          msg.className = "pc-msg err";
-          msg.textContent = "Field '" + p.action.correlationKeyField + "' is required";
-          return;
-        }
-        // Send the trimmed key back as the variable too, so the value a worker
-        // reads matches the key the message was correlated on (no leading/trailing
-        // whitespace divergence between correlationKey and variables[field]).
-        variables[p.action.correlationKeyField] = correlationKey;
-        await getJSON("/app/actions/message", { method: "POST",
-          headers: { "content-type": "application/json" },
-          body: JSON.stringify({ name: p.action.message, correlationKey, variables }) });
-        msg.className = "pc-msg ok";
-        msg.textContent = "Message published";
-      } else {
-        if (!p.action || !p.action.process) {
-          msg.className = "pc-msg err";
-          msg.textContent = "This form has no action configured";
-          return;
-        }
-        const res = await getJSON("/app/actions/start/" + encodeURIComponent(p.action.process),
-          { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ variables }) });
-        msg.className = "pc-msg ok";
-        msg.textContent = "Started (instance " + (res.processInstanceKey ?? "?") + ")";
-      }
+      // Route-driven: POST the form (as { variables } by default, or the action's
+      // own body template) to the action's route path. correlationKey / process /
+      // message are expressed by the path + body template the page author supplies,
+      // e.g. { path: "/app/actions/message", body: { name, correlationKey, variables: "{{form}}" } }.
+      const res = await runRoute(p.action, { form: variables });
+      msg.className = "pc-msg ok";
+      msg.textContent = (p.action && p.action.successLabel) ||
+        (res && res.processInstanceKey != null ? "Started (instance " + res.processInstanceKey + ")" : "Done");
       for (const input of inputs.values()) input.value = "";
       document.dispatchEvent(new CustomEvent("pc:refresh"));
     } catch (e) {
@@ -791,23 +828,9 @@ function renderDataGrid(node) {
   }
 
   async function fireAction(action, row) {
-    if (action.kind === "cancelProcess") {
-      return getJSON("/app/actions/cancel", { method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ processInstanceKey: row[action.keyField] }) });
-    }
-    if (action.kind === "publishMessage") {
-      return getJSON("/app/actions/message", { method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ name: action.message, correlationKey: row[action.correlationKeyField],
-          variables: { ...(action.variables || {}) } }) });
-    }
-    if (action.kind === "startProcess") {
-      return getJSON("/app/actions/start/" + encodeURIComponent(action.process), { method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ variables: { ...(action.variables || {}) } }) });
-    }
-    throw new Error("unknown action");
+    // Route-driven row action: POST the action's body template (default {})
+    // to its route path, with {{row.KEY}} tokens resolved from this row.
+    return runRoute(action, { row });
   }
 
   function rowActionButton(row, ra) {
@@ -842,11 +865,13 @@ function renderDataGrid(node) {
     btn.addEventListener("click", async () => {
       btn.disabled = true; msg.className = "pc-msg"; msg.textContent = "Sending…";
       try {
-        await getJSON("/app/actions/message", { method: "POST",
-          headers: { "content-type": "application/json" },
-          body: JSON.stringify({ name: f.action.message, correlationKey: row[f.action.correlationKeyField],
-            variables: { [f.inputKey]: input.value, ...(f.action.variables || {}) } }) });
-        msg.className = "pc-msg ok"; msg.textContent = "Sent";
+        // The textarea value is the form's single field (f.inputKey); route + body
+        // template come from f.action, e.g. { path: "/app/actions/message",
+        // body: { name, correlationKey: "{{row.pr_key}}", variables: "{{form}}" } }.
+        // Null-proto so an f.inputKey of "__proto__"/"constructor" can't mutate a prototype.
+        const form = Object.create(null); form[f.inputKey] = input.value;
+        await runRoute(f.action, { form, row });
+        msg.className = "pc-msg ok"; msg.textContent = (f.action && f.action.successLabel) || "Sent";
         document.dispatchEvent(new CustomEvent("pc:refresh"));
       } catch (e) {
         btn.disabled = false; msg.className = "pc-msg err"; msg.textContent = String(e.message || e);

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

@@ -95,7 +95,7 @@ export function mountSurfaces(ctx, app) {
         enabled.push(`actions(${actions.routes.length})`);
     }
     // The OpenAPI endpoint surface (ADR 0058) mounts AFTER actions (so an exact `actions[]` route
-    // still shadows an operation) and BEFORE the generic pages routes. It owns the `api.base`
+    // still shadows an operation) and BEFORE the generic pages routes. It owns the fixed `/app/api`
     // namespace via a regex dispatcher, so it only contributes routes when the app declares `api`.
     const api = mountApi(ctx, app);
     if (api.routes.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.32.2",
+  "version": "0.33.0",
   "description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
   "license": "Apache-2.0",
   "type": "module",
@@ -66,7 +66,7 @@
     "@nanobpm/nano-sdk": "^1.2.3",
     "@nanobpm/workflow": "^0.8.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2",
-    "create-urban-app": "^0.8.0"
+    "create-urban-app": "^0.9.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",

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

@@ -228,12 +228,13 @@ test("a malformed spec surfaces as a 500, not a boot failure", async () => {
   assert.match(JSON.parse(res.body!).error, /failed to load/);
 });
 
-test("a manifest api.base without a leading slash is normalized so routes still match", async () => {
+test("a leftover manifest api.base is ignored — operations always mount at the fixed /app/api", async () => {
   let got: Record<string, string> | undefined;
   const { router } = build(
-    { spec: "openapi.json", base: "app/api" }, // no leading slash
+    { spec: "openapi.json", base: "/somewhere/else" }, // base is no longer honoured
     { "/app/operations/getInvoice": { default: (i: { params: Record<string, string> }) => { got = i.params; return { body: { ok: true } }; } } },
   );
+  assert.equal((await router(req("GET", "/somewhere/else/invoices/42"))).status, 404);
   const res = await router(req("GET", "/app/api/invoices/42"));
   assert.equal(res.status, 200);
   assert.deepEqual(got, { id: "42" });
@@ -393,10 +394,10 @@ test("an op declaring no requestBody gets body:undefined at runtime (matches der
   assert.equal(seenBody, undefined);
 });
 
-test("readApiBinding trims whitespace on base/dir/spec so benign formatting can't break resolution", async () => {
+test("readApiBinding trims whitespace on dir/spec so benign formatting can't break resolution", async () => {
   let got: Record<string, string> | undefined;
   const { router, imported } = build(
-    { spec: "  openapi.json  ", base: "  app/api  ", dir: "  operations  " },
+    { spec: "  openapi.json  ", dir: "  operations  " },
     { "/app/operations/getInvoice": { default: (i: { params: Record<string, string> }) => { got = i.params; return { body: { ok: true } }; } } },
   );
   const res = await router(req("GET", "/app/api/invoices/42"));
@@ -515,7 +516,7 @@ test("a string docs overrides the UI route (and the spec route beneath it)", asy
 
 test("apiDocsPath resolves the UI route (and honours disable / override)", () => {
   assert.equal(apiDocsPath({ api: { spec: "openapi.json" } }), "/app/api-docs");
-  assert.equal(apiDocsPath({ api: { spec: "openapi.json", base: "/x" } }), "/x-docs");
+  assert.equal(apiDocsPath({ api: { spec: "openapi.json", base: "/x" } }), "/app/api-docs"); // base ignored
   assert.equal(apiDocsPath({ api: { spec: "openapi.json", docs: "/help" } }), "/help");
   assert.equal(apiDocsPath({ api: { spec: "openapi.json", docs: false } }), undefined);
   assert.equal(apiDocsPath({}), undefined);

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

@@ -2,7 +2,7 @@
 // instead of hand-rolled imperative handlers, an author declares `api: { spec }` in the manifest and
 // writes one delegate module per `operationId`. This runtime reads the SAME OpenAPI document the
 // toolkit deriver turns into types (via the shared `openapi/spec.ts`), mounts one dispatcher over the
-// `api.base` namespace, and for each request: parses → validates params/query/body against the spec →
+// fixed `/app/api` namespace, and for each request: parses → validates params/query/body against the spec →
 // 400 with a structured error → resolves + calls the operationId delegate (validated, typed input +
 // the injected AppApi, exactly like a worker/action handler) → serializes the result.
 //
@@ -38,15 +38,19 @@ import {
 export interface ApiBinding {
   spec: string;
   dir?: string;
-  base?: string;
   validateResponses?: "dev" | "always" | "never";
   eject?: boolean;
-  /** Human API docs (Swagger UI). `true`/omitted → on at `${base}-docs` (ADR 0058); `false` →
+  /** Human API docs (Swagger UI). `true`/omitted → on at `/app/api-docs` (ADR 0058); `false` →
    *  off; a string → a custom absolute route to mount the UI under. Spec-first apps get docs
    *  for free — the UI reads the SAME OpenAPI document the runtime routes + validates from. */
   docs?: boolean | string;
 }
 
+/** The canonical, non-configurable mount prefix for an app's OpenAPI operations. Operations always
+ *  live under `/app/api` so page actions, links, and any `callRoute` can name an operation path as a
+ *  stable framework constant (`/app/api/<op path>`) — there is no per-app `base` knob to drift. */
+const API_BASE = "/app/api";
+
 /** Pinned Swagger UI dist served from a CDN, so the docs UI adds zero bundle/runtime deps to an
  *  Urban app (matching the deps-free spirit of the rest of the surface — validators are standalone,
  *  ADR 0058 Consequences). Pinned (not `latest`) for reproducibility. */
@@ -152,7 +156,6 @@ function readApiBinding(manifest: unknown): ApiBinding | undefined {
   const spec = Reflect.get(raw, "spec");
   if (typeof spec !== "string" || spec.trim().length === 0) return undefined;
   const dir = Reflect.get(raw, "dir");
-  const base = Reflect.get(raw, "base");
   const validateResponses = Reflect.get(raw, "validateResponses");
   const eject = Reflect.get(raw, "eject");
   const docs = Reflect.get(raw, "docs");
@@ -160,7 +163,6 @@ function readApiBinding(manifest: unknown): ApiBinding | undefined {
   return {
     spec: spec.trim(),
     dir: typeof dir === "string" && dir.trim().length > 0 ? dir.trim() : undefined,
-    base: typeof base === "string" && base.trim().length > 0 ? base.trim() : undefined,
     validateResponses:
       validateResponses === "dev" || validateResponses === "always" || validateResponses === "never"
         ? validateResponses
@@ -172,18 +174,19 @@ function readApiBinding(manifest: unknown): ApiBinding | undefined {
   };
 }
 
-/** Resolve the api `base` + docs routing from a binding, in ONE place, so `mountApi` (which
- *  serves the docs) and `apiDocsPath` (which the pages surface links to) can never drift. */
+/** Resolve the api `base` + docs routing, in ONE place, so `mountApi` (which serves the docs) and
+ *  `apiDocsPath` (which the pages surface links to) can never drift. The operation base is the fixed
+ *  `/app/api` constant; only the docs route remains manifest-configurable. */
 function resolveApiRoutes(binding: ApiBinding): {
   base: string;
   docsEnabled: boolean;
   docsBase: string;
 } {
-  const base = normalizeRoutePath(binding.base, "/app/api");
+  const base = API_BASE;
   const docsEnabled = binding.docs !== false;
-  // Swagger UI at a SIBLING of the base (`${base}-docs`, e.g. /app/api-docs), never a subpath
-  // of it — so the docs routes can't collide with, or be shadowed by, the operation dispatcher
-  // that owns the `${base}/` prefix (a string `docs` overrides the whole route).
+  // Swagger UI at a SIBLING of the base (`/app/api-docs`), never a subpath of it — so the docs
+  // routes can't collide with, or be shadowed by, the operation dispatcher that owns the
+  // `${base}/` prefix (a string `docs` overrides the whole route).
   const docsBase = normalizeRoutePath(
     typeof binding.docs === "string" ? binding.docs : `${base}-docs`,
     `${base}-docs`,
@@ -239,15 +242,11 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
   const binding = readApiBinding(ctx.manifest);
   if (!binding) return { name: "api", routes: [], describe: () => ({ api: "disabled" }) };
 
-  // Normalize the manifest base the same way actions[] routes do (shared normalizeRoutePath):
-  // ensure a leading "/", strip trailing slashes, and fall back when empty — otherwise a base
-  // like "app/api" would never match request paths, which always start with "/".
-  //
-  // The api `base` and the docs routing are derived TOGETHER by the shared helper (ADR 0058) so
-  // this module (which serves the docs) and `apiDocsPath` (which links to them from the pages
-  // shell) stay in lockstep with a single normalization of `binding.base` — no second, drifting
-  // copy of that logic here. The spec JSON is served under the docs path so the operations
-  // namespace stays purely operations.
+  // The api `base` is the fixed `/app/api` constant; only the docs routing is derived here. Both
+  // come from the shared helper (ADR 0058) so this module (which serves the docs) and `apiDocsPath`
+  // (which links to them from the pages shell) stay in lockstep — no second, drifting copy of that
+  // logic here. The spec JSON is served under the docs path so the operations namespace stays
+  // purely operations.
   const { base, docsEnabled, docsBase } = resolveApiRoutes(binding);
   const dir = binding.dir ?? "operations";
   const surfaceEject = binding.eject === true;

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

@@ -161,22 +161,23 @@ test("the shell renders an API-docs badge only when an apiDocsPath is provided",
   assert.doesNotMatch(noBadge, /class="pc-apidocs"/);
 });
 
-test("renderActionForm supports a publishMessage action (message-started processes)", async () => {
+test("page actions are route-driven: the runtime ships a single callRoute dispatcher, no bespoke kinds", async () => {
   const res = await dispatch("GET", "/app/runtime.js");
   const js = res.body ?? "";
-  // The form submit branches on the action kind: publishMessage posts to the message endpoint,
-  // deriving the correlation key from the named form field; startProcess keeps its old path.
-  assert.match(js, /p\.action\.kind === "publishMessage"/);
-  assert.match(js, /variables\[p\.action\.correlationKeyField\]/);
-  assert.match(js, /"\/app\/actions\/message"/);
-  // The trimmed correlation key is written back as the variable, so the value a
-  // worker reads matches the key the message was correlated on.
-  assert.match(js, /variables\[p\.action\.correlationKeyField\] = correlationKey/);
-  // startProcess remains the default/back-compat branch.
-  assert.match(js, /"\/app\/actions\/start\/" \+ encodeURIComponent\(p\.action\.process\)/);
-  // A missing action is reported clearly instead of throwing on p.action.process.
-  assert.match(js, /if \(!p\.action \|\| !p\.action\.process\)/);
-  assert.match(js, /no action configured/);
+  // A single primitive resolves { path, method?, body? } and POSTs it — there is no per-kind
+  // branching. The template resolver splices {{form}} / {{row}} and {{form.KEY}} / {{row.KEY}}.
+  assert.match(js, /async function runRoute\(action, ctx\)/);
+  assert.match(js, /function resolveTemplate\(node, ctx\)/);
+  assert.match(js, /function lookupToken\(path, ctx\)/);
+  // The form default body is the { variables } envelope, so plain forms hit start operations
+  // without any per-form config; row/detail forms carry an explicit body template instead.
+  assert.match(js, /body = \{ variables: ctx\.form \}/);
+  // Path tokens are URL-encoded (real keys like owner/repo#123 must not break the path).
+  assert.match(js, /encodeURIComponent\(String\(v\)\)/);
+  // The removed bespoke action kinds no longer appear anywhere in the client runtime.
+  assert.doesNotMatch(js, /p\.action\.kind/);
+  assert.doesNotMatch(js, /correlationKeyField/);
+  assert.doesNotMatch(js, /action\.kind === "(startProcess|publishMessage|cancelProcess)"/);
 });
 
 test("the renderer bridges the console theme over postMessage", async () => {

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

@@ -14,6 +14,13 @@
 //   POST /app/actions/start/<process>               → engine.createInstance
 //   POST /app/actions/cancel                        → engine.cancelInstance
 //   POST /app/actions/message                       → engine.publishMessage
+//
+// Page actions are ROUTE-DRIVEN: an `actionForm`/rowAction/detail-form `action` is just
+// `{ path, method?, body?, successLabel? }`. The client POSTs the resolved body (default
+// `{ variables: <form> }`) to `path`, templating `{{form.KEY}}` / `{{row.KEY}}` (and the
+// whole-object `{{form}}` / `{{row}}`) tokens. There are NO bespoke action kinds — a form
+// reaches start/cancel/message above, an OpenAPI operation under /app/api, or any app route
+// uniformly by naming its path.
 
 import type { AppApi, RuntimeContext } from "../context.ts";
 import { errorMessage, isRecord } from "../guards.ts";
@@ -634,6 +641,59 @@ async function getJSON(url, opts) {
   return body;
 }
 
+// ── route-driven actions ────────────────────────────────────────────────
+// Every page action is a single primitive: POST (or any method) the resolved
+// body to an app route path. There are NO bespoke action kinds — a form/row
+// reaches process start, message publish, cancel, an OpenAPI operation, a
+// webhook, or any app route uniformly by naming its path. Path + body may
+// interpolate the current form fields and (for grid rows/detail forms) the row
+// via {{form.KEY}} / {{row.KEY}} tokens; the whole-string tokens {{form}} and
+// {{row}} splice the object itself (type-preserving), so a body of
+// "variables": "{{form}}" sends the form object as the variable map.
+function lookupToken(path, ctx) {
+  const segs = String(path).split(".");
+  const head = segs[0];
+  let base = head === "form" ? (ctx.form || {}) : head === "row" ? (ctx.row || {}) : undefined;
+  for (let i = 1; i < segs.length; i++) base = base == null ? undefined : base[segs[i]];
+  return base;
+}
+function resolveTemplate(node, ctx) {
+  if (typeof node === "string") {
+    const whole = node.match(/^\{\{\s*([\w.]+)\s*\}\}$/);
+    if (whole) return lookupToken(whole[1], ctx);
+    return node.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, k) => {
+      const v = lookupToken(k, ctx);
+      return v == null ? "" : String(v);
+    });
+  }
+  if (Array.isArray(node)) return node.map((n) => resolveTemplate(n, ctx));
+  if (node && typeof node === "object") {
+    // Null-proto target so a template key like "__proto__" can't trigger prototype
+    // mutation (prototype-pollution class) when copied into the resolved object.
+    const out = Object.create(null);
+    for (const [k, v] of Object.entries(node)) out[k] = resolveTemplate(v, ctx);
+    return out;
+  }
+  return node;
+}
+async function runRoute(action, ctx) {
+  if (!action || typeof action.path !== "string" || action.path === "") {
+    throw new Error("This action has no route configured (action.path is missing or blank)");
+  }
+  const path = action.path.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, k) => {
+    const v = lookupToken(k, ctx);
+    return v == null ? "" : encodeURIComponent(String(v));
+  });
+  const method = String(action.method || "POST").toUpperCase();
+  let body;
+  if (action.body !== undefined) body = resolveTemplate(action.body, ctx);
+  else if (ctx.form) body = { variables: ctx.form };
+  else body = {};
+  const opts = { method, headers: { "content-type": "application/json" } };
+  if (method !== "GET" && method !== "HEAD") opts.body = JSON.stringify(body);
+  return getJSON(path, opts);
+}
+
 function el(tag, attrs = {}, ...kids) {
   const n = document.createElement(tag);
   for (const [k, v] of Object.entries(attrs)) {
@@ -734,37 +794,14 @@ function renderActionForm(node) {
     }
     btn.disabled = true; msg.className = "pc-msg"; msg.textContent = "Submitting…";
     try {
-      // Two action kinds: startProcess (default, back-compat) -> engine.createInstance; and
-      // publishMessage -> engine.publishMessage, which correlates a message to a message start
-      // (or intermediate catch) event. correlationKeyField names the form field that carries
-      // the correlation key; the whole form becomes the message variables.
-      if (p.action && p.action.kind === "publishMessage") {
-        const correlationKey = String(variables[p.action.correlationKeyField] ?? "").trim();
-        if (!correlationKey) {
-          msg.className = "pc-msg err";
-          msg.textContent = "Field '" + p.action.correlationKeyField + "' is required";
-          return;
-        }
-        // Send the trimmed key back as the variable too, so the value a worker
-        // reads matches the key the message was correlated on (no leading/trailing
-        // whitespace divergence between correlationKey and variables[field]).
-        variables[p.action.correlationKeyField] = correlationKey;
-        await getJSON("/app/actions/message", { method: "POST",
-          headers: { "content-type": "application/json" },
-          body: JSON.stringify({ name: p.action.message, correlationKey, variables }) });
-        msg.className = "pc-msg ok";
-        msg.textContent = "Message published";
-      } else {
-        if (!p.action || !p.action.process) {
-          msg.className = "pc-msg err";
-          msg.textContent = "This form has no action configured";
-          return;
-        }
-        const res = await getJSON("/app/actions/start/" + encodeURIComponent(p.action.process),
-          { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ variables }) });
-        msg.className = "pc-msg ok";
-        msg.textContent = "Started (instance " + (res.processInstanceKey ?? "?") + ")";
-      }
+      // Route-driven: POST the form (as { variables } by default, or the action's
+      // own body template) to the action's route path. correlationKey / process /
+      // message are expressed by the path + body template the page author supplies,
+      // e.g. { path: "/app/actions/message", body: { name, correlationKey, variables: "{{form}}" } }.
+      const res = await runRoute(p.action, { form: variables });
+      msg.className = "pc-msg ok";
+      msg.textContent = (p.action && p.action.successLabel) ||
+        (res && res.processInstanceKey != null ? "Started (instance " + res.processInstanceKey + ")" : "Done");
       for (const input of inputs.values()) input.value = "";
       document.dispatchEvent(new CustomEvent("pc:refresh"));
     } catch (e) {
@@ -839,23 +876,9 @@ function renderDataGrid(node) {
   }
 
   async function fireAction(action, row) {
-    if (action.kind === "cancelProcess") {
-      return getJSON("/app/actions/cancel", { method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ processInstanceKey: row[action.keyField] }) });
-    }
-    if (action.kind === "publishMessage") {
-      return getJSON("/app/actions/message", { method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ name: action.message, correlationKey: row[action.correlationKeyField],
-          variables: { ...(action.variables || {}) } }) });
-    }
-    if (action.kind === "startProcess") {
-      return getJSON("/app/actions/start/" + encodeURIComponent(action.process), { method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ variables: { ...(action.variables || {}) } }) });
-    }
-    throw new Error("unknown action");
+    // Route-driven row action: POST the action's body template (default {})
+    // to its route path, with {{row.KEY}} tokens resolved from this row.
+    return runRoute(action, { row });
   }
 
   function rowActionButton(row, ra) {
@@ -890,11 +913,13 @@ function renderDataGrid(node) {
     btn.addEventListener("click", async () => {
       btn.disabled = true; msg.className = "pc-msg"; msg.textContent = "Sending…";
       try {
-        await getJSON("/app/actions/message", { method: "POST",
-          headers: { "content-type": "application/json" },
-          body: JSON.stringify({ name: f.action.message, correlationKey: row[f.action.correlationKeyField],
-            variables: { [f.inputKey]: input.value, ...(f.action.variables || {}) } }) });
-        msg.className = "pc-msg ok"; msg.textContent = "Sent";
+        // The textarea value is the form's single field (f.inputKey); route + body
+        // template come from f.action, e.g. { path: "/app/actions/message",
+        // body: { name, correlationKey: "{{row.pr_key}}", variables: "{{form}}" } }.
+        // Null-proto so an f.inputKey of "__proto__"/"constructor" can't mutate a prototype.
+        const form = Object.create(null); form[f.inputKey] = input.value;
+        await runRoute(f.action, { form, row });
+        msg.className = "pc-msg ok"; msg.textContent = (f.action && f.action.successLabel) || "Sent";
         document.dispatchEvent(new CustomEvent("pc:refresh"));
       } catch (e) {
         btn.disabled = false; msg.className = "pc-msg err"; msg.textContent = String(e.message || e);

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

@@ -111,7 +111,7 @@ export function mountSurfaces(ctx: RuntimeContext, app: AppApi): SurfacesHandle
   }
 
   // The OpenAPI endpoint surface (ADR 0058) mounts AFTER actions (so an exact `actions[]` route
-  // still shadows an operation) and BEFORE the generic pages routes. It owns the `api.base`
+  // still shadows an operation) and BEFORE the generic pages routes. It owns the fixed `/app/api`
   // namespace via a regex dispatcher, so it only contributes routes when the app declares `api`.
   const api = mountApi(ctx, app);
   if (api.routes.length > 0) {