@nanobpm/urban 0.17.1 → 0.19.0

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

@@ -0,0 +1,204 @@
+// connectors — mount connector-pack workers (ADR 0050, in-process port).
+//
+// A connector is an installed npm pack that ships a `nano-ide.ext.json` manifest
+// and a worker `entry` program. The app enables it by adding a `workers[]` entry
+// with a `connector: <pack-id>` field (no `handler`/`llm`) — see `urban add` and
+// `addConnector`. This module resolves each such enabled worker to its installed
+// pack, imports the pack `entry` in-process (via the host's `@nanobpm/worker`
+// alias), and registers the drained handler on the engine like any other worker.
+//
+// The old Rust host supervised each connector worker as its own child process
+// (ADR 0050 §4). The @nanobpm/urban runtime hosts app workers in-process, so it
+// hosts connector workers the same way — trading process isolation for a simpler,
+// single-process model. `job.error(code)` still routes to a real BPMN error.
+//
+// This file is runtime-agnostic (core purity): the Node/Deno specifics of aliasing
+// the pack's `@nanobpm/worker` import live behind `host.importConnectorModule`.
+import { BpmnError } from "../host.js";
+import { workerJobType } from "../manifest.js";
+import { drainDefinedWorkers, } from "../../connector-worker-sdk.js";
+function joinRoot(root, p) {
+    return p.startsWith("/") ? p : `${root.replace(/\/+$/, "")}/${p.replace(/^\/+/, "")}`;
+}
+/** Env vars a pack worker requires before it can be imported/run: every config
+ *  field that points at an env var and has no baked default. In-process, a missing
+ *  var would let the pack's top-level guard `process.exit` the whole app, so the
+ *  runtime skips the worker instead. */
+function requiredEnv(spec) {
+    const seen = new Set();
+    for (const f of spec.configFields ?? []) {
+        if (f.env && (f.default === undefined || f.default === ""))
+            seen.add(f.env);
+    }
+    return [...seen];
+}
+/** Read + parse a JSON file under the app root; undefined if absent. In `strict`
+ *  mode a malformed file throws a named parse error (used for the app's own files);
+ *  otherwise a malformed file is treated as absent (used for third-party packs). */
+async function readJson(ctx, relPath, opts) {
+    const path = joinRoot(ctx.root, relPath);
+    if (!(await ctx.host.exists(path)))
+        return undefined;
+    try {
+        return JSON.parse(await ctx.host.readTextFile(path));
+    }
+    catch (err) {
+        if (opts?.strict) {
+            throw new Error(`failed to parse ${relPath}: ${err.message}`);
+        }
+        return undefined;
+    }
+}
+/**
+ * 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 async function resolveInstalledConnectors(ctx) {
+    const out = new Map();
+    const pkg = await readJson(ctx, "package.json", { strict: true });
+    if (!pkg)
+        return out;
+    const names = new Set([
+        ...Object.keys(pkg.dependencies ?? {}),
+        ...Object.keys(pkg.devDependencies ?? {}),
+        ...Object.keys(pkg.optionalDependencies ?? {}),
+    ]);
+    for (const name of names) {
+        const dir = `node_modules/${name}`;
+        const manifest = await readJson(ctx, `${dir}/nano-ide.ext.json`);
+        if (!manifest || typeof manifest.id !== "string" || !manifest.id)
+            continue;
+        if (!Array.isArray(manifest.workers) || manifest.workers.length === 0)
+            continue;
+        out.set(manifest.id, { id: manifest.id, dir, manifest });
+    }
+    return out;
+}
+/** 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 function adaptConnectorHandler(worker) {
+    return async (job) => {
+        let outcome;
+        const facade = {
+            jobKey: job.jobKey,
+            type: job.jobType,
+            processInstanceKey: job.processInstanceKey ?? "",
+            elementId: job.elementId,
+            variables: job.variables,
+            async complete(vars) {
+                outcome = { kind: "complete", vars };
+            },
+            async fail(message) {
+                outcome = { kind: "fail", message };
+            },
+            async error(code, message) {
+                outcome = { kind: "error", code, message };
+            },
+        };
+        const ret = await worker.handle(facade);
+        if (outcome?.kind === "error")
+            throw new BpmnError(outcome.code, outcome.message);
+        if (outcome?.kind === "fail")
+            throw new Error(outcome.message);
+        if (outcome?.kind === "complete")
+            return outcome.vars ?? {};
+        // No explicit outcome: fall back to the handle's return value (SDK-style).
+        return ret && typeof ret === "object" ? ret : {};
+    };
+}
+/**
+ * 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 async function mountConnectors(ctx, app) {
+    const decls = (ctx.manifest.workers ?? []).filter((w) => w.connector);
+    const subs = [];
+    const jobTypes = [];
+    if (decls.length === 0)
+        return makeHandle(subs, jobTypes);
+    const packs = await resolveInstalledConnectors(ctx);
+    // Cache drained workers per imported entry (an entry may register several).
+    const drainedByEntry = new Map();
+    for (const decl of decls) {
+        const jobType = workerJobType(decl);
+        if (!jobType)
+            continue;
+        const packId = decl.connector;
+        const pack = packs.get(packId);
+        if (!pack) {
+            throw new Error(`connector worker "${jobType}" references pack "${packId}", which is not installed ` +
+                `(no dependency exposes a nano-ide.ext.json with id "${packId}"). Run \`urban add <pkg>\`.`);
+        }
+        const spec = pack.manifest.workers?.find((w) => w.type === jobType);
+        if (!spec) {
+            throw new Error(`connector worker "${jobType}" is not provided by pack "${packId}" ` +
+                `(its nano-ide.ext.json declares no worker of that type).`);
+        }
+        const missing = requiredEnv(spec).filter((name) => !app.env(name));
+        if (missing.length > 0) {
+            ctx.host.log("warn", "skipping connector worker: required env unset", {
+                jobType,
+                connector: packId,
+                missing: missing.join(", "),
+            });
+            continue;
+        }
+        if (!ctx.host.importConnectorModule) {
+            ctx.host.log("warn", "skipping connector worker: host cannot host connector packs", {
+                jobType,
+                connector: packId,
+                runtime: ctx.host.runtime,
+            });
+            continue;
+        }
+        const entryAbs = joinRoot(ctx.root, `${pack.dir}/${spec.entry}`);
+        let drained = drainedByEntry.get(entryAbs);
+        if (!drained) {
+            await ctx.host.importConnectorModule(entryAbs);
+            // Fail closed on a duplicate worker `type` within one pack entry: silently
+            // keeping the last registration would bind an arbitrary handler.
+            drained = new Map();
+            for (const w of drainDefinedWorkers()) {
+                if (drained.has(w.type)) {
+                    throw new Error(`connector pack "${packId}" entry "${spec.entry}" registered the worker ` +
+                        `type "${w.type}" more than once (duplicate defineWorker call).`);
+                }
+                drained.set(w.type, w);
+            }
+            drainedByEntry.set(entryAbs, drained);
+        }
+        const worker = drained.get(jobType);
+        if (!worker) {
+            throw new Error(`connector pack "${packId}" entry "${spec.entry}" did not register a worker for ` +
+                `"${jobType}" (its defineWorker call declares a different type).`);
+        }
+        const wrapped = adaptConnectorHandler(worker);
+        const sub = await ctx.engine.registerWorker(jobType, wrapped, {
+            workerName: `${ctx.manifest.id}:${jobType}`,
+            // The pack's `defineWorker({ maxParallelJobs })` is the authoritative runtime
+            // value; the ext.json spec is a design-time default when the code omits it.
+            maxParallelJobs: worker.maxParallelJobs ?? spec.maxParallelJobs,
+        });
+        subs.push(sub);
+        jobTypes.push(jobType);
+        ctx.host.log("info", "connector worker registered", { jobType, connector: packId });
+    }
+    return makeHandle(subs, jobTypes);
+}
+function makeHandle(subs, jobTypes) {
+    return {
+        name: "connectors",
+        jobTypes,
+        async stop() {
+            await Promise.allSettled(subs.map((s) => s.unsubscribe()));
+        },
+        describe: () => ({ jobTypes }),
+    };
+}

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

@@ -140,11 +140,26 @@ async function applyMigrations(host, db, root, migrationsDir) {
         if (applied.has(file))
             continue;
         const sql = await host.readTextFile(`${dir}/${file}`);
-        db.exec(sql);
-        db.run("INSERT INTO _urban_migrations (name, applied_at) VALUES (?, ?)", [
-            file,
-            new Date(host.now()).toISOString(),
-        ]);
+        // Apply the migration and record it in the ledger atomically. SQLite DDL is
+        // transactional, so wrapping both in one BEGIN/COMMIT makes a migration all-or-nothing:
+        // either the schema change AND its `_urban_migrations` row commit together, or neither
+        // does. Without this, an interruption (or an error later in the file's SQL) can leave the
+        // schema changed but the migration unrecorded — which poisons every future boot, because
+        // the runner then re-applies the "unapplied" migration and hits e.g. "duplicate column".
+        // Migration files must therefore not contain their own transaction-control statements.
+        db.exec("BEGIN");
+        try {
+            db.exec(sql);
+            db.run("INSERT INTO _urban_migrations (name, applied_at) VALUES (?, ?)", [
+                file,
+                new Date(host.now()).toISOString(),
+            ]);
+            db.exec("COMMIT");
+        }
+        catch (err) {
+            db.exec("ROLLBACK");
+            throw new Error(`migration "${file}" failed and was rolled back (no partial schema change, not recorded as applied): ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+        }
         newlyApplied.push(file);
     }
     return newlyApplied;

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

@@ -68,6 +68,11 @@ export async function mountWorkers(ctx, app) {
         const jobType = workerJobType(decl);
         if (!jobType)
             continue;
+        // Connector-backed workers (a `connector` field, no handler/llm) are mounted
+        // separately by mountConnectors — skip them here silently so they don't trip
+        // the "neither handler nor llm" warning below on every startup.
+        if (decl.connector)
+            continue;
         if (!decl.handler) {
             // LLM-backed worker (schema `oneOf` handler|llm): synthesise a handler that runs
             // the job through the bound LLM (and optional decision rails) instead of loading a

package/dist/runtime/core/runtime.js

@@ -8,6 +8,7 @@ import { makeRouter } from "./router.js";
 import { deployModels } from "./modules/deploy.js";
 import { provisionData, DataLayer } from "./modules/datasource.js";
 import { mountWorkers } from "./modules/workers.js";
+import { mountConnectors } from "./modules/connectors.js";
 import { mountSurfaces } from "./modules/surfaces.js";
 import { mountTriggers } from "./modules/triggers.js";
 import { mountSecurity } from "./modules/security.js";
@@ -122,6 +123,12 @@ export async function createUrbanApp(opts) {
                     const w = await mountWorkers(ctx, api);
                     mounted.push(w);
                     describe.workers = w.describe?.();
+                    // Connector-pack workers share the `workers` flag: same lifecycle, same
+                    // engine, distinguished only by a `connector` field on the declaration.
+                    const c = await mountConnectors(ctx, api);
+                    mounted.push(c);
+                    if (c.jobTypes.length > 0)
+                        describe.connectors = c.describe?.();
                 }
                 const routes = [];
                 if (flags.surfaces) {

package/dist/runtime/core/validate.js

@@ -56,15 +56,41 @@ export function collectManifestIssues(m) {
             if (!workerJobType(w)) {
                 issues.push({ path: `workers[${i}]`, message: "missing taskType" });
             }
-            // The schema allows a worker backed by either a `handler` file or an `llm`
-            // binding (oneOf). Require exactly one — don't force `handler`.
-            const hasHandler = typeof w?.handler === "string" && w.handler.length > 0;
-            const hasLlm = typeof w?.llm === "string" && w.llm.length > 0;
-            if (!hasHandler && !hasLlm) {
-                issues.push({ path: `workers[${i}]`, message: "worker requires a `handler` or `llm`" });
+            // A worker is backed by exactly one of: a `handler` file, an `llm` binding,
+            // or an installed `connector` pack (ADR 0050). The schema models these as a
+            // oneOf; enforce the "exactly one" here without forcing `handler`. Whether a
+            // `connector` actually resolves to an installed pack is a runtime seam check
+            // (mountConnectors), not something this static manifest check can see.
+            const backings = [];
+            if (typeof w?.handler === "string" && w.handler.length > 0)
+                backings.push("handler");
+            if (typeof w?.llm === "string" && w.llm.length > 0)
+                backings.push("llm");
+            if (typeof w?.connector === "string" && w.connector.length > 0)
+                backings.push("connector");
+            if (backings.length === 0) {
+                issues.push({
+                    path: `workers[${i}]`,
+                    message: "worker requires a `handler`, `llm`, or `connector`",
+                });
             }
-            else if (hasHandler && hasLlm) {
-                issues.push({ path: `workers[${i}]`, message: "worker declares both `handler` and `llm` (mutually exclusive)" });
+            else if (backings.length > 1) {
+                issues.push({
+                    path: `workers[${i}]`,
+                    message: `worker declares ${backings.join(" + ")} (mutually exclusive)`,
+                });
+            }
+            // A `connection` must reference a declared top-level `connections` entry.
+            if (typeof w?.connection === "string" && w.connection.length > 0) {
+                const conns = man.connections && typeof man.connections === "object" && !Array.isArray(man.connections)
+                    ? man.connections
+                    : undefined;
+                if (!conns || !(w.connection in conns)) {
+                    issues.push({
+                        path: `workers[${i}].connection`,
+                        message: `no such connection "${w.connection}" (add it to connections)`,
+                    });
+                }
             }
         });
     }

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

@@ -16,6 +16,13 @@ export interface NanoSdkActivatedJob {
         errorMessage: string;
         retries?: number;
     }): Promise<unknown>;
+    /** Raise a BPMN error (Zeebe `ThrowError`) routed to an error boundary/event.
+     *  Present on the nano-sdk enriched job at runtime; typed here so the adapter
+     *  can honour a handler's {@link BpmnError} (ADR 0050). */
+    error?(e: {
+        errorCode: string;
+        errorMessage?: string;
+    }): Promise<unknown>;
 }
 /** Config for a nano-sdk job worker (the subset this adapter sets). */
 export interface NanoSdkJobWorkerConfig {

package/dist/runtime/engine/nanosdk.js

@@ -18,6 +18,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+import { isBpmnError } from "../core/host.js";
 /** 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) {
@@ -121,6 +122,32 @@ export class SdkEngineClient {
                     return await job.complete(out ?? {});
                 }
                 catch (err) {
+                    // A handler-raised BPMN error is a modelled, non-retryable outcome:
+                    // report it as a BPMN error (routed to an error boundary/event) rather
+                    // than a plain failure. If the transport lacks `error` (older SDK) — or
+                    // the `error` call itself fails — fall through to the `fail` path below
+                    // so the job is still acknowledged rather than left to lock-timeout.
+                    if (isBpmnError(err) && typeof job.error === "function") {
+                        // `message` is typed loosely (the guard survives module duplication),
+                        // so coerce to a string before slicing to avoid a secondary crash.
+                        const raw = err.message;
+                        const message = typeof raw === "string" && raw.length > 0 ? raw : err.errorCode;
+                        this.log("info", `handler ${jobType} raised BPMN error`, {
+                            errorCode: err.errorCode,
+                        });
+                        try {
+                            return await job.error({
+                                errorCode: err.errorCode,
+                                errorMessage: message.slice(0, 500),
+                            });
+                        }
+                        catch (errReportErr) {
+                            this.log("warn", `handler ${jobType}: BPMN error report failed, failing the job`, {
+                                err: errReportErr instanceof Error ? errReportErr.message : String(errReportErr),
+                            });
+                            // fall through to the fail path
+                        }
+                    }
                     const message = err instanceof Error ? err.message : String(err);
                     this.log("error", `handler ${jobType} threw`, { err: message });
                     try {

package/dist/runtime/index.d.ts

@@ -6,6 +6,9 @@ export { collectManifestIssues, ManifestValidationError, validateManifest, } fro
 export type { ValidationIssue } from "./core/validate.ts";
 export type { EngineClient, EngineJob, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, SqliteDb, WatchHandle, WorkerSubscription, } from "./core/host.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
+export { BpmnError, isBpmnError } from "./core/host.ts";
+export { adaptConnectorHandler, mountConnectors, resolveInstalledConnectors, } from "./core/modules/connectors.ts";
+export type { ConnectorsHandle } from "./core/modules/connectors.ts";
 export { DataLayer, TypeRepo } from "./core/modules/datasource.ts";
 export type { ProvisionedSource } from "./core/modules/datasource.ts";
 export { makeGateway, Table } from "./core/modules/gateway.ts";

package/dist/runtime/index.js

@@ -5,6 +5,11 @@ export { createUrbanApp } from "./core/runtime.js";
 export { expandEnv, expandEnvString, loadManifest, parseManifest, workerJobType, } from "./core/manifest.js";
 // Validation
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.js";
+// BPMN error contract: a handler throws `BpmnError(code)` to raise a modelled
+// error routed to an error boundary (ADR 0050), instead of a retryable failure.
+export { BpmnError, isBpmnError } from "./core/host.js";
+// Connector packs (ADR 0050, in-process port)
+export { adaptConnectorHandler, mountConnectors, resolveInstalledConnectors, } from "./core/modules/connectors.js";
 // Data layer
 export { DataLayer, TypeRepo } from "./core/modules/datasource.js";
 export { makeGateway, Table } from "./core/modules/gateway.js";

package/dist/toolkit/addConnector.d.ts

@@ -0,0 +1,29 @@
+import type { GenIO } from "./gen.ts";
+export interface AddConnectorOptions {
+    /** App root directory. */
+    root: string;
+    /** The installed npm package name (already present under node_modules). */
+    pkg: string;
+    /** Manifest filename under root. Default "nano.app.json". */
+    manifestFile?: string;
+    io: GenIO;
+}
+export interface AddConnectorResult {
+    /** The pack id (`nano-ide.ext.json` `id`) written to each worker's `connector`. */
+    packId: string;
+    /** Workers considered, with whether one was already wired (idempotent). */
+    wired: {
+        taskType: string;
+        alreadyPresent: boolean;
+    }[];
+    /** The named connection created/reused, if the pack needs credentials. */
+    connection?: string;
+    /** Env vars the operator must set for the enabled workers to run. */
+    requiredEnv: string[];
+}
+/**
+ * Read the installed pack manifest, then wire its workers into the app manifest.
+ * Idempotent: re-running never duplicates a `workers[]`/`connections[]` entry.
+ * The app manifest object is mutated in place and written back.
+ */
+export declare function addConnector(opts: AddConnectorOptions): Promise<AddConnectorResult>;

