@nanobpm/urban 0.17.1 → 0.18.0

package/dist/cli.js

@@ -2,7 +2,8 @@
 //
 //   urban new <name>     scaffold a new app (delegates to create-urban-app)
 //   urban check          load + validate the manifest, report issues
-//   urban gen            derive generated artifacts (migrations, worker I/O)
+//   urban gen            derive generated artifacts (migrations, worker I/O, code-first models)
+//   urban derive         derive code-first models only (workflows/*.ts → processes/*.bpmn)
 //   urban run            materialize + serve the app (deploy, data, workers, surfaces, triggers)
 //   urban dev            like run, plus watch sources and hot-reload on change
 //   urban deploy         deploy models only, then exit
@@ -11,7 +12,7 @@
 //               --port <n>, -h/--help, -v/--version.
 import { collectManifestIssues, installSignalHandlers, loadManifest, runDev, runFromEnv, selectHost, } from "./runtime/index.js";
 import { scaffold, slugify } from "create-urban-app";
-import { createNodeGenIO, runGen, scaffoldWorkers } from "./toolkit/index.js";
+import { createNodeGenIO, previewModels, runGen, scaffoldWorkers } from "./toolkit/index.js";
 import { pathToFileURL } from "node:url";
 import { readFileSync } from "node:fs";
 // Read the package version from package.json (one hop up from both src/cli.ts and the
