@nanobpm/urban 0.17.1 → 0.19.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,9 +12,10 @@
 //               --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 { addConnector, createNodeGenIO, previewModels, runGen, scaffoldWorkers } from "./toolkit/index.js";
 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.
 function readVersion() {
@@ -27,7 +29,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, install: true, help: false, version: false, _: [] };
     const need = (i, flag) => {
         const v = argv[i];
         if (v === undefined || v.startsWith("-"))
@@ -46,6 +48,16 @@ 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 === "--no-install")
+            f.install = false;
+        else if (a === "--install")
+            f.install = true;
         else if (a === "--code-first")
             f.style = "code";
         else if (a === "--style") {
@@ -81,8 +93,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
@@ -113,7 +129,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 +151,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 });
@@ -206,6 +274,60 @@ async function cmdNew(f) {
         console.log(`  # or on Deno: deno task start`);
     return 0;
 }
+async function cmdAdd(f) {
+    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.message}`);
+        return 1;
+    }
+}
 export async function main(argv) {
     let f;
     try {
@@ -232,8 +354,12 @@ export async function main(argv) {
             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":

package/dist/runtime/adapters/node.js

@@ -9,11 +9,62 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { readFile, readdir, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import { watch as fsWatch } from "node:fs";
 import { createServer } from "node:http";
+import { register } from "node:module";
 import { isAbsolute, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { DatabaseSync } from "node:sqlite";
+/** Resolve the in-process `@nanobpm/worker` shim URL relative to this adapter,
+ *  tolerating both the compiled package (`.js`, the published/`urban run` path)
+ *  and a from-source run (`.ts`). */
+function connectorShimUrl() {
+    const js = new URL("../connector-worker-sdk.js", import.meta.url);
+    if (existsSync(fileURLToPath(js)))
+        return js.href;
+    return new URL("../connector-worker-sdk.ts", import.meta.url).href;
+}
+let connectorHooksRegistered = false;
+/**
+ * Register (once per process) the ESM customization hooks that let a connector
+ * pack's worker `entry` be imported in-process (ADR 0050, in-process port):
+ *   - a **resolve** hook aliasing the bare `@nanobpm/worker` specifier the pack
+ *     imports to the runtime's shim, so its `defineWorker(...)` registers into the
+ *     registry the runtime drains;
+ *   - a **load** hook that strips TypeScript from ANY `.ts` module resolved under
+ *     `node_modules` (Node refuses to type-strip there by default). In practice
+ *     only a connector pack's `.ts` entry and its `.ts` imports travel this path,
+ *     but the hook is process-global once registered, so it applies to every
+ *     subsequent `node_modules` `.ts` import — a safe superset (Node would
+ *     otherwise throw on such a file). The module's real URL is preserved so its
+ *     own bare imports (npm deps) still resolve.
+ * The hooks run on a separate thread, so the shim URL is baked into the hook
+ * source; the shim itself loads on the main thread (shared registry instance).
+ */
+function ensureConnectorHooks() {
+    if (connectorHooksRegistered)
+        return;
+    const shim = JSON.stringify(connectorShimUrl());
+    const src = `import { readFileSync } from "node:fs";\n` +
+        `import { fileURLToPath } from "node:url";\n` +
+        `import { stripTypeScriptTypes } from "node:module";\n` +
+        `const SHIM = ${shim};\n` +
+        `export async function resolve(spec, ctx, next) {\n` +
+        `  if (spec === "@nanobpm/worker") return { url: SHIM, shortCircuit: true };\n` +
+        `  return next(spec, ctx);\n` +
+        `}\n` +
+        `export async function load(url, ctx, next) {\n` +
+        `  const path = url.split("?")[0];\n` +
+        `  if (path.endsWith(".ts") && path.includes("/node_modules/")) {\n` +
+        `    const source = stripTypeScriptTypes(readFileSync(fileURLToPath(path), "utf8"), { mode: "strip" });\n` +
+        `    return { format: "module", source, shortCircuit: true };\n` +
+        `  }\n` +
+        `  return next(url, ctx);\n` +
+        `}\n`;
+    register("data:text/javascript," + encodeURIComponent(src));
+    connectorHooksRegistered = true;
+}
 export function createNodeHost(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const abs = (p) => (isAbsolute(p) ? p : resolve(cwd, p));
@@ -52,6 +103,15 @@ export function createNodeHost(opts = {}) {
             const href = pathToFileURL(abs(p)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
             return import(__rewriteRelativeImportExtension(href));
         },
+        async importConnectorModule(entry) {
+            ensureConnectorHooks();
+            // Import for side effects only: the pack's top-level `defineWorker(...)` runs
+            // and registers into the shim registry, which the caller drains. Apply the
+            // dev `importNonce` cache-buster (as importModule does) so a hot-reloaded
+            // pack entry is re-evaluated instead of served stale from the ESM cache.
+            const href = pathToFileURL(abs(entry)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
+            await import(__rewriteRelativeImportExtension(href));
+        },
         async serveHttp(port, handler) {
             return await startNodeServer(port, handler);
         },

package/dist/runtime/connector-worker-sdk.d.ts

@@ -0,0 +1,39 @@
+/** One activated job handed to a connector worker's `handle` (the subset the
+ *  `@nanobpm/worker` contract exposes; mirrors packages/connector-slack/types). */
+export interface ConnectorWorkerJob {
+    readonly jobKey: string;
+    readonly type: string;
+    readonly processInstanceKey: string;
+    readonly elementId?: string;
+    readonly variables: Record<string, unknown>;
+    /** Complete the job, optionally with output variables. */
+    complete(variables?: Record<string, unknown>): Promise<void>;
+    /** Fail the job (retryable). */
+    fail(message: string, retries?: number): Promise<void>;
+    /** Raise a BPMN error (routed to an error boundary event). */
+    error(code: string, message?: string): Promise<void>;
+}
+/** The options a connector worker passes to `defineWorker`. */
+export interface ConnectorWorkerOptions {
+    type: string;
+    maxParallelJobs?: number;
+    timeoutMs?: number;
+    /** Ignored in-process: the runtime owns the engine connection. Accepted so a
+     *  pack authored against the standalone SDK still type-checks and imports. */
+    baseUrl?: string;
+    worker?: string;
+    handle(job: ConnectorWorkerJob): Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+}
+/** A worker the runtime will register on the engine, drained from the registry. */
+export interface DefinedConnectorWorker {
+    type: string;
+    maxParallelJobs?: number;
+    handle: ConnectorWorkerOptions["handle"];
+}
+/** The `@nanobpm/worker` entrypoint the pack calls. Records the handler; does not
+ *  connect. */
+export declare function defineWorker(opts: ConnectorWorkerOptions): void;
+/** Return every worker registered since the last drain, and clear the registry.
+ *  The runtime calls this immediately after importing one pack entry, so the
+ *  returned set belongs to that pack. */
+export declare function drainDefinedWorkers(): DefinedConnectorWorker[];

package/dist/runtime/connector-worker-sdk.js

@@ -0,0 +1,40 @@
+// The in-process `@nanobpm/worker` shim (ADR 0050, in-process port).
+//
+// A connector pack's `worker.ts` is a self-contained program that imports the
+// host-provided `@nanobpm/worker` SDK and calls `defineWorker({ type, handle })`.
+// The old Rust host ran each such worker as its own supervised child process. The
+// @nanobpm/urban runtime hosts app workers IN-PROCESS, so it hosts connector
+// workers the same way: it aliases the pack's `@nanobpm/worker` import to THIS
+// module, imports the pack entry, and reads back the registered handler(s) —
+// which it then registers on the engine like any other worker.
+//
+// `defineWorker` here does NOT connect to anything. It only records the handler in
+// a module-level registry that the runtime drains (`drainDefinedWorkers`). Because
+// the pack and the runtime resolve `@nanobpm/worker` to the SAME module URL, they
+// share this registry instance.
+//
+// This module is deliberately runtime-agnostic (no `node:*`, no `Deno`): it is the
+// contract surface, and the Node/Deno specifics of aliasing the import live in the
+// adapters.
+// Module-level registry. Shared across every importer of this module URL, which is
+// exactly how the pack's `defineWorker` call reaches the runtime's drain: both
+// resolve `@nanobpm/worker` to this file.
+const registered = [];
+/** The `@nanobpm/worker` entrypoint the pack calls. Records the handler; does not
+ *  connect. */
+export function defineWorker(opts) {
+    if (!opts || typeof opts.type !== "string" || opts.type.length === 0) {
+        throw new Error("defineWorker: `type` is required");
+    }
+    if (typeof opts.handle !== "function") {
+        throw new Error(`defineWorker("${opts.type}"): handle must be a function`);
+    }
+    registered.push({ type: opts.type, maxParallelJobs: opts.maxParallelJobs, handle: opts.handle });
+}
+/** Return every worker registered since the last drain, and clear the registry.
+ *  The runtime calls this immediately after importing one pack entry, so the
+ *  returned set belongs to that pack. */
+export function drainDefinedWorkers() {
+    const out = registered.splice(0, registered.length);
+    return out;
+}

package/dist/runtime/core/host.d.ts

@@ -60,6 +60,16 @@ export interface HostContext {
      * between runtimes, so it lives behind the host seam.
      */
     importModule(path: string): Promise<Record<string, unknown>>;
+    /**
+     * Import a connector pack's worker `entry` (ADR 0050) with the bare
+     * `@nanobpm/worker` specifier the pack imports aliased to the runtime's
+     * in-process shim (`connector-worker-sdk.ts`), so its top-level
+     * `defineWorker(...)` registers into the shared registry. `entry` is an
+     * absolute path (already resolved from the installed pack). Hosts that cannot
+     * alias a bare specifier (or run no connector workers) may omit this; the
+     * connector mount then reports the workers as unsupported rather than crashing.
+     */
+    importConnectorModule?(entry: string): Promise<void>;
     /** Start an HTTP server. Routing is done by the caller inside `handler`. */
     serveHttp(port: number, handler: HttpHandler): Promise<HttpServer>;
     /**
@@ -87,6 +97,26 @@ export interface EngineJob<In extends object = Record<string, unknown>> {
     variables: In;
 }
 export type JobHandler = (job: EngineJob) => Promise<Record<string, unknown> | void> | Record<string, unknown> | void;
+/**
+ * A BPMN error raised by a job handler. When a handler throws this, the engine
+ * adapter reports it to the engine as a BPMN error (`throwError`) — routed to a
+ * matching error boundary/event subprocess — instead of a plain job failure
+ * (which retries then raises an incident). This is the runtime face of a
+ * connector worker's `job.error(code, message)` (ADR 0050): a non-retryable,
+ * modelled outcome. Handlers that throw any other error are failed (retried).
+ */
+export declare class BpmnError extends Error {
+    readonly errorCode: string;
+    constructor(errorCode: string, message?: string);
+}
+/** Structural guard: true for a {@link BpmnError} or any error carrying a
+ *  non-empty string `errorCode`, so the check survives module-duplication (a
+ *  BpmnError constructed against a different copy of this module still routes as
+ *  a BPMN error rather than a generic failure). */
+export declare function isBpmnError(err: unknown): err is {
+    errorCode: string;
+    message?: string;
+};
 /** A registered worker subscription. */
 export interface WorkerSubscription {
     readonly jobType: string;

package/dist/runtime/core/host.js

@@ -2,4 +2,29 @@
 // JavaScript runtime (Node or Deno) or the Nano engine. Everything under core/ is
 // written against these interfaces and MUST NOT import `node:*` or reference `Deno`.
 // The adapters/ directory supplies concrete implementations.
-export {};
+/**
+ * A BPMN error raised by a job handler. When a handler throws this, the engine
+ * adapter reports it to the engine as a BPMN error (`throwError`) — routed to a
+ * matching error boundary/event subprocess — instead of a plain job failure
+ * (which retries then raises an incident). This is the runtime face of a
+ * connector worker's `job.error(code, message)` (ADR 0050): a non-retryable,
+ * modelled outcome. Handlers that throw any other error are failed (retried).
+ */
+export class BpmnError extends Error {
+    errorCode;
+    constructor(errorCode, message) {
+        super(message ?? errorCode);
+        this.name = "BpmnError";
+        this.errorCode = errorCode;
+    }
+}
+/** Structural guard: true for a {@link BpmnError} or any error carrying a
+ *  non-empty string `errorCode`, so the check survives module-duplication (a
+ *  BpmnError constructed against a different copy of this module still routes as
+ *  a BPMN error rather than a generic failure). */
+export function isBpmnError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        typeof err.errorCode === "string" &&
+        err.errorCode.length > 0);
+}

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

@@ -0,0 +1,53 @@
+import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
+import { type JobHandler } from "../host.ts";
+import { type DefinedConnectorWorker } from "../../connector-worker-sdk.ts";
+/** A config field a pack declares (subset of ext-types `ConfigField`): an env
+ *  pointer with an optional default. */
+interface PackConfigField {
+    key: string;
+    env?: string;
+    default?: string;
+}
+/** A worker a pack declares (subset of ext-types `WorkerSpec`). */
+interface PackWorkerSpec {
+    type: string;
+    entry: string;
+    maxParallelJobs?: number;
+    configFields?: PackConfigField[];
+}
+/** The pack manifest (`nano-ide.ext.json`) fields the runtime reads. */
+interface PackManifest {
+    id: string;
+    workers?: PackWorkerSpec[];
+}
+/** An installed connector pack, indexed by its manifest `id`. */
+interface InstalledPack {
+    id: string;
+    /** Pack dir relative to the app root, e.g. `node_modules/@nanobpm/nano-ide-connector-slack`. */
+    dir: string;
+    manifest: PackManifest;
+}
+export interface ConnectorsHandle extends Mounted {
+    readonly jobTypes: string[];
+}
+/**
+ * Discover installed connector packs: read the app `package.json` dependencies,
+ * and for each that ships a `nano-ide.ext.json` with a worker, index it by its
+ * declared pack `id` (the value a manifest `worker.connector` field carries — NOT
+ * the npm package name).
+ */
+export declare function resolveInstalledConnectors(ctx: RuntimeContext): Promise<Map<string, InstalledPack>>;
+/** Wrap a pack's `DefinedConnectorWorker.handle` as an engine `JobHandler`,
+ *  bridging the `@nanobpm/worker` job facade (complete/fail/error) to the engine
+ *  seam. `job.error(code)` becomes a thrown {@link BpmnError} (routed to a BPMN
+ *  error boundary by the engine adapter); `job.fail(msg)` a plain throw (retry). */
+export declare function adaptConnectorHandler(worker: DefinedConnectorWorker): JobHandler;
+/**
+ * Mount every enabled connector worker (`workers[]` entries carrying a
+ * `connector` field). Fails closed on a seam mismatch (an enabled connector whose
+ * pack or worker type is not installed); skips-with-warning a worker whose
+ * required env is unset (so a missing credential does not crash the app), or when
+ * the host cannot host connector workers (`importConnectorModule` absent).
+ */
+export declare function mountConnectors(ctx: RuntimeContext, app: AppApi): Promise<ConnectorsHandle>;
+export {};