@nanobpm/urban 0.6.0 → 0.8.0

package/dist/runtime/core/host.d.ts

@@ -99,6 +99,10 @@ export interface EngineClient {
         processInstanceKey: string;
         variables?: Record<string, unknown>;
     }>;
+    /** Cancel a running process instance (the pages surface's row-cancel action). */
+    cancelInstance(input: {
+        processInstanceKey: string;
+    }): Promise<void>;
     /** Publish a message for correlation. */
     publishMessage(input: {
         name: string;

package/dist/runtime/core/manifest.d.ts

@@ -36,6 +36,30 @@ export interface SurfaceDecl {
     enabled?: boolean;
     path?: string;
     agent?: string;
+    /** pages surface: directory of `*.page.json` (relative to app root). Default `pages`. */
+    pagesDir?: string;
+    /** pages surface: the page served at `/`. Default `home`. */
+    homePage?: string;
+    /** pages surface: max rows a `dataGrid` fetch returns. Default 200. */
+    rowLimit?: number;
+    /** pages surface: the injected default datasource name. Default `app`. */
+    sourceName?: string;
+}
+/**
+ * An app-authored action handler override (ADR 0055 phase 3). Each declaration binds a
+ * route to a handler module (default-exports an `ActionHandler`), letting an app wrap the
+ * generic pages start/cancel/message actions with business logic. Mounted before the
+ * generic pages action routes, so an exact override shadows the generic one.
+ */
+export interface ActionDecl {
+    /** Route path to serve, e.g. "/app/actions/cancel" or "/app/actions/start/convergence-loop". */
+    path: string;
+    /** Handler module path relative to the app root; default-exports an `ActionHandler`. */
+    module: string;
+    /** HTTP method to match. Default "POST". */
+    method?: string;
+    /** Match `path` as a prefix rather than exactly. Default false. */
+    prefix?: boolean;
 }
 export interface AppManifest {
     $schema?: string;
@@ -63,6 +87,7 @@ export interface AppManifest {
         [k: string]: unknown;
     }>;
     surfaces?: Record<string, SurfaceDecl>;
+    actions?: ActionDecl[];
     workers?: WorkerDecl[];
     llm?: Record<string, unknown>;
     security?: Record<string, unknown>;

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

@@ -0,0 +1,45 @@
+import type { AppApi, RuntimeContext } from "../context.ts";
+import type { HttpRequest } from "../host.ts";
+import { type Route } from "../router.ts";
+/** The request handed to an action handler: the raw request plus its parsed JSON body. */
+export interface ActionRequest {
+    /** The raw HTTP request (method, path, query, headers). */
+    req: HttpRequest;
+    /**
+     * The request body parsed as JSON (`{}` when the body is empty). A body that is present
+     * but not valid JSON is rejected with `400` before the handler runs.
+     */
+    body: unknown;
+}
+/** What an action handler returns; the runtime serializes `body` as JSON. */
+export interface ActionResult {
+    /** HTTP status. Default `200`, or `204` when the handler returns nothing. */
+    status?: number;
+    /** Response payload, serialized as JSON. Omit for an empty response. */
+    body?: unknown;
+    /** Response headers merged over `content-type: application/json`. */
+    headers?: Record<string, string>;
+}
+/**
+ * An app-authored action handler: the parsed request plus the injected app API. Return an
+ * {@link ActionResult}, or nothing for an empty `204`. Throwing yields a `500` with the
+ * error message.
+ */
+export type ActionHandler = (input: ActionRequest, app: AppApi) => Promise<ActionResult | void> | ActionResult | void;
+/**
+ * Resolve an action handler from a loaded module, in priority order:
+ *   1. `default` (when it is a function — the common one-handler-per-file case)
+ *   2. a named export `handler`
+ */
+export declare function resolveActionHandler(mod: Record<string, unknown>): ActionHandler | undefined;
+export interface ActionsHandle {
+    readonly name: string;
+    routes: Route[];
+    describe(): Record<string, unknown>;
+}
+/**
+ * Mount the declared action handlers. Each declaration contributes one route; the handler
+ * module is imported lazily (and cached) on first request, so a missing or malformed module
+ * surfaces as a clear `500` on that route rather than failing the whole boot.
+ */
+export declare function mountActions(ctx: RuntimeContext, app: AppApi): ActionsHandle;

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

@@ -0,0 +1,113 @@
+// actions — per-app action handler files (ADR 0055 phase 3). The pages surface serves
+// generic start/cancel/message actions; a real app usually needs to wrap those with
+// business logic (register a domain row before starting, reconcile app-owned rest state
+// on cancel, correlate a message to an aggregate). An app declares such overrides in the
+// manifest `actions[]` and authors a small module per action. Each module is injected with
+// the app's `AppApi` (typed datasource + engine + sdk + host utils) — the same contract as
+// a worker handler — so the handler code reads exactly like the app's own service layer.
+//
+// Precedence: action routes are mounted BEFORE the generic pages action routes (the router
+// is first-match-wins), so an override at `/app/actions/cancel` shadows the generic one,
+// while an unmatched process still falls through to the generic `/app/actions/start/` route.
+import { json, normalizeRoutePath } from "../router.js";
+/**
+ * Resolve an action handler from a loaded module, in priority order:
+ *   1. `default` (when it is a function — the common one-handler-per-file case)
+ *   2. a named export `handler`
+ */
+export function resolveActionHandler(mod) {
+    if (typeof mod.default === "function")
+        return mod.default;
+    if (typeof mod.handler === "function")
+        return mod.handler;
+    return undefined;
+}
+/**
+ * Mount the declared action handlers. Each declaration contributes one route; the handler
+ * module is imported lazily (and cached) on first request, so a missing or malformed module
+ * surfaces as a clear `500` on that route rather than failing the whole boot.
+ */
+export function mountActions(ctx, app) {
+    const decls = (ctx.manifest.actions ?? []);
+    const routes = [];
+    const mounted = [];
+    const joinRoot = (p) => p.startsWith("/") ? p : `${ctx.root.replace(/\/+$/, "")}/${p.replace(/^\/+/, "")}`;
+    // Cache module loads so a module reused across several declarations is imported once.
+    const moduleCache = new Map();
+    const loadModule = (path) => {
+        const key = joinRoot(path);
+        let pending = moduleCache.get(key);
+        if (!pending) {
+            // Evict the entry if the import rejects, so a transient failure doesn't
+            // permanently wedge the route (a cached rejected Promise would reject forever).
+            pending = ctx.host.importModule(key).catch((err) => {
+                moduleCache.delete(key);
+                throw err;
+            });
+            moduleCache.set(key, pending);
+        }
+        return pending;
+    };
+    for (const decl of decls) {
+        if (!decl?.path || !decl?.module) {
+            ctx.host.log("warn", "skipping action: needs both `path` and `module`", {
+                action: decl,
+            });
+            continue;
+        }
+        const method = (decl.method ?? "POST").trim().toUpperCase() || "POST";
+        const prefix = decl.prefix === true;
+        // The router's prefix match is a raw `startsWith`, so a prefix route needs a trailing
+        // slash to stay boundary-safe (otherwise "/hooks" would also match "/hooks2"). Exact
+        // routes keep the normalized (trailing-slash-stripped) path. Guard the root case so a
+        // prefix path of "/" doesn't become "//" (which would never match).
+        const base = normalizeRoutePath(decl.path, decl.path);
+        const path = prefix ? (base.endsWith("/") ? base : `${base}/`) : base;
+        routes.push({
+            method,
+            path,
+            prefix,
+            source: `actions:${decl.module}`,
+            handler: async (req) => {
+                const raw = await req.text();
+                let body;
+                try {
+                    body = raw ? JSON.parse(raw) : {};
+                }
+                catch {
+                    return json({ error: "request body must be JSON" }, 400);
+                }
+                let handler;
+                try {
+                    handler = resolveActionHandler(await loadModule(decl.module));
+                }
+                catch (e) {
+                    ctx.host.log("error", "action handler module failed to load", {
+                        path,
+                        module: decl.module,
+                        error: String(e?.message ?? e),
+                    });
+                    return json({ error: `action handler ${decl.module} failed to load` }, 500);
+                }
+                if (!handler) {
+                    return json({ error: `action handler ${decl.module} exports no default function or named \`handler\`` }, 500);
+                }
+                try {
+                    const result = await handler({ req, body }, app);
+                    if (!result)
+                        return { status: 204 };
+                    return {
+                        status: result.status ?? 200,
+                        headers: { "content-type": "application/json", ...(result.headers ?? {}) },
+                        body: result.body === undefined ? undefined : JSON.stringify(result.body),
+                    };
+                }
+                catch (e) {
+                    return json({ error: String(e?.message ?? e) }, 500);
+                }
+            },
+        });
+        mounted.push({ path, method, module: decl.module, prefix });
+    }
+    return { name: "actions", routes, describe: () => ({ actions: mounted }) };
+}

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

@@ -47,6 +47,8 @@ export interface DataSource {
      * (default "id"). */
     table<T extends object = Row>(name: string, pk?: string): Table<T>;
 }
+/** Double-quote a SQL identifier (table/column), escaping embedded quotes. */
+export declare function quoteIdent(name: string): string;
 /** A typed gateway over a single table — the record-oriented data object a handler binds to
  * instead of hand-writing SQL (the Delphi `TTable`/data-module idea, ADR 0029 §6). It builds
  * parameterised SQL from a typed row object's own keys, so callers manipulate rows as records.

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

@@ -11,7 +11,8 @@
 //   const orders = db.table<Order>("orders");   // a typed gateway over one table
 //   await orders.insert({ id, status: "new" });
 //   const o = await orders.get(id);
-function quoteIdent(name) {
+/** Double-quote a SQL identifier (table/column), escaping embedded quotes. */
+export function quoteIdent(name) {
     return `"${name.replaceAll('"', '""')}"`;
 }
 /** Build a parameterised ` WHERE a = ? AND b = ?` clause from an equality map; an empty map

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

@@ -0,0 +1,42 @@
+import type { AppApi, RuntimeContext } from "../context.ts";
+import type { EngineClient } from "../host.ts";
+import { type Route } from "../router.ts";
+/** The subset of the datasource gateway the page runtime needs. */
+export interface PagesDataSource {
+    query(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
+    schema(): Promise<{
+        name: string;
+    }[]>;
+}
+export interface PagesOptions {
+    /** Directory holding `*.page.json` (relative to the app root). Default `pages`. */
+    pagesDir?: string;
+    /** The page served at `/`. Default `home`. */
+    homePage?: string;
+    /** Max rows a `dataGrid` fetch returns. Default 200. */
+    rowLimit?: number;
+    /** The injected default datasource name (the alias apps bind to). Default `app`. */
+    sourceName?: string;
+}
+export interface PagesDeps {
+    db: PagesDataSource;
+    engine: EngineClient;
+    /** Read a page file; injectable for tests. */
+    readPage(path: string): Promise<string>;
+}
+/**
+ * Build the page-runtime routes over an injected datasource + engine. Pure over its deps
+ * so it is unit-testable without a real host/server (see pages.test.ts).
+ */
+export declare function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[];
+export interface PagesHandle {
+    readonly name: string;
+    routes: Route[];
+    describe(): Record<string, unknown>;
+}
+/**
+ * Mount the `pages` surface when enabled in the manifest. Binds the page runtime to the
+ * app's datasource gateway (`app.data.open(source)`), engine, and the host's file read.
+ * Returns no routes when the surface is disabled or absent.
+ */
+export declare function mountPages(ctx: RuntimeContext, app: AppApi): PagesHandle;