@nanobpm/urban 0.77.0 → 0.77.1

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

@@ -11,7 +11,8 @@
 //   GET  /              (+ /app/runtime.js)         → the schema-driven browser renderer
 //   GET  /app/pages/<id>                            → the page's page.json
 //   GET  /app/data/<source>/<table>[?where&order]   → rows (filtered/ordered, whitelisted)
-//   GET  /{embed,standalone}.html /mount.js /cockpit.css → appView sidecars (from pagesDir, #420)
+//   GET  /{embed,standalone}.html /mount.js /cockpit.css → flat appView sidecars (from pagesDir, #420)
+//   GET  /<subdir>/<asset>                          → nested appView sidecars (pages/<subdir>/…, #442)
 //   GET  /dist/<path>                               → the app dist/ bundle the sidecars reference
 //   POST /app/actions/start/<process>               → engine.createInstance
 //   POST /app/actions/cancel                        → engine.cancelInstance
@@ -45,7 +46,10 @@ function javascript(body, status = 200, extraHeaders) {
 // document then pulls `./cockpit.css`, `./mount.js`, and (via its import-map)
 // `../dist/…`. A DEPLOYED app served none of these, so the src 404'd and the cockpit
 // iframe loaded nothing (#416's user-facing "nothing shows in the Cockpit"). These are
-// the root-served sidecar files, mapped 1:1 onto `pagesDir/<name>`. The `dist/` tree the
+// the root-served sidecar files, mapped 1:1 onto `pagesDir/<name>`. An app that ships
+// MORE than one `appView` gives each its own SUBDIR sidecar (`./cockpit/embed.html`,
+// `./board/embed.html`, …) — those are served by the nested prefix route below (#442);
+// this flat set stays as the single-appView back-compat case (#420). The `dist/` tree the
 // import-map references is served separately under the `/dist/` prefix below.
 const SIDECAR_ASSETS = ["embed.html", "standalone.html", "mount.js", "cockpit.css"];
 // The app `dist/` directory (app-root sibling of the pages dir) the sidecar import-maps
@@ -485,6 +489,45 @@ export function createPagesRoutes(opts, deps) {
             }
         },
     });
+    // ── nested (multi-appView) sidecars (#442) ──────────────────────────────
+    // An app with more than one `appView` cannot share the four FLAT sidecar names above:
+    // each view ships its own SUBDIR sidecar — e.g. `pages/cockpit.page.json` →
+    // `./cockpit/embed.html`, `pages/board.page.json` → `./board/embed.html`. The renderer's
+    // `baseRelativeUrl(p.embed)` rebases those onto the mount root, so the browser fetches
+    // `/cockpit/embed.html`, `/board/mount.js`, … — every one of which #420's flat 4-name
+    // serve 404'd. Serve the `pagesDir` as a TREE, mapping `/<subpath>` onto
+    // `pagesDir/<subpath>` with the SAME traversal guard as the `/dist/` route (mirroring it).
+    // It is a `/`-prefix route, so to avoid a root catch-all silently swallowing `/healthz`,
+    // the app's own trigger routes, or any other route, the handler DECLINES (returns
+    // undefined → the router falls through to the next route, see `RouteHandler`) whenever it
+    // cannot serve a real nested asset:
+    //   • a bare single-segment path (`/healthz`, the flat sidecars) — owned by its own exact
+    //     route / the runtime's liveness route, never this tree;
+    //   • an unsafe subpath (`..`/absolute/percent-escaped/backslash) — traversal-rejected
+    //     before it reaches the filesystem;
+    //   • a miss (no such file) — so a same-path route registered AFTER the pages surface (a
+    //     trigger, the appended `/healthz`) still resolves instead of being masked by a 404.
+    // Registered LAST among the pages routes so every exact/prefix pages route above wins first.
+    routes.push({
+        method: "GET",
+        path: "/",
+        prefix: true,
+        source: "surface:pages",
+        handler: async (req) => {
+            const rest = req.path.slice(1); // drop the leading "/"
+            // Only a SUBDIR asset (has a `/`) belongs to this tree; a single-segment path is left
+            // to its own exact route / the appended `/healthz` liveness route.
+            if (!rest.includes("/"))
+                return undefined;
+            const safe = safeAssetSubpath(rest);
+            if (safe === null)
+                return undefined; // traversal/escape → decline (never touch the FS)
+            const res = await serveAsset(readAsset, `${pagesDir}/${safe}`);
+            // A miss declines rather than 404s, so a later same-path route (e.g. a trigger) can
+            // still claim it; the router's own default 404 covers a genuinely absent asset.
+            return res.status === 404 ? undefined : res;
+        },
+    });
     return routes;
 }
 /**

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

@@ -1,10 +1,22 @@
-import type { HttpHandler, HttpResponse } from "./host.ts";
+import type { HttpHandler, HttpRequest, HttpResponse } from "./host.ts";
+/**
+ * A route handler that may DECLINE a matched request by returning `undefined`
+ * (or a promise of it). The router then treats the route as if it had not matched
+ * and continues to the next route (fall-through). This lets a broad prefix route —
+ * e.g. the pages surface's nested static serve at `/` — claim only the requests it
+ * can actually satisfy (a real, safe asset) and let everything else (`/healthz`, an
+ * app's own trigger routes registered *after* it) resolve to their own handlers,
+ * instead of a root catch-all silently swallowing them. A handler that returns a
+ * concrete `HttpResponse` (including a 404) still short-circuits as before, so this
+ * is backwards-compatible with every existing handler (none return `undefined`).
+ */
+export type RouteHandler = (req: HttpRequest) => Promise<HttpResponse | undefined> | HttpResponse | undefined;
 export interface Route {
     method: string;
     path: string;
     /** When true, match any path that starts with `path`. */
     prefix?: boolean;
-    handler: HttpHandler;
+    handler: RouteHandler;
     /** For diagnostics / inspect(). */
     source?: string;
 }

