@nanobpm/urban 0.17.1 → 0.19.0

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,10 +20,14 @@ 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";
 export type { ScaffoldOptions, ScaffoldRun, StubOutcome, StubStatus } from "./scaffold.ts";
+export { addConnector } from "./addConnector.ts";
+export type { AddConnectorOptions, AddConnectorResult } from "./addConnector.ts";

package/dist/toolkit/index.js

@@ -18,8 +18,11 @@ 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";
+export { addConnector } from "./addConnector.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.19.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",
@@ -64,7 +64,7 @@
   "dependencies": {
     "@nanobpm/nano-app-schema": "^0.1.0",
     "@nanobpm/nano-sdk": "^1.2.3",
-    "@nanobpm/workflow": "^0.7.0",
+    "@nanobpm/workflow": "^0.8.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2",
     "create-urban-app": "^0.5.0"
   },

package/src/cli.ts

@@ -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
@@ -19,9 +20,10 @@ import {
   selectHost,
 } from "./runtime/index.ts";
 import { scaffold, slugify } from "create-urban-app";
-import { createNodeGenIO, runGen, scaffoldWorkers } from "./toolkit/index.ts";
+import { addConnector, createNodeGenIO, previewModels, runGen, scaffoldWorkers } from "./toolkit/index.ts";
 import { pathToFileURL } from "node:url";
 import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 
 // Read the package version from package.json (one hop up from both src/cli.ts and the
 // compiled dist/cli.js) so `urban --version` never drifts from the published version.
@@ -44,6 +46,9 @@ interface Flags {
   check: boolean;
   write: boolean;
   deno: boolean;
+  models: boolean;
+  stdout: boolean;
+  install: boolean;
   style?: "model" | "code";
   help: boolean;
   version: boolean;
@@ -51,7 +56,7 @@ interface Flags {
 }
 
 function parse(argv: string[]): Flags {
-  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, write: false, deno: false, help: false, version: false, _: [] };
+  const f: Flags = { root: ".", manifest: "nano.app.json", check: false, write: false, deno: false, models: true, stdout: false, install: true, help: false, version: false, _: [] };
   const need = (i: number, flag: string): string => {
     const v = argv[i];
     if (v === undefined || v.startsWith("-")) throw new Error(`flag ${flag} requires a value`);
@@ -64,6 +69,11 @@ function parse(argv: string[]): Flags {
     else if (a === "--check") f.check = true;
     else if (a === "--write") f.write = true;
     else if (a === "--deno") f.deno = true;
+    else if (a === "--no-models") f.models = false;
+    else if (a === "--models") f.models = true;
+    else if (a === "--stdout") f.stdout = true;
+    else if (a === "--no-install") f.install = false;
+    else if (a === "--install") f.install = true;
     else if (a === "--code-first") f.style = "code";
     else if (a === "--style") {
       const v = need(++i, a);
@@ -92,8 +102,12 @@ 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 add <pkg> [--no-install]    install a connector pack + wire it into nano.app.json
   urban run                         materialize + serve the app
   urban dev                         run + watch sources, hot-reload on change
   urban deploy                      deploy models only, then exit
@@ -125,7 +139,12 @@ async function cmdCheck(f: Flags): Promise<number> {
 
 async function cmdGen(f: Flags): Promise<number> {
   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)`);
@@ -140,6 +159,55 @@ async function cmdGen(f: Flags): Promise<number> {
   return 0;
 }
 
+async function cmdDerive(f: Flags): Promise<number> {
+  // `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: Flags): Promise<number> {
   const io = createNodeGenIO();
   const run = await scaffoldWorkers({ root: f.root, io, manifestFile: f.manifest, write: f.write });
@@ -218,6 +286,57 @@ async function cmdNew(f: Flags): Promise<number> {
   return 0;
 }
 
+async function cmdAdd(f: Flags): Promise<number> {
+  const pkg = f._[1];
+  if (!pkg) {
+    console.error("usage: urban add <pkg> [--no-install]");
+    return 1;
+  }
+  // Install the connector pack (a subprocess — the toolkit stays runtime-agnostic).
+  if (f.install) {
+    console.log(`Installing ${pkg} …`);
+    const res = spawnSync("npm", ["install", pkg], {
+      cwd: f.root,
+      stdio: "inherit",
+    });
+    if (res.error) {
+      console.error(`npm install failed: ${res.error.message}`);
+      return 1;
+    }
+    if (res.signal) {
+      console.error(`npm install was terminated by signal ${res.signal}`);
+      return 1;
+    }
+    if (res.status !== 0) {
+      console.error(`npm install exited with code ${res.status}`);
+      return res.status ?? 1;
+    }
+  }
+
+  try {
+    const result = await addConnector({
+      root: f.root,
+      pkg,
+      manifestFile: f.manifest,
+      io: createNodeGenIO(),
+    });
+    const added = result.wired.filter((w) => !w.alreadyPresent);
+    const kept = result.wired.filter((w) => w.alreadyPresent);
+    console.log(`✔ enabled connector "${result.packId}" from ${pkg}`);
+    for (const w of added) console.log(`  + worker ${w.taskType}`);
+    for (const w of kept) console.log(`  = worker ${w.taskType} (already wired)`);
+    if (result.connection) console.log(`  connection: ${result.connection}`);
+    if (result.requiredEnv.length > 0) {
+      console.log(`\nSet these environment variables before \`urban run\`:`);
+      for (const name of result.requiredEnv) console.log(`  ${name}`);
+    }
+    return 0;
+  } catch (err) {
+    console.error(`✖ ${(err as Error).message}`);
+    return 1;
+  }
+}
+
 export async function main(argv: string[]): Promise<number> {
   let f: Flags;
   try {
@@ -243,8 +362,12 @@ export async function main(argv: string[]): Promise<number> {
       return cmdCheck(f);
     case "gen":
       return cmdGen(f);
+    case "derive":
+      return cmdDerive(f);
     case "stubs":
       return cmdStubs(f);
+    case "add":
+      return cmdAdd(f);
     case "run":
       return cmdRun(f);
     case "dev":