@nanobpm/urban 0.3.0 → 0.5.0

package/dist/runtime/engine/nanosdk.d.ts

@@ -0,0 +1,151 @@
+import type { EngineClient, JobHandler, WorkerSubscription } from "../core/host.ts";
+import type { EngineSdkClient } from "./sdk.ts";
+/** Coerce an engine response's process-instance key to a non-empty string, or
+ * throw — a missing key means a malformed/partial response, not a real instance. */
+export declare function requireProcessInstanceKey(key: string | number | null | undefined): string;
+/** A job as delivered to a nano-sdk job handler: the frame fields plus the
+ *  acknowledgement actions the handler must call. */
+export interface NanoSdkActivatedJob {
+    jobKey: string;
+    type?: string;
+    processInstanceKey?: string | number;
+    elementId?: string;
+    variables?: Record<string, unknown>;
+    complete(variables?: Record<string, unknown>): Promise<unknown>;
+    fail(body: {
+        errorMessage: string;
+        retries?: number;
+    }): Promise<unknown>;
+}
+/** Config for a nano-sdk job worker (the subset this adapter sets). */
+export interface NanoSdkJobWorkerConfig {
+    jobType: string;
+    jobHandler: (job: NanoSdkActivatedJob) => Promise<unknown> | unknown;
+    workerName?: string;
+    maxParallelJobs?: number;
+    jobTimeoutMs?: number;
+    pollTimeoutMs?: number;
+    fetchVariables?: string[];
+    /** Start polling immediately. This adapter sets it false and starts explicitly. */
+    autoStart?: boolean;
+}
+/** The handle returned by `createJobWorker`. */
+export interface NanoSdkJobWorker {
+    start(): void | Promise<void>;
+    stop(): void | Promise<void>;
+    stopGracefully?(opts?: {
+        waitUpToMs?: number;
+    }): Promise<void>;
+}
+/**
+ * The subset of the `@nanobpm/nano-sdk` (Camunda orchestration-cluster) client the
+ * engine adapter uses. `createCamundaClient` returns a superset of this, so a test —
+ * or an author bringing their own transport (e.g. the embedded engine) — can inject
+ * any object satisfying it.
+ */
+export interface NanoSdkClient {
+    createDeployment(input: {
+        resources: File[];
+        [k: string]: unknown;
+    }, options?: unknown): Promise<Record<string, unknown>>;
+    createProcessInstance(input: {
+        processDefinitionId: string;
+        variables?: Record<string, unknown>;
+        awaitCompletion?: boolean;
+    }, options?: unknown): Promise<Record<string, unknown>>;
+    publishMessage(input: {
+        name: string;
+        correlationKey?: string;
+        variables?: Record<string, unknown>;
+    }, options?: unknown): Promise<Record<string, unknown>>;
+    searchUserTasks(input: {
+        filter?: Record<string, unknown>;
+    }, consistency?: unknown, options?: unknown): Promise<Record<string, unknown>>;
+    completeUserTask(input: {
+        userTaskKey: string;
+        variables?: Record<string, unknown>;
+    }, options?: unknown): Promise<unknown>;
+    createJobWorker(cfg: NanoSdkJobWorkerConfig): NanoSdkJobWorker;
+    close?(): void | Promise<void>;
+}
+type Log = (level: "info" | "warn" | "error", msg: string, fields?: Record<string, unknown>) => void;
+/**
+ * An `EngineClient` backed entirely by a `@nanobpm/nano-sdk` client. Deploy, create,
+ * message, and user-task calls map one-to-one onto the SDK's client methods; workers
+ * are the SDK's own job worker, which handles activation, completion, failure, and
+ * long-poll/backoff reconnect behind the same transport.
+ */
+export declare class SdkEngineClient implements EngineClient {
+    private readonly workers;
+    private readonly client;
+    private readonly log;
+    constructor(client: NanoSdkClient, log?: Log);
+    /**
+     * The underlying `@nanobpm/nano-sdk` client — the full Camunda orchestration-cluster
+     * surface (decisions, cluster variables, incidents, agents, batch operations, …) over
+     * the same connection. Surfaced to handlers as `AppApi.sdk`.
+     */
+    get sdk(): EngineSdkClient;
+    deployResources(resources: {
+        name: string;
+        content: string;
+        contentType: string;
+    }[]): Promise<{
+        deployed: number;
+    }>;
+    createInstance(input: {
+        processDefinitionId: string;
+        variables?: Record<string, unknown>;
+        awaitCompletion?: boolean;
+    }): Promise<{
+        processInstanceKey: string;
+        variables?: Record<string, unknown>;
+    }>;
+    publishMessage(input: {
+        name: string;
+        correlationKey?: string;
+        variables?: Record<string, unknown>;
+    }): Promise<void>;
+    searchUserTasks(filter?: {
+        processInstanceKey?: string;
+        assignee?: string;
+        candidateGroup?: string;
+    }): Promise<{
+        userTaskKey: string;
+        elementId?: string;
+        variables?: Record<string, unknown>;
+    }[]>;
+    completeUserTask(userTaskKey: string, variables?: Record<string, unknown>): Promise<void>;
+    registerWorker(jobType: string, handler: JobHandler, options?: {
+        workerName?: string;
+        maxParallelJobs?: number;
+        fetchVariables?: string[];
+    }): Promise<WorkerSubscription>;
+    /** Stop one worker, tolerating a Falcon worker whose transport never bound
+     *  (detection still pending) — its `stop` throws, which must not fail teardown. */
+    private stopWorker;
+    close(): Promise<void>;
+}
+export interface NanoSdkEngineOptions {
+    /** REST base, e.g. http://localhost:8080/v2. */
+    restAddress: string;
+    token?: string;
+    /** CAMUNDA_TRANSPORT: "auto" | "falcon" | "rest" | "embedded". Passed to createCamundaClient. */
+    transport?: string;
+    log?: Log;
+    /** Test seam: inject a ready-made SDK client (or a compatible fake). */
+    client?: NanoSdkClient;
+    /** Test seam: provide the SDK client factory instead of importing @nanobpm/nano-sdk. */
+    createClient?: (opts: {
+        restAddress: string;
+        token?: string;
+        transport?: string;
+    }) => NanoSdkClient;
+}
+/**
+ * Build the Urban runtime's `EngineClient`, backed by a single `@nanobpm/nano-sdk`
+ * client. Provide a `client`/`createClient` seam to inject a fake (tests, embedded
+ * transport); otherwise a client is constructed from `restAddress`/`token`/`transport`.
+ */
+export declare function createNanoSdkEngineClient(opts: NanoSdkEngineOptions): Promise<EngineClient>;
+export {};