package/dist/runtime/core/router.js

@@ -43,8 +43,14 @@ function matches(route, req) {
 export function makeRouter(routes) {
     return async (req) => {
         for (const route of routes) {
-            if (matches(route, req))
-                return route.handler(req);
+            if (matches(route, req)) {
+                // A handler may DECLINE by returning `undefined` (see RouteHandler): treat the
+                // route as unmatched and keep looking, so a broad prefix serve can't shadow a
+                // later exact route (`/healthz`, a trigger) it didn't actually satisfy.
+                const res = await route.handler(req);
+                if (res !== undefined)
+                    return res;
+            }
         }
         return text("not found", 404);
     };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.77.0",
+	"version": "0.77.1",
 	"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/modules/agent.test.ts

@@ -5,7 +5,8 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import { mountAgent } from "./agent.ts";
 import type { RuntimeContext } from "../context.ts";
-import type { EngineClient, HostContext, HttpRequest, HttpResponse } from "../host.ts";
+import type { EngineClient, HostContext, HttpResponse } from "../host.ts";
+import type { Route } from "../router.ts";
 
 const fakeEngine: EngineClient = {
   deployResources: async () => ({ deployed: 0 }),
@@ -44,14 +45,16 @@ function ctxWithFiles(files: Record<string, string>): RuntimeContext {
   return { root: ".", manifest: { schemaVersion: 1, id: "app", name: "App" }, host, engine: fakeEngine };
 }
 
-async function call(route: { handler: (req: HttpRequest) => HttpResponse | Promise<HttpResponse> }): Promise<HttpResponse> {
-  return route.handler({
+async function call(route: Route): Promise<HttpResponse> {
+  const res = await route.handler({
     method: "GET",
     path: "/",
     query: new URLSearchParams(),
     headers: new Headers(),
     text: async () => "",
   });
+  assert.ok(res, "handler should not decline");
+  return res;
 }
 
 const routeAt = (ctx: RuntimeContext, path: string) => {

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

@@ -1823,3 +1823,130 @@ test("the static asset routes do not shadow the app's own routes or /healthz", a
   const home = await router(req("GET", "/"));
   assert.match(home.body ?? "", /data-home="home"/);
 });
+
+// ── nested (multi-appView) sidecar serving (#442) ──────────────────────────
+// An app with two-or-more appViews ships each view's sidecar under its own subdir
+// (`./cockpit/embed.html`, `./board/embed.html`); #420's flat 4-name serve 404'd every
+// one. These pin the generalized nested prefix serve of `pages/<subpath>` (and that it
+// still declines — never a root catch-all — so `/healthz` / triggers keep resolving).
+
+test("GET /<subdir>/embed.html serves the nested appView sidecar", async () => {
+  const router = buildWithAssets({
+    "pages/cockpit/embed.html": "<!doctype html><title>cockpit</title>",
+    "pages/board/embed.html": "<!doctype html><title>board</title>",
+  });
+  const cockpit = await router(req("GET", "/cockpit/embed.html"));
+  assert.equal(cockpit.status, 200);
+  assert.match(cockpit.headers?.["content-type"] ?? "", /text\/html/);
+  assert.match(cockpit.body ?? "", /<title>cockpit<\/title>/);
+  const board = await router(req("GET", "/board/embed.html"));
+  assert.equal(board.status, 200);
+  assert.match(board.body ?? "", /<title>board<\/title>/);
+});
+
+test("all nested subdir sidecar assets are served with correct content types", async () => {
+  const router = buildWithAssets({
+    "pages/cockpit/embed.html": "<html>embed</html>",
+    "pages/cockpit/standalone.html": "<html>standalone</html>",
+    "pages/cockpit/mount.js": "export const mountCockpit = () => {};",
+    "pages/cockpit/cockpit.css": "body{margin:0}",
+    "pages/delivery-graphs/embed.html": "<html>dg</html>",
+  });
+  const cases: [string, RegExp][] = [
+    ["/cockpit/embed.html", /text\/html/],
+    ["/cockpit/standalone.html", /text\/html/],
+    ["/cockpit/mount.js", /text\/javascript/],
+    ["/cockpit/cockpit.css", /text\/css/],
+    // A hyphenated multi-appView page id (the merlin repro) resolves too.
+    ["/delivery-graphs/embed.html", /text\/html/],
+  ];
+  for (const [path, ct] of cases) {
+    const res = await router(req("GET", path));
+    assert.equal(res.status, 200, `${path} should 200`);
+    assert.match(res.headers?.["content-type"] ?? "", ct, `${path} content-type`);
+  }
+});
+
+test("the flat single-appView sidecar back-compat still serves (#420) alongside nested", async () => {
+  // The root `pages/embed.html` case #420 shipped must keep working: an app with exactly
+  // one appView (no subdir) is unaffected by the nested generalization.
+  const router = buildWithAssets({
+    "pages/embed.html": "<html>flat</html>",
+    "pages/cockpit/embed.html": "<html>nested</html>",
+  });
+  const flat = await router(req("GET", "/embed.html"));
+  assert.equal(flat.status, 200);
+  assert.match(flat.body ?? "", /flat/);
+  const nested = await router(req("GET", "/cockpit/embed.html"));
+  assert.equal(nested.status, 200);
+  assert.match(nested.body ?? "", /nested/);
+});
+
+test("a missing nested sidecar 404s instead of throwing", async () => {
+  const router = buildWithAssets({ "pages/cockpit/embed.html": "<html>ok</html>" });
+  const res = await router(req("GET", "/board/embed.html"));
+  assert.equal(res.status, 404);
+});
+
+test("a nested-serve path traversal attempt is rejected (never reaches the filesystem)", async () => {
+  // The `pages/` tree reuses the SAME sub-path guard as `/dist/`: any `..` / absolute /
+  // percent-escaped / backslash / doubled-slash segment must be rejected before a read.
+  let readAttempts = 0;
+  const { engine } = fakeEngine();
+  const router = makeRouter(
+    createPagesRoutes(
+      { pagesDir: "pages", homePage: "home", sourceName: "app" },
+      {
+        db: fakeDb(),
+        engine,
+        readPage: async () => JSON.stringify({ title: "Home", nodes: [] }),
+        readAsset: async (path: string) => {
+          readAttempts++;
+          return `bytes of ${path}`;
+        },
+        listPages: async () => ["home"],
+      },
+    ),
+  );
+  for (const evil of ["/cockpit/../secret.json", "/a/../../secret", "/cockpit/%2e%2e/secret", "/cockpit//etc"]) {
+    const res = await router(req("GET", evil));
+    assert.equal(res.status, 404, `${evil} must 404`);
+  }
+  assert.equal(readAttempts, 0, "no traversal path may reach the asset reader");
+});
+
+test("the nested serve declines (does not shadow) a same-path trigger route registered after it", async () => {
+  // The nested serve is a `/`-prefix route registered before the triggers surface. A miss
+  // must DECLINE (fall through) so a trigger at `/webhooks/deploy` still resolves, rather
+  // than being masked by the pages tree's 404. A root catch-all would silently swallow it.
+  const routes = createPagesRoutes(
+    { pagesDir: "pages", homePage: "home", sourceName: "app" },
+    {
+      db: fakeDb(),
+      engine: fakeEngine().engine,
+      readPage: async () => JSON.stringify({ title: "Home", nodes: [] }),
+      readAsset: async (path: string) => {
+        // Only the real nested sidecar exists; every other path is a miss.
+        if (path === "pages/cockpit/embed.html") return "<html>cockpit</html>";
+        throw new Error(`no such file: ${path}`);
+      },
+      listPages: async () => ["home"],
+    },
+  );
+  const router = makeRouter([
+    ...routes,
+    {
+      method: "GET",
+      path: "/webhooks/deploy",
+      handler: () => ({ status: 202, headers: { "content-type": "application/json" }, body: JSON.stringify({ queued: true }) }),
+    },
+  ]);
+  // The real nested sidecar is served by the pages tree.
+  const sidecar = await router(req("GET", "/cockpit/embed.html"));
+  assert.equal(sidecar.status, 200);
+  assert.match(sidecar.body ?? "", /cockpit/);
+  // The multi-segment trigger path is NOT shadowed — the nested serve declines the miss.
+  const hook = await router(req("GET", "/webhooks/deploy"));
+  assert.equal(hook.status, 202);
+  assert.deepEqual(JSON.parse(hook.body ?? "{}"), { queued: true });
+});

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

@@ -11,7 +11,8 @@
 //   GET  /              (+ /app/runtime.js)         → the schema-driven browser renderer
 //   GET  /app/pages/<id>                            → the page's page.json
 //   GET  /app/data/<source>/<table>[?where&order]   → rows (filtered/ordered, whitelisted)
-//   GET  /{embed,standalone}.html /mount.js /cockpit.css → appView sidecars (from pagesDir, #420)
+//   GET  /{embed,standalone}.html /mount.js /cockpit.css → flat appView sidecars (from pagesDir, #420)
+//   GET  /<subdir>/<asset>                          → nested appView sidecars (pages/<subdir>/…, #442)
 //   GET  /dist/<path>                               → the app dist/ bundle the sidecars reference
 //   POST /app/actions/start/<process>               → engine.createInstance
 //   POST /app/actions/cancel                        → engine.cancelInstance
@@ -107,7 +108,10 @@ function javascript(
 // document then pulls `./cockpit.css`, `./mount.js`, and (via its import-map)
 // `../dist/…`. A DEPLOYED app served none of these, so the src 404'd and the cockpit
 // iframe loaded nothing (#416's user-facing "nothing shows in the Cockpit"). These are
-// the root-served sidecar files, mapped 1:1 onto `pagesDir/<name>`. The `dist/` tree the
+// the root-served sidecar files, mapped 1:1 onto `pagesDir/<name>`. An app that ships
+// MORE than one `appView` gives each its own SUBDIR sidecar (`./cockpit/embed.html`,
+// `./board/embed.html`, …) — those are served by the nested prefix route below (#442);
+// this flat set stays as the single-appView back-compat case (#420). The `dist/` tree the
 // import-map references is served separately under the `/dist/` prefix below.
 const SIDECAR_ASSETS = ["embed.html", "standalone.html", "mount.js", "cockpit.css"] as const;
 
@@ -541,6 +545,44 @@ export function createPagesRoutes(opts: PagesOptions, deps: PagesDeps): Route[]
     },
   });
 
+  // ── nested (multi-appView) sidecars (#442) ──────────────────────────────
+  // An app with more than one `appView` cannot share the four FLAT sidecar names above:
+  // each view ships its own SUBDIR sidecar — e.g. `pages/cockpit.page.json` →
+  // `./cockpit/embed.html`, `pages/board.page.json` → `./board/embed.html`. The renderer's
+  // `baseRelativeUrl(p.embed)` rebases those onto the mount root, so the browser fetches
+  // `/cockpit/embed.html`, `/board/mount.js`, … — every one of which #420's flat 4-name
+  // serve 404'd. Serve the `pagesDir` as a TREE, mapping `/<subpath>` onto
+  // `pagesDir/<subpath>` with the SAME traversal guard as the `/dist/` route (mirroring it).
+  // It is a `/`-prefix route, so to avoid a root catch-all silently swallowing `/healthz`,
+  // the app's own trigger routes, or any other route, the handler DECLINES (returns
+  // undefined → the router falls through to the next route, see `RouteHandler`) whenever it
+  // cannot serve a real nested asset:
+  //   • a bare single-segment path (`/healthz`, the flat sidecars) — owned by its own exact
+  //     route / the runtime's liveness route, never this tree;
+  //   • an unsafe subpath (`..`/absolute/percent-escaped/backslash) — traversal-rejected
+  //     before it reaches the filesystem;
+  //   • a miss (no such file) — so a same-path route registered AFTER the pages surface (a
+  //     trigger, the appended `/healthz`) still resolves instead of being masked by a 404.
+  // Registered LAST among the pages routes so every exact/prefix pages route above wins first.
+  routes.push({
+    method: "GET",
+    path: "/",
+    prefix: true,
+    source: "surface:pages",
+    handler: async (req) => {
+      const rest = req.path.slice(1); // drop the leading "/"
+      // Only a SUBDIR asset (has a `/`) belongs to this tree; a single-segment path is left
+      // to its own exact route / the appended `/healthz` liveness route.
+      if (!rest.includes("/")) return undefined;
+      const safe = safeAssetSubpath(rest);
+      if (safe === null) return undefined; // traversal/escape → decline (never touch the FS)
+      const res = await serveAsset(readAsset, `${pagesDir}/${safe}`);
+      // A miss declines rather than 404s, so a later same-path route (e.g. a trigger) can
+      // still claim it; the router's own default 404 covers a genuinely absent asset.
+      return res.status === 404 ? undefined : res;
+    },
+  });
+
   return routes;
 }
 

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

@@ -4,9 +4,10 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { mountSurfaces } from "./surfaces.ts";
-import type { EngineClient, HostContext, HttpRequest, HttpResponse } from "../host.ts";
+import type { EngineClient, HostContext, HttpResponse } from "../host.ts";
 import { DataLayer } from "./datasource.ts";
 import { createLogger } from "../logger.ts";
+import type { Route } from "../router.ts";
 
 function ctxWith(surfaces: Record<string, unknown>): Parameters<typeof mountSurfaces>[0] {
   const host: HostContext = {
@@ -63,7 +64,7 @@ const fakeApp: Parameters<typeof mountSurfaces>[1] = {
   log: createLogger(() => {}),
 };
 
-async function render(route: { handler: (req: HttpRequest) => HttpResponse | Promise<HttpResponse> }): Promise<string> {
+async function render(route: Route): Promise<string> {
   const res = await route.handler({
     method: "GET",
     path: "/",
@@ -71,6 +72,7 @@ async function render(route: { handler: (req: HttpRequest) => HttpResponse | Pro
     headers: new Headers(),
     text: async () => "",
   });
+  assert.ok(res, "handler should not decline");
   return String(res.body);
 }
 
@@ -118,16 +120,18 @@ function appWith(engine: EngineClient): Parameters<typeof mountSurfaces>[1] {
 
 /** Invoke a route handler with an optional query string and POST body. */
 async function call(
-  route: { handler: (req: HttpRequest) => HttpResponse | Promise<HttpResponse> },
+  route: Route,
   opts: { method?: string; query?: string; body?: string } = {},
 ): Promise<HttpResponse> {
-  return route.handler({
+  const res = await route.handler({
     method: opts.method ?? "GET",
     path: "/",
     query: new URLSearchParams(opts.query ?? ""),
     headers: new Headers(),
     text: async () => opts.body ?? "",
   });
+  assert.ok(res, "handler should not decline");
+  return res;
 }
 
 function inboxRoutes(engine: EngineClient) {

package/src/runtime/core/router.ts

@@ -4,12 +4,25 @@
 
 import type { HttpHandler, HttpRequest, HttpResponse } from "./host.ts";
 
+/**
+ * A route handler that may DECLINE a matched request by returning `undefined`
+ * (or a promise of it). The router then treats the route as if it had not matched
+ * and continues to the next route (fall-through). This lets a broad prefix route —
+ * e.g. the pages surface's nested static serve at `/` — claim only the requests it
+ * can actually satisfy (a real, safe asset) and let everything else (`/healthz`, an
+ * app's own trigger routes registered *after* it) resolve to their own handlers,
+ * instead of a root catch-all silently swallowing them. A handler that returns a
+ * concrete `HttpResponse` (including a 404) still short-circuits as before, so this
+ * is backwards-compatible with every existing handler (none return `undefined`).
+ */
+export type RouteHandler = (req: HttpRequest) => Promise<HttpResponse | undefined> | HttpResponse | undefined;
+
 export interface Route {
   method: string;
   path: string;
   /** When true, match any path that starts with `path`. */
   prefix?: boolean;
-  handler: HttpHandler;
+  handler: RouteHandler;
   /** For diagnostics / inspect(). */
   source?: string;
 }
@@ -61,7 +74,13 @@ function matches(route: Route, req: HttpRequest): boolean {
 export function makeRouter(routes: Route[]): HttpHandler {
   return async (req: HttpRequest): Promise<HttpResponse> => {
     for (const route of routes) {
-      if (matches(route, req)) return route.handler(req);
+      if (matches(route, req)) {
+        // A handler may DECLINE by returning `undefined` (see RouteHandler): treat the
+        // route as unmatched and keep looking, so a broad prefix serve can't shadow a
+        // later exact route (`/healthz`, a trigger) it didn't actually satisfy.
+        const res = await route.handler(req);
+        if (res !== undefined) return res;
+      }
     }
     return text("not found", 404);
   };