@nanobpm/urban 0.15.0 → 0.16.0

package/dist/cli.js

@@ -46,6 +46,14 @@ function parse(argv) {
             f.write = true;
         else if (a === "--deno")
             f.deno = true;
+        else if (a === "--code-first")
+            f.style = "code";
+        else if (a === "--style") {
+            const v = need(++i, a);
+            if (v !== "model" && v !== "code")
+                throw new Error(`flag --style requires "model" or "code" (got "${v}")`);
+            f.style = v;
+        }
         else if (a === "--")
             continue; // tolerate a bare "--" some runners inject (not an option terminator here)
         else if (a === "--root")
@@ -70,7 +78,8 @@ function parse(argv) {
 const USAGE = `urban — build and run Urban apps (nano.app.json)
 
 Usage:
-  urban new <name> [--root <path>] [--deno]    scaffold a new Urban app
+  urban new <name> [--root <path>] [--deno] [--style model|code]    scaffold a new Urban app
+                                    (--code-first is shorthand for --style code)
   urban check                       validate the manifest
   urban gen [--check]               derive artifacts (migrations, worker-io)
   urban stubs [--write]             scaffold write-once handler stubs from the model
@@ -183,14 +192,16 @@ async function cmdDeploy(f) {
 async function cmdNew(f) {
     const name = f._[1];
     if (!name) {
-        console.error("usage: urban new <name> [--root <path>] [--deno]");
+        console.error("usage: urban new <name> [--root <path>] [--deno] [--style model|code] (or --code-first)");
         return 1;
     }
     const dir = f.root !== "." ? f.root : `./${slugify(name)}`;
-    const res = await scaffold({ name, dir, deno: f.deno });
+    const res = await scaffold({ name, dir, deno: f.deno, style: f.style });
     console.log(`✔ scaffolded "${res.id}" in ${res.dir} (${res.files.length} files)`);
     console.log(`  cd ${res.dir}`);
     console.log(`  npm install && npm start`);
+    if (f.style === "code")
+        console.log(`  npm run greet -- Adam   # start a code-first instance`);
     if (f.deno)
         console.log(`  # or on Deno: deno task start`);
     return 0;

package/dist/toolkit/scaffold/workers.js

@@ -43,7 +43,7 @@ export function renderWorkerStub(taskType, typedIn, typedOut) {
     return (`// Handler stub for the \`${taskType}\` service task, scaffolded from the model (ADR 0056).\n` +
         `// This file is yours to edit — \`urban stubs\` will never overwrite it. Implement the body\n` +
         `// below (use \`app.data.table(...)\` for state) and delete the throw.\n` +
-        `import type { AppJobHandler } from "@nanobpm/urban";\n` +
+        `import type { AppJobHandler } from "@nanobpm/urban/worker";\n` +
         generatedImport +
         `\n` +
         `const handler: AppJobHandler${generic} = async (job, app) => {\n` +

package/dist/worker.d.ts

@@ -0,0 +1,3 @@
+export type { AppJobHandler } from "./runtime/core/modules/workers.ts";
+export type { EngineJob, JobHandler } from "./runtime/core/host.ts";
+export type { AppApi } from "./runtime/core/context.ts";

package/dist/worker.js

@@ -0,0 +1,18 @@
+// `@nanobpm/urban/worker` — the runtime-free worker-authoring surface.
+//
+// A service-task handler only needs a handful of *types*: the handler signature and the
+// shapes it is handed. Those all live under `runtime/core/`, which is guaranteed free of any
+// `node:*` import or `Deno` reference (the ADR 0052 purity invariant, enforced by
+// core/purity.test.ts). Importing them from the package barrel (`@nanobpm/urban`) instead
+// drags in `runtime/index.ts`, which re-exports the Node and Deno host adapters — so the
+// barrel's type graph transitively references `node:*` and a consumer must have `@types/node`
+// resolvable (or `skipLibCheck` on) just to typecheck a handler.
+//
+// This entry re-exports ONLY those core authoring types, so a worker module (e.g. a scaffolded
+// stub, ADR 0056) typechecks on Node or Deno, with or without `skipLibCheck`, and never needs
+// `@types/node`. It is types-only: nothing here emits runtime code.
+//
+// (One caveat: `AppApi.sdk` exposes the full `@nanobpm/nano-sdk` client by design, so the
+// handler surface also reaches the SDK's types. Those are kept node-free by the
+// `@nanobpm/nano-sdk` >= 1.2.2 floor in package.json — see ADR 0056.)
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.15.0",
+  "version": "0.16.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",
@@ -43,6 +43,10 @@
       "types": "./dist/toolkit/index.d.ts",
       "default": "./dist/toolkit/index.js"
     },
+    "./worker": {
+      "types": "./dist/worker.d.ts",
+      "default": "./dist/worker.js"
+    },
     "./source": "./src/index.ts"
   },
   "files": [
@@ -58,10 +62,10 @@
     "test:deno": "deno test -A --no-check src/"
   },
   "dependencies": {
-    "@nanobpm/nano-sdk": "^1.2.0",
+    "@nanobpm/nano-sdk": "^1.2.2",
     "@nanobpm/workflow": "^0.7.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2",
-    "create-urban-app": "^0.4.0"
+    "create-urban-app": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",

package/src/cli.ts

@@ -44,6 +44,7 @@ interface Flags {
   check: boolean;
   write: boolean;
   deno: boolean;
+  style?: "model" | "code";
   help: boolean;
   version: boolean;
   _: string[];
@@ -63,6 +64,12 @@ function parse(argv: string[]): Flags {
     else if (a === "--check") f.check = true;
     else if (a === "--write") f.write = true;
     else if (a === "--deno") f.deno = true;
+    else if (a === "--code-first") f.style = "code";
+    else if (a === "--style") {
+      const v = need(++i, a);
+      if (v !== "model" && v !== "code") throw new Error(`flag --style requires "model" or "code" (got "${v}")`);
+      f.style = v;
+    }
     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);
@@ -82,7 +89,8 @@ function parse(argv: string[]): Flags {
 const USAGE = `urban — build and run Urban apps (nano.app.json)
 
 Usage:
-  urban new <name> [--root <path>] [--deno]    scaffold a new Urban app
+  urban new <name> [--root <path>] [--deno] [--style model|code]    scaffold a new Urban app
+                                    (--code-first is shorthand for --style code)
   urban check                       validate the manifest
   urban gen [--check]               derive artifacts (migrations, worker-io)
   urban stubs [--write]             scaffold write-once handler stubs from the model
@@ -197,14 +205,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>] [--deno]");
+    console.error("usage: urban new <name> [--root <path>] [--deno] [--style model|code] (or --code-first)");
     return 1;
   }
   const dir = f.root !== "." ? f.root : `./${slugify(name)}`;
-  const res = await scaffold({ name, dir, deno: f.deno });
+  const res = await scaffold({ name, dir, deno: f.deno, style: f.style });
   console.log(`✔ scaffolded "${res.id}" in ${res.dir} (${res.files.length} files)`);
   console.log(`  cd ${res.dir}`);
   console.log(`  npm install && npm start`);
+  if (f.style === "code") console.log(`  npm run greet -- Adam   # start a code-first instance`);
   if (f.deno) console.log(`  # or on Deno: deno task start`);
   return 0;
 }

package/src/toolkit/scaffold/workers.test.ts

@@ -40,6 +40,7 @@ test("slugifyTaskType makes a filesystem-safe slug", () => {
 
 test("typed in+out stub imports both symbols and parameterises the handler", () => {
   const stub = renderWorkerStub("pr.finalize", true, true);
+  assert.match(stub, /import type \{ AppJobHandler \} from "@nanobpm\/urban\/worker";/);
   assert.match(stub, /import type \{ WorkerInputs, WorkerOutputs \} from "\.\.\/\.\.\/nano-generated\/worker-io\.d\.ts";/);
   assert.match(stub, /AppJobHandler<WorkerInputs\["pr\.finalize"\], WorkerOutputs\["pr\.finalize"\]>/);
   assert.match(stub, /export default handler;/);

package/src/toolkit/scaffold/workers.ts

@@ -94,7 +94,7 @@ export function renderWorkerStub(
     `// Handler stub for the \`${taskType}\` service task, scaffolded from the model (ADR 0056).\n` +
     `// This file is yours to edit — \`urban stubs\` will never overwrite it. Implement the body\n` +
     `// below (use \`app.data.table(...)\` for state) and delete the throw.\n` +
-    `import type { AppJobHandler } from "@nanobpm/urban";\n` +
+    `import type { AppJobHandler } from "@nanobpm/urban/worker";\n` +
     generatedImport +
     `\n` +
     `const handler: AppJobHandler${generic} = async (job, app) => {\n` +

package/src/worker.test.ts

@@ -0,0 +1,104 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join, normalize } from "node:path";
+
+// Guard for the `@nanobpm/urban/worker` authoring surface. Its job is to keep urban's OWN
+// host adapters (runtime/adapters/node.ts, runtime/adapters/deno.ts and their node:* imports)
+// out of the type graph a worker handler imports — the coupling that otherwise forces
+// `@types/node` / `skipLibCheck` on a consumer just to typecheck a handler.
+//
+// This walks the *relative*-import closure from worker.ts, so it covers urban's own reachable
+// sources. It does NOT follow the bare `@nanobpm/nano-sdk` dependency behind `AppApi.sdk`
+// (engine/sdk.ts) — that dependency's own node-freeness is enforced separately by the
+// `@nanobpm/nano-sdk` >= 1.2.2 floor in package.json (which pulls @camunda8 >= 10.0.0-alpha.20,
+// whose public types no longer reference node:worker_threads). Together, urban's node-free
+// relative closure + that SDK floor make a scaffolded stub (ADR 0056) typecheck on Node or Deno
+// with no `@types/node` and no `skipLibCheck`.
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** Collect relative-specifier imports/re-exports from a source file. */
+function relativeSpecifiers(src: string): string[] {
+  const out: string[] = [];
+  const re = /\bfrom\s+["'](\.[^"']+)["']/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(src)) !== null) {
+    // Skip template-placeholder specifiers (e.g. `./${DOMAIN_DTS}` emitted as codegen strings),
+    // which are not real static import paths.
+    if (!m[1].includes("${")) out.push(m[1]);
+  }
+  return out;
+}
+
+/** Resolve a relative specifier (with explicit .ts) against a containing file. */
+function resolveSpec(fromFile: string, spec: string): string {
+  return normalize(join(dirname(fromFile), spec));
+}
+
+async function closureFrom(entry: string): Promise<string[]> {
+  const seen = new Set<string>();
+  const stack = [entry];
+  while (stack.length > 0) {
+    const file = stack.pop()!;
+    if (seen.has(file)) continue;
+    seen.add(file);
+    let src: string;
+    try {
+      src = await readFile(file, "utf8");
+    } catch {
+      // A statically-extracted specifier that doesn't resolve to a real file (dynamic/generated
+      // path). Skip it — the purity assertions below only care about files that actually exist.
+      continue;
+    }
+    for (const spec of relativeSpecifiers(src)) {
+      stack.push(resolveSpec(file, spec));
+    }
+  }
+  return [...seen];
+}
+
+test("@nanobpm/urban/worker closure is free of node:* and Deno", async () => {
+  const files = await closureFrom(join(here, "worker.ts"));
+  // Sanity: the walk actually reached the core authoring modules.
+  assert.ok(
+    files.some((f) => f.endsWith(join("core", "modules", "workers.ts"))),
+    "closure should include core/modules/workers.ts",
+  );
+  const offenders: string[] = [];
+  for (const file of files) {
+    const src = await readFile(file, "utf8");
+    if (/from\s+["']node:/.test(src)) offenders.push(`${file}: imports node:*`);
+    if (/\bDeno\s*\./.test(src)) offenders.push(`${file}: references Deno.*`);
+  }
+  assert.deepEqual(offenders, [], `worker surface purity violations:\n${offenders.join("\n")}`);
+});
+
+test("@nanobpm/urban/worker excludes urban's host adapters (the barrel includes them)", async () => {
+  const workerClosure = await closureFrom(join(here, "worker.ts"));
+  const barrelClosure = await closureFrom(join(here, "index.ts"));
+  const adapters = [
+    join("runtime", "adapters", "node.ts"),
+    join("runtime", "adapters", "deno.ts"),
+  ];
+  for (const a of adapters) {
+    assert.ok(
+      !workerClosure.some((f) => f.endsWith(a)),
+      `worker closure must NOT include ${a}`,
+    );
+    assert.ok(
+      barrelClosure.some((f) => f.endsWith(a)),
+      `barrel closure is expected to include ${a} (control)`,
+    );
+  }
+});
+
+test("@nanobpm/urban/worker re-exports the authoring types", async () => {
+  const src = await readFile(join(here, "worker.ts"), "utf8");
+  for (const sym of ["AppJobHandler", "EngineJob", "JobHandler", "AppApi"]) {
+    assert.match(src, new RegExp(`\\b${sym}\\b`), `worker.ts should export ${sym}`);
+  }
+  // Types-only surface: no value exports (nothing that would emit runtime code).
+  assert.doesNotMatch(src, /^export\s+(?!type\b)/m, "worker.ts must be a types-only re-export");
+});

package/src/worker.ts

@@ -0,0 +1,21 @@
+// `@nanobpm/urban/worker` — the runtime-free worker-authoring surface.
+//
+// A service-task handler only needs a handful of *types*: the handler signature and the
+// shapes it is handed. Those all live under `runtime/core/`, which is guaranteed free of any
+// `node:*` import or `Deno` reference (the ADR 0052 purity invariant, enforced by
+// core/purity.test.ts). Importing them from the package barrel (`@nanobpm/urban`) instead
+// drags in `runtime/index.ts`, which re-exports the Node and Deno host adapters — so the
+// barrel's type graph transitively references `node:*` and a consumer must have `@types/node`
+// resolvable (or `skipLibCheck` on) just to typecheck a handler.
+//
+// This entry re-exports ONLY those core authoring types, so a worker module (e.g. a scaffolded
+// stub, ADR 0056) typechecks on Node or Deno, with or without `skipLibCheck`, and never needs
+// `@types/node`. It is types-only: nothing here emits runtime code.
+//
+// (One caveat: `AppApi.sdk` exposes the full `@nanobpm/nano-sdk` client by design, so the
+// handler surface also reaches the SDK's types. Those are kept node-free by the
+// `@nanobpm/nano-sdk` >= 1.2.2 floor in package.json — see ADR 0056.)
+
+export type { AppJobHandler } from "./runtime/core/modules/workers.ts";
+export type { EngineJob, JobHandler } from "./runtime/core/host.ts";
+export type { AppApi } from "./runtime/core/context.ts";