@nanobpm/urban 0.96.1 → 0.96.2

package/dist/cli.js

@@ -11,11 +11,15 @@
 //
 // Global flags: --root <dir> (default "."), --manifest <file> (default nano.app.json),
 //               --port <n>, -h/--help, -v/--version.
-import { collectManifestIssues, installSignalHandlers, loadManifest, runDataOp, runDev, runFromEnv, selectHost, } from "./runtime/index.js";
+//
+// 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 { denoGlobal, processGlobal } from "./runtime/adapters/globals.js";
 import { errorMessage, isRecord } from "./runtime/core/guards.js";
-import { scaffold, slugify } from "create-urban-app";
-import { addConnector, createNodeGenIO, previewModels, generate, runGen } from "./toolkit/index.js";
 import { pathToFileURL } from "node:url";
 import { readFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
@@ -119,6 +123,9 @@ Global flags:
 Engine address: $CAMUNDA_REST_ADDRESS (default http://localhost:8080/v2).
 `;
 async function cmdCheck(f) {
+    const { selectHost } = await import("./runtime/adapters/detect.js");
+    const { loadManifest } = await import("./runtime/core/manifest.js");
+    const { collectManifestIssues } = await import("./runtime/core/validate.js");
     // 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 });
@@ -134,6 +141,7 @@ async function cmdCheck(f) {
     return 1;
 }
 async function cmdGen(f) {
+    const { createNodeGenIO, generate } = await import("./toolkit/index.js");
     const io = createNodeGenIO();
     const res = await generate({ root: f.root, io, manifestFile: f.manifest, check: f.check, emitModels: f.models });
     if (res.incomplete) {
@@ -198,6 +206,7 @@ async function cmdDerive(f) {
         console.error("✖ `urban derive` derives models — `--no-models` is contradictory. Use `urban gen --no-models` for type-contracts only.");
         return 2;
     }
+    const { createNodeGenIO, previewModels, runGen } = await import("./toolkit/index.js");
     const io = createNodeGenIO();
     // Non-writing preview: emit `{ models: [{ id, kind, xml }], incomplete }` to stdout for the
     // console's read-only model viewer (never touches `processes/`).
@@ -238,6 +247,7 @@ async function cmdDerive(f) {
     return 0;
 }
 async function cmdRun(f, mount) {
+    const { runFromEnv } = await import("./runtime/run.js");
     const app = await runFromEnv({
         root: f.root,
         manifestPath: f.manifest,
@@ -249,11 +259,14 @@ async function cmdRun(f, mount) {
     return -1; // keep the process alive; signal handlers stop it
 }
 async function cmdDev(f) {
+    const { runDev } = await import("./runtime/devserver.js");
+    const { installSignalHandlers } = await import("./runtime/run.js");
     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) {
+    const { runFromEnv } = await import("./runtime/run.js");
     const app = await runFromEnv({
         root: f.root,
         manifestPath: f.manifest,
@@ -306,6 +319,12 @@ export async function cmdData(f, readInput = readStdin) {
         }));
         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.js");
+    const { runDataOp } = await import("./runtime/core/modules/dataops.js");
     const host = selectHost({ cwd: f.root });
     try {
         // Mirror runFromEnv: the host is anchored at f.root, so pass root "." to avoid
@@ -324,6 +343,7 @@ async function cmdNew(f) {
         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)`);
@@ -362,6 +382,7 @@ async function cmdAdd(f) {
         }
     }
     try {
+        const { addConnector, createNodeGenIO } = await import("./toolkit/index.js");
         const result = await addConnector({
             root: f.root,
             pkg,

package/dist/runtime/core/modules/dataops.d.ts

@@ -1,9 +1,9 @@
 import type { HostContext } from "../host.ts";
 import type { AppManifest } from "../manifest.ts";
-import { type 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";
+import type { 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
  * and catches typos at compile time. */

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

@@ -23,16 +23,6 @@ import { loadManifest } from "../manifest.js";
 import { validateManifest } from "../validate.js";
 import { makeGateway } from "./gateway.js";
 import { applyMigrations, MIGRATIONS_TABLE, openSqliteSource, resolveAppPath } from "./datasource.js";
-// 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.js";
-import { DOMAIN_BINDINGS, emitDomainBindings, emitDomainModel, registryFromManifest, } from "../../../toolkit/derivers/domain.js";
-import { DOMAIN_MODEL_JSON, emitDomainModelJson, resolveShapes, } from "../../../toolkit/derivers/shapes.js";
-import { DOMAIN_DTS, emitWorkerBindings, emitWorkerBindingsRuntime, overlayDerivedWorkerIo, WORKER_BINDINGS_DTS, WORKER_BINDINGS_TS, } from "../../../toolkit/derivers/worker-io.js";
-import { emitMessageBindings, emitMessageBindingsRuntime, MESSAGE_BINDINGS_DTS, MESSAGE_BINDINGS_TS, } from "../../../toolkit/derivers/messages.js";
-import { emitMeta, META_TS } from "../../../toolkit/derivers/meta.js";
 const DEFAULT_MIGRATIONS_DIR = "db/migrations";
 /** JSON-safe a value: BigInt → number (when lossless) or string, recursing objects/arrays. SQLite
  * reports `lastInsertRowid` (and INTEGER columns) as BigInt, which `JSON.stringify` cannot encode. */
@@ -242,6 +232,17 @@ export async function runDataOp(host, root, manifestPath, req) {
             // 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.js");
+            const { DOMAIN_BINDINGS, emitDomainBindings, emitDomainModel, registryFromManifest, } = await import("../../../toolkit/derivers/domain.js");
+            const { DOMAIN_MODEL_JSON, emitDomainModelJson, resolveShapes } = await import("../../../toolkit/derivers/shapes.js");
+            const { DOMAIN_DTS, emitWorkerBindings, emitWorkerBindingsRuntime, overlayDerivedWorkerIo, WORKER_BINDINGS_DTS, WORKER_BINDINGS_TS, } = await import("../../../toolkit/derivers/worker-io.js");
+            const { emitMessageBindings, emitMessageBindingsRuntime, MESSAGE_BINDINGS_DTS, MESSAGE_BINDINGS_TS, } = await import("../../../toolkit/derivers/messages.js");
+            const { emitMeta, META_TS } = await import("../../../toolkit/derivers/meta.js");
             // 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/dist/runtime/core/modules/datasource.d.ts

@@ -2,7 +2,6 @@ import type { RuntimeContext } from "../context.ts";
 import type { HostContext, SqliteDb } from "../host.ts";
 import type { DomainType } from "../manifest.ts";
 import { Table, type DataSource as GatewayDataSource, type InsertObserver } from "./gateway.ts";
-import { isAbsolutePath } from "../../../toolkit/artifact.ts";
 export declare function sqlitePathFromUrl(url: string): string;
 /** True when `p` is already an absolute path on any host `urban data` targets. `urban data` runs
  * on a Node host that may be Windows, so absolute-path detection can't assume POSIX: this matches
@@ -10,10 +9,12 @@ export declare 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 declare function isAbsolutePath(p: string): boolean;
 /** 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
  * we never emit a doubled separator. The join separator matches the root's own style so we never

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

@@ -4,7 +4,6 @@
 // runtime side of ADR 0024 (datasource) + ADR 0040 (domain model), scoped to what an app needs.
 import { makeGateway, } from "./gateway.js";
 import { currentJobContext } from "../execContext.js";
-import { isAbsolutePath } from "../../../toolkit/artifact.js";
 import { SQL_IDENT, isReservedObjectName } from "../read-model.js";
 export function sqlitePathFromUrl(url) {
     // Accept "file:./x.db", "file:x.db", "sqlite:./x.db" or a bare path.
@@ -16,10 +15,14 @@ export function sqlitePathFromUrl(url) {
  * 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) {
+    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
  * we never emit a doubled separator. The join separator matches the root's own style so we never

package/dist/toolkit/artifact.d.ts

@@ -29,7 +29,9 @@ export declare const RUNTIME_MATERIALIZED_ARTIFACTS: readonly string[];
 /** Stable ordering so artifact lists compare deterministically. */
 export declare 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 declare function isAbsolutePath(p: string): boolean;
+ *  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/dist/toolkit/artifact.js

@@ -28,9 +28,9 @@ export function sortArtifacts(a) {
     return [...a].sort((x, y) => (x.path < y.path ? -1 : x.path > y.path ? 1 : 0));
 }
 /** 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) {
-    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.js";

package/dist/toolkit/gen.js

@@ -19,7 +19,8 @@ function join(root, rel) {
     // pass either style without gen/runtime drift over where a file resolves.
     const norm = (s) => 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.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.96.1",
+	"version": "0.96.2",
 	"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/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/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

@@ -76,7 +76,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.