package/dist/runtime/engine/nanosdk.js

@@ -0,0 +1,209 @@
+// The Urban runtime's single engine client. Every path to a Nano engine — deploy,
+// instance creation, message publication, user tasks, and job workers — routes
+// through one `@nanobpm/nano-sdk` client (ADR 0055). The SDK's `createCamundaClient`
+// transparently upgrades the throughput-critical paths (process-instance creation and
+// job serving) to the Falcon protocol on a Nano server and falls back to REST
+// everywhere else, so the runtime and the IDE talk to the engine the same way with a
+// single transport instead of a hand-rolled REST client plus a Falcon shim.
+//
+// `@nanobpm/nano-sdk` is a direct dependency, but it is imported lazily (via an
+// indirected specifier) so a caller that injects its own client — unit tests, the
+// Deno smoke, or an author bringing the embedded transport — never loads it, keeping
+// a dependency-free import graph for those paths.
+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;
+};
+/** Coerce an engine response's process-instance key to a non-empty string, or
+ * throw — a missing key means a malformed/partial response, not a real instance. */
+export function requireProcessInstanceKey(key) {
+    if (key == null || key === "") {
+        throw new Error("engine response missing processInstanceKey/key");
+    }
+    return String(key);
+}
+/**
+ * An `EngineClient` backed entirely by a `@nanobpm/nano-sdk` client. Deploy, create,
+ * message, and user-task calls map one-to-one onto the SDK's client methods; workers
+ * are the SDK's own job worker, which handles activation, completion, failure, and
+ * long-poll/backoff reconnect behind the same transport.
+ */
+export class SdkEngineClient {
+    workers = new Set();
+    client;
+    log;
+    constructor(client, log = () => { }) {
+        this.client = client;
+        this.log = log;
+    }
+    /**
+     * The underlying `@nanobpm/nano-sdk` client — the full Camunda orchestration-cluster
+     * surface (decisions, cluster variables, incidents, agents, batch operations, …) over
+     * the same connection. Surfaced to handlers as `AppApi.sdk`.
+     */
+    get sdk() {
+        return this.client;
+    }
+    async deployResources(resources) {
+        const files = resources.map((r) => new File([r.content], r.name, { type: r.contentType }));
+        await this.client.createDeployment({ resources: files });
+        return { deployed: resources.length };
+    }
+    async createInstance(input) {
+        const body = await this.client.createProcessInstance({
+            processDefinitionId: input.processDefinitionId,
+            variables: input.variables ?? {},
+            awaitCompletion: input.awaitCompletion ?? false,
+        });
+        const key = body.processInstanceKey ??
+            body.key;
+        return {
+            processInstanceKey: requireProcessInstanceKey(key),
+            variables: body.variables ?? undefined,
+        };
+    }
+    async publishMessage(input) {
+        await this.client.publishMessage({
+            name: input.name,
+            correlationKey: input.correlationKey ?? "",
+            variables: input.variables ?? {},
+        });
+    }
+    async searchUserTasks(filter) {
+        // User tasks are an eventually consistent read; ask for zero-wait consistency so
+        // the search reflects what is currently visible without blocking.
+        const body = await this.client.searchUserTasks({ filter: (filter ?? {}) }, { consistency: { waitUpToMs: 0 } });
+        const items = body.items ?? [];
+        return items.flatMap((it) => {
+            const userTaskKey = it.userTaskKey ?? it.key;
+            if (userTaskKey == null || userTaskKey === "") {
+                this.log("warn", "skipping user task with no key in engine response");
+                return [];
+            }
+            return [{
+                    userTaskKey: String(userTaskKey),
+                    elementId: it.elementId,
+                    variables: it.variables,
+                }];
+        });
+    }
+    async completeUserTask(userTaskKey, variables) {
+        await this.client.completeUserTask({ userTaskKey, variables: variables ?? {} });
+    }
+    async registerWorker(jobType, handler, options) {
+        const worker = this.client.createJobWorker({
+            jobType,
+            workerName: options?.workerName ?? `urban:${jobType}`,
+            maxParallelJobs: options?.maxParallelJobs ?? 8,
+            fetchVariables: options?.fetchVariables,
+            // Own the poll lifecycle here rather than leaving it to the SDK's auto-start
+            // default, so nothing polls until `start()` is called below.
+            autoStart: false,
+            jobHandler: async (job) => {
+                const rawKey = job.jobKey;
+                if (rawKey == null || rawKey === "") {
+                    this.log("warn", `activation ${jobType}: skipping job with no jobKey in engine response`);
+                    return undefined;
+                }
+                const engineJob = {
+                    jobKey: String(rawKey),
+                    jobType,
+                    processInstanceKey: job.processInstanceKey != null ? String(job.processInstanceKey) : undefined,
+                    elementId: job.elementId,
+                    variables: job.variables ?? {},
+                };
+                try {
+                    const out = await handler(engineJob);
+                    return await job.complete(out ?? {});
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    this.log("error", `handler ${jobType} threw`, { err: message });
+                    try {
+                        // Best-effort failure report; the engine redelivers after the lock
+                        // times out (at-least-once → handlers must be idempotent). Await +
+                        // swallow so a rejected `fail` cannot escape as an unhandled rejection.
+                        return await job.fail({ errorMessage: message.slice(0, 500), retries: 0 });
+                    }
+                    catch {
+                        return undefined;
+                    }
+                }
+            },
+        });
+        await worker.start();
+        this.workers.add(worker);
+        return {
+            jobType,
+            unsubscribe: async () => {
+                await this.stopWorker(worker);
+                this.workers.delete(worker);
+            },
+        };
+    }
+    /** Stop one worker, tolerating a Falcon worker whose transport never bound
+     *  (detection still pending) — its `stop` throws, which must not fail teardown. */
+    async stopWorker(worker) {
+        try {
+            await (worker.stopGracefully ? worker.stopGracefully() : worker.stop());
+        }
+        catch {
+            /* worker never fully started (transport unbound); nothing to drain */
+        }
+    }
+    async close() {
+        for (const w of this.workers)
+            await this.stopWorker(w);
+        this.workers.clear();
+        try {
+            await this.client.close?.();
+        }
+        catch {
+            /* transport already closed / never opened */
+        }
+    }
+}
+async function importNanoSdk() {
+    // Indirect the specifier so the (lazily loaded) module is not resolved at
+    // typecheck time and stays out of the import graph for injected-client paths.
+    const spec = "@nanobpm/nano-sdk";
+    const mod = (await import(__rewriteRelativeImportExtension(spec)));
+    if (typeof mod.createCamundaClient !== "function") {
+        throw new Error("@nanobpm/nano-sdk does not export createCamundaClient");
+    }
+    return mod.createCamundaClient;
+}
+/**
+ * Build the Urban runtime's `EngineClient`, backed by a single `@nanobpm/nano-sdk`
+ * client. Provide a `client`/`createClient` seam to inject a fake (tests, embedded
+ * transport); otherwise a client is constructed from `restAddress`/`token`/`transport`.
+ */
+export async function createNanoSdkEngineClient(opts) {
+    const log = opts.log ?? (() => { });
+    let client;
+    if (opts.client) {
+        client = opts.client;
+    }
+    else if (opts.createClient) {
+        client = opts.createClient({
+            restAddress: opts.restAddress,
+            token: opts.token,
+            transport: opts.transport,
+        });
+    }
+    else {
+        const createCamundaClient = await importNanoSdk();
+        client = createCamundaClient({
+            config: {
+                CAMUNDA_REST_ADDRESS: opts.restAddress,
+                ...(opts.token ? { CAMUNDA_TOKEN: opts.token } : {}),
+                CAMUNDA_TRANSPORT: opts.transport ?? "auto",
+            },
+        });
+    }
+    return new SdkEngineClient(client, log);
+}