package/dist/toolkit/addConnector.js

@@ -0,0 +1,170 @@
+// addConnector — enable an installed connector pack into an app's nano.app.json.
+//
+// A connector pack ships a `nano-ide.ext.json` manifest declaring one or more
+// workers (a `taskType`, a worker `entry`, and its config fields). "Enabling" it
+// means the pure, idempotent manifest edit the `urban add` CLI performs after
+// `npm install <pkg>` (ADR 0050 §5): for every worker the pack declares, append a
+// pack-backed `workers[]` entry (`{ taskType, connector: <pack-id>, connection }`)
+// and, when the pack needs credentials, a named `connections[]` entry whose values
+// are env-pointer templates (never inline secrets, ADR 0025 §1 / 0027 §5).
+//
+// This module only reads/writes files through the GenIO port — installing the
+// package (a subprocess) is the CLI's job, so this stays runtime-agnostic and
+// unit-testable.
+const MANIFEST_FILE = "nano-ide.ext.json";
+function joinPath(a, b) {
+    // Trim both slash styles (as toolkit/gen.ts joinPath does) so a Windows-style
+    // root does not produce an invalid path.
+    return `${a.replace(/[/\\]+$/, "")}/${b.replace(/^[/\\]+/, "")}`;
+}
+/** A stable, slug-ish connection name for a pack id (kebab, no leading scope). */
+function connectionNameFor(packId) {
+    const base = packId.includes("/") ? packId.slice(packId.lastIndexOf("/") + 1) : packId;
+    return base.replace(/[^a-z0-9]+/gi, "-").replace(/^-+|-+$/g, "").toLowerCase() || packId;
+}
+/**
+ * Read the installed pack manifest, then wire its workers into the app manifest.
+ * Idempotent: re-running never duplicates a `workers[]`/`connections[]` entry.
+ * The app manifest object is mutated in place and written back.
+ */
+export async function addConnector(opts) {
+    const { root, pkg, io } = opts;
+    const manifestFile = opts.manifestFile ?? "nano.app.json";
+    const packManifestPath = joinPath(joinPath(joinPath(root, "node_modules"), pkg), MANIFEST_FILE);
+    if (!(await io.exists(packManifestPath))) {
+        throw new Error(`"${pkg}" is not an Urban connector: no ${MANIFEST_FILE} found at ${packManifestPath}. ` +
+            `Install the package first (\`npm install ${pkg}\`), and check it is a connector pack.`);
+    }
+    let pack;
+    try {
+        pack = JSON.parse(await io.readText(packManifestPath));
+    }
+    catch (err) {
+        throw new Error(`failed to parse ${packManifestPath}: ${err.message}`);
+    }
+    if (typeof pack.id !== "string" || !pack.id) {
+        throw new Error(`${packManifestPath} has no string "id" (a pack must declare its id).`);
+    }
+    const specs = Array.isArray(pack.workers) ? pack.workers : [];
+    if (specs.length === 0) {
+        throw new Error(`connector pack "${pack.id}" declares no workers[] — nothing to enable.`);
+    }
+    // `type` comes from JSON; a malformed pack must fail loudly rather than wire an
+    // invalid worker entry (or manufacture a confusing conflict).
+    for (const spec of specs) {
+        if (typeof spec.type !== "string" || spec.type.length === 0) {
+            throw new Error(`connector pack "${pack.id}" has a worker with a missing/non-string "type" in ${packManifestPath}.`);
+        }
+    }
+    const appManifestPath = joinPath(root, manifestFile);
+    if (!(await io.exists(appManifestPath))) {
+        throw new Error(`no ${manifestFile} at ${appManifestPath} — run this inside an Urban app.`);
+    }
+    let app;
+    try {
+        app = JSON.parse(await io.readText(appManifestPath));
+    }
+    catch (err) {
+        throw new Error(`failed to parse ${appManifestPath}: ${err.message}`);
+    }
+    if (app === null || typeof app !== "object" || Array.isArray(app)) {
+        throw new Error(`${appManifestPath} is not a JSON object.`);
+    }
+    if (app.workers !== undefined && !Array.isArray(app.workers)) {
+        throw new Error(`${appManifestPath} "workers" must be an array.`);
+    }
+    if (app.connections !== undefined &&
+        (app.connections === null || typeof app.connections !== "object" || Array.isArray(app.connections))) {
+        throw new Error(`${appManifestPath} "connections" must be an object.`);
+    }
+    const workers = (app.workers ??= []);
+    // Required env across the pack's workers (env-pointer fields without a default).
+    const envFields = [];
+    const requiredEnvSet = new Set();
+    for (const spec of specs) {
+        for (const f of spec.configFields ?? []) {
+            if (f.env) {
+                envFields.push(f);
+                if (f.default === undefined || f.default === "")
+                    requiredEnvSet.add(f.env);
+            }
+        }
+    }
+    // Create/reuse a named connection when the pack carries credential config, so the
+    // required env pointers are documented in the manifest (secrets stay templates).
+    let connection;
+    if (envFields.length > 0) {
+        connection = connectionNameFor(pack.id);
+        const connections = (app.connections ??= {});
+        const existing = connections[connection];
+        if (existing === undefined) {
+            const conn = { type: pack.id };
+            for (const f of envFields) {
+                if (!(f.key in conn) && f.env)
+                    conn[f.key] = `\${${f.env}}`;
+            }
+            connections[connection] = conn;
+        }
+        else {
+            // A pre-existing connection of this name must be a compatible object of the
+            // same pack `type`; otherwise wiring workers to it would produce an invalid
+            // or misleading manifest. Fail loudly instead of silently reusing it.
+            if (existing === null || typeof existing !== "object" || Array.isArray(existing)) {
+                throw new Error(`connection "${connection}" already exists and is not an object.`);
+            }
+            const conn = existing;
+            if (conn.type !== undefined && conn.type !== pack.id) {
+                throw new Error(`connection "${connection}" already exists with type "${String(conn.type)}", ` +
+                    `not "${pack.id}".`);
+            }
+            // Backfill the pack's `type` and any missing env-pointer templates.
+            if (conn.type === undefined)
+                conn.type = pack.id;
+            for (const f of envFields) {
+                if (!(f.key in conn) && f.env)
+                    conn[f.key] = `\${${f.env}}`;
+            }
+        }
+    }
+    const wired = [];
+    for (const spec of specs) {
+        const existing = workers.find((w) => w.taskType === spec.type);
+        if (existing) {
+            // A same-taskType worker backed by a handler/llm or a different connector is
+            // a real conflict — enabling this pack would not take effect. Fail loudly
+            // instead of reporting a false success.
+            if (existing.connector !== pack.id) {
+                const backing = existing.handler
+                    ? `handler "${existing.handler}"`
+                    : existing.llm
+                        ? `llm "${existing.llm}"`
+                        : existing.connector
+                            ? `connector "${existing.connector}"`
+                            : "another backing";
+                throw new Error(`worker "${spec.type}" is already declared with ${backing}; ` +
+                    `remove it before enabling connector "${pack.id}" for that taskType.`);
+            }
+            wired.push({ taskType: spec.type, alreadyPresent: true });
+            // Heal an entry that references the pack but predates the connection.
+            if (connection && !existing.connection) {
+                existing.connection = connection;
+            }
+            continue;
+        }
+        const entry = {
+            taskType: spec.type,
+            connector: pack.id,
+        };
+        if (connection)
+            entry.connection = connection;
+        workers.push(entry);
+        wired.push({ taskType: spec.type, alreadyPresent: false });
+    }
+    await io.writeText(appManifestPath, JSON.stringify(app, null, 2) + "\n");
+    return {
+        packId: pack.id,
+        wired,
+        connection,
+        requiredEnv: [...requiredEnvSet],
+    };
+}

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));
+        },
     };
 }