@nanobpm/urban 0.96.1 → 0.96.3

package/src/cli-lazy.test.ts

@@ -0,0 +1,172 @@
+// Module-load laziness guard for nanobpm/nano-ide#592: the CLI used to import the whole
+// toolkit (`create-urban-app`, `./toolkit/index.ts`) and the runtime barrel at the top of
+// cli.ts, so EVERY command — including the per-data-op `urban data` gateway — paid the full
+// load before dispatching. On small hosts that load is ~90% of a command's cost (measured:
+// ~2s CPU on a 4-core Atom vs ~0.1s bare Node start-up). The fix keeps only argument parsing
+// and stdio/guard helpers at the top level and dynamically imports each command's modules
+// inside its handler.
+//
+// These tests pin the laziness per command: they spawn the real CLI entrypoint with a
+// `--import` preload that registers a module-resolution hook recording every resolved URL,
+// then assert which module trees the command did NOT load.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { isRecord } from "./runtime/core/guards.ts";
+
+const cli = fileURLToPath(new URL("./cli.ts", import.meta.url));
+
+// Spawning with --experimental-strip-types runs the TypeScript source directly, so the test
+// exercises the authored cli.ts (no build step needed) — same as the >64 KB stdout test above.
+// bin.mjs is Node-only, so skip under Deno (`test:deno`), whose process.execPath is not Node.
+const runtimeIsNode = !("Deno" in globalThis);
+
+interface RunResult {
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  resolved: string[];
+}
+
+/**
+ * Spawn `cli.ts <args>` with a preload that records every module URL the process resolves.
+ * The preload registers a resolve hook (via `module.register`) on a loader thread that
+ * appends each resolved URL to a file; the parent then reads that file.
+ */
+async function runCliRecordingModules(
+  dir: string,
+  args: string[],
+  stdin: string,
+): Promise<RunResult> {
+  const resolvedFile = join(dir, "resolved.txt");
+  await writeFile(resolvedFile, "");
+  const hooks = join(dir, "hooks.mjs");
+  await writeFile(
+    hooks,
+    [
+      'import { appendFileSync } from "node:fs";',
+      `const file = ${JSON.stringify(resolvedFile)};`,
+      "export async function resolve(specifier, context, nextResolve) {",
+      "  const result = await nextResolve(specifier, context);",
+      "  try { appendFileSync(file, result.url + \"\\n\"); } catch {}",
+      "  return result;",
+      "}",
+      "",
+    ].join("\n"),
+  );
+  const preload = join(dir, "preload.mjs");
+  await writeFile(
+    preload,
+    [
+      'import { register } from "node:module";',
+      `register(${JSON.stringify(pathToFileURL(hooks).href)});`,
+      "",
+    ].join("\n"),
+  );
+
+  const { stdout, stderr, code } = await new Promise<{
+    stdout: Buffer;
+    stderr: Buffer;
+    code: number | null;
+  }>((resolve, reject) => {
+    const child = spawn(
+      process.execPath,
+      ["--experimental-strip-types", `--import=${pathToFileURL(preload).href}`, cli, ...args],
+      { stdio: ["pipe", "pipe", "pipe"] },
+    );
+    const out: Buffer[] = [];
+    const err: Buffer[] = [];
+    child.stdout.on("data", (c: Buffer) => out.push(c));
+    child.stderr.on("data", (c: Buffer) => err.push(c));
+    child.on("error", reject);
+    child.on("close", (code) =>
+      resolve({ stdout: Buffer.concat(out), stderr: Buffer.concat(err), code }),
+    );
+    child.stdin.end(stdin);
+  });
+
+  const { readFile } = await import("node:fs/promises");
+  const resolved = (await readFile(resolvedFile, "utf8")).split("\n").filter((l) => l.length > 0);
+  return { stdout: stdout.toString("utf8"), stderr: stderr.toString("utf8"), code, resolved };
+}
+
+/** Resolved URLs under the given package path fragments (the heavy module trees of #592). */
+function heavyLoads(resolved: string[]): string[] {
+  return resolved.filter(
+    (u) =>
+      // Node resolves a workspace package's node_modules symlink to its real target, so in a
+      // monorepo checkout `create-urban-app` resolves under `packages/create-urban-app/` — match
+      // both the installed and the workspace-real shape or a scaffold regression slips through.
+      u.includes("/node_modules/create-urban-app/") ||
+      u.includes("/packages/create-urban-app/") ||
+      u.includes("/dist/toolkit/") ||
+      u.includes("/src/toolkit/"),
+  );
+}
+
+test("urban data does not load the toolkit, scaffold or gen modules", {
+  skip: runtimeIsNode ? false : "Node-only: spawns cli.ts via process.execPath (Deno's execPath is not Node)",
+}, async () => {
+  const dir = await mkdtemp(join(tmpdir(), "urban-cli-lazy-data-"));
+  try {
+    // A parseable request, so cmdData gets past JSON.parse and actually runs the command-specific
+    // dynamic imports (host detector + data-op runner) — malformed JSON would return from the
+    // parse-error branch first and prove nothing about the data path's module graph. The root has
+    // no manifest, so the op still fails; the CLI answers with its parseable envelope and exits 0.
+    const { stdout, stderr, code, resolved } = await runCliRecordingModules(
+      dir,
+      ["data", "--root", dir],
+      JSON.stringify({ op: "sources" }),
+    );
+    assert.equal(code, 0, `CLI exited ${code}, expected 0. stderr:\n${stderr}`);
+    const reply: unknown = JSON.parse(stdout);
+    assert.ok(isRecord(reply));
+    assert.equal(reply.ok, false);
+
+    const heavy = heavyLoads(resolved);
+    assert.deepEqual(
+      heavy,
+      [],
+      `urban data eagerly loaded toolkit/scaffold modules:\n${heavy.join("\n")}`,
+    );
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("urban --version loads neither the toolkit nor the runtime modules", {
+  skip: runtimeIsNode ? false : "Node-only: spawns cli.ts via process.execPath (Deno's execPath is not Node)",
+}, async () => {
+  const dir = await mkdtemp(join(tmpdir(), "urban-cli-lazy-version-"));
+  try {
+    const { stdout, stderr, code, resolved } = await runCliRecordingModules(dir, ["--version"], "");
+    assert.equal(code, 0, `CLI exited ${code}, expected 0. stderr:\n${stderr}`);
+    assert.match(stdout, /^\d+\.\d+\.\d+/);
+
+    // The only runtime-tree modules the CLI itself may touch eagerly are its two tiny
+    // stdio/guard helpers — everything else under runtime/ (the barrel, run.ts, the data-op
+    // modules, the engine adapters, …) must stay unloaded until a command needs it.
+    const allowed = new Set(["/src/runtime/adapters/globals.ts", "/src/runtime/core/guards.ts"]);
+    const heavy = resolved.filter(
+      (u) =>
+        u.includes("/node_modules/create-urban-app/") ||
+        u.includes("/packages/create-urban-app/") ||
+        u.includes("/dist/toolkit/") ||
+        u.includes("/src/toolkit/") ||
+        ((u.includes("/dist/runtime/") || u.includes("/src/runtime/")) &&
+          ![...allowed].some((a) => u.endsWith(a))),
+    );
+    assert.deepEqual(
+      heavy,
+      [],
+      `urban --version eagerly loaded toolkit/runtime modules:\n${heavy.join("\n")}`,
+    );
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/cli.ts

@@ -11,22 +11,18 @@
 //
 // Global flags: --root <dir> (default "."), --manifest <file> (default nano.app.json),
 //               --port <n>, -h/--help, -v/--version.
+//
+// Module-load laziness (nano-ide#592): only argument parsing, the stdio/guard helpers and the
+// dispatcher load eagerly. Every command's modules are dynamically imported inside its handler —
+// a top-level import of the toolkit, the scaffold package or the runtime barrel made EVERY
+// command (including the per-data-op `urban data` gateway) pay the full ~2s load on small
+// hosts before dispatching. `urban data` loads only the host detector and the data-op runner.
+// Guarded by cli-lazy.test.ts, which records the URLs each command resolves.
 
-import {
-  collectManifestIssues,
-  installSignalHandlers,
-  loadManifest,
-  runDataOp,
-  runDev,
-  runFromEnv,
-  selectHost,
-} from "./runtime/index.ts";
 import { denoGlobal, processGlobal } from "./runtime/adapters/globals.ts";
 import type { WritableStdio } from "./runtime/adapters/globals.ts";
 import { errorMessage, isRecord } from "./runtime/core/guards.ts";
-import { scaffold, slugify } from "create-urban-app";
-import type { DataRequest } from "./runtime/index.ts";
-import { addConnector, createNodeGenIO, previewModels, generate, runGen } from "./toolkit/index.ts";
+import type { DataRequest } from "./runtime/core/modules/dataops.ts";
 import { pathToFileURL } from "node:url";
 import { readFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
@@ -132,6 +128,9 @@ Engine address: $CAMUNDA_REST_ADDRESS (default http://localhost:8080/v2).
 `;
 
 async function cmdCheck(f: Flags): Promise<number> {
+  const { selectHost } = await import("./runtime/adapters/detect.ts");
+  const { loadManifest } = await import("./runtime/core/manifest.ts");
+  const { collectManifestIssues } = await import("./runtime/core/validate.ts");
   // The host is anchored at f.root, so manifest paths are already root-relative —
   // pass the bare manifest filename (prefixing root again would double it).
   const host = selectHost({ cwd: f.root });
@@ -147,6 +146,7 @@ async function cmdCheck(f: Flags): Promise<number> {
 }
 
 async function cmdGen(f: Flags): Promise<number> {
+  const { createNodeGenIO, generate } = await import("./toolkit/index.ts");
   const io = createNodeGenIO();
   const res = await generate({ root: f.root, io, manifestFile: f.manifest, check: f.check, emitModels: f.models });
   if (res.incomplete) {
@@ -209,6 +209,7 @@ async function cmdDerive(f: Flags): Promise<number> {
     );
     return 2;
   }
+  const { createNodeGenIO, previewModels, runGen } = await import("./toolkit/index.ts");
   const io = createNodeGenIO();
 
   // Non-writing preview: emit `{ models: [{ id, kind, xml }], incomplete }` to stdout for the
@@ -250,6 +251,7 @@ async function cmdDerive(f: Flags): Promise<number> {
 }
 
 async function cmdRun(f: Flags, mount?: Record<string, boolean>): Promise<number> {
+  const { runFromEnv } = await import("./runtime/run.ts");
   const app = await runFromEnv({
     root: f.root,
     manifestPath: f.manifest,
@@ -262,12 +264,15 @@ async function cmdRun(f: Flags, mount?: Record<string, boolean>): Promise<number
 }
 
 async function cmdDev(f: Flags): Promise<number> {
+  const { runDev } = await import("./runtime/devserver.ts");
+  const { installSignalHandlers } = await import("./runtime/run.ts");
   const dev = await runDev({ root: f.root, manifestPath: f.manifest, port: f.port });
   installSignalHandlers(() => dev.stop());
   return -1; // keep the process alive; signal handlers stop the dev server
 }
 
 async function cmdDeploy(f: Flags): Promise<number> {
+  const { runFromEnv } = await import("./runtime/run.ts");
   const app = await runFromEnv({
     root: f.root,
     manifestPath: f.manifest,
@@ -322,6 +327,12 @@ export async function cmdData(f: Flags, readInput: () => Promise<string> = readS
     );
     return 0;
   }
+  // Lazily the only modules `urban data` loads (nano-ide#592): the host detector (both
+  // adapters, no toolkit) and the data-op runner (gateway + SQLite adapter; the toolkit
+  // derivers behind the `domaintypes` op load only when that op is dispatched). Imported
+  // directly rather than via the runtime barrel, which would pull in the whole runtime.
+  const { selectHost } = await import("./runtime/adapters/detect.ts");
+  const { runDataOp } = await import("./runtime/core/modules/dataops.ts");
   const host = selectHost({ cwd: f.root });
   try {
     // Mirror runFromEnv: the host is anchored at f.root, so pass root "." to avoid
@@ -342,6 +353,7 @@ async function cmdNew(f: Flags): Promise<number> {
     console.error("usage: urban new <name> [--root <path>] [--deno] [--style model|code] (or --code-first)");
     return 1;
   }
+  const { scaffold, slugify } = await import("create-urban-app");
   const dir = f.root !== "." ? f.root : `./${slugify(name)}`;
   const res = await scaffold({ name, dir, deno: f.deno, style: f.style });
   console.log(`✔ scaffolded "${res.id}" in ${res.dir} (${res.files.length} files)`);
@@ -380,6 +392,7 @@ async function cmdAdd(f: Flags): Promise<number> {
   }
 
   try {
+    const { addConnector, createNodeGenIO } = await import("./toolkit/index.ts");
     const result = await addConnector({
       root: f.root,
       pkg,

package/src/index.ts

@@ -31,6 +31,7 @@ export {
   declarativeToBpmn,
   declarativeToLayoutedBpmn,
   externalJobTypes,
+  inlineJobTypes,
   envelope,
   layoutBpmn,
   toBpmn,

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

@@ -27,43 +27,17 @@ import { validateManifest } from "../validate.ts";
 import { makeGateway, type DataSource as GatewayDataSource } from "./gateway.ts";
 import { applyMigrations, MIGRATIONS_TABLE, openSqliteSource, resolveAppPath } from "./datasource.ts";
 // The `domaintypes` op composes the domain reifier from the pure toolkit derivers (single source of
-// truth for the IDE's codegen, host dry-out nano-bpm#576). Imported directly from the deriver files
-// (not the `toolkit/` barrel, which pulls the Node fs IO) so core stays free of `node:*`/Deno; the
-// derivers' only core dependency is the gateway's `TableMeta`/`ColumnMeta` *types*, which erase.
-import { GENERATED_DIR } from "../../../toolkit/artifact.ts";
-import {
-  DOMAIN_BINDINGS,
-  type DomainTypeDef,
-  type DomainTypeRegistry,
-  emitDomainBindings,
-  emitDomainModel,
-  registryFromManifest,
-  type SourceSchema,
-} from "../../../toolkit/derivers/domain.ts";
-import {
-  DOMAIN_MODEL_JSON,
-  emitDomainModelJson,
-  type FusedMetaDecl,
-  resolveShapes,
-  type ShapeDecl,
-} from "../../../toolkit/derivers/shapes.ts";
-import {
-  DOMAIN_DTS,
-  emitWorkerBindings,
-  emitWorkerBindingsRuntime,
-  overlayDerivedWorkerIo,
-  WORKER_BINDINGS_DTS,
-  WORKER_BINDINGS_TS,
-  type WorkerBindingDecl,
-} from "../../../toolkit/derivers/worker-io.ts";
-import {
-  emitMessageBindings,
-  emitMessageBindingsRuntime,
-  MESSAGE_BINDINGS_DTS,
-  MESSAGE_BINDINGS_TS,
-  type MessageBindingDecl,
-} from "../../../toolkit/derivers/messages.ts";
-import { emitMeta, META_TS, type MetaDecl } from "../../../toolkit/derivers/meta.ts";
+// truth for the IDE's codegen, host dry-out nano-bpm#576). They are imported lazily inside the
+// `domaintypes` case — a static import would make EVERY `urban data` op (the latency-sensitive
+// gateway path, nano-ide#592) load the whole `src/toolkit/` tree before dispatching, when only
+// `domaintypes` ever runs a deriver. The derivers are pure (no host-specific IO); their only core
+// dependency is the gateway's `TableMeta`/`ColumnMeta` *types*, which erase. The deriver *types* the
+// request carries are type-only imports (erased), so they cost nothing at module load.
+import type { DomainTypeDef, DomainTypeRegistry, SourceSchema } from "../../../toolkit/derivers/domain.ts";
+import type { FusedMetaDecl, ShapeDecl } from "../../../toolkit/derivers/shapes.ts";
+import type { WorkerBindingDecl } from "../../../toolkit/derivers/worker-io.ts";
+import type { MessageBindingDecl } from "../../../toolkit/derivers/messages.ts";
+import type { MetaDecl } from "../../../toolkit/derivers/meta.ts";
 
 /** The DB-manager op protocol's known op set — every op (including `domaintypes`) is dispatched by
  * `runDataOp`. Typing `op` as this union (instead of `string`) gives SDK/console callers type-safety
@@ -349,6 +323,36 @@ export async function runDataOp(
       // debounced keystroke has no DB side-effect and pays only for `text` + `shapeDiagnostics`.
       const { default: def, sources } = listSources(manifest);
       const persist = req.write !== false;
+      // The derivers are the only toolkit modules `urban data` ever needs, and only this op runs
+      // them — load them here, not at module scope, so every other op (the hot path of the data
+      // gateway, nano-ide#592) never pays for the `src/toolkit/` tree. Imported directly from the
+      // deriver files (not the `toolkit/` barrel, which pulls the Node fs IO) so core stays free
+      // of host-specific IO.
+      const { GENERATED_DIR } = await import("../../../toolkit/artifact.ts");
+      const {
+        DOMAIN_BINDINGS,
+        emitDomainBindings,
+        emitDomainModel,
+        registryFromManifest,
+      } = await import("../../../toolkit/derivers/domain.ts");
+      const { DOMAIN_MODEL_JSON, emitDomainModelJson, resolveShapes } = await import(
+        "../../../toolkit/derivers/shapes.ts"
+      );
+      const {
+        DOMAIN_DTS,
+        emitWorkerBindings,
+        emitWorkerBindingsRuntime,
+        overlayDerivedWorkerIo,
+        WORKER_BINDINGS_DTS,
+        WORKER_BINDINGS_TS,
+      } = await import("../../../toolkit/derivers/worker-io.ts");
+      const {
+        emitMessageBindings,
+        emitMessageBindingsRuntime,
+        MESSAGE_BINDINGS_DTS,
+        MESSAGE_BINDINGS_TS,
+      } = await import("../../../toolkit/derivers/messages.ts");
+      const { emitMeta, META_TS } = await import("../../../toolkit/derivers/meta.ts");
       // Introspect each sqlite source's live schema. When persisting, migrate first (the domain
       // model is derived from `gw.schema()`, so a regen that raced ahead of `migrate` on a fresh DB
       // would emit an empty `Domain`); the migration runs on the shared `_urban_migrations` ledger.

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

@@ -13,7 +13,6 @@ import {
   type InsertObserver,
 } from "./gateway.ts";
 import { currentJobContext } from "../execContext.ts";
-import { isAbsolutePath } from "../../../toolkit/artifact.ts";
 import { SQL_IDENT, isReservedObjectName } from "../read-model.ts";
 
 export function sqlitePathFromUrl(url: string): string {
@@ -27,10 +26,14 @@ export function sqlitePathFromUrl(url: string): string {
  * that starts with a single backslash ("\data\app.db") and a Windows UNC path
  * ("\\\\server\\share"). A single leading backslash covers both the drive-root and UNC cases,
  * matching Node's `path.win32.isAbsolute`. Used by `resolveAppPath` so a caller-supplied absolute
- * path is never incorrectly prefixed with the app root. Defined once in `toolkit/artifact.ts` (the
- * shared, dependency-free layer) and re-exported here so the toolkit's gen path-join and this
- * runtime resolver apply the identical rule (no gen/runtime drift). */
-export { isAbsolutePath };
+ * path is never incorrectly prefixed with the app root. Defined here in the runtime (not imported
+ * from `toolkit/artifact.ts`) so the `urban data` gateway's static module graph never touches the
+ * `src/toolkit/` tree (nano-ide#592); `toolkit/artifact.ts` re-exports this definition so the
+ * toolkit's gen path-join and this runtime resolver apply the identical rule (no gen/runtime
+ * drift). */
+export function isAbsolutePath(p: string): boolean {
+  return /^(\/|\\|[A-Za-z]:[/\\])/.test(p);
+}
 
 /** Resolve `p` against the app `root`: an absolute `p` (see `isAbsolutePath`) is returned as-is;
  * a relative `p` is joined onto `root`. Trims a trailing separator of either kind off `root` so

package/src/toolkit/artifact.ts

@@ -48,9 +48,9 @@ export function sortArtifacts(a: DerivedArtifact[]): DerivedArtifact[] {
 }
 
 /** True when `p` is an absolute path — POSIX root (`/`), a drive-letter root (`C:\` or `C:/`), or a
- *  Windows UNC/drive-root backslash (`\`). The single source of truth for the absolute-path rule,
- *  shared by the toolkit's path join (gen.ts) and the runtime's resolveAppPath so both agree on
- *  whether a manifest path is app-root-relative or absolute (no gen/runtime drift). */
-export function isAbsolutePath(p: string): boolean {
-  return /^(\/|\\|[A-Za-z]:[/\\])/.test(p);
-}
+ *  Windows UNC/drive-root backslash (`\`). The single source of truth for the absolute-path rule is
+ *  the runtime's `resolveAppPath` side (`runtime/core/modules/datasource.ts`); it is re-exported
+ *  here so the toolkit's path join (gen.ts) and the runtime resolver agree on whether a manifest
+ *  path is app-root-relative or absolute (no gen/runtime drift) without the runtime's data gateway
+ *  statically importing the toolkit tree (nano-ide#592). */
+export { isAbsolutePath } from "../runtime/core/modules/datasource.ts";

package/src/toolkit/gen.ts

@@ -65,6 +65,16 @@ export interface GenResult {
   incomplete: boolean;
   /** Per-file model-derivation errors (empty on success). */
   modelErrors: ModelError[];
+  /** Job types of inline-handled (`w.run`) code-first steps — the set the app's in-process
+   *  Worker already serves (nano-ide#595). The worker-stub scaffolder skips these; empty for a
+   *  model-first app. */
+  inlineTaskTypes: string[];
+  /** The code-first models derived in-memory this run (`deriveModels().models`) — the
+   *  worker-stub scaffolder plans against these in addition to the on-disk models, since a
+   *  declared `models` block (e.g. `models.workflows`) suppresses the `resources/` convention
+   *  scan that would otherwise pick the written `.bpmn` up (nano-ide#595). Empty for a
+   *  model-first app. */
+  derivedModels: ModelSource[];
   /** Non-fatal spec-hygiene warnings (e.g. a requestBody schema shared by >1 operation). Empty on
    *  a clean spec. Surfaced by the CLI but never fail gen/check — advisory only. */
   warnings: string[];
@@ -76,7 +86,8 @@ function join(root: string, rel: string): string {
   // pass either style without gen/runtime drift over where a file resolves.
   const norm = (s: string): string => s.replace(/\\/g, "/");
   // An absolute `rel` resolves to itself — never prefixed with `root` — mirroring the runtime's
-  // resolveAppPath (isAbsolutePath is the shared SoT in artifact.ts). Without this an absolute
+  // resolveAppPath (isAbsolutePath is the shared SoT, defined in runtime's datasource.ts and
+  // re-exported from artifact.ts). Without this an absolute
   // manifest path (e.g. "/abs/openapi.json") would be stripped to root-relative and gen would
   // read/derive a different file than the runtime resolves. Trailing edge separators are still
   // trimmed for stable, comparable artifact keys.
@@ -332,7 +343,7 @@ export async function runGen(opts: GenOptions & { check?: boolean }): Promise<Ge
     }
   }
 
-  return { artifacts, drift, swept: swept.sort(), incomplete: derived.incomplete, modelErrors: derived.errors, warnings };
+  return { artifacts, drift, swept: swept.sort(), incomplete: derived.incomplete, modelErrors: derived.errors, inlineTaskTypes: derived.inlineTaskTypes, derivedModels: derived.models, warnings };
 }
 
 export { dirOf, join as joinPath };

package/src/toolkit/generate.test.ts

@@ -2,9 +2,13 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import { generate } from "./generate.ts";
 import type { GenIO } from "./gen.ts";
+import { defineFlow, envelope } from "@nanobpm/workflow";
 
 /** In-memory filesystem mirroring gen.test.ts's memIO (IO-free, deterministic). */
-function memIO(files: Record<string, string>): GenIO & { files: Record<string, string> } {
+function memIO(
+  files: Record<string, string>,
+  modules: Record<string, Record<string, unknown>> = {},
+): GenIO & { files: Record<string, string> } {
   return {
     files,
     async readText(p) {
@@ -25,12 +29,28 @@ function memIO(files: Record<string, string>): GenIO & { files: Record<string, s
       }
       return [...names];
     },
+    async listSubdirs(p) {
+      const prefix = p.replace(/\/+$/, "") + "/";
+      const names = new Set<string>();
+      for (const f of Object.keys(files)) {
+        if (f.startsWith(prefix)) {
+          const rest = f.slice(prefix.length);
+          const slash = rest.indexOf("/");
+          if (slash > 0) names.add(rest.slice(0, slash));
+        }
+      }
+      return [...names];
+    },
     async exists(p) {
       return p in files;
     },
     async remove(p) {
       delete files[p];
     },
+    async importModule(p) {
+      if (!(p in modules)) throw new Error(`no module registered for ${p}`);
+      return modules[p];
+    },
   };
 }
 
@@ -133,3 +153,68 @@ test("generate keeps existing human-owned stubs (write-once, never clobbered)",
   assert.deepEqual(res.operationStubs.map((s) => s.status), ["kept"]);
   assert.deepEqual(res.missingStubs, []);
 });
+
+// --- code-first: w.run steps are inline-handled, so gen must never scaffold stubs for them ---
+
+const GreetIn = envelope("GreetIn", { who: "string" });
+const GreetOut = envelope("GreetOut", { message: "string" });
+
+/** The stock code-first template's flow: one inline-handled `w.run` step (nano-ide#595's repro). */
+const greetFlow = defineFlow("greet", { hello: { in: GreetIn, out: GreetOut } }, (w) => {
+  w.run("hello", async () => ({ message: "hi" }));
+});
+
+test("generate on a code-first app scaffolds NO stub for an inline w.run step (nano-ide#595)", async () => {
+  // The stock code-first app (create-urban-app --code-first): `greet:hello` is served by
+  // `w.run("hello", …)` and hosted in-process by main.ts's Worker. Scaffolding a throwing stub
+  // for it puts a second, always-failing worker on the same job type.
+  const io = memIO(
+    {
+      "/cf/nano.app.json": JSON.stringify({
+        id: "cf",
+        data: { default: "app" },
+        models: { workflows: ["workflows/*.ts"] },
+      }),
+      "/cf/workflows/greet.ts": "// derived in-memory via importModule stub",
+    },
+    { "/cf/workflows/greet.ts": { greet: greetFlow } },
+  );
+
+  const res = await generate({ root: "/cf", io });
+
+  assert.equal(res.incomplete, false);
+  assert.deepEqual(res.workerStubs, [], "no worker stub is scaffolded for an inline-handled step");
+  assert.deepEqual(res.wiredWorkers, [], "nothing is wired into workers[]");
+  assert.equal(res.manifestPatched, false, "the manifest is untouched");
+  assert.equal(io.files["/cf/workers/greet-hello/worker.ts"], undefined, "no throwing stub on disk");
+  const manifest = JSON.parse(io.files["/cf/nano.app.json"]);
+  assert.equal(manifest.workers, undefined, "workers[] stays undeclared");
+  // The model itself is still derived and written.
+  assert.ok(io.files["/cf/resources/processes/greet.bpmn"], "the derived .bpmn still lands");
+});
+
+test("generate on a code-first app still scaffolds a stub for an external w.task step", async () => {
+  // The other half of the split: only `w.run` steps are inline; a `w.task` step has no in-process
+  // handler, so it still needs its write-once stub.
+  const flow = defineFlow("orders", (w) => {
+    w.run("charge", async () => ({}));
+    w.task("sign"); // external worker
+  });
+  const io = memIO(
+    {
+      "/cf/nano.app.json": JSON.stringify({
+        id: "cf",
+        data: { default: "app" },
+        models: { workflows: ["workflows/*.ts"] },
+      }),
+      "/cf/workflows/orders.ts": "// derived in-memory via importModule stub",
+    },
+    { "/cf/workflows/orders.ts": { flow } },
+  );
+
+  const res = await generate({ root: "/cf", io });
+
+  assert.deepEqual(res.workerStubs.map((s) => s.taskType), ["orders:sign"]);
+  assert.ok(io.files["/cf/workers/orders-sign/worker.ts"], "external task gets its stub");
+  assert.equal(io.files["/cf/workers/orders-charge/worker.ts"], undefined, "inline step gets none");
+});

package/src/toolkit/generate.ts

@@ -52,7 +52,15 @@ export async function generate(opts: GenOptions & { check?: boolean }): Promise<
 
   const write = !opts.check;
   const scaffoldOpts = { root: opts.root, io: opts.io, manifestFile: opts.manifestFile, write };
-  const workers = await scaffoldWorkers(scaffoldOpts);
+  // Inline-handled (`w.run`) steps are already served by the app's in-process Worker — never
+  // scaffold a competing throwing stub for them (nano-ide#595). The derived models are also
+  // handed over: a code-first manifest's declared `models` block suppresses the resources/
+  // convention scan in readModels, so without them the scaffolder would plan from nothing.
+  const workers = await scaffoldWorkers({
+    ...scaffoldOpts,
+    inlineTaskTypes: res.inlineTaskTypes,
+    extraModels: res.derivedModels,
+  });
   const operations = await scaffoldOperations(scaffoldOpts);
 
   const missingStubs = [

package/src/toolkit/models.test.ts

@@ -157,3 +157,24 @@ test("deriveModels treats a genuine same-module re-export as one model, no error
   assert.deepEqual(d.errors, []);
   assert.equal(d.ids.length, 1);
 });
+
+test("deriveModels reports the inline-handled (w.run) task types alongside the model (nano-ide#595)", async () => {
+  // The worker-stub scaffolder consumes `inlineTaskTypes` to skip steps whose handler is hosted
+  // in-process by the flow's Worker — only `w.task` (external) steps may be scaffolded.
+  const mixed = defineFlow("orders", (w) => {
+    w.run("charge", async () => ({}));
+    w.task("sign"); // external — must NOT be reported inline
+    w.run("ship", async () => ({}));
+  });
+  const io = memIO(
+    { "/app/workflows/orders.ts": "// source" },
+    { "workflows/orders.ts": { mixed } },
+  );
+  const d = await deriveModels("/app", io, CODE_FIRST_MANIFEST);
+  assert.equal(d.incomplete, false);
+  assert.deepEqual(d.inlineTaskTypes.sort(), ["orders:charge", "orders:ship"]);
+  // A no-op derivation (no loader / no workflow files) reports an empty set, not undefined.
+  const noLoader = memIO({ "/app/workflows/orders.ts": "// source" });
+  delete noLoader.importModule;
+  assert.deepEqual((await deriveModels("/app", noLoader, CODE_FIRST_MANIFEST)).inlineTaskTypes, []);
+});

package/src/toolkit/models.ts

@@ -9,7 +9,7 @@
 // loader is absent — or the app authors its models directly (model-first) — derivation is a
 // no-op and the rest of `urban gen` proceeds on the authored/derived models unchanged.
 
-import { toDeployableBpmn } from "@nanobpm/workflow";
+import { inlineJobTypes, toDeployableBpmn } from "@nanobpm/workflow";
 import type { Workflow } from "@nanobpm/workflow";
 import type { DerivedArtifact } from "./artifact.ts";
 import type { GenIO } from "./gen.ts";
@@ -78,6 +78,13 @@ export interface DerivedModels {
   models: ModelSource[];
   /** Derived flow ids (used for the provenance-scoped stale sweep). */
   ids: string[];
+  /** Job types of inline-handled (`w.run`) steps across every derived declarative flow —
+   *  the set the app's in-process Worker already serves (nano-ide#595). The worker-stub
+   *  scaffolder skips these; only `w.task` (external) steps may be scaffolded. Empty when
+   *  derivation was a no-op (no loader / no workflow files) or all flows are imperative
+   *  (an imperative flow's steps run inside its single `:__orchestrate` job, which the
+   *  planner already skips). */
+  inlineTaskTypes: string[];
   /** Per-flow `{ id, kind, xml }` for the non-writing preview (`urban derive --stdout`). */
   list: DerivedModelInfo[];
   /** The output directory the artifacts were written into. */
@@ -101,6 +108,7 @@ function emptyDerived(outDir: string): DerivedModels {
     artifacts: [],
     models: [],
     ids: [],
+    inlineTaskTypes: [],
     list: [],
     outDir,
     attempted: false,
@@ -184,6 +192,7 @@ export async function deriveModels(
         const path = `${outDir}/${bpmnFilename(id)}`;
         out.artifacts.push({ path, content: xml });
         out.models.push({ path, xml });
+        if (value.kind === "declarative") out.inlineTaskTypes.push(...inlineJobTypes(value));
         out.list.push({ id, kind: value.kind, xml });
         out.ids.push(id);
       } catch (e) {