package/dist/runtime/engine/sdk.d.ts

@@ -0,0 +1,3 @@
+/** The full nano-sdk (Camunda orchestration-cluster) engine client type — the value
+ *  returned by `createCamundaClient`. */
+export type EngineSdkClient = ReturnType<typeof import("@nanobpm/nano-sdk").createCamundaClient>;

package/dist/runtime/engine/sdk.js

@@ -0,0 +1,13 @@
+// The full nano-sdk engine client, surfaced to code-first Urban authors.
+//
+// `AppApi.engine` is the transport-agnostic seam (deploy, create, message, user
+// tasks, workers). When the app runs on the nano-sdk transport, `AppApi.sdk` also
+// carries the underlying `@nanobpm/nano-sdk` client, giving handlers the whole
+// Camunda orchestration-cluster surface — decisions, cluster variables, incidents,
+// agents, batch operations, and more — over the same connection, without a separate
+// `@nanobpm/nano-sdk` dependency.
+//
+// This module is type-only: the `import(...)` type query resolves nano-sdk's types at
+// typecheck and is fully erased at runtime, so re-exporting it from the runtime barrel
+// adds no load-time dependency on nano-sdk.
+export {};

package/dist/runtime/index.d.ts

@@ -0,0 +1,21 @@
+export { createUrbanApp } from "./core/runtime.ts";
+export type { CreateUrbanAppOptions, MountFlags, UrbanApp, } from "./core/runtime.ts";
+export { expandEnv, expandEnvString, loadManifest, parseManifest, workerJobType, } from "./core/manifest.ts";
+export type { AppManifest, DataSource, DomainType, SurfaceDecl, TriggerDecl, TypeField, WorkerDecl, } from "./core/manifest.ts";
+export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.ts";
+export type { ValidationIssue } from "./core/validate.ts";
+export type { EngineClient, EngineJob, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, SqliteDb, WorkerSubscription, } from "./core/host.ts";
+export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
+export { DataLayer, TypeRepo } from "./core/modules/datasource.ts";
+export type { ProvisionedSource } from "./core/modules/datasource.ts";
+export type { AppJobHandler } from "./core/modules/workers.ts";
+export { resolveHandler } from "./core/modules/workers.ts";
+export { evalCorrelation } from "./core/modules/triggers.ts";
+export { createNodeHost } from "./adapters/node.ts";
+export { createDenoHost } from "./adapters/deno.ts";
+export { isDeno, selectHost } from "./adapters/detect.ts";
+export { createNanoSdkEngineClient, SdkEngineClient } from "./engine/nanosdk.ts";
+export type { NanoSdkClient, NanoSdkEngineOptions, NanoSdkJobWorker, NanoSdkJobWorkerConfig, } from "./engine/nanosdk.ts";
+export type { EngineSdkClient } from "./engine/sdk.ts";
+export { runFromEnv } from "./run.ts";
+export type { RunOptions } from "./run.ts";

