@nanobpm/urban 0.11.0 → 0.12.0

package/dist/cli.js

@@ -27,7 +27,7 @@ function readVersion() {
 }
 const VERSION = readVersion();
 function parse(argv) {
-    const f = { root: ".", manifest: "nano.app.json", check: false, help: false, version: false, _: [] };
+    const f = { root: ".", manifest: "nano.app.json", check: false, deno: false, help: false, version: false, _: [] };
     const need = (i, flag) => {
         const v = argv[i];
         if (v === undefined || v.startsWith("-"))
@@ -42,6 +42,10 @@ function parse(argv) {
             f.version = true;
         else if (a === "--check")
             f.check = true;
+        else if (a === "--deno")
+            f.deno = true;
+        else if (a === "--")
+            continue; // tolerate a bare "--" some runners inject (not an option terminator here)
         else if (a === "--root")
             f.root = need(++i, a);
         else if (a === "--manifest")
@@ -64,7 +68,7 @@ function parse(argv) {
 const USAGE = `urban — build and run Urban apps (nano.app.json)
 
 Usage:
-  urban new <name> [--root <path>]    scaffold a new Urban app
+  urban new <name> [--root <path>] [--deno]    scaffold a new Urban app
   urban check                       validate the manifest
   urban gen [--check]               derive artifacts (migrations, worker-io)
   urban run                         materialize + serve the app
@@ -138,13 +142,16 @@ async function cmdDeploy(f) {
 async function cmdNew(f) {
     const name = f._[1];
     if (!name) {
-        console.error("usage: urban new <name> [--root <path>]");
+        console.error("usage: urban new <name> [--root <path>] [--deno]");
         return 1;
     }
     const dir = f.root !== "." ? f.root : `./${slugify(name)}`;
-    const res = await scaffold({ name, dir });
+    const res = await scaffold({ name, dir, deno: f.deno });
     console.log(`✔ scaffolded "${res.id}" in ${res.dir} (${res.files.length} files)`);
-    console.log(`  cd ${res.dir} && (npm install && npm start) || deno task start`);
+    console.log(`  cd ${res.dir}`);
+    console.log(`  npm install && npm start`);
+    if (f.deno)
+        console.log(`  # or on Deno: deno task start`);
     return 0;
 }
 export async function main(argv) {

package/dist/runtime/engine/nanosdk.d.ts

@@ -26,7 +26,8 @@ export interface NanoSdkJobWorkerConfig {
     jobTimeoutMs?: number;
     pollTimeoutMs?: number;
     fetchVariables?: string[];
-    /** Start polling immediately. This adapter sets it false and starts explicitly. */
+    /** Start polling immediately (the SDK default). The adapter leaves this unset so the
+     * SDK owns the start lifecycle after its async Nano/Falcon transport detection. */
     autoStart?: boolean;
 }
 /** The handle returned by `createJobWorker`. */
@@ -69,6 +70,10 @@ export interface NanoSdkClient {
         variables?: Record<string, unknown>;
     }, options?: unknown): Promise<unknown>;
     createJobWorker(cfg: NanoSdkJobWorkerConfig): NanoSdkJobWorker;
+    /** Stop every worker created on this client. Used on teardown to also drain a
+     * REST-fallback worker, whose handle the `createJobWorker` proxy starts internally
+     * and does not hand back. Optional: not every injected client implements it. */
+    stopAllWorkers?(): void | Promise<void>;
     close?(): void | Promise<void>;
 }
 type Log = (level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>) => void;

package/dist/runtime/engine/nanosdk.js

@@ -103,9 +103,6 @@ export class SdkEngineClient {
             workerName: options?.workerName ?? `urban:${jobType}`,
             maxParallelJobs: options?.maxParallelJobs ?? 8,
             fetchVariables: options?.fetchVariables,
-            // Own the poll lifecycle here rather than leaving it to the SDK's auto-start
-            // default, so nothing polls until `start()` is called below.
-            autoStart: false,
             jobHandler: async (job) => {
                 const rawKey = job.jobKey;
                 if (rawKey == null || rawKey === "") {
@@ -138,7 +135,11 @@ export class SdkEngineClient {
                 }
             },
         });
-        await worker.start();
+        // The nano-sdk job worker owns its own start lifecycle: `createJobWorker` runs
+        // async Nano/Falcon detection and, once the transport is bound, starts polling
+        // itself (Falcon) or hands off to an auto-started REST worker. Calling `start()`
+        // here would race that detection and dereference a still-null transport, so we
+        // don't — the worker autostarts.
         this.workers.add(worker);
         return {
             jobType,
@@ -162,6 +163,14 @@ export class SdkEngineClient {
         for (const w of this.workers)
             await this.stopWorker(w);
         this.workers.clear();
+        try {
+            // Also drain any REST-fallback worker the SDK started internally (its handle is
+            // not the one we hold), which `stopWorker` above cannot reach.
+            await this.client.stopAllWorkers?.();
+        }
+        catch {
+            /* no workers running / already stopped */
+        }
         try {
             await this.client.close?.();
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.11.0",
+  "version": "0.12.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",
@@ -61,7 +61,7 @@
     "@nanobpm/nano-sdk": "^1.2.0",
     "@nanobpm/workflow": "^0.7.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2",
-    "create-urban-app": "^0.2.0"
+    "create-urban-app": "^0.3.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",

package/src/cli.ts

@@ -40,13 +40,14 @@ interface Flags {
   manifest: string;
   port?: number;
   check: boolean;
+  deno: boolean;
   help: boolean;
   version: boolean;
   _: string[];
 }
 
 function parse(argv: string[]): Flags {
-  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, help: false, version: false, _: [] };
+  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, deno: false, help: false, version: false, _: [] };
   const need = (i: number, flag: string): string => {
     const v = argv[i];
     if (v === undefined || v.startsWith("-")) throw new Error(`flag ${flag} requires a value`);
@@ -57,6 +58,8 @@ function parse(argv: string[]): Flags {
     if (a === "-h" || a === "--help") f.help = true;
     else if (a === "-v" || a === "--version") f.version = true;
     else if (a === "--check") f.check = true;
+    else if (a === "--deno") f.deno = true;
+    else if (a === "--") continue; // tolerate a bare "--" some runners inject (not an option terminator here)
     else if (a === "--root") f.root = need(++i, a);
     else if (a === "--manifest") f.manifest = need(++i, a);
     else if (a === "--port") {
@@ -75,7 +78,7 @@ function parse(argv: string[]): Flags {
 const USAGE = `urban — build and run Urban apps (nano.app.json)
 
 Usage:
-  urban new <name> [--root <path>]    scaffold a new Urban app
+  urban new <name> [--root <path>] [--deno]    scaffold a new Urban app
   urban check                       validate the manifest
   urban gen [--check]               derive artifacts (migrations, worker-io)
   urban run                         materialize + serve the app
@@ -151,13 +154,15 @@ async function cmdDeploy(f: Flags): Promise<number> {
 async function cmdNew(f: Flags): Promise<number> {
   const name = f._[1];
   if (!name) {
-    console.error("usage: urban new <name> [--root <path>]");
+    console.error("usage: urban new <name> [--root <path>] [--deno]");
     return 1;
   }
   const dir = f.root !== "." ? f.root : `./${slugify(name)}`;
-  const res = await scaffold({ name, dir });
+  const res = await scaffold({ name, dir, deno: f.deno });
   console.log(`✔ scaffolded "${res.id}" in ${res.dir} (${res.files.length} files)`);
-  console.log(`  cd ${res.dir} && (npm install && npm start) || deno task start`);
+  console.log(`  cd ${res.dir}`);
+  console.log(`  npm install && npm start`);
+  if (f.deno) console.log(`  # or on Deno: deno task start`);
   return 0;
 }
 

package/src/runtime/engine/nanosdk.test.ts

@@ -81,6 +81,9 @@ function fakeSdkClient(overrides: Partial<NanoSdkClient> = {}): NanoSdkClient &
           rec.stopped++;
         },
       };
+      // The real nano-sdk starts the worker itself after async transport detection
+      // (autoStart defaults on). Model that here so the adapter must NOT call start().
+      if (cfg.autoStart !== false) worker.start();
       return worker;
     },
     close() {
@@ -198,7 +201,7 @@ test("completeUserTask routes through the SDK", async () => {
   assert.deepEqual(seen, { userTaskKey: "utk", variables: { done: true } });
 });
 
-test("registerWorker creates a worker (autoStart false), starts it, and dispatches + completes", async () => {
+test("registerWorker creates a worker the SDK auto-starts, and dispatches + completes", async () => {
   const client = fakeSdkClient();
   const engine = new SdkEngineClient(client);
   const handled: Record<string, unknown>[] = [];
@@ -212,7 +215,9 @@ test("registerWorker creates a worker (autoStart false), starts it, and dispatch
   );
   assert.equal(sub.jobType, "svc");
   const rec = client.workers[0];
-  assert.equal(rec.cfg.autoStart, false);
+  // The adapter must not force autoStart off or call start() itself (that races the
+  // SDK's async transport detection); the SDK owns the start lifecycle.
+  assert.equal(rec.cfg.autoStart, undefined);
   assert.equal(rec.cfg.workerName, "urban:svc");
   assert.equal(rec.cfg.maxParallelJobs, 4);
   assert.equal(rec.started, 1);
@@ -272,6 +277,31 @@ test("close stops every worker and closes the SDK client", async () => {
   assert.equal(client.closed, 1);
 });
 
+test("close drains the REST-fallback worker via the SDK's stopAllWorkers", async () => {
+  let stopAllCalls = 0;
+  const client = fakeSdkClient({
+    async stopAllWorkers() {
+      stopAllCalls++;
+    },
+  });
+  const engine = new SdkEngineClient(client);
+  await engine.registerWorker("a", async () => ({}));
+  await engine.close();
+  // The SDK may start a REST-fallback worker whose handle we never receive;
+  // close() must reach it through the client's stopAllWorkers().
+  assert.equal(stopAllCalls, 1, "close awaits client.stopAllWorkers exactly once");
+  assert.equal(client.closed, 1);
+});
+
+test("close tolerates a client without stopAllWorkers", async () => {
+  const client = fakeSdkClient();
+  delete (client as { stopAllWorkers?: unknown }).stopAllWorkers;
+  const engine = new SdkEngineClient(client);
+  await engine.registerWorker("a", async () => ({}));
+  await engine.close();
+  assert.equal(client.closed, 1);
+});
+
 test("exposes the underlying nano-sdk client as .sdk", () => {
   const client = fakeSdkClient();
   const engine = new SdkEngineClient(client);

package/src/runtime/engine/nanosdk.ts

@@ -49,7 +49,8 @@ export interface NanoSdkJobWorkerConfig {
   jobTimeoutMs?: number;
   pollTimeoutMs?: number;
   fetchVariables?: string[];
-  /** Start polling immediately. This adapter sets it false and starts explicitly. */
+  /** Start polling immediately (the SDK default). The adapter leaves this unset so the
+   * SDK owns the start lifecycle after its async Nano/Falcon transport detection. */
   autoStart?: boolean;
 }
 
@@ -97,6 +98,10 @@ export interface NanoSdkClient {
     options?: unknown,
   ): Promise<unknown>;
   createJobWorker(cfg: NanoSdkJobWorkerConfig): NanoSdkJobWorker;
+  /** Stop every worker created on this client. Used on teardown to also drain a
+   * REST-fallback worker, whose handle the `createJobWorker` proxy starts internally
+   * and does not hand back. Optional: not every injected client implements it. */
+  stopAllWorkers?(): void | Promise<void>;
   close?(): void | Promise<void>;
 }
 
@@ -210,9 +215,6 @@ export class SdkEngineClient implements EngineClient {
       workerName: options?.workerName ?? `urban:${jobType}`,
       maxParallelJobs: options?.maxParallelJobs ?? 8,
       fetchVariables: options?.fetchVariables,
-      // Own the poll lifecycle here rather than leaving it to the SDK's auto-start
-      // default, so nothing polls until `start()` is called below.
-      autoStart: false,
       jobHandler: async (job) => {
         const rawKey = job.jobKey;
         if (rawKey == null || rawKey === "") {
@@ -244,7 +246,11 @@ export class SdkEngineClient implements EngineClient {
         }
       },
     });
-    await worker.start();
+    // The nano-sdk job worker owns its own start lifecycle: `createJobWorker` runs
+    // async Nano/Falcon detection and, once the transport is bound, starts polling
+    // itself (Falcon) or hands off to an auto-started REST worker. Calling `start()`
+    // here would race that detection and dereference a still-null transport, so we
+    // don't — the worker autostarts.
     this.workers.add(worker);
 
     return {
@@ -269,6 +275,13 @@ export class SdkEngineClient implements EngineClient {
   async close(): Promise<void> {
     for (const w of this.workers) await this.stopWorker(w);
     this.workers.clear();
+    try {
+      // Also drain any REST-fallback worker the SDK started internally (its handle is
+      // not the one we hold), which `stopWorker` above cannot reach.
+      await this.client.stopAllWorkers?.();
+    } catch {
+      /* no workers running / already stopped */
+    }
     try {
       await this.client.close?.();
     } catch {