@@ -27,7 +28,7 @@ function readVersion() {
 }
 const VERSION = readVersion();
 function parse(argv) {
-    const f = { root: ".", manifest: "nano.app.json", check: false, write: false, deno: false, help: false, version: false, _: [] };
+    const f = { root: ".", manifest: "nano.app.json", check: false, write: false, deno: false, models: true, stdout: false, help: false, version: false, _: [] };
     const need = (i, flag) => {
         const v = argv[i];
         if (v === undefined || v.startsWith("-"))
@@ -46,6 +47,12 @@ function parse(argv) {
             f.write = true;
         else if (a === "--deno")
             f.deno = true;
+        else if (a === "--no-models")
+            f.models = false;
+        else if (a === "--models")
+            f.models = true;
+        else if (a === "--stdout")
+            f.stdout = true;
         else if (a === "--code-first")
             f.style = "code";
         else if (a === "--style") {
@@ -81,7 +88,10 @@ Usage:
   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 gen [--check] [--no-models] derive artifacts (migrations, worker-io, + code-first models)
+                                    (--no-models: skip writing derived .bpmn; type-contracts only)
+  urban derive [--check|--stdout]   derive code-first models only (workflows/*.ts → processes/*.bpmn)
+                                    (--stdout: print {models,incomplete} JSON without writing)
   urban stubs [--write]             scaffold write-once handler stubs from the model
   urban run                         materialize + serve the app
   urban dev                         run + watch sources, hot-reload on change
@@ -113,7 +123,13 @@ async function cmdCheck(f) {
 }
 async function cmdGen(f) {
     const io = createNodeGenIO();
-    const res = await runGen({ root: f.root, io, manifestFile: f.manifest, check: f.check });
+    const res = await runGen({ root: f.root, io, manifestFile: f.manifest, check: f.check, emitModels: f.models });
+    if (res.incomplete) {
+        console.error(`✖ ${res.modelErrors.length} workflow(s) failed to derive:`);
+        for (const e of res.modelErrors)
+            console.error(`  • ${e.path}: ${e.message}`);
+        return 1;
+    }
     if (f.check) {
         if (res.drift.length === 0) {
             console.log(`✔ generated artifacts are up to date (${res.artifacts.length} checked)`);
@@ -129,6 +145,52 @@ async function cmdGen(f) {
         console.log(`  • ${a.path}`);
     return 0;
 }
+async function cmdDerive(f) {
+    // `urban derive` IS model derivation, so `--no-models` is contradictory. Reject it explicitly
+    // rather than silently ignoring it (flags are global, so it's easy to pass by accident).
+    if (!f.models) {
+        console.error("✖ `urban derive` derives models — `--no-models` is contradictory. Use `urban gen --no-models` for type-contracts only.");
+        return 2;
+    }
+    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/`).
+    if (f.stdout) {
+        const d = await previewModels({ root: f.root, io, manifestFile: f.manifest });
+        process.stdout.write(JSON.stringify({
+            models: d.list.map((m) => ({ id: m.id, kind: m.kind, xml: m.xml })),
+            incomplete: d.incomplete,
+        }) + "\n");
+        if (d.incomplete) {
+            for (const e of d.errors)
+                console.error(`  • ${e.path}: ${e.message}`);
+            return 1;
+        }
+        return 0;
+    }
+    // Derive + write models only (skip the type-contract derivers); `generate_models` delegates here.
+    const res = await runGen({ root: f.root, io, manifestFile: f.manifest, check: f.check, modelsOnly: true });
+    if (res.incomplete) {
+        console.error(`✖ ${res.modelErrors.length} workflow(s) failed to derive:`);
+        for (const e of res.modelErrors)
+            console.error(`  • ${e.path}: ${e.message}`);
+        return 1;
+    }
+    if (f.check) {
+        if (res.drift.length === 0) {
+            console.log(`✔ derived models are up to date (${res.artifacts.length} checked)`);
+            return 0;
+        }
+        console.error(`✖ ${res.drift.length} derived model(s) are out of date — run \`urban derive\`:`);
+        for (const p of res.drift)
+            console.error(`  • ${p}`);
+        return 1;
+    }
+    console.log(`✔ derived ${res.artifacts.length} model(s):`);
+    for (const a of res.artifacts)
+        console.log(`  • ${a.path}`);
+    return 0;
+}
 async function cmdStubs(f) {
     const io = createNodeGenIO();
     const run = await scaffoldWorkers({ root: f.root, io, manifestFile: f.manifest, write: f.write });
@@ -232,6 +294,8 @@ export async function main(argv) {
             return cmdCheck(f);
         case "gen":
             return cmdGen(f);
+        case "derive":
+            return cmdDerive(f);
         case "stubs":
             return cmdStubs(f);
         case "run":

package/dist/toolkit/fsio.js

@@ -1,7 +1,16 @@
 // Node/Deno filesystem implementation of the GenIO port. Uses node:fs/promises, which both
 // Node and Deno provide, so a single implementation serves both runtimes.
-import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 export function createNodeGenIO() {
     return {
         async readText(path) {
@@ -31,5 +40,25 @@ export function createNodeGenIO() {
                 return false;
             }
         },
+        async remove(path) {
+            await rm(path, { force: true });
+        },
+        // Import an app module for code-first model derivation. `import()` of a file URL loads TS on
+        // Deno natively and on Node with type-stripping (≥22.18 default, or `--experimental-strip-types`).
+        // The cache key is the file's mtime, not a monotonic clock: an unchanged workflow reuses the
+        // cached module instance (bounding the ESM module map in long-lived processes like `urban dev`)
+        // while an edited one still reloads.
+        async importModule(path) {
+            const abs = resolve(path);
+            let version = "";
+            try {
+                version = `?v=${(await stat(abs)).mtimeMs}`;
+            }
+            catch {
+                // stat failed (e.g. a virtual path); fall back to no cache key and let import() surface it.
+            }
+            const href = `${pathToFileURL(abs).href}${version}`;
+            return import(__rewriteRelativeImportExtension(href));
+        },
     };
 }

package/dist/toolkit/gen.d.ts

@@ -1,5 +1,6 @@
 import type { DerivedArtifact } from "./artifact.ts";
 import { type ModelSource } from "./derivers/worker-io.ts";
+import { type DerivedModels, type ModelError } from "./models.ts";
 /** Minimal filesystem port. Node/Deno impls live in `fsio.ts`. */
 export interface GenIO {
     readText(path: string): Promise<string>;
@@ -7,19 +8,43 @@ export interface GenIO {
     /** File names (not paths) in a directory; empty if it does not exist. */
     listDir(path: string): Promise<string[]>;
     exists(path: string): Promise<boolean>;
+    /**
+     * Import an app module and return its exports. Optional: only present when the caller runs on
+     * a runtime that can load the app's TypeScript (Node with type-stripping, or Deno). Code-first
+     * model derivation (`workflows/*.ts` → BPMN) needs it; when absent, gen still derives everything
+     * else (migrations, domain, worker I/O from authored/derived models).
+     */
+    importModule?(path: string): Promise<Record<string, unknown>>;
+    /** Delete a file. Optional: enables the provenance-scoped stale-model sweep (skipped when absent). */
+    remove?(path: string): Promise<void>;
 }
 export interface GenOptions {
     root: string;
     io: GenIO;
     manifestFile?: string;
+    /**
+     * Whether to emit (write) derived `.bpmn` models. Default true. When false, code-first models
+     * are still derived *in-memory* to feed the type-contract derivers (worker I/O, meta, messages)
+     * — they are just not written to disk or swept. This is the `urban gen --no-models` path, so
+     * the console's type-contract regen never mutates `processes/*.bpmn`.
+     */
+    emitModels?: boolean;
+    /** Derive ONLY the models (skip migrations/domain/worker-I/O). The `urban derive` path. */
+    modelsOnly?: boolean;
 }
 export interface GenResult {
     artifacts: DerivedArtifact[];
     /** Paths that differ from disk (only populated by `check`). */
     drift: string[];
+    /** True if any code-first workflow failed to import/derive. */
+    incomplete: boolean;
+    /** Per-file model-derivation errors (empty on success). */
+    modelErrors: ModelError[];
 }
 declare function join(root: string, rel: string): string;
 declare function dirOf(p: string): string;
+/** Resolve a `dir/*.ext` (or literal) manifest pattern to file paths relative to root. */
+export declare function expandPattern(root: string, io: GenIO, pattern: string): Promise<string[]>;
 /** Read + resolve the app's process models from the manifest's `models.processes` patterns. */
 export declare function readModels(root: string, io: GenIO, manifest: {
     models?: {
@@ -33,3 +58,6 @@ export declare function runGen(opts: GenOptions & {
     check?: boolean;
 }): Promise<GenResult>;
 export { dirOf, join as joinPath };
+/** Derive code-first models in-memory (no writes) — backs `urban derive --stdout`, the
+ * non-mutating preview the console's read-only model viewer uses. */
+export declare function previewModels(opts: GenOptions): Promise<DerivedModels>;

package/dist/toolkit/gen.js

@@ -8,6 +8,7 @@ import { deriveDomain } from "./derivers/domain.js";
 import { deriveWorkerBindings } from "./derivers/worker-io.js";
 import { deriveMeta } from "./derivers/meta.js";
 import { deriveMessageBindings } from "./derivers/messages.js";
+import { deriveModels, MODEL_PROVENANCE } from "./models.js";
 function join(root, rel) {
     // Trim either separator so callers may pass Windows-style paths; GenIO
     // implementations accept forward slashes on all platforms.
@@ -18,7 +19,7 @@ function dirOf(p) {
     return i <= 0 ? "." : p.slice(0, i);
 }
 /** Resolve a `dir/*.ext` (or literal) manifest pattern to file paths relative to root. */
-async function expandPattern(root, io, pattern) {
+export async function expandPattern(root, io, pattern) {
     const star = pattern.indexOf("*");
     if (star === -1) {
         return (await io.exists(join(root, pattern))) ? [pattern] : [];
@@ -46,29 +47,47 @@ export async function readModels(root, io, manifest) {
 }
 /** Collect all artifacts a run would produce, without touching disk beyond reads. */
 export async function collectArtifacts(opts) {
+    return (await collectAll(opts)).artifacts;
+}
+/** Internal: collect artifacts AND the model-derivation details (needed by `runGen` for the
+ * incomplete signal + the provenance-scoped stale sweep). */
+async function collectAll(opts) {
     const { root, io } = opts;
+    const emitModels = opts.emitModels ?? true;
     const manifestPath = join(root, opts.manifestFile ?? "nano.app.json");
     const manifest = JSON.parse(await io.readText(manifestPath));
     const artifacts = [];
     // 1. types → migrations + domain row types (DomainTables spine + DomainTypes registry)
-    if (manifest.types && Object.keys(manifest.types).length > 0) {
+    if (!opts.modelsOnly && manifest.types && Object.keys(manifest.types).length > 0) {
         artifacts.push(...deriveMigrations(manifest));
         artifacts.push(...deriveDomain(manifest));
     }
-    // 2. models → worker I/O index + model-metadata accessor + message payload map
-    const models = await readModels(root, io, manifest);
-    if (models.length > 0) {
-        const declaredTypeIds = Object.keys(manifest.types ?? {});
-        artifacts.push(...deriveWorkerBindings(models, declaredTypeIds));
-        artifacts.push(...deriveMeta(models));
-        artifacts.push(...deriveMessageBindings(models, declaredTypeIds));
+    // 2. code-first models → derive BPMN from `workflows/*.ts` (executes the app's TS). The derived
+    //    `.bpmn` are emitted only when `emitModels` (default), but always fed to the type-contract
+    //    derivers below so worker I/O works for a code-first app even on a `--no-models` run.
+    const derived = await deriveModels(root, io, manifest);
+    if (emitModels)
+        artifacts.push(...derived.artifacts);
+    // 3. models (authored on-disk + derived) → worker I/O index + meta accessor + message map.
+    //    Drop any on-disk model whose path a derived model already covers, to avoid double-counting.
+    if (!opts.modelsOnly) {
+        const derivedPaths = new Set(derived.artifacts.map((a) => a.path));
+        const diskModels = (await readModels(root, io, manifest)).filter((m) => !derivedPaths.has(m.path));
+        const models = [...diskModels, ...derived.models];
+        if (models.length > 0) {
+            const declaredTypeIds = Object.keys(manifest.types ?? {});
+            artifacts.push(...deriveWorkerBindings(models, declaredTypeIds));
+            artifacts.push(...deriveMeta(models));
+            artifacts.push(...deriveMessageBindings(models, declaredTypeIds));
+        }
     }
-    return sortArtifacts(artifacts);
+    return { artifacts: sortArtifacts(artifacts), derived };
 }
 /** Run the derivers and write artifacts (or, with `check`, report drift without writing). */
 export async function runGen(opts) {
-    const artifacts = await collectArtifacts(opts);
+    const { artifacts, derived } = await collectAll(opts);
     const { root, io } = opts;
+    const emitModels = opts.emitModels ?? true;
     const drift = [];
     for (const a of artifacts) {
         const abs = join(root, a.path);
@@ -81,6 +100,30 @@ export async function runGen(opts) {
             await io.writeText(abs, a.content);
         }
     }
-    return { artifacts, drift };
+    // Provenance-scoped stale sweep: delete derived `.bpmn` for flows that no longer exist. Only
+    // in write mode, only when we emitted models, only on a complete derivation (never delete when
+    // a workflow failed to load), and only files bearing our marker (authored models are untouched).
+    if (!opts.check && emitModels && derived.attempted && !derived.incomplete && io.remove) {
+        const keep = new Set(derived.artifacts.map((a) => a.path));
+        for (const name of await io.listDir(join(root, derived.outDir))) {
+            if (!name.endsWith(".bpmn"))
+                continue;
+            const rel = `${derived.outDir}/${name}`;
+            if (keep.has(rel))
+                continue;
+            const content = await io.readText(join(root, rel));
+            if (content.includes(MODEL_PROVENANCE))
+                await io.remove(join(root, rel));
+        }
+    }
+    return { artifacts, drift, incomplete: derived.incomplete, modelErrors: derived.errors };
 }
 export { dirOf, join as joinPath };
+/** Derive code-first models in-memory (no writes) — backs `urban derive --stdout`, the
+ * non-mutating preview the console's read-only model viewer uses. */
+export async function previewModels(opts) {
+    const { root, io } = opts;
+    const manifestPath = join(root, opts.manifestFile ?? "nano.app.json");
+    const manifest = JSON.parse(await io.readText(manifestPath));
+    return deriveModels(root, io, manifest);
+}

package/dist/toolkit/index.d.ts

@@ -20,9 +20,11 @@ export declare const DERIVERS: readonly [import("./artifact.ts").Deriver<import(
     models: import("./derivers/worker-io.ts").ModelSource[];
     declaredTypeIds: Iterable<string>;
 }>];
-export { collectArtifacts, runGen, joinPath, readModels } from "./gen.ts";
+export { collectArtifacts, runGen, joinPath, readModels, expandPattern, previewModels } from "./gen.ts";
 export type { GenIO, GenOptions, GenResult } from "./gen.ts";
 export { createNodeGenIO } from "./fsio.ts";
+export { deriveModels, isWorkflow, bpmnFilename, processesOutDir, DEFAULT_WORKFLOW_PATTERNS, PROCESSES_DIR, MODEL_PROVENANCE, } from "./models.ts";
+export type { DerivedModels, DerivedModelInfo, ModelError, ModelsManifest } from "./models.ts";
 export { planWorkerScaffold, renderWorkerStub, slugifyTaskType, } from "./scaffold/workers.ts";
 export type { ScaffoldWorker, SkippedWorker, SkipReason, StubManifestEntry, WorkerScaffoldPlan, WorkerStubPlan, } from "./scaffold/workers.ts";
 export { scaffoldWorkers } from "./scaffold.ts";

package/dist/toolkit/index.js

@@ -18,8 +18,10 @@ import { metaDeriver } from "./derivers/meta.js";
 import { messagesDeriver } from "./derivers/messages.js";
 export const DERIVERS = [migrationsDeriver, domainDeriver, workerIoDeriver, metaDeriver, messagesDeriver];
 // Gen orchestrator + IO
-export { collectArtifacts, runGen, joinPath, readModels } from "./gen.js";
+export { collectArtifacts, runGen, joinPath, readModels, expandPattern, previewModels } from "./gen.js";
 export { createNodeGenIO } from "./fsio.js";
+// Code-first model derivation (workflows/*.ts → BPMN)
+export { deriveModels, isWorkflow, bpmnFilename, processesOutDir, DEFAULT_WORKFLOW_PATTERNS, PROCESSES_DIR, MODEL_PROVENANCE, } from "./models.js";
 // Worker-stub scaffolder (ADR 0056): write-once handler stubs from the model.
 export { planWorkerScaffold, renderWorkerStub, slugifyTaskType, } from "./scaffold/workers.js";
 export { scaffoldWorkers } from "./scaffold.js";

package/dist/toolkit/models.d.ts

@@ -0,0 +1,63 @@
+import type { Workflow } from "@nanobpm/workflow";
+import type { DerivedArtifact } from "./artifact.ts";
+import type { GenIO } from "./gen.ts";
+import type { ModelSource } from "./derivers/worker-io.ts";
+/** Default source glob for code-first flows (matches the code-first scaffold layout). */
+export declare const DEFAULT_WORKFLOW_PATTERNS: string[];
+/** Default output dir for derived models (matches the model-first scaffold, so a derived
+ * model is ejectable to model-first and picked up by `models.processes: ["processes/*.bpmn"]`). */
+export declare const PROCESSES_DIR = "processes";
+/** Marker stamped into every derived `.bpmn` (an XML comment) so re-gen overwrites and the
+ * stale sweep deletes ONLY derived output — never an authored, human-owned model. */
+export declare const MODEL_PROVENANCE = "Generated by @nanobpm/urban from workflows/*.ts \u2014 do not edit; edit the flow and re-run `urban gen`.";
+/** Minimal shape a code-first manifest declares for model derivation. */
+export interface ModelsManifest {
+    models?: {
+        processes?: string[];
+        workflows?: string[];
+    };
+}
+/** A `defineFlow` export: has a string `id` and an `imperative`/`declarative` `kind`. */
+export declare function isWorkflow(v: unknown): v is Workflow;
+/** Sanitize a flow id into a safe `.bpmn` filename (mirrors the host generator). */
+export declare function bpmnFilename(id: string): string;
+/** The directory derived models are written to: the dir of the first `models.processes`
+ * glob if the manifest declares one, else the `processes/` default. */
+export declare function processesOutDir(manifest: ModelsManifest): string;
+export interface ModelError {
+    path: string;
+    message: string;
+}
+export interface DerivedModels {
+    /** `processes/<id>.bpmn` artifacts (path + provenance-stamped content). */
+    artifacts: DerivedArtifact[];
+    /** The same models, in-memory, for feeding the type-contract derivers (worker I/O, meta, messages). */
+    models: ModelSource[];
+    /** Derived flow ids (used for the provenance-scoped stale sweep). */
+    ids: string[];
+    /** Per-flow `{ id, kind, xml }` for the non-writing preview (`urban derive --stdout`). */
+    list: DerivedModelInfo[];
+    /** The output directory the artifacts were written into. */
+    outDir: string;
+    /** True once we attempted derivation (loader present AND at least one workflow file matched). */
+    attempted: boolean;
+    /** True if any workflow module failed to import/derive — suppresses the destructive sweep. */
+    incomplete: boolean;
+    /** Per-file derivation errors (empty on full success). */
+    errors: ModelError[];
+}
+export interface DerivedModelInfo {
+    id: string;
+    kind: Workflow["kind"];
+    xml: string;
+}
+/**
+ * Derive executable BPMN models from an app's code-first `workflows/*.ts`.
+ *
+ * Returns everything in-memory (artifacts + `ModelSource`s + ids). The caller decides whether
+ * to write the `.bpmn` to disk (`urban gen` / `urban derive`) or keep them in memory to feed
+ * the type-contract derivers only (`urban gen --no-models`) or preview them (`urban derive
+ * --stdout`). Never throws on a bad workflow: a failing module is recorded in `errors`,
+ * `incomplete` is set, and the sweep is suppressed so a partial failure can't delete good models.
+ */
+export declare function deriveModels(root: string, io: GenIO, manifest: ModelsManifest): Promise<DerivedModels>;

package/dist/toolkit/models.js

@@ -0,0 +1,142 @@
+// Model derivation for code-first apps — the toolkit's one *executing* edge.
+//
+// Unlike the pure derivers (migrations, domain, worker I/O), which transform strings, this
+// imports the app's `workflows/*.ts`, turns each `defineFlow` into executable BPMN via
+// `@nanobpm/workflow` (`toBpmn` + `bpmn-auto-layout` DI), and writes `processes/<id>.bpmn`.
+// Executing the app's TypeScript needs a runtime module loader, so this is gated on the
+// optional `GenIO.importModule` (present on Node with type-stripping, and on Deno). When the
+// 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 { expandPattern, joinPath } from "./gen.js";
+/** Default source glob for code-first flows (matches the code-first scaffold layout). */
+export const DEFAULT_WORKFLOW_PATTERNS = ["workflows/*.ts"];
+/** Default output dir for derived models (matches the model-first scaffold, so a derived
+ * model is ejectable to model-first and picked up by `models.processes: ["processes/*.bpmn"]`). */
+export const PROCESSES_DIR = "processes";
+/** Marker stamped into every derived `.bpmn` (an XML comment) so re-gen overwrites and the
+ * stale sweep deletes ONLY derived output — never an authored, human-owned model. */
+export const MODEL_PROVENANCE = "Generated by @nanobpm/urban from workflows/*.ts — do not edit; edit the flow and re-run `urban gen`.";
+/** A `defineFlow` export: has a string `id` and an `imperative`/`declarative` `kind`. */
+export function isWorkflow(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const o = v;
+    return typeof o.id === "string" && (o.kind === "imperative" || o.kind === "declarative");
+}
+/** Sanitize a flow id into a safe `.bpmn` filename (mirrors the host generator). */
+export function bpmnFilename(id) {
+    return `${id.replace(/[^A-Za-z0-9._-]/g, "-")}.bpmn`;
+}
+/** The directory derived models are written to: the dir of the first `models.processes`
+ * glob if the manifest declares one, else the `processes/` default. */
+export function processesOutDir(manifest) {
+    for (const pat of manifest.models?.processes ?? []) {
+        const star = pat.indexOf("*");
+        const slash = star === -1 ? pat.lastIndexOf("/") : pat.lastIndexOf("/", star);
+        if (slash > 0)
+            return pat.slice(0, slash);
+    }
+    return PROCESSES_DIR;
+}
+/** Insert the provenance marker as an XML comment right after the `<?xml … ?>` prolog. */
+function withProvenance(xml) {
+    const comment = `<!-- ${MODEL_PROVENANCE} -->`;
+    const m = xml.match(/^\uFEFF?\s*<\?xml[^>]*\?>/);
+    if (m)
+        return `${m[0]}\n${comment}\n${xml.slice(m[0].length).replace(/^\r?\n/, "")}`;
+    return `${comment}\n${xml}`;
+}
+function emptyDerived(outDir) {
+    return {
+        artifacts: [],
+        models: [],
+        ids: [],
+        list: [],
+        outDir,
+        attempted: false,
+        incomplete: false,
+        errors: [],
+    };
+}
+function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** Append an actionable hint when a `.ts` import fails because the runtime can't strip types. */
+function importHint(rel, e) {
+    const base = messageOf(e);
+    const code = e?.code ?? "";
+    const looksLikeNoTsLoader = rel.endsWith(".ts") &&
+        (code === "ERR_UNKNOWN_FILE_EXTENSION" || /Unknown file extension "\.ts"/.test(base));
+    if (!looksLikeNoTsLoader)
+        return base;
+    return (`${base}\n    ↳ importing TypeScript workflows needs a runtime that strips types: ` +
+        "Node ≥22.18 (default) or `node --experimental-strip-types`, or run under Deno.");
+}
+/**
+ * Derive executable BPMN models from an app's code-first `workflows/*.ts`.
+ *
+ * Returns everything in-memory (artifacts + `ModelSource`s + ids). The caller decides whether
+ * to write the `.bpmn` to disk (`urban gen` / `urban derive`) or keep them in memory to feed
+ * the type-contract derivers only (`urban gen --no-models`) or preview them (`urban derive
+ * --stdout`). Never throws on a bad workflow: a failing module is recorded in `errors`,
+ * `incomplete` is set, and the sweep is suppressed so a partial failure can't delete good models.
+ */
+export async function deriveModels(root, io, manifest) {
+    const outDir = processesOutDir(manifest);
+    const importModule = io.importModule;
+    if (!importModule)
+        return emptyDerived(outDir);
+    const patterns = manifest.models?.workflows ?? DEFAULT_WORKFLOW_PATTERNS;
+    const files = [];
+    for (const pat of patterns) {
+        for (const rel of await expandPattern(root, io, pat))
+            files.push(rel);
+    }
+    if (files.length === 0)
+        return emptyDerived(outDir);
+    const out = { ...emptyDerived(outDir), attempted: true };
+    // id → { source file, workflow ref } — distinguishes a genuine re-export (same
+    // object under two export names) from a true collision (two distinct flows, one id).
+    const byId = new Map();
+    for (const rel of files.sort()) {
+        let mod;
+        try {
+            mod = await importModule(joinPath(root, rel));
+        }
+        catch (e) {
+            out.incomplete = true;
+            out.errors.push({ path: rel, message: importHint(rel, e) });
+            continue;
+        }
+        for (const value of Object.values(mod)) {
+            if (!isWorkflow(value))
+                continue;
+            const id = value.id;
+            const prior = byId.get(id);
+            if (prior) {
+                if (prior.ref === value && prior.rel === rel)
+                    continue; // genuine intra-module re-export
+                out.incomplete = true;
+                const where = prior.rel === rel ? "also defined in the same module" : `also defined in ${prior.rel}`;
+                out.errors.push({ path: rel, message: `duplicate flow id "${id}" (${where})` });
+                continue;
+            }
+            byId.set(id, { rel, ref: value });
+            try {
+                const semantic = await toDeployableBpmn(value);
+                const xml = withProvenance(semantic);
+                const path = `${outDir}/${bpmnFilename(id)}`;
+                out.artifacts.push({ path, content: xml });
+                out.models.push({ path, xml });
+                out.list.push({ id, kind: value.kind, xml });
+                out.ids.push(id);
+            }
+            catch (e) {
+                out.incomplete = true;
+                out.errors.push({ path: rel, message: `deriving "${id}": ${messageOf(e)}` });
+            }
+        }
+    }
+    return out;
+}

package/package.json

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