@nanobpm/urban 0.24.0 → 0.25.0

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

@@ -1,14 +1,6 @@
 import type { HostContext } from "./host.ts";
 import type { AppManifest, Worker } from "@nanobpm/nano-app-schema";
 export type { ActionDecl, AppManifest, AppUi, ChatSurface, Connection, Data, DataSource, DomainField, DomainType, LlmBinding, Models, PagesSurface, Runtime, Security, Surfaces, TaskInboxSurface, Trigger, TriggerAction, Worker, } from "@nanobpm/nano-app-schema";
-declare module "@nanobpm/nano-app-schema" {
-    interface Models {
-        /** `{{name}}` template sources substituted into model resources at deploy time: globs, a bare
-         *  directory (scanned), or literal files. A template's name is its file stem
-         *  (`prompts/review-round.md` → `{{review-round}}`). See `deployModels`. */
-        templates?: string[];
-    }
-}
 /** The job type a worker subscribes to (schema key: `taskType`). */
 export declare function workerJobType(w: Worker): string | undefined;
 /**

package/dist/runtime/core/runtime.js

@@ -131,9 +131,11 @@ export async function createUrbanApp(opts) {
                         describe.connectors = c.describe?.();
                 }
                 const routes = [];
+                let hasUiSurfaces = false;
                 if (flags.surfaces) {
                     const s = mountSurfaces(ctx, api);
                     routes.push(...s.routes);
+                    hasUiSurfaces = s.routes.length > 0;
                     describe.surfaces = s.describe();
                 }
                 if (flags.triggers) {
@@ -160,6 +162,23 @@ export async function createUrbanApp(opts) {
                     server = await host.serveHttp(port, makeRouter(routes));
                     httpPort = server.port;
                     host.log("info", "urban app serving surfaces/triggers", { port: httpPort, routes: routes.length });
+                    // ADR 0057 boot handshake: under a supervising host (the nano-bpm
+                    // Studio sets NANOBPMN_APP_HANDSHAKE), announce the port we actually
+                    // bound on a machine-readable stdout control line so the host can
+                    // locate the app's UI even when the app picks its port at runtime.
+                    // Only emitted when the app actually serves UI surfaces (a trigger- or
+                    // worker-only app binds a port too, but it has no webview for the host
+                    // to frame), and gated on the env var so direct terminal runs aren't
+                    // cluttered. `=== "1"` so an app that sets the var to "0" opts out.
+                    if (httpPort !== undefined && hasUiSurfaces && host.env("NANOBPMN_APP_HANDSHAKE") === "1") {
+                        try {
+                            console.log(`@@NBPM_LISTENING@@${JSON.stringify({ port: httpPort })}`);
+                        }
+                        catch {
+                            // stdout may be closed / non-writable — the handshake is
+                            // best-effort telemetry, never fatal to the app.
+                        }
+                    }
                 }
                 host.log("info", `urban app "${manifest.id}" started`, {});
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.24.0",
+  "version": "0.25.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",
@@ -62,7 +62,7 @@
     "test:deno": "deno test -A --no-check src/"
   },
   "dependencies": {
-    "@nanobpm/nano-app-schema": "^0.2.0",
+    "@nanobpm/nano-app-schema": "^0.3.0",
     "@nanobpm/nano-sdk": "^1.2.3",
     "@nanobpm/workflow": "^0.8.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2",

package/src/runtime/core/manifest.ts

@@ -33,20 +33,6 @@ export type {
   Worker,
 } from "@nanobpm/nano-app-schema";
 
-// The published `@nanobpm/nano-app-schema` does not declare `models.templates`; the manifest
-// validator only enforces `additionalProperties:false` at the top level (see validate.ts), so the
-// nested key is accepted at runtime. Augment `Models` here so the deploy path can read it typed
-// (no cast) until it is formalized in the schema package. (The top-level `ui` block, by contrast,
-// now ships natively in the schema as `AppUi` — re-exported above — so it needs no shim.)
-declare module "@nanobpm/nano-app-schema" {
-  interface Models {
-    /** `{{name}}` template sources substituted into model resources at deploy time: globs, a bare
-     *  directory (scanned), or literal files. A template's name is its file stem
-     *  (`prompts/review-round.md` → `{{review-round}}`). See `deployModels`. */
-    templates?: string[];
-  }
-}
-
 /** The job type a worker subscribes to (schema key: `taskType`). */
 export function workerJobType(w: Worker): string | undefined {
   return w.taskType;

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

@@ -324,3 +324,81 @@ test("runFromEnv anchors the host at a non-'.' root without double-prefixing pat
     await rm(dir, { recursive: true, force: true });
   }
 });