package/dist/runtime/index.js

@@ -0,0 +1,17 @@
+// Public API for the Urban runtime (@nanobpm/urban, subpath ./runtime).
+// Core runtime
+export { createUrbanApp } from "./core/runtime.js";
+// Manifest
+export { expandEnv, expandEnvString, loadManifest, parseManifest, workerJobType, } from "./core/manifest.js";
+// Validation
+export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.js";
+// Data layer
+export { DataLayer, TypeRepo } from "./core/modules/datasource.js";
+export { resolveHandler } from "./core/modules/workers.js";
+export { evalCorrelation } from "./core/modules/triggers.js";
+// Adapters + engine + run entrypoint
+export { createNodeHost } from "./adapters/node.js";
+export { createDenoHost } from "./adapters/deno.js";
+export { isDeno, selectHost } from "./adapters/detect.js";
+export { createNanoSdkEngineClient, SdkEngineClient } from "./engine/nanosdk.js";
+export { runFromEnv } from "./run.js";

package/dist/runtime/run.d.ts

@@ -0,0 +1,17 @@
+import { type CreateUrbanAppOptions, type UrbanApp } from "./core/runtime.ts";
+export interface RunOptions extends Partial<CreateUrbanAppOptions> {
+    /** App root. Default ".". */
+    root?: string;
+    /** Engine REST base. Default $CAMUNDA_REST_ADDRESS or http://localhost:8080/v2. */
+    restAddress?: string;
+    /**
+     * Engine transport passed to `@nanobpm/nano-sdk`: "auto" (default) upgrades
+     * process-instance creation and job serving to the Falcon protocol on a Nano
+     * server and falls back to REST elsewhere; "falcon" forces it; "rest" never
+     * upgrades; "embedded" runs an in-process engine. Overridable via $CAMUNDA_TRANSPORT.
+     */
+    transport?: string;
+    /** Install SIGINT/SIGTERM handlers to stop the app. Default true. */
+    handleSignals?: boolean;
+}
+export declare function runFromEnv(opts?: RunOptions): Promise<UrbanApp>;

