@elench/testkit 0.1.139 → 0.1.140

package/lib/app/configs.mjs

@@ -25,8 +25,8 @@ export function resolveTargetConfig(configs, serviceName = null) {
   }
 
   if (configs.length === 1) return configs[0];
-  const withLocalDb = configs.filter((config) => config.testkit.database?.provider === "local");
-  if (withLocalDb.length === 1) return withLocalDb[0];
+  const withDatabase = configs.filter((config) => config.testkit.database);
+  if (withDatabase.length === 1) return withDatabase[0];
 
   const available = configs.map((config) => config.name).join(", ");
   throw new Error(`Multiple services available. Pass --service. Available: ${available}`);

package/lib/cli/operations/db/schema/refresh/operation.mjs

@@ -31,7 +31,7 @@ export async function executeDatabaseSchemaRefreshOperation(options = {}) {
   try {
     for (const config of topologicallySortConfigs(resolvedConfigs)) {
       if (config.name === resolvedTarget.name) break;
-      if (config.testkit.database?.provider === "local") {
+      if (config.testkit.database) {
         await prepareDatabaseRuntime(config, { reporter, logRegistry, setupRegistry });
       }
     }

package/lib/cli/operations/db/schema/verify/operation.mjs

@@ -29,7 +29,7 @@ export async function executeDatabaseSchemaVerifyOperation(options = {}) {
   const setupRegistry = createSetupOperationRegistry({ logRegistry });
   try {
     for (const config of topologicallySortConfigs(resolvedConfigs)) {
-      if (config.testkit.database?.provider === "local") {
+      if (config.testkit.database) {
         await prepareDatabaseRuntime(config, {
           reporter,
           logRegistry,

package/lib/config/database.mjs

@@ -12,26 +12,41 @@ export function normalizeDatabaseConfig(explicitService, serviceName) {
   if (explicitService.databaseFrom) return undefined;
   if (!explicitService.database) return undefined;
 
-  const database =
-    explicitService.database.provider === "local"
-      ? explicitService.database
-      : {
-          provider: "local",
-          ...explicitService.database,
-        };
+  const rawDatabase = explicitService.database;
+  const provider = rawDatabase.provider || (rawDatabase.resource ? "resource" : "local");
+  if (!["local", "resource"].includes(provider)) {
+    throw new Error(`Service "${serviceName}" database.provider must be "local" or "resource"`);
+  }
+
+  const base = {
+    ...rawDatabase,
+    provider,
+    binding: normalizeDatabaseBinding(rawDatabase.binding || "per-runtime", `Service "${serviceName}" database.binding`),
+    reset: rawDatabase.reset !== false,
+    sourceSchema: normalizeSourceSchemaConfig(rawDatabase.sourceSchema, serviceName),
+    template: normalizeDatabaseTemplateConfig(rawDatabase.template, serviceName),
+    serviceName,
+  };
+
+  if (provider === "resource") {
+    const resource = String(rawDatabase.resource || "").trim();
+    if (!resource) {
+      throw new Error(`Service "${serviceName}" database.resource must be a non-empty string`);
+    }
+    return {
+      ...base,
+      resource,
+      selectedBackend: "resource",
+    };
+  }
 
   return {
-    ...database,
-    binding: normalizeDatabaseBinding(database.binding || "per-runtime", `Service "${serviceName}" database.binding`),
+    ...base,
     provider: "local",
     selectedBackend: "local",
-    reset: database.reset !== false,
-    image: database.image || DEFAULT_LOCAL_IMAGE,
-    user: database.user || DEFAULT_LOCAL_USER,
-    password: database.password || DEFAULT_LOCAL_PASSWORD,
-    sourceSchema: normalizeSourceSchemaConfig(database.sourceSchema, serviceName),
-    template: normalizeDatabaseTemplateConfig(database.template, serviceName),
-    serviceName,
+    image: rawDatabase.image || DEFAULT_LOCAL_IMAGE,
+    user: rawDatabase.user || DEFAULT_LOCAL_USER,
+    password: rawDatabase.password || DEFAULT_LOCAL_PASSWORD,
   };
 }
 

package/lib/config-api/index.d.ts

@@ -96,6 +96,17 @@ export interface LocalDatabaseConfig {
   user?: string;
 }
 
+export interface ResourceDatabaseConfig {
+  provider: "resource";
+  binding?: "shared" | "per-runtime";
+  reset?: boolean;
+  resource: string;
+  sourceSchema?: DatabaseSourceSchemaConfig | null;
+  template?: DatabaseTemplateConfig;
+}
+
+export type PostgresDatabaseConfig = LocalDatabaseConfig | ResourceDatabaseConfig;
+
 export interface SkipFileRule {
   path: string;
   reason: string;
@@ -250,7 +261,7 @@ export interface DiscoveryConfig {
 }
 
 export interface ServiceConfig {
-  database?: LocalDatabaseConfig;
+  database?: PostgresDatabaseConfig;
   databaseFrom?: string;
   dependsOn?: string[];
   discovery?: DiscoveryConfig;
@@ -621,6 +632,15 @@ export declare const database: {
       verify?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
     }
   ): LocalDatabaseConfig;
+  postgres(
+    options?: Omit<ResourceDatabaseConfig, "provider" | "template"> & {
+      inputs?: string[];
+      migrate?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
+      seed?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
+      template?: DatabaseTemplateOptions;
+      verify?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
+    }
+  ): ResourceDatabaseConfig;
   fixture(
     options?: Omit<LocalDatabaseConfig, "provider" | "template"> & {
       inputs?: string[];

package/lib/config-api/index.mjs

@@ -27,8 +27,9 @@ export function defineFile(metadata) {
 }
 
 function postgresDatabase(options = {}) {
+  const provider = options.resource ? "resource" : options.provider || "local";
   return {
-    provider: "local",
+    provider,
     ...options,
   };
 }

package/lib/database/index.mjs

@@ -19,6 +19,7 @@ import {
   getLocalInfraDir as getLocalInfraDirModel,
   getLocalLocksDir as getLocalLocksDirModel,
   getLocalServiceCacheDir as getLocalServiceCacheDirModel,
+  getResourceLocksDir as getResourceLocksDirModel,
   hasRemainingLocalArtifacts as hasRemainingLocalArtifactsModel,
   readStateValue as readStateValueModel,
   visitDirs as visitDirsModel,
@@ -56,6 +57,10 @@ export async function prepareDatabaseRuntime(config, options = {}) {
     await prepareLocalDatabase(config, options);
     return;
   }
+  if (db.provider === "resource") {
+    await prepareResourceDatabase(config, options);
+    return;
+  }
 
   throw new Error(`Unsupported database provider "${db.provider}"`);
 }
@@ -64,6 +69,8 @@ export async function destroyRuntimeDatabase({ productDir, stateDir }) {
   const backend = readStateValue(path.join(stateDir, "database_backend"));
   if (backend === "local") {
     await destroyLocalRuntimeDatabase(productDir, stateDir);
+  } else if (backend === "resource") {
+    await destroyResourceRuntimeDatabase(stateDir);
   }
 }
 
@@ -72,12 +79,26 @@ export async function destroyServiceDatabaseCache(productDir, serviceName) {
   if (!fs.existsSync(cacheDir)) return;
 
   const backend = readStateValue(path.join(cacheDir, "database_backend"));
+  const lockDir = getLocalLocksDir(productDir);
+  if (backend === "resource") {
+    const resourceName = readStateValue(path.join(cacheDir, "resource_name"));
+    const resourceLockDir = getResourceLocksDir(productDir, resourceName || "unknown");
+    fs.mkdirSync(resourceLockDir, { recursive: true });
+    await withLock(path.join(resourceLockDir, `template-${serviceName}.lock`), async () => {
+      const infra = resolveResourcePostgresInfraFromState(cacheDir);
+      const templateDbName = readStateValue(path.join(cacheDir, "template_database_name"));
+      if (infra && templateDbName) {
+        await dropDatabaseIfExists(infra, templateDbName);
+      }
+      fs.rmSync(cacheDir, { recursive: true, force: true });
+    });
+    return;
+  }
   if (backend !== "local") {
     fs.rmSync(cacheDir, { recursive: true, force: true });
     return;
   }
 
-  const lockDir = getLocalLocksDir(productDir);
   fs.mkdirSync(lockDir, { recursive: true });
   await withLock(path.join(lockDir, `template-${serviceName}.lock`), async () => {
     const infra = await loadExistingLocalContainer(productDir);
@@ -165,6 +186,40 @@ async function prepareLocalDatabase(config, options = {}) {
   });
 }
 
+async function prepareResourceDatabase(config, options = {}) {
+  const db = config.testkit.database;
+  const productDir = config.productDir;
+  const serviceName = config.name;
+  const bindingKey = resolveDatabaseBindingKey(config);
+  const lockDir = getResourceLocksDir(productDir, db.resource);
+  const cacheDir = getLocalServiceCacheDir(productDir, serviceName);
+  fs.mkdirSync(lockDir, { recursive: true });
+  fs.mkdirSync(cacheDir, { recursive: true });
+
+  const infra = resolveResourcePostgresInfra(config);
+  let templateFingerprint = null;
+
+  await waitForResourcePostgresReady(infra);
+  await withLock(path.join(lockDir, `template-${serviceName}.lock`), async () => {
+    const sourceSchemaState = await prepareSourceSchemaCache(config, options);
+    templateFingerprint = await computeTemplateFingerprint(config, { sourceSchemaState });
+    templateFingerprint = await ensureTemplateDatabase(
+      config,
+      infra,
+      cacheDir,
+      templateFingerprint,
+      {
+        ...options,
+        sourceSchemaState,
+      }
+    );
+  });
+
+  await withLock(path.join(lockDir, `runtime-${serviceName}-${hashString(bindingKey, 10)}.lock`), async () => {
+    await ensureRuntimeClone(config, infra, cacheDir, templateFingerprint, bindingKey);
+  });
+}
+
 async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerprint, options = {}) {
   const serviceName = config.name;
   let activeFingerprint = templateFingerprint;
@@ -187,7 +242,7 @@ async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerpri
         kind: "database-template",
         summary: "template cache hit",
       });
-      writeLocalCacheState(cacheDir, infra, existingDbName, activeFingerprint);
+      writeCacheState(cacheDir, config, infra, existingDbName, activeFingerprint);
       return activeFingerprint;
     }
 
@@ -213,7 +268,7 @@ async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerpri
       continue;
     }
 
-    writeLocalCacheState(cacheDir, infra, desiredDbName, activeFingerprint);
+    writeCacheState(cacheDir, config, infra, desiredDbName, activeFingerprint);
     return activeFingerprint;
   }
 }
@@ -320,8 +375,13 @@ async function ensureRuntimeClone(config, infra, cacheDir, templateFingerprint,
   }
 
   const desiredDbName = buildRuntimeDatabaseName(serviceName, bindingKey, templateFingerprint);
-  const existingDbName = readStateValue(path.join(config.stateDir, "local_database_name"));
-  const existingFingerprint = readStateValue(path.join(config.stateDir, "local_template_fingerprint"));
+  const backend = config.testkit.database.provider;
+  const existingDbName =
+    readStateValue(path.join(config.stateDir, `${backend}_database_name`)) ||
+    readStateValue(path.join(config.stateDir, "local_database_name"));
+  const existingFingerprint =
+    readStateValue(path.join(config.stateDir, `${backend}_template_fingerprint`)) ||
+    readStateValue(path.join(config.stateDir, "local_template_fingerprint"));
   const needsReset =
     config.testkit.database.reset !== false ||
     existingFingerprint !== templateFingerprint ||
@@ -338,12 +398,17 @@ async function ensureRuntimeClone(config, infra, cacheDir, templateFingerprint,
   }
 
   fs.mkdirSync(config.stateDir, { recursive: true });
-  fs.writeFileSync(path.join(config.stateDir, "database_backend"), "local");
+  fs.writeFileSync(path.join(config.stateDir, "database_backend"), backend);
   fs.writeFileSync(path.join(config.stateDir, "database_url"), buildDatabaseUrl(infra, desiredDbName));
-  fs.writeFileSync(path.join(config.stateDir, "local_database_name"), desiredDbName);
-  fs.writeFileSync(path.join(config.stateDir, "local_template_fingerprint"), templateFingerprint);
-  fs.writeFileSync(path.join(config.stateDir, "local_template_database_name"), templateDbName);
-  fs.writeFileSync(path.join(config.stateDir, "local_container_name"), infra.containerName);
+  fs.writeFileSync(path.join(config.stateDir, `${backend}_database_name`), desiredDbName);
+  fs.writeFileSync(path.join(config.stateDir, `${backend}_template_fingerprint`), templateFingerprint);
+  fs.writeFileSync(path.join(config.stateDir, `${backend}_template_database_name`), templateDbName);
+  if (backend === "local") {
+    fs.writeFileSync(path.join(config.stateDir, "local_container_name"), infra.containerName);
+  } else {
+    fs.writeFileSync(path.join(config.stateDir, "resource_name"), infra.resourceName);
+    writeResourceConnectionState(config.stateDir, infra);
+  }
 }
 
 function resolveDatabaseBindingKey(config) {
@@ -366,6 +431,15 @@ async function destroyLocalRuntimeDatabase(productDir, stateDir) {
   await dropDatabaseIfExists(infra, dbName);
 }
 
+async function destroyResourceRuntimeDatabase(stateDir) {
+  const dbName = readStateValue(path.join(stateDir, "resource_database_name"));
+  if (!dbName) return;
+
+  const infra = resolveResourcePostgresInfraFromState(stateDir);
+  if (!infra) return;
+  await dropDatabaseIfExists(infra, dbName);
+}
+
 async function ensureLocalContainer(productDir, database = {}) {
   const infraDir = getLocalInfraDir(productDir);
   fs.mkdirSync(infraDir, { recursive: true });
@@ -476,6 +550,21 @@ async function waitForLocalContainerReady(infra) {
   throw new Error(`Timed out waiting for local database container ${infra.containerName}`);
 }
 
+async function waitForResourcePostgresReady(infra) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < LOCAL_READY_TIMEOUT_MS) {
+    try {
+      await runAdminQuery(infra, ["-tAc", "SELECT 1"]);
+      return;
+    } catch (error) {
+      if (!isTransientAdminQueryConnectionError(error)) throw error;
+      await sleep(LOCAL_POLL_INTERVAL_MS);
+    }
+  }
+
+  throw new Error(`Timed out waiting for Postgres resource "${infra.resourceName}" at ${infra.host}:${infra.port}`);
+}
+
 async function inspectContainer(containerName) {
   try {
     const { stdout } = await execa("docker", ["inspect", containerName]);
@@ -589,24 +678,48 @@ export async function waitForDatabaseConnectionsToDrain(infra, dbName, hooks = {
 }
 
 async function runAdminQuery(infra, args) {
-  const commandArgs = [
-    "exec",
-    "-e",
-    `PGPASSWORD=${infra.password}`,
-    infra.containerName,
-    "psql",
-    "-v",
-    "ON_ERROR_STOP=1",
-    "-U",
-    infra.user,
-    "-d",
-    LOCAL_ADMIN_DB,
-    ...args,
-  ];
+  const command = infra.containerName ? "docker" : "psql";
+  const commandArgs = infra.containerName
+    ? [
+        "exec",
+        "-e",
+        `PGPASSWORD=${infra.password}`,
+        infra.containerName,
+        "psql",
+        "-v",
+        "ON_ERROR_STOP=1",
+        "-U",
+        infra.user,
+        "-d",
+        infra.adminDatabase || LOCAL_ADMIN_DB,
+        ...args,
+      ]
+    : [
+        "-v",
+        "ON_ERROR_STOP=1",
+        "-h",
+        infra.host,
+        "-p",
+        String(infra.port),
+        "-U",
+        infra.user,
+        "-d",
+        infra.adminDatabase || LOCAL_ADMIN_DB,
+        ...args,
+      ];
+  const commandOptions = infra.containerName
+    ? {}
+    : {
+        env: {
+          ...process.env,
+          PGPASSWORD: infra.password,
+          ...(infra.sslMode ? { PGSSLMODE: infra.sslMode } : {}),
+        },
+      };
   const startedAt = Date.now();
   while (true) {
     try {
-      const { stdout } = await execa("docker", commandArgs);
+      const { stdout } = await execa(command, commandArgs, commandOptions);
       return stdout;
     } catch (error) {
       if (
@@ -669,6 +782,75 @@ function buildDatabaseUrl(infra, dbName) {
   return buildDatabaseUrlModel(infra, dbName);
 }
 
+function resolveResourcePostgresInfra(config, processEnv = process.env) {
+  const resourceName = String(config.testkit?.database?.resource || "").trim();
+  if (!resourceName) {
+    throw new Error("Resource-backed Postgres database requires database.resource");
+  }
+  const connections = parseResourceConnections(processEnv.TESTKIT_RESOURCE_CONNECTIONS_JSON);
+  const connection = connections[resourceName];
+  if (!connection) {
+    const available = Object.keys(connections).sort().join(", ") || "none";
+    throw new Error(`Postgres resource "${resourceName}" is not available. Available resources: ${available}`);
+  }
+  return normalizeResourcePostgresConnection(resourceName, connection);
+}
+
+function resolveResourcePostgresInfraFromState(stateDir, processEnv = process.env) {
+  const resourceName = readStateValue(path.join(stateDir, "resource_name"));
+  if (!resourceName) return null;
+  const connections = parseResourceConnections(processEnv.TESTKIT_RESOURCE_CONNECTIONS_JSON);
+  const connection = connections[resourceName] || readResourceConnectionState(stateDir);
+  return connection ? normalizeResourcePostgresConnection(resourceName, connection) : null;
+}
+
+function parseResourceConnections(raw) {
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch (error) {
+    throw new Error(`Invalid TESTKIT_RESOURCE_CONNECTIONS_JSON: ${error.message}`);
+  }
+}
+
+function normalizeResourcePostgresConnection(resourceName, connection) {
+  const fromUrl = connection.url ? parsePostgresConnectionUrl(connection.url) : {};
+  const host = connection.host || fromUrl.host;
+  const port = Number(connection.port || fromUrl.port || 5432);
+  const user = connection.user || fromUrl.user;
+  const password = connection.password || fromUrl.password || "";
+  const adminDatabase = connection.adminDatabase || connection.admin_database || fromUrl.database || LOCAL_ADMIN_DB;
+  const sslMode = connection.sslMode || connection.sslmode || fromUrl.sslMode || "disable";
+  if (!host) throw new Error(`Postgres resource "${resourceName}" connection is missing host`);
+  if (!Number.isInteger(port) || port <= 0) {
+    throw new Error(`Postgres resource "${resourceName}" connection has invalid port`);
+  }
+  if (!user) throw new Error(`Postgres resource "${resourceName}" connection is missing user`);
+  return {
+    backend: "resource",
+    resourceName,
+    host,
+    port,
+    user,
+    password,
+    adminDatabase,
+    sslMode,
+  };
+}
+
+function parsePostgresConnectionUrl(rawUrl) {
+  const parsed = new URL(rawUrl);
+  return {
+    host: parsed.hostname,
+    port: parsed.port ? Number(parsed.port) : 5432,
+    database: decodeURIComponent(parsed.pathname.replace(/^\//, "")) || LOCAL_ADMIN_DB,
+    user: decodeURIComponent(parsed.username || ""),
+    password: decodeURIComponent(parsed.password || ""),
+    sslMode: parsed.searchParams.get("sslmode") || undefined,
+  };
+}
+
 function buildContainerName(productDir) {
   return buildContainerNameModel(productDir);
 }
@@ -692,11 +874,40 @@ function writeLocalInfraState(infraDir, infra) {
   fs.writeFileSync(path.join(infraDir, "port"), String(infra.port));
 }
 
-function writeLocalCacheState(cacheDir, infra, templateDbName, fingerprint) {
-  fs.writeFileSync(path.join(cacheDir, "database_backend"), "local");
+function writeCacheState(cacheDir, config, infra, templateDbName, fingerprint) {
+  const backend = config.testkit.database.provider;
+  fs.writeFileSync(path.join(cacheDir, "database_backend"), backend);
   fs.writeFileSync(path.join(cacheDir, "template_database_name"), templateDbName);
   fs.writeFileSync(path.join(cacheDir, "template_fingerprint"), fingerprint);
-  fs.writeFileSync(path.join(cacheDir, "container_name"), infra.containerName);
+  if (backend === "local") {
+    fs.writeFileSync(path.join(cacheDir, "container_name"), infra.containerName);
+  } else {
+    fs.writeFileSync(path.join(cacheDir, "resource_name"), infra.resourceName);
+    writeResourceConnectionState(cacheDir, infra);
+  }
+}
+
+function writeResourceConnectionState(stateDir, infra) {
+  fs.writeFileSync(path.join(stateDir, "resource_host"), infra.host);
+  fs.writeFileSync(path.join(stateDir, "resource_port"), String(infra.port));
+  fs.writeFileSync(path.join(stateDir, "resource_user"), infra.user);
+  fs.writeFileSync(path.join(stateDir, "resource_password"), infra.password);
+  fs.writeFileSync(path.join(stateDir, "resource_admin_database"), infra.adminDatabase || LOCAL_ADMIN_DB);
+  fs.writeFileSync(path.join(stateDir, "resource_sslmode"), infra.sslMode || "disable");
+}
+
+function readResourceConnectionState(stateDir) {
+  const host = readStateValue(path.join(stateDir, "resource_host"));
+  const user = readStateValue(path.join(stateDir, "resource_user"));
+  if (!host || !user) return null;
+  return {
+    host,
+    port: Number(readStateValue(path.join(stateDir, "resource_port")) || 5432),
+    user,
+    password: readStateValue(path.join(stateDir, "resource_password")) || "",
+    adminDatabase: readStateValue(path.join(stateDir, "resource_admin_database")) || LOCAL_ADMIN_DB,
+    sslMode: readStateValue(path.join(stateDir, "resource_sslmode")) || "disable",
+  };
 }
 
 function getLocalInfraDir(productDir) {
@@ -711,6 +922,10 @@ function getLocalServiceCacheDir(productDir, serviceName) {
   return getLocalServiceCacheDirModel(productDir, serviceName);
 }
 
+function getResourceLocksDir(productDir, resourceName) {
+  return getResourceLocksDirModel(productDir, resourceName);
+}
+
 function hasRemainingLocalArtifacts(productDir) {
   return hasRemainingLocalArtifactsModel(productDir, readStateValue);
 }

package/lib/database/naming.mjs

@@ -2,7 +2,8 @@ import crypto from "crypto";
 import path from "path";
 
 export function buildDatabaseUrl(infra, dbName) {
-  return `postgresql://${encodeURIComponent(infra.user)}:${encodeURIComponent(infra.password)}@${infra.host}:${infra.port}/${dbName}?sslmode=disable`;
+  const sslMode = infra.sslMode || "disable";
+  return `postgresql://${encodeURIComponent(infra.user)}:${encodeURIComponent(infra.password)}@${infra.host}:${infra.port}/${dbName}?sslmode=${encodeURIComponent(sslMode)}`;
 }
 
 export function buildContainerName(productDir) {

package/lib/database/state.mjs

@@ -13,6 +13,10 @@ export function getLocalServiceCacheDir(productDir, serviceName) {
   return path.join(productDir, ".testkit", "_dbcache", serviceName);
 }
 
+export function getResourceLocksDir(productDir, resourceName) {
+  return path.join(productDir, ".testkit", "_infra", "resource-postgres", resourceName, "locks");
+}
+
 export function hasRemainingLocalArtifacts(productDir, readStateValue) {
   const root = path.join(productDir, ".testkit");
   if (!fs.existsSync(root)) return false;

package/lib/local/kiln-driver.mjs

@@ -123,7 +123,12 @@ export async function kilnLocalDown(context, name, options = {}) {
   const ssh = await sshFromManifest(manifest);
   const args = ["local", "down", name, ...(options.destroyState ? ["--destroy-state"] : [])];
   try {
-    const result = await remoteTestkit(ssh, manifest.remoteProductDir, args);
+    const resourceConnections = manifestResourceConnections(manifest);
+    const result = await remoteTestkit(ssh, manifest.remoteProductDir, args, {
+      ...(Object.keys(resourceConnections).length > 0
+        ? { TESTKIT_RESOURCE_CONNECTIONS_JSON: JSON.stringify(resourceConnections) }
+        : {}),
+    });
     if (result.exitCode !== 0) {
       throw new Error(`remote testkit local down failed\n${result.stdout}${result.stderr}`);
     }
@@ -621,6 +626,14 @@ function pickAppliance(appliance) {
   };
 }
 
+function manifestResourceConnections(manifest) {
+  return Object.fromEntries(
+    Object.entries(manifest.resources || {})
+      .map(([name, resource]) => [name, resource?.connection || null])
+      .filter(([_name, connection]) => connection && typeof connection === "object")
+  );
+}
+
 function pickAPIConfig(api) {
   return {
     ...(api.apiUrl ? { apiUrl: api.apiUrl } : {}),

package/node_modules/@elench/next-analysis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/next-analysis",
-  "version": "0.1.139",
+  "version": "0.1.140",
   "description": "SWC-backed Next.js source analysis primitives for Erench tools",
   "type": "module",
   "exports": {

package/node_modules/@elench/testkit-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-bridge",
-  "version": "0.1.139",
+  "version": "0.1.140",
   "description": "Browser bridge helpers for testkit",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,7 +22,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@elench/testkit-protocol": "0.1.139"
+    "@elench/testkit-protocol": "0.1.140"
   },
   "private": false
 }

package/node_modules/@elench/testkit-protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-protocol",
-  "version": "0.1.139",
+  "version": "0.1.140",
   "description": "Shared browser protocol for testkit bridge and extension consumers",
   "type": "module",
   "main": "./dist/index.js",

package/node_modules/@elench/ts-analysis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/ts-analysis",
-  "version": "0.1.139",
+  "version": "0.1.140",
   "description": "TypeScript compiler-backed source analysis primitives for Erench tools",
   "type": "module",
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.139",
+  "version": "0.1.140",
   "description": "Assistant-first CLI for running, inspecting, and debugging local testkit suites",
   "type": "module",
   "workspaces": [
@@ -98,10 +98,10 @@
   },
   "dependencies": {
     "@babel/code-frame": "^7.29.0",
-    "@elench/next-analysis": "0.1.139",
-    "@elench/testkit-bridge": "0.1.139",
-    "@elench/testkit-protocol": "0.1.139",
-    "@elench/ts-analysis": "0.1.139",
+    "@elench/next-analysis": "0.1.140",
+    "@elench/testkit-bridge": "0.1.140",
+    "@elench/testkit-protocol": "0.1.140",
+    "@elench/ts-analysis": "0.1.140",
     "@oclif/core": "^4.10.6",
     "@playwright/test": "^1.52.0",
     "esbuild": "^0.25.11",