@nanobpm/urban 0.6.0 → 0.7.0

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

@@ -3,6 +3,7 @@
 // linked `.form` and posts completion back. The `chat` surface is stubbed as a mount point
 // (LLM wiring is a separate concern). Surfaces contribute routes to the shared server.
 import { html, json, normalizeRoutePath } from "../router.js";
+import { mountPages } from "./pages.js";
 /** Escape HTML-significant characters before embedding a value in markup. */
 function escapeHtml(s) {
     return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
@@ -83,6 +84,12 @@ export function mountSurfaces(ctx, app) {
 <p>Chat surface mount point (agent: <code>${escapeHtml(chat.agent ?? "?")}</code>). LLM wiring pending.</p>`),
         });
     }
+    // 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/dist/runtime/engine/nanosdk.d.ts

@@ -53,6 +53,9 @@ export interface NanoSdkClient {
         variables?: Record<string, unknown>;
         awaitCompletion?: boolean;
     }, options?: unknown): Promise<Record<string, unknown>>;
+    cancelProcessInstance(input: {
+        processInstanceKey: string | number;
+    }, options?: unknown): Promise<unknown>;
     publishMessage(input: {
         name: string;
         correlationKey?: string;
@@ -101,6 +104,9 @@ export declare class SdkEngineClient implements EngineClient {
         processInstanceKey: string;
         variables?: Record<string, unknown>;
     }>;
+    cancelInstance(input: {
+        processInstanceKey: string;
+    }): Promise<void>;
     publishMessage(input: {
         name: string;
         correlationKey?: string;

package/dist/runtime/engine/nanosdk.js

@@ -66,6 +66,9 @@ export class SdkEngineClient {
             variables: body.variables ?? undefined,
         };
     }
+    async cancelInstance(input) {
+        await this.client.cancelProcessInstance({ processInstanceKey: input.processInstanceKey });
+    }
     async publishMessage(input) {
         await this.client.publishMessage({
             name: input.name,

package/dist/runtime/index.d.ts

@@ -10,6 +10,8 @@ export { DataLayer, TypeRepo } from "./core/modules/datasource.ts";
 export type { ProvisionedSource } from "./core/modules/datasource.ts";
 export { makeGateway, Table } from "./core/modules/gateway.ts";
 export type { ColumnMeta, DataSource as GatewayDataSource, ExecResult, ForeignKeyMeta, 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 type { AppJobHandler } from "./core/modules/workers.ts";
 export { resolveHandler } from "./core/modules/workers.ts";
 export { evalCorrelation } from "./core/modules/triggers.ts";

package/dist/runtime/index.js

@@ -8,6 +8,7 @@ export { collectManifestIssues, ManifestValidationError, validateManifest, } fro
 // Data layer
 export { DataLayer, TypeRepo } from "./core/modules/datasource.js";
 export { makeGateway, Table } from "./core/modules/gateway.js";
+export { createPagesRoutes, mountPages } from "./core/modules/pages.js";
 export { resolveHandler } from "./core/modules/workers.js";
 export { evalCorrelation } from "./core/modules/triggers.js";
 // Adapters + engine + run entrypoint

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.6.0",
+  "version": "0.7.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",

package/src/runtime/core/host.ts

@@ -105,6 +105,8 @@ export interface EngineClient {
     variables?: Record<string, unknown>;
     awaitCompletion?: boolean;
   }): Promise<{ 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/src/runtime/core/manifest.ts

@@ -44,6 +44,14 @@ 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;
 }
 
 export interface AppManifest {

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

@@ -68,7 +68,8 @@ export interface DataSource {
   table<T extends object = Row>(name: string, pk?: string): Table<T>;
 }
 
-function quoteIdent(name: string): string {
+/** Double-quote a SQL identifier (table/column), escaping embedded quotes. */
+export function quoteIdent(name: string): string {
   return `"${name.replaceAll('"', '""')}"`;
 }
 

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

@@ -0,0 +1,224 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import type { EngineClient, HttpRequest, HttpResponse } from "../host.ts";
+import { makeRouter } from "../router.ts";
+import { createPagesRoutes, type PagesDataSource } from "./pages.ts";
+
+function req(
+  method: string,
+  path: string,
+  opts: { query?: string; body?: unknown } = {},
+): HttpRequest {
+  const bodyText = opts.body === undefined ? "" : JSON.stringify(opts.body);
+  return {
+    method,
+    path,
+    query: new URLSearchParams(opts.query ?? ""),
+    headers: new Headers(),
+    text: () => Promise.resolve(bodyText),
+  };
+}
+
+interface FakeEngineCalls {
+  created: { processDefinitionId: string; variables?: Record<string, unknown> }[];
+  canceled: string[];
+  messages: { name: string; correlationKey?: string; variables?: Record<string, unknown> }[];
+}
+
+function fakeEngine(): { engine: EngineClient; calls: FakeEngineCalls } {
+  const calls: FakeEngineCalls = { created: [], canceled: [], messages: [] };
+  const engine = {
+    async createInstance(input: { processDefinitionId: string; variables?: Record<string, unknown> }) {
+      calls.created.push(input);
+      return { processInstanceKey: "pi-42" };
+    },
+    async cancelInstance(input: { processInstanceKey: string }) {
+      calls.canceled.push(input.processInstanceKey);
+    },
+    async publishMessage(input: { name: string; correlationKey?: string; variables?: Record<string, unknown> }) {
+      calls.messages.push(input);
+    },
+  } as unknown as EngineClient;
+  return { engine, calls };
+}
+
+function fakeDb(overrides: Partial<PagesDataSource> = {}): PagesDataSource {
+  return {
+    schema: async () => [{ name: "orders" }],
+    query: async (sql: string) => {
+      if (/PRAGMA table_info/i.test(sql)) {
+        return [{ name: "id" }, { name: "status" }, { name: "total" }];
+      }
+      return [{ id: 1, status: "new", total: 10 }];
+    },
+    ...overrides,
+  };
+}
+
+function build(dbOverrides: Partial<PagesDataSource> = {}) {
+  const { engine, calls } = fakeEngine();
+  const db = fakeDb(dbOverrides);
+  const readPage = async (path: string) => {
+    if (path === "pages/home.page.json") return JSON.stringify({ title: "Home", nodes: [] });
+    throw new Error("not found");
+  };
+  const routes = createPagesRoutes({ pagesDir: "pages", homePage: "home", sourceName: "app" }, {
+    db,
+    engine,
+    readPage,
+  });
+  const router = makeRouter(routes);
+  return { router, calls };
+}
+
+async function dispatch(method: string, path: string, opts?: { query?: string; body?: unknown }): Promise<HttpResponse> {
+  const { router } = build();
+  return router(req(method, path, opts));
+}
+
+test("GET / serves the renderer shell with the home marker", async () => {
+  const res = await dispatch("GET", "/");
+  assert.equal(res.status, 200);
+  assert.match(res.headers?.["content-type"] ?? "", /text\/html/);
+  assert.match(res.body ?? "", /data-home="home"/);
+});
+
+test("GET /app/runtime.js serves the renderer module", async () => {
+  const res = await dispatch("GET", "/app/runtime.js");
+  assert.match(res.headers?.["content-type"] ?? "", /javascript/);
+  assert.match(res.body ?? "", /pc:refresh/);
+});
+
+test("GET /app/pages/<id> returns the page json, 404 for unknown", async () => {
+  const ok = await dispatch("GET", "/app/pages/home");
+  assert.equal(ok.status, 200);
+  assert.deepEqual(JSON.parse(ok.body ?? "{}").title, "Home");
+  const miss = await dispatch("GET", "/app/pages/nope");
+  assert.equal(miss.status, 404);
+});
+
+test("GET /app/data/<source>/<table> returns rows", async () => {
+  const res = await dispatch("GET", "/app/data/app/orders");
+  assert.equal(res.status, 200);
+  const body = JSON.parse(res.body ?? "{}");
+  assert.equal(body.rows.length, 1);
+  assert.equal(body.rows[0].status, "new");
+});
+
+test("GET /app/data rejects unknown source, invalid + unknown table", async () => {
+  assert.equal((await dispatch("GET", "/app/data/other/orders")).status, 404);
+  const { router } = build();
+  const unknownTable = await router(req("GET", "/app/data/app/customers"));
+  assert.equal(unknownTable.status, 404);
+});
+
+test("GET /app/data whitelists filter columns", async () => {
+  const { router } = build();
+  const good = await router(req("GET", "/app/data/app/orders", { query: "where=status:new" }));
+  assert.equal(good.status, 200);
+  const bad = await router(req("GET", "/app/data/app/orders", { query: "where=evil:1" }));
+  assert.equal(bad.status, 400);
+});
+
+test("POST /app/actions/start/<process> creates an instance", async () => {
+  const { router, calls } = build();
+  const res = await router(req("POST", "/app/actions/start/my-proc", { body: { variables: { a: 1 } } }));
+  assert.equal(res.status, 200);
+  assert.equal(JSON.parse(res.body ?? "{}").processInstanceKey, "pi-42");
+  assert.equal(calls.created.length, 1);
+  assert.equal(calls.created[0].processDefinitionId, "my-proc");
+  assert.deepEqual(calls.created[0].variables, { a: 1 });
+});
+
+test("POST /app/actions/cancel cancels, 400 without a key", async () => {
+  const { router, calls } = build();
+  const ok = await router(req("POST", "/app/actions/cancel", { body: { processInstanceKey: "pi-9" } }));
+  assert.equal(ok.status, 200);
+  assert.deepEqual(calls.canceled, ["pi-9"]);
+  const bad = await router(req("POST", "/app/actions/cancel", { body: {} }));
+  assert.equal(bad.status, 400);
+});
+
+test("POST /app/actions/message publishes, 400 on missing fields", async () => {
+  const { router, calls } = build();
+  const ok = await router(req("POST", "/app/actions/message", {
+    body: { name: "answered", correlationKey: "k1", variables: { answer: "yes" } },
+  }));
+  assert.equal(ok.status, 200);
+  assert.equal(calls.messages.length, 1);
+  assert.equal(calls.messages[0].name, "answered");
+  const noName = await router(req("POST", "/app/actions/message", { body: { correlationKey: "k" } }));
+  assert.equal(noName.status, 400);
+  const noKey = await router(req("POST", "/app/actions/message", { body: { name: "m" } }));
+  assert.equal(noKey.status, 400);
+});
+
+test("GET /app/data quotes table/column identifiers in the emitted SQL", async () => {
+  const seen: string[] = [];
+  const db = fakeDb({
+    query: async (sql: string) => {
+      seen.push(sql);
+      if (/PRAGMA table_info/i.test(sql)) {
+        return [{ name: "id" }, { name: "status" }, { name: "total" }];
+      }
+      return [{ id: 1 }];
+    },
+  });
+  const routes = createPagesRoutes({ pagesDir: "pages", homePage: "home", sourceName: "app" }, {
+    db,
+    engine: fakeEngine().engine,
+    readPage: async () => "{}",
+  });
+  const router = makeRouter(routes);
+  const res = await router(req("GET", "/app/data/app/orders", {
+    query: "where=status:new&order=total:desc",
+  }));
+  assert.equal(res.status, 200);
+  const pragma = seen.find((s) => /PRAGMA table_info/i.test(s))!;
+  assert.match(pragma, /table_info\("orders"\)/);
+  const select = seen.find((s) => /^SELECT/.test(s))!;
+  assert.match(select, /FROM "orders"/);
+  assert.match(select, /WHERE "status" = \?/);
+  assert.match(select, /ORDER BY "total" DESC/);
+});
+
+test("GET /app/data returns a structured 500 when the SELECT query throws", async () => {
+  const db = fakeDb({
+    query: async (sql: string) => {
+      if (/PRAGMA table_info/i.test(sql)) return [{ name: "id" }, { name: "status" }];
+      throw new Error("disk gone");
+    },
+  });
+  const routes = createPagesRoutes({ pagesDir: "pages", homePage: "home", sourceName: "app" }, {
+    db,
+    engine: fakeEngine().engine,
+    readPage: async () => "{}",
+  });
+  const res = await makeRouter(routes)(req("GET", "/app/data/app/orders"));
+  assert.equal(res.status, 500);
+  assert.match(JSON.parse(res.body ?? "{}").error, /disk gone/);
+});
+
+test("rowLimit respects an explicit 0 and falls back for non-finite values", async () => {
+  const limits: string[] = [];
+  const mkDb = () => fakeDb({
+    query: async (sql: string) => {
+      if (/PRAGMA table_info/i.test(sql)) return [{ name: "id" }];
+      const m = sql.match(/LIMIT (\S+)/);
+      if (m) limits.push(m[1]);
+      return [];
+    },
+  });
+  const run = async (rowLimit: number | undefined) => {
+    const routes = createPagesRoutes({ pagesDir: "p", homePage: "h", sourceName: "app", rowLimit }, {
+      db: mkDb(),
+      engine: fakeEngine().engine,
+      readPage: async () => "{}",
+    });
+    return makeRouter(routes)(req("GET", "/app/data/app/orders"));
+  };
+  await run(0);
+  await run(Infinity);
+  await run(undefined);
+  assert.deepEqual(limits, ["0", "200", "200"]);
+});