+
+// Captures console.log for the duration of `fn`, restoring it after.
+async function captureStdout(fn: () => Promise<void>): Promise<string[]> {
+  const lines: string[] = [];
+  const original = console.log;
+  console.log = (...args: unknown[]) => {
+    lines.push(args.map((a) => (typeof a === "string" ? a : String(a))).join(" "));
+  };
+  try {
+    await fn();
+  } finally {
+    console.log = original;
+  }
+  return lines;
+}
+
+test("emits the ADR 0057 boot handshake when NANOBPMN_APP_HANDSHAKE is set", async () => {
+  const dir = await makeFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+  const prev = process.env.NANOBPMN_APP_HANDSHAKE;
+  process.env.NANOBPMN_APP_HANDSHAKE = "1";
+  try {
+    const lines = await captureStdout(() => app.start());
+    const handshake = lines.find((l) => l.startsWith("@@NBPM_LISTENING@@"));
+    assert.ok(handshake, "a @@NBPM_LISTENING@@ line was emitted");
+    const payload = JSON.parse(handshake!.slice("@@NBPM_LISTENING@@".length));
+    assert.equal(payload.port, app.httpPort, "handshake reports the actual bound port");
+    assert.ok(payload.port > 0);
+  } finally {
+    if (prev === undefined) delete process.env.NANOBPMN_APP_HANDSHAKE;
+    else process.env.NANOBPMN_APP_HANDSHAKE = prev;
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("does NOT emit the boot handshake without NANOBPMN_APP_HANDSHAKE", async () => {
+  const dir = await makeFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+  const prev = process.env.NANOBPMN_APP_HANDSHAKE;
+  delete process.env.NANOBPMN_APP_HANDSHAKE;
+  try {
+    const lines = await captureStdout(() => app.start());
+    assert.ok(
+      !lines.some((l) => l.startsWith("@@NBPM_LISTENING@@")),
+      "no handshake line when the supervisor env is unset (clean terminal runs)",
+    );
+  } finally {
+    if (prev !== undefined) process.env.NANOBPMN_APP_HANDSHAKE = prev;
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("treats NANOBPMN_APP_HANDSHAKE other than \"1\" as opt-out", async () => {
+  const dir = await makeFixture();
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const engine = new FakeEngine();
+  const app = await createUrbanApp({ host, engine, root: ".", port: 0 });
+  const prev = process.env.NANOBPMN_APP_HANDSHAKE;
+  process.env.NANOBPMN_APP_HANDSHAKE = "0";
+  try {
+    const lines = await captureStdout(() => app.start());
+    assert.ok(
+      !lines.some((l) => l.startsWith("@@NBPM_LISTENING@@")),
+      '"0" is not the opt-in sentinel ("1"), so no handshake is emitted',
+    );
+  } finally {
+    if (prev === undefined) delete process.env.NANOBPMN_APP_HANDSHAKE;
+    else process.env.NANOBPMN_APP_HANDSHAKE = prev;
+    await app.stop();
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/runtime/core/runtime.ts

@@ -191,9 +191,11 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
         }
 
         const routes: Route[] = [];
+        let hasUiSurfaces = false;
         if (flags.surfaces) {
           const s = mountSurfaces(ctx, api);
           routes.push(...s.routes);
+          hasUiSurfaces = s.routes.length > 0;
           describe.surfaces = s.describe();
         }
         if (flags.triggers) {
@@ -219,6 +221,22 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
           server = await host.serveHttp(port, makeRouter(routes));
           httpPort = server.port;
           host.log("info", "urban app serving surfaces/triggers", { port: httpPort, routes: routes.length });
+          // ADR 0057 boot handshake: under a supervising host (the nano-bpm
+          // Studio sets NANOBPMN_APP_HANDSHAKE), announce the port we actually
+          // bound on a machine-readable stdout control line so the host can
+          // locate the app's UI even when the app picks its port at runtime.
+          // Only emitted when the app actually serves UI surfaces (a trigger- or
+          // worker-only app binds a port too, but it has no webview for the host
+          // to frame), and gated on the env var so direct terminal runs aren't
+          // cluttered. `=== "1"` so an app that sets the var to "0" opts out.
+          if (httpPort !== undefined && hasUiSurfaces && host.env("NANOBPMN_APP_HANDSHAKE") === "1") {
+            try {
+              console.log(`@@NBPM_LISTENING@@${JSON.stringify({ port: httpPort })}`);
+            } catch {
+              // stdout may be closed / non-writable — the handshake is
+              // best-effort telemetry, never fatal to the app.
+            }
+          }
         }
         host.log("info", `urban app "${manifest.id}" started`, {});
       } catch (err) {