@nanobpm/urban 0.18.0 → 0.19.0

package/src/runtime/core/modules/datasource.migrations.test.ts

@@ -0,0 +1,114 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createNodeHost } from "../../adapters/node.ts";
+import { provisionData } from "./datasource.ts";
+import type { RuntimeContext } from "../context.ts";
+import type { EngineClient } from "../host.ts";
+import type { AppManifest } from "../manifest.ts";
+
+// provisionData never touches the engine — a bare stub is enough for these datasource tests.
+const noEngine = {} as EngineClient;
+
+async function fixture(migrations: Record<string, string>): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "urban-mig-"));
+  await mkdir(join(dir, "db", "migrations"), { recursive: true });
+  for (const [name, sql] of Object.entries(migrations)) {
+    await writeFile(join(dir, "db", "migrations", name), sql);
+  }
+  return dir;
+}
+
+function ctx(dir: string): RuntimeContext {
+  const manifest = {
+    schemaVersion: 1,
+    id: "mig-fixture",
+    name: "Migration Fixture",
+    data: {
+      default: "app",
+      sources: { app: { driver: "sqlite", url: "file:./app.db", migrations: "db/migrations" } },
+    },
+  } as unknown as AppManifest;
+  return { manifest, host: createNodeHost({ cwd: dir, log: () => {} }), engine: noEngine, root: "." };
+}
+
+function columns(dir: string, table: string): string[] {
+  const db = createNodeHost({ cwd: dir, log: () => {} }).openSqlite(join(dir, "app.db"));
+  try {
+    return db.all<{ name: string }>(`PRAGMA table_info(${table})`).map((r) => r.name);
+  } finally {
+    db.close();
+  }
+}
+
+function ledger(dir: string): string[] {
+  const db = createNodeHost({ cwd: dir, log: () => {} }).openSqlite(join(dir, "app.db"));
+  try {
+    return db.all<{ name: string }>("SELECT name FROM _urban_migrations ORDER BY name").map((r) => r.name);
+  } finally {
+    db.close();
+  }
+}
+
+test("migrations apply once and are skipped on the next boot (idempotent)", async () => {
+  const dir = await fixture({
+    "001_init.sql": "CREATE TABLE rounds (id INTEGER PRIMARY KEY, summary TEXT);",
+    "002_transcript.sql": "ALTER TABLE rounds ADD COLUMN transcript TEXT;",
+  });
+  try {
+    const first = await provisionData(ctx(dir));
+    assert.deepEqual(first.source("app").migrationsApplied, ["001_init.sql", "002_transcript.sql"]);
+    first.closeAll();
+
+    assert.deepEqual(ledger(dir), ["001_init.sql", "002_transcript.sql"]);
+    assert.ok(columns(dir, "rounds").includes("transcript"));
+
+    // Second boot: everything is already recorded, so nothing re-runs (no "duplicate column").
+    const second = await provisionData(ctx(dir));
+    assert.deepEqual(second.source("app").migrationsApplied, []);
+    second.closeAll();
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("a failing migration rolls back atomically — schema is never left ahead of the ledger", async () => {
+  // Models the real urban-pr-review failure: an interrupted/failing migration must NOT leave a
+  // column present while its `_urban_migrations` row is missing, or every future boot re-applies
+  // it and dies with "duplicate column name". 002 adds `transcript`, then hits an error.
+  const dir = await fixture({
+    "001_init.sql": "CREATE TABLE rounds (id INTEGER PRIMARY KEY, summary TEXT);",
+    "002_transcript.sql":
+      "ALTER TABLE rounds ADD COLUMN transcript TEXT;\nINSERT INTO does_not_exist VALUES (1);",
+  });
+  try {
+    await assert.rejects(
+      provisionData(ctx(dir)),
+      /migration "002_transcript.sql" failed and was rolled back/,
+    );
+
+    // The whole migration rolled back: 001 is applied, but 002 left NO trace.
+    assert.deepEqual(ledger(dir), ["001_init.sql"]);
+    assert.ok(
+      !columns(dir, "rounds").includes("transcript"),
+      "the partially-applied ALTER must have been rolled back",
+    );
+
+    // Repair the migration and re-boot: because the earlier attempt left no partial state,
+    // `transcript` applies cleanly instead of colliding — the poisoned state can never arise.
+    await writeFile(
+      join(dir, "db", "migrations", "002_transcript.sql"),
+      "ALTER TABLE rounds ADD COLUMN transcript TEXT;",
+    );
+    const repaired = await provisionData(ctx(dir));
+    assert.deepEqual(repaired.source("app").migrationsApplied, ["002_transcript.sql"]);
+    repaired.closeAll();
+
+    assert.deepEqual(ledger(dir), ["001_init.sql", "002_transcript.sql"]);
+    assert.ok(columns(dir, "rounds").includes("transcript"));
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/runtime/core/modules/datasource.ts

@@ -188,11 +188,30 @@ async function applyMigrations(
   for (const file of files) {
     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/src/runtime/core/modules/workers.test.ts

@@ -157,6 +157,19 @@ test("sdkDecisionEvaluator throws a clear error when the SDK lacks evaluateDecis
   await assert.rejects(evaluate("risk", {}), /does not support evaluateDecision.*"risk"/);
 });
 
+test("mountWorkers silently skips a connector-backed worker (mountConnectors owns it)", async () => {
+  const engine = new MiniEngine();
+  const { ctx, logs } = makeCtx(
+    { workers: [{ taskType: "slack:send-message", connector: "nano-ide-connector-slack" }] },
+    engine,
+  );
+  const handle = await mountWorkers(ctx, makeApp());
+  assert.deepEqual(handle.jobTypes, []);
+  assert.equal(engine.workers.size, 0);
+  // No spurious "neither a handler nor an llm" warning for a connector worker.
+  assert.ok(!logs.some((l) => l.msg.includes("neither a handler nor an llm")));
+});
+
 // ── AppJobHandler generics: optional In/Out type parameters ──────────────────────────────
 // These are primarily compile-time assertions (the suite is typechecked by `tsc --noEmit`),
 // with a runtime smoke that a typed handler still returns its output when delivered a job.

package/src/runtime/core/modules/workers.ts

@@ -109,6 +109,10 @@ export async function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<Wo
   for (const decl of decls as Worker[]) {
     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/src/runtime/core/runtime.ts

@@ -12,6 +12,7 @@ import { makeRouter, type Route } from "./router.ts";
 import { deployModels } from "./modules/deploy.ts";
 import { provisionData, DataLayer } from "./modules/datasource.ts";
 import { mountWorkers } from "./modules/workers.ts";
+import { mountConnectors } from "./modules/connectors.ts";
 import { mountSurfaces } from "./modules/surfaces.ts";
 import { mountTriggers } from "./modules/triggers.ts";
 import { mountSecurity, type SecurityPolicy } from "./modules/security.ts";
@@ -169,6 +170,11 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
           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: Route[] = [];

package/src/runtime/core/validate.test.ts

@@ -72,6 +72,30 @@ test("data.default must reference an existing source", () => {
   assert.ok(issues.some((i) => i.path === "data.default"));
 });
 
+test("a worker connection must reference a declared connections entry", () => {
+  const missing = collectManifestIssues({
+    ...valid,
+    workers: [{ taskType: "a.b", connector: "slack", connection: "slack" }],
+  });
+  assert.ok(missing.some((i) => i.path === "workers[0].connection"));
+
+  const present = collectManifestIssues({
+    ...valid,
+    workers: [{ taskType: "a.b", connector: "slack", connection: "slack" }],
+    connections: { slack: { type: "slack" } },
+  });
+  assert.ok(!present.some((i) => i.path === "workers[0].connection"));
+});
+
+test("a non-object connections does not throw and flags the reference", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    workers: [{ taskType: "a.b", connector: "slack", connection: "slack" }],
+    connections: "nope",
+  });
+  assert.ok(issues.some((i) => i.path === "workers[0].connection"));
+});
+
 test("validateManifest throws ManifestValidationError with issues", () => {
   assert.throws(() => validateManifest({ schemaVersion: 1 }), (e: unknown) => {
     assert.ok(e instanceof ManifestValidationError);

package/src/runtime/core/validate.ts

@@ -76,14 +76,38 @@ export function collectManifestIssues(m: unknown): ValidationIssue[] {
       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`" });
-      } else if (hasHandler && hasLlm) {
-        issues.push({ path: `workers[${i}]`, message: "worker declares both `handler` and `llm` (mutually exclusive)" });
+      // 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: string[] = [];
+      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 (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 as Record<string, unknown>)
+            : undefined;
+        if (!conns || !(w.connection in conns)) {
+          issues.push({
+            path: `workers[${i}].connection`,
+            message: `no such connection "${w.connection}" (add it to connections)`,
+          });
+        }
       }
     });
   }

package/src/runtime/engine/nanosdk.test.ts

@@ -9,6 +9,7 @@ import {
   type NanoSdkJobWorker,
   type NanoSdkJobWorkerConfig,
 } from "./nanosdk.ts";
+import { BpmnError } from "../core/host.ts";
 
 /** A fake nano-sdk client that records calls and lets a test drive its job worker. */
 function fakeSdkClient(overrides: Partial<NanoSdkClient> = {}): NanoSdkClient & {
@@ -266,6 +267,81 @@ test("registerWorker fails the job when the handler throws", async () => {
   assert.equal(failBody?.retries, 0);
 });
 
+test("registerWorker routes a thrown BpmnError to the engine's error()", async () => {
+  const client = fakeSdkClient();
+  const engine = new SdkEngineClient(client);
+  await engine.registerWorker("svc", () => {
+    throw new BpmnError("NOT_FOUND", "no such record");
+  });
+  const rec = client.workers[0];
+  let errorBody: { errorCode: string; errorMessage?: string } | undefined;
+  await rec.dispatch({
+    jobKey: "j1",
+    variables: {},
+    async complete() {
+      throw new Error("should not complete");
+    },
+    async fail() {
+      throw new Error("should not fail — a BPMN error is not a job failure");
+    },
+    async error(body: { errorCode: string; errorMessage?: string }) {
+      errorBody = body;
+      return "raised";
+    },
+  } as unknown as NanoSdkActivatedJob);
+  assert.equal(errorBody?.errorCode, "NOT_FOUND");
+  assert.equal(errorBody?.errorMessage, "no such record");
+});
+
+test("registerWorker falls back to fail() for a BpmnError when the SDK has no error()", async () => {
+  const client = fakeSdkClient();
+  const engine = new SdkEngineClient(client);
+  await engine.registerWorker("svc", () => {
+    throw new BpmnError("NOT_FOUND", "no such record");
+  });
+  const rec = client.workers[0];
+  let failBody: { errorMessage: string } | undefined;
+  await rec.dispatch({
+    jobKey: "j1",
+    variables: {},
+    async complete() {
+      throw new Error("should not complete");
+    },
+    async fail(body: { errorMessage: string }) {
+      failBody = body;
+      return "failed";
+    },
+    // no error() — older transport
+  } as unknown as NanoSdkActivatedJob);
+  assert.equal(failBody?.errorMessage, "no such record");
+});
+
+test("registerWorker falls back to fail() when the BPMN error report itself throws", async () => {
+  const client = fakeSdkClient();
+  const engine = new SdkEngineClient(client);
+  await engine.registerWorker("svc", () => {
+    throw new BpmnError("NOT_FOUND", "no such record");
+  });
+  const rec = client.workers[0];
+  let failBody: { errorMessage: string } | undefined;
+  await rec.dispatch({
+    jobKey: "j1",
+    variables: {},
+    async complete() {
+      throw new Error("should not complete");
+    },
+    async error() {
+      throw new Error("transport down");
+    },
+    async fail(body: { errorMessage: string }) {
+      failBody = body;
+      return "failed";
+    },
+  } as unknown as NanoSdkActivatedJob);
+  // The job must still be acknowledged via fail() rather than silently dropped.
+  assert.equal(failBody?.errorMessage, "no such record");
+});
+
 test("close stops every worker and closes the SDK client", async () => {
   const client = fakeSdkClient();
   const engine = new SdkEngineClient(client);

package/src/runtime/engine/nanosdk.ts

@@ -17,6 +17,7 @@ import type {
   JobHandler,
   WorkerSubscription,
 } from "../core/host.ts";
+import { isBpmnError } from "../core/host.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 
 /** Coerce an engine response's process-instance key to a non-empty string, or
@@ -38,6 +39,10 @@ export interface NanoSdkActivatedJob {
   variables?: Record<string, unknown>;
   complete(variables?: Record<string, unknown>): Promise<unknown>;
   fail(body: { 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). */
@@ -233,6 +238,31 @@ export class SdkEngineClient implements EngineClient {
           const out = await handler(engineJob);
           return await job.complete((out as Record<string, unknown> | undefined) ?? {});
         } 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 as { message?: unknown }).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/src/runtime/index.ts

@@ -55,6 +55,18 @@ export type {
 } from "./core/host.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
 
+// 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.ts";
+
+// Connector packs (ADR 0050, in-process port)
+export {
+  adaptConnectorHandler,
+  mountConnectors,
+  resolveInstalledConnectors,
+} from "./core/modules/connectors.ts";
+export type { ConnectorsHandle } from "./core/modules/connectors.ts";
+
 // Data layer
 export { DataLayer, TypeRepo } from "./core/modules/datasource.ts";
 export type { ProvisionedSource } from "./core/modules/datasource.ts";

package/src/toolkit/addConnector.test.ts

@@ -0,0 +1,161 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import type { GenIO } from "./gen.ts";
+import { addConnector } from "./addConnector.ts";
+
+function memIO(files: Record<string, string>): GenIO & { files: Record<string, string> } {
+  return {
+    files,
+    async readText(p) {
+      if (!(p in files)) throw new Error(`ENOENT ${p}`);
+      return files[p];
+    },
+    async writeText(p, c) {
+      files[p] = c;
+    },
+    async listDir() {
+      return [];
+    },
+    async exists(p) {
+      return p in files;
+    },
+    async remove(p) {
+      delete files[p];
+    },
+  };
+}
+
+const PKG = "@nanobpm/nano-ide-connector-slack";
+const PACK_ID = "nano-ide-connector-slack";
+
+function baseFiles(appManifest: Record<string, unknown> = { schemaVersion: 1, id: "t", name: "T" }) {
+  return {
+    "app/nano.app.json": JSON.stringify(appManifest),
+    [`app/node_modules/${PKG}/nano-ide.ext.json`]: JSON.stringify({
+      id: PACK_ID,
+      workers: [
+        {
+          type: "slack:send-message",
+          entry: "worker.ts",
+          configFields: [{ key: "botToken", env: "SLACK_BOT_TOKEN" }],
+        },
+      ],
+    }),
+  };
+}
+
+test("addConnector wires a pack-backed worker + a connection into nano.app.json", async () => {
+  const io = memIO(baseFiles());
+  const res = await addConnector({ root: "app", pkg: PKG, io });
+
+  assert.equal(res.packId, PACK_ID);
+  assert.deepEqual(res.wired, [{ taskType: "slack:send-message", alreadyPresent: false }]);
+  assert.deepEqual(res.requiredEnv, ["SLACK_BOT_TOKEN"]);
+  assert.equal(res.connection, "nano-ide-connector-slack");
+
+  const app = JSON.parse(io.files["app/nano.app.json"]);
+  assert.deepEqual(app.workers, [
+    {
+      taskType: "slack:send-message",
+      connector: PACK_ID,
+      connection: "nano-ide-connector-slack",
+    },
+  ]);
+  assert.deepEqual(app.connections["nano-ide-connector-slack"], {
+    type: PACK_ID,
+    botToken: "${SLACK_BOT_TOKEN}",
+  });
+});
+
+test("addConnector is idempotent — re-running does not duplicate entries", async () => {
+  const io = memIO(baseFiles());
+  await addConnector({ root: "app", pkg: PKG, io });
+  const res2 = await addConnector({ root: "app", pkg: PKG, io });
+  assert.deepEqual(res2.wired, [{ taskType: "slack:send-message", alreadyPresent: true }]);
+  const app = JSON.parse(io.files["app/nano.app.json"]);
+  assert.equal(app.workers.length, 1);
+  assert.equal(Object.keys(app.connections).length, 1);
+});
+
+test("addConnector throws on a taskType already backed by a handler (conflict)", async () => {
+  const io = memIO(
+    baseFiles({
+      schemaVersion: 1,
+      id: "t",
+      name: "T",
+      workers: [{ taskType: "slack:send-message", handler: "handlers/slack.ts" }],
+    }),
+  );
+  await assert.rejects(() => addConnector({ root: "app", pkg: PKG, io }), /already declared with handler/);
+});
+
+test("addConnector throws when the package is not an Urban connector", async () => {
+  const io = memIO({ "app/nano.app.json": JSON.stringify({ schemaVersion: 1, id: "t", name: "T" }) });
+  await assert.rejects(() => addConnector({ root: "app", pkg: PKG, io }), /not an Urban connector/);
+});
+
+test("addConnector reports which app manifest fails to parse", async () => {
+  const io = memIO({
+    "app/nano.app.json": "{ not json",
+    [`app/node_modules/${PKG}/nano-ide.ext.json`]: JSON.stringify({
+      id: PACK_ID,
+      workers: [{ type: "slack:send-message", entry: "worker.ts" }],
+    }),
+  });
+  await assert.rejects(() => addConnector({ root: "app", pkg: PKG, io }), /failed to parse .*nano\.app\.json/);
+});
+
+test("addConnector rejects a manifest whose connections is not an object", async () => {
+  const io = memIO(baseFiles({ schemaVersion: 1, id: "t", name: "T", connections: "nope" }));
+  await assert.rejects(() => addConnector({ root: "app", pkg: PKG, io }), /"connections" must be an object/);
+});
+
+test("addConnector rejects an existing connection of a different type", async () => {
+  const io = memIO(
+    baseFiles({
+      schemaVersion: 1,
+      id: "t",
+      name: "T",
+      connections: { [PACK_ID]: { type: "other" } },
+    }),
+  );
+  await assert.rejects(
+    () => addConnector({ root: "app", pkg: PKG, io }),
+    /already exists with type "other"/,
+  );
+});
+
+test("addConnector rejects an existing connection that is not an object", async () => {
+  const io = memIO(
+    baseFiles({ schemaVersion: 1, id: "t", name: "T", connections: { [PACK_ID]: "nope" } }),
+  );
+  await assert.rejects(
+    () => addConnector({ root: "app", pkg: PKG, io }),
+    /already exists and is not an object/,
+  );
+});
+
+test("addConnector backfills missing env pointers on a matching existing connection", async () => {
+  const io = memIO(
+    baseFiles({ schemaVersion: 1, id: "t", name: "T", connections: { [PACK_ID]: { type: PACK_ID } } }),
+  );
+  await addConnector({ root: "app", pkg: PKG, io });
+  const app = JSON.parse(io.files["app/nano.app.json"]);
+  assert.deepEqual(app.connections[PACK_ID], { type: PACK_ID, botToken: "${SLACK_BOT_TOKEN}" });
+});
+
+test("addConnector omits a connection when the pack needs no env credentials", async () => {
+  const io = memIO({
+    "app/nano.app.json": JSON.stringify({ schemaVersion: 1, id: "t", name: "T" }),
+    [`app/node_modules/${PKG}/nano-ide.ext.json`]: JSON.stringify({
+      id: PACK_ID,
+      workers: [{ type: "noop:run", entry: "worker.ts" }],
+    }),
+  });
+  const res = await addConnector({ root: "app", pkg: PKG, io });
+  assert.equal(res.connection, undefined);
+  assert.deepEqual(res.requiredEnv, []);
+  const app = JSON.parse(io.files["app/nano.app.json"]);
+  assert.deepEqual(app.workers, [{ taskType: "noop:run", connector: PACK_ID }]);
+  assert.equal(app.connections, undefined);
+});