package/dist/runtime/run.js

@@ -0,0 +1,69 @@
+// runFromEnv — the one-call entrypoint a scaffolded app's main and the `urban run` CLI both
+// use: select the host for the current runtime, build the nano-sdk engine client from env,
+// create the Urban app, start it, and install a graceful-shutdown handler.
+import { createUrbanApp } from "./core/runtime.js";
+import { selectHost } from "./adapters/detect.js";
+import { createNanoSdkEngineClient } from "./engine/nanosdk.js";
+export async function runFromEnv(opts = {}) {
+    const host = opts.host ?? selectHost({ cwd: opts.root });
+    const restAddress = opts.restAddress ?? host.env("CAMUNDA_REST_ADDRESS") ?? "http://localhost:8080/v2";
+    const transport = opts.transport ?? host.env("CAMUNDA_TRANSPORT") ?? "auto";
+    const engine = opts.engine ??
+        (await createNanoSdkEngineClient({
+            restAddress,
+            token: host.env("CAMUNDA_TOKEN"),
+            transport,
+            log: host.log,
+        }));
+    const app = await createUrbanApp({
+        host,
+        engine,
+        // The host is anchored at opts.root (cwd), so its APIs are already
+        // root-relative; passing opts.root here as well would double-prefix every
+        // path (e.g. "<root>/<root>/nano.app.json"). Keep root "." for the app.
+        root: ".",
+        manifest: opts.manifest,
+        manifestPath: opts.manifestPath,
+        port: opts.port,
+        mount: opts.mount,
+    });
+    await app.start();
+    if (opts.handleSignals !== false)
+        installSignalHandlers(() => app.stop());
+    return app;
+}
+function installSignalHandlers(stop) {
+    let stopping = false;
+    const onSignal = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        // Neither Deno.addSignalListener nor process.on awaits the callback, so a
+        // rejection from stop() would surface as an unhandled rejection during
+        // shutdown. Register a non-async listener and swallow/log any rejection.
+        Promise.resolve()
+            .then(stop)
+            .catch((err) => {
+            try {
+                console.error("error during shutdown:", err);
+            }
+            catch {
+                /* ignore logging failures during teardown */
+            }
+        });
+    };
+    const g = globalThis;
+    if (g.Deno) {
+        try {
+            g.Deno.addSignalListener("SIGINT", onSignal);
+            g.Deno.addSignalListener("SIGTERM", onSignal);
+        }
+        catch {
+            /* signal listeners may be unavailable (e.g. Windows) */
+        }
+    }
+    else if (g.process) {
+        g.process.on("SIGINT", onSignal);
+        g.process.on("SIGTERM", onSignal);
+    }
+}