@nanobpm/urban 0.7.0 → 0.9.0

package/src/runtime/core/manifest.ts

@@ -32,6 +32,24 @@ export interface WorkerDecl {
   llm?: string;
 }
 
+/**
+ * One named LLM binding (`llm.<id>` in the manifest). A binding is usable as a worker
+ * (LLM-as-worker, ADR 0022 §E role 1) or as a chat surface agent. `provider` selects how
+ * the endpoint is resolved (`"env"` reads it from the environment); `model` is typically
+ * an env template. When `output.decision` is set, the model's JSON reply is fed through
+ * that DMN decision (the "rails") and the decision's output is returned instead.
+ */
+export interface LlmBinding {
+  /** Provider selector. `"env"` resolves an OpenAI-compatible endpoint from the environment. */
+  provider: string;
+  /** Model id, typically an env template (e.g. `${NANO_APP_LLM_MODEL}`). */
+  model: string;
+  /** Constrains the model's structured output — currently a DMN decision id (the rails). */
+  output?: { decision?: string };
+  /** Action-API tools the agent may call (chat-agent role; unused by the worker role). */
+  tools?: string[];
+}
+
 export interface TriggerDecl {
   id: string;
   type: string;
@@ -54,6 +72,23 @@ export interface SurfaceDecl {
   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;
   schemaVersion: 1;
@@ -67,8 +102,9 @@ export interface AppManifest {
   triggers?: TriggerDecl[];
   connections?: Record<string, { type: string; [k: string]: unknown }>;
   surfaces?: Record<string, SurfaceDecl>;
+  actions?: ActionDecl[];
   workers?: WorkerDecl[];
-  llm?: Record<string, unknown>;
+  llm?: Record<string, LlmBinding>;
   security?: Record<string, unknown>;
   [k: string]: unknown;
 }

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

@@ -0,0 +1,239 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import type { AppApi, RuntimeContext } from "../context.ts";
+import type { HttpRequest } from "../host.ts";
+import { makeRouter } from "../router.ts";
+import { mountActions, resolveActionHandler, type ActionHandler } from "./actions.ts";
+
+function req(method: string, path: string, opts: { query?: string; body?: string } = {}): HttpRequest {
+  return {
+    method,
+    path,
+    query: new URLSearchParams(opts.query ?? ""),
+    headers: new Headers(),
+    text: () => Promise.resolve(opts.body ?? ""),
+  };
+}
+
+interface Built {
+  router: (r: HttpRequest) => Promise<{ status?: number; body?: string }>;
+  imported: string[];
+  logs: Array<{ level: string; msg: string }>;
+}
+
+function build(
+  actions: RuntimeContext["manifest"]["actions"],
+  modules: Record<string, Record<string, unknown>>,
+  app: AppApi = {} as AppApi,
+): Built {
+  const imported: string[] = [];
+  const logs: Array<{ level: string; msg: string }> = [];
+  const ctx = {
+    root: "/app",
+    manifest: { schemaVersion: 1, id: "t", name: "T", actions } as RuntimeContext["manifest"],
+    host: {
+      importModule: (path: string) => {
+        imported.push(path);
+        const mod = modules[path];
+        if (!mod) return Promise.reject(new Error(`no module at ${path}`));
+        return Promise.resolve(mod);
+      },
+      log: (level: string, msg: string) => logs.push({ level, msg }),
+    },
+  } as unknown as RuntimeContext;
+  const handle = mountActions(ctx, app);
+  const router = makeRouter(handle.routes) as unknown as Built["router"];
+  return { router, imported, logs };
+}
+
+test("resolveActionHandler prefers default, then handler", () => {
+  const fn = () => ({});
+  assert.equal(resolveActionHandler({ default: fn }), fn);
+  assert.equal(resolveActionHandler({ handler: fn }), fn);
+  assert.equal(resolveActionHandler({ default: fn, handler: () => ({}) }), fn);
+  assert.equal(resolveActionHandler({ nope: fn }), undefined);
+});
+
+test("routes an action to its handler with parsed body + injected app", async () => {
+  const seen: unknown[] = [];
+  const app = { id: "myApp" } as unknown as AppApi;
+  const handler: ActionHandler = (input, a) => {
+    seen.push({ body: input.body, method: input.req.method, app: a });
+    return { status: 201, body: { ok: true } };
+  };
+  const { router } = build(
+    [{ path: "/app/actions/cancel", module: "actions/cancel.ts" }],
+    { "/app/actions/cancel.ts": { default: handler } },
+    app,
+  );
+  const res = await router(req("POST", "/app/actions/cancel", { body: JSON.stringify({ key: "k1" }) }));
+  assert.equal(res.status, 201);
+  assert.deepEqual(JSON.parse(res.body!), { ok: true });
+  assert.deepEqual(seen, [{ body: { key: "k1" }, method: "POST", app }]);
+});
+
+test("empty body parses to {} and a void return is 204", async () => {
+  const bodies: unknown[] = [];
+  const { router } = build(
+    [{ path: "/app/actions/ping", module: "m.ts" }],
+    { "/app/m.ts": { default: (i: { body: unknown }) => { bodies.push(i.body); } } },
+  );
+  const res = await router(req("POST", "/app/actions/ping"));
+  assert.equal(res.status, 204);
+  assert.equal(res.body, undefined);
+  assert.deepEqual(bodies, [{}]);
+});
+
+test("invalid JSON body is rejected with 400 before the handler runs", async () => {
+  let called = false;
+  const { router, imported } = build(
+    [{ path: "/a", module: "m.ts" }],
+    { "/app/m.ts": { default: () => { called = true; } } },
+  );
+  const res = await router(req("POST", "/a", { body: "{not json" }));
+  assert.equal(res.status, 400);
+  assert.match(res.body!, /must be JSON/);
+  assert.equal(called, false);
+  assert.deepEqual(imported, []); // module not even loaded
+});
+
+test("a thrown handler error becomes a 500 with the message", async () => {
+  const { router } = build(
+    [{ path: "/a", module: "m.ts" }],
+    { "/app/m.ts": { default: () => { throw new Error("boom"); } } },
+  );
+  const res = await router(req("POST", "/a", { body: "{}" }));
+  assert.equal(res.status, 500);
+  assert.match(res.body!, /boom/);
+});
+
+test("a module that fails to load yields a 500", async () => {
+  const { router, logs } = build([{ path: "/a", module: "missing.ts" }], {});
+  const res = await router(req("POST", "/a", { body: "{}" }));
+  assert.equal(res.status, 500);
+  assert.match(res.body!, /failed to load/);
+  assert.ok(logs.some((l) => l.level === "error"));
+});
+
+test("a module with no default/handler export yields a 500", async () => {
+  const { router } = build(
+    [{ path: "/a", module: "m.ts" }],
+    { "/app/m.ts": { notAHandler: () => ({}) } },
+  );
+  const res = await router(req("POST", "/a", { body: "{}" }));
+  assert.equal(res.status, 500);
+  assert.match(res.body!, /no default function/);
+});
+
+test("the module is imported once and cached across requests", async () => {
+  const { router, imported } = build(
+    [{ path: "/a", module: "m.ts" }],
+    { "/app/m.ts": { default: () => ({ body: 1 }) } },
+  );
+  await router(req("POST", "/a", { body: "{}" }));
+  await router(req("POST", "/a", { body: "{}" }));
+  assert.deepEqual(imported, ["/app/m.ts"]);
+});
+
+test("method defaults to POST; a GET does not match", async () => {
+  const { router } = build(
+    [{ path: "/a", module: "m.ts" }],
+    { "/app/m.ts": { default: () => ({ body: "ok" }) } },
+  );
+  const res = await router(req("GET", "/a"));
+  assert.equal(res.status, 404);
+});
+
+test("a custom method is honored", async () => {
+  const { router } = build(
+    [{ path: "/a", method: "PUT", module: "m.ts" }],
+    { "/app/m.ts": { default: () => ({ body: "ok" }) } },
+  );
+  assert.equal((await router(req("PUT", "/a", { body: "{}" }))).status, 200);
+  assert.equal((await router(req("POST", "/a", { body: "{}" }))).status, 404);
+});
+
+test("prefix routes match by path prefix and stay boundary-safe", async () => {
+  const { router } = build(
+    // declared without a trailing slash — the mount adds one so it can't over-match
+    [{ path: "/hooks", prefix: true, module: "m.ts" }],
+    { "/app/m.ts": { default: () => ({ body: "hooked" }) } },
+  );
+  const hit = await router(req("POST", "/hooks/github", { body: "{}" }));
+  assert.equal(hit.status, 200);
+  assert.equal(JSON.parse(hit.body!), "hooked");
+  // "/hooks2" must NOT match "/hooks" (raw startsWith would have over-matched)
+  assert.equal((await router(req("POST", "/hooks2", { body: "{}" }))).status, 404);
+});
+
+test("an absolute module path is used as-is (not joined to root)", async () => {
+  const { router, imported } = build(
+    [{ path: "/a", module: "/abs/m.ts" }],
+    { "/abs/m.ts": { default: () => ({ body: 1 }) } },
+  );
+  await router(req("POST", "/a", { body: "{}" }));
+  assert.deepEqual(imported, ["/abs/m.ts"]);
+});
+
+test("declarations missing path or module are skipped with a warning", () => {
+  const { router, logs } = build(
+    [{ path: "/a" } as unknown as { path: string; module: string }],
+    {},
+  );
+  void router;
+  assert.ok(logs.some((l) => l.level === "warn"));
+});
+
+test("a manifest path without a leading slash is normalized to match", async () => {
+  const { router } = build(
+    [{ path: "app/actions/go", module: "m.ts" }],
+    { "/app/m.ts": { default: () => ({ body: "ok" }) } },
+  );
+  const res = await router(req("POST", "/app/actions/go", { body: "{}" }));
+  assert.equal(res.status, 200);
+});
+
+test("a rejected import is evicted from the cache so a later load can succeed", async () => {
+  let attempt = 0;
+  const imported: string[] = [];
+  const ctx = {
+    root: "/app",
+    manifest: { schemaVersion: 1, id: "t", name: "T", actions: [{ path: "/a", module: "m.ts" }] },
+    host: {
+      importModule: (path: string) => {
+        imported.push(path);
+        attempt += 1;
+        if (attempt === 1) return Promise.reject(new Error("transient"));
+        return Promise.resolve({ default: () => ({ body: "ok" }) });
+      },
+      log: () => {},
+    },
+  } as unknown as import("../context.ts").RuntimeContext;
+  const router = makeRouter(mountActions(ctx, {} as import("../context.ts").AppApi).routes) as unknown as (
+    r: HttpRequest,
+  ) => Promise<{ status?: number; body?: string }>;
+  const first = await router(req("POST", "/a", { body: "{}" }));
+  assert.equal(first.status, 500); // transient failure surfaces
+  const second = await router(req("POST", "/a", { body: "{}" }));
+  assert.equal(second.status, 200); // retry re-imports and succeeds (cache was evicted)
+  assert.deepEqual(imported, ["/app/m.ts", "/app/m.ts"]);
+});
+
+test("a prefix route at the root path does not become //", async () => {
+  const { router } = build(
+    [{ path: "/", prefix: true, module: "m.ts" }],
+    { "/app/m.ts": { default: () => ({ body: "root" }) } },
+  );
+  const res = await router(req("POST", "/anything/at/all", { body: "{}" }));
+  assert.equal(res.status, 200);
+  assert.equal(JSON.parse(res.body!), "root");
+});
+
+test("method is trimmed and falls back to POST for whitespace", async () => {
+  const { router } = build(
+    [{ path: "/a", method: "  post  ", module: "m.ts" }, { path: "/b", method: "   ", module: "m.ts" }],
+    { "/app/m.ts": { default: () => ({ body: "ok" }) } },
+  );
+  assert.equal((await router(req("POST", "/a", { body: "{}" }))).status, 200);
+  assert.equal((await router(req("POST", "/b", { body: "{}" }))).status, 200);
+});

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

@@ -0,0 +1,161 @@
+// 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 type { AppApi, RuntimeContext } from "../context.ts";
+import type { HttpRequest } from "../host.ts";
+import type { ActionDecl } from "../manifest.ts";
+import { json, normalizeRoutePath, 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 function resolveActionHandler(mod: Record<string, unknown>): ActionHandler | undefined {
+  if (typeof mod.default === "function") return mod.default as ActionHandler;
+  if (typeof mod.handler === "function") return mod.handler as ActionHandler;
+  return 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 function mountActions(ctx: RuntimeContext, app: AppApi): ActionsHandle {
+  const decls = (ctx.manifest.actions ?? []) as ActionDecl[];
+  const routes: Route[] = [];
+  const mounted: Array<{ path: string; method: string; module: string; prefix: boolean }> = [];
+
+  const joinRoot = (p: string): string =>
+    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<string, Promise<Record<string, unknown>>>();
+  const loadModule = (path: string): Promise<Record<string, unknown>> => {
+    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 as unknown as Record<string, unknown>,
+      });
+      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: HttpRequest) => {
+        const raw = await req.text();
+        let body: unknown;
+        try {
+          body = raw ? JSON.parse(raw) : {};
+        } catch {
+          return json({ error: "request body must be JSON" }, 400);
+        }
+
+        let handler: ActionHandler | undefined;
+        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 as Error)?.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 as Error)?.message ?? e) }, 500);
+        }
+      },
+    });
+    mounted.push({ path, method, module: decl.module, prefix });
+  }
+
+  return { name: "actions", routes, describe: () => ({ actions: mounted }) };
+}