@nanobpm/urban 0.6.0 → 0.8.0

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

@@ -5,6 +5,8 @@
 
 import type { AppApi, RuntimeContext } from "../context.ts";
 import { html, json, normalizeRoutePath, type Route } from "../router.ts";
+import { mountActions } from "./actions.ts";
+import { mountPages } from "./pages.ts";
 
 /** Escape HTML-significant characters before embedding a value in markup. */
 function escapeHtml(s: string): string {
@@ -98,6 +100,22 @@ export function mountSurfaces(ctx: RuntimeContext, app: AppApi): SurfacesHandle
     });
   }
 
+  // App-authored action overrides mount BEFORE the generic pages routes so an exact
+  // override (e.g. /app/actions/cancel) shadows the generic action; the router is
+  // first-match-wins.
+  const actions = mountActions(ctx, app);
+  if (actions.routes.length > 0) {
+    routes.push(...actions.routes);
+    enabled.push(`actions(${actions.routes.length})`);
+  }
+
+  // The pages surface (the schema-driven page runtime) mounts its own routes.
+  const pages = mountPages(ctx, app);
+  if (pages.routes.length > 0) {
+    routes.push(...pages.routes);
+    enabled.push("pages@/");
+  }
+
   ctx.host.log("info", "surfaces mounted", { enabled });
   return { name: "surfaces", routes, describe: () => ({ enabled }) };
 }

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

@@ -18,6 +18,7 @@ class FakeEngine implements EngineClient {
   deployed = 0;
   workers = new Map<string, JobHandler>();
   messages: { name: string; correlationKey?: string; variables?: Record<string, unknown> }[] = [];
+  canceledInstances: string[] = [];
   completedTasks: { key: string; variables?: Record<string, unknown> }[] = [];
   userTasks = [{ userTaskKey: "ut-1", elementId: "approve", variables: {} }];
 
@@ -28,6 +29,9 @@ class FakeEngine implements EngineClient {
   async createInstance() {
     return { processInstanceKey: "pi-1" };
   }
+  async cancelInstance(input: { processInstanceKey: string }) {
+    this.canceledInstances.push(input.processInstanceKey);
+  }
   async publishMessage(input: { name: string; correlationKey?: string; variables?: Record<string, unknown> }) {
     this.messages.push(input);
   }

package/src/runtime/core/validate.test.ts

@@ -29,6 +29,14 @@ test("unknown top-level keys are rejected (additionalProperties:false)", () => {
   assert.ok(issues.some((i) => i.path === "bogus"));
 });
 
+test("an `actions` array is an accepted top-level key (ADR 0055 §3)", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    actions: [{ path: "/app/actions/cancel", module: "actions/cancel.ts" }],
+  });
+  assert.deepEqual(issues, []);
+});
+
 test("bad schemaVersion and bad slug id are reported", () => {
   const issues = collectManifestIssues({ ...valid, schemaVersion: 2, id: "Not A Slug" });
   assert.ok(issues.some((i) => i.path === "schemaVersion"));

package/src/runtime/engine/nanosdk.test.ts

@@ -53,6 +53,10 @@ function fakeSdkClient(overrides: Partial<NanoSdkClient> = {}): NanoSdkClient &
       calls.push("createProcessInstance");
       return { processInstanceKey: 99, variables: input.variables };
     },
+    async cancelProcessInstance(input) {
+      calls.push("cancelProcessInstance");
+      return { ...input };
+    },
     async publishMessage(input) {
       calls.push("publishMessage");
       return { key: 1, ...input };
@@ -131,6 +135,20 @@ test("createInstance throws when the SDK response omits the instance key", async
   );
 });
 
+test("cancelInstance routes through the SDK", async () => {
+  let seen: { processInstanceKey: string | number } | undefined;
+  const client = fakeSdkClient({
+    cancelProcessInstance: async (input) => {
+      seen = input;
+      return {};
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  await engine.cancelInstance({ processInstanceKey: "pi-7" });
+  assert.deepEqual(seen, { processInstanceKey: "pi-7" });
+  assert.ok(client.calls.includes("cancelProcessInstance") || seen !== undefined);
+});
+
 test("publishMessage defaults correlationKey/variables", async () => {
   let seen: Record<string, unknown> | undefined;
   const client = fakeSdkClient({

package/src/runtime/engine/nanosdk.ts

@@ -79,6 +79,10 @@ export interface NanoSdkClient {
     },
     options?: unknown,
   ): Promise<Record<string, unknown>>;
+  cancelProcessInstance(
+    input: { processInstanceKey: string | number },
+    options?: unknown,
+  ): Promise<unknown>;
   publishMessage(
     input: { name: string; correlationKey?: string; variables?: Record<string, unknown> },
     options?: unknown,
@@ -150,6 +154,10 @@ export class SdkEngineClient implements EngineClient {
     };
   }
 
+  async cancelInstance(input: { processInstanceKey: string }): Promise<void> {
+    await this.client.cancelProcessInstance({ processInstanceKey: input.processInstanceKey });
+  }
+
   async publishMessage(input: {
     name: string;
     correlationKey?: string;

package/src/runtime/index.ts

@@ -17,6 +17,7 @@ export {
   workerJobType,
 } from "./core/manifest.ts";
 export type {
+  ActionDecl,
   AppManifest,
   DataSource,
   DomainType,
@@ -61,6 +62,10 @@ export type {
   Row,
   TableMeta,
 } from "./core/modules/gateway.ts";
+export { createPagesRoutes, mountPages } from "./core/modules/pages.ts";
+export type { PagesDataSource, PagesDeps, PagesHandle, PagesOptions } from "./core/modules/pages.ts";
+export { mountActions, resolveActionHandler } from "./core/modules/actions.ts";
+export type { ActionHandler, ActionRequest, ActionResult, ActionsHandle } from "./core/modules/actions.ts";
 export type { AppJobHandler } from "./core/modules/workers.ts";
 export { resolveHandler } from "./core/modules/workers.ts";
 export { evalCorrelation } from "./core/modules/triggers.ts";

package/src/runtime/schema/nano-app.schema.json

@@ -52,6 +52,11 @@
       "additionalProperties": { "$ref": "#/$defs/connection" }
     },
     "surfaces": { "$ref": "#/$defs/surfaces" },
+    "actions": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/action" },
+      "description": "App-authored action handler overrides (ADR 0055 §3): each binds an HTTP route to a handler module that wraps the generic pages start/cancel/message actions with business logic, injected with the app's runtime API."
+    },
     "workers": {
       "type": "array",
       "items": { "$ref": "#/$defs/worker" },
@@ -367,6 +372,33 @@
         }
       }
     },
+    "action": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "module"],
+      "description": "An app-authored action handler override (ADR 0055 §3): binds a route to a handler module (default-exports an ActionHandler). Mounted before the generic pages action routes, so an exact override shadows the generic one.",
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Route path to serve, e.g. '/app/actions/cancel' or '/app/actions/start/convergence-loop'."
+        },
+        "module": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Handler module path relative to the app root; default-exports (or names `handler`) an ActionHandler."
+        },
+        "method": {
+          "type": "string",
+          "minLength": 1,
+          "description": "HTTP method to match. Default 'POST'."
+        },
+        "prefix": {
+          "type": "boolean",
+          "description": "Match `path` as a prefix rather than exactly. Default false."
+        }
+      }
+    },
     "llmBinding": {
       "type": "object",
       "additionalProperties": false,