@elench/testkit 0.1.136 → 0.1.138

package/lib/config/index.mjs

@@ -224,12 +224,71 @@ function normalizeEnvironmentConfig(name, environment) {
   if (!Number.isInteger(portOffset) || portOffset < 0) {
     throw new Error(`Environment "${name}" portOffset must be a non-negative integer`);
   }
+  const driver = environment.driver || "host";
+  if (!["host", "kiln"].includes(driver)) {
+    throw new Error(`Environment "${name}" driver must be one of: host, kiln`);
+  }
+  const kiln = normalizeKilnEnvironmentConfig(name, environment.kiln);
   return {
     kind: "local",
+    driver,
     target,
     data,
     portOffset,
     env: normalizeEnvironmentEnv(environment.env),
+    resources: normalizeEnvironmentResources(name, environment.resources),
+    productionLike: Boolean(environment.productionLike),
+    ...(environment.publicHost ? { publicHost: String(environment.publicHost) } : {}),
+    ...(kiln ? { kiln } : {}),
+  };
+}
+
+function normalizeEnvironmentResources(environmentName, resources = {}) {
+  if (resources == null) return {};
+  if (typeof resources !== "object" || Array.isArray(resources)) {
+    throw new Error(`Environment "${environmentName}" resources must be an object`);
+  }
+  return Object.fromEntries(
+    Object.entries(resources).map(([name, resource]) => {
+      const normalizedName = normalizeDatabaseEnvToken(name, `Environment "${environmentName}" resource name`, false);
+      if (!resource || typeof resource !== "object" || Array.isArray(resource)) {
+        throw new Error(`Environment "${environmentName}" resource "${name}" must be an object`);
+      }
+      const kind = String(resource.kind || "").trim();
+      if (!["postgres", "server"].includes(kind)) {
+        throw new Error(`Environment "${environmentName}" resource "${name}" kind must be "postgres" or "server"`);
+      }
+      return [normalizedName, { ...resource, kind }];
+    })
+  );
+}
+
+function normalizeKilnEnvironmentConfig(name, kiln) {
+  if (!kiln) return null;
+  if (typeof kiln !== "object" || Array.isArray(kiln)) {
+    throw new Error(`Environment "${name}" kiln must be an object`);
+  }
+  const vm = kiln.vm || {};
+  if (vm && (typeof vm !== "object" || Array.isArray(vm))) {
+    throw new Error(`Environment "${name}" kiln.vm must be an object`);
+  }
+  const network = kiln.network || null;
+  if (network && (typeof network !== "object" || Array.isArray(network))) {
+    throw new Error(`Environment "${name}" kiln.network must be an object`);
+  }
+  const workspace = kiln.workspace || null;
+  if (workspace && (typeof workspace !== "object" || Array.isArray(workspace))) {
+    throw new Error(`Environment "${name}" kiln.workspace must be an object`);
+  }
+  return {
+    ...kiln,
+    vm: {
+      ...(vm || {}),
+      ...(vm.name ? { name: String(vm.name) } : {}),
+      ...(vm.profile ? { profile: String(vm.profile) } : {}),
+    },
+    ...(network ? { network: { ...network } } : {}),
+    ...(workspace ? { workspace: { ...workspace } } : {}),
   };
 }
 
@@ -240,13 +299,14 @@ function normalizeEnvironmentEnv(env) {
   }
   const hasPresetShape =
     Object.prototype.hasOwnProperty.call(env, "values") ||
-    Object.prototype.hasOwnProperty.call(env, "databases");
+    Object.prototype.hasOwnProperty.call(env, "databases") ||
+    Object.prototype.hasOwnProperty.call(env, "resources");
   if (!hasPresetShape) {
     return Object.fromEntries(
       Object.entries(env).map(([key, value]) => [key, String(value)])
     );
   }
-  const allowedKeys = new Set(["values", "databases"]);
+  const allowedKeys = new Set(["values", "databases", "resources"]);
   const unexpectedKeys = Object.keys(env).filter((key) => !allowedKeys.has(key));
   if (unexpectedKeys.length > 0) {
     throw new Error(
@@ -256,8 +316,11 @@ function normalizeEnvironmentEnv(env) {
   const values = env.values && typeof env.values === "object" && !Array.isArray(env.values) ? env.values : {};
   const databases =
     env.databases && typeof env.databases === "object" && !Array.isArray(env.databases) ? env.databases : {};
+  const resources =
+    env.resources && typeof env.resources === "object" && !Array.isArray(env.resources) ? env.resources : {};
   return {
     ...expandDatabaseBindings(databases),
+    ...expandResourceBindings(resources),
     ...Object.fromEntries(Object.entries(values).map(([key, value]) => [key, String(value)])),
   };
 }
@@ -280,6 +343,22 @@ function expandDatabaseBindings(bindings) {
   return env;
 }
 
+function expandResourceBindings(bindings) {
+  const env = {};
+  for (const [envName, binding] of Object.entries(bindings || {})) {
+    if (typeof binding === "string") {
+      const [resourceName, field = "url"] = binding.split(".");
+      env[envName] = `{resource:${normalizeDatabaseEnvToken(resourceName, `env.resources.${envName}`, false)}:${normalizeDatabaseEnvToken(field, `env.resources.${envName} field`, false)}}`;
+      continue;
+    }
+    if (!binding || typeof binding !== "object" || Array.isArray(binding)) {
+      throw new Error(`env.resources.${envName} must be a string or object`);
+    }
+    env[envName] = `{resource:${normalizeDatabaseEnvToken(binding.resource, `env.resources.${envName}.resource`, false)}:${normalizeDatabaseEnvToken(binding.field || "url", `env.resources.${envName}.field`, false)}}`;
+  }
+  return env;
+}
+
 function normalizeDatabaseEnvToken(value, label, sanitize = true) {
   const raw = String(value || "").trim();
   const normalized = sanitize

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

@@ -280,13 +280,50 @@ export interface DatabaseBindingEnvConfig {
 export interface PresetEnvConfig {
   values?: Record<string, string>;
   databases?: Record<string, DatabaseBindingEnvConfig>;
+  resources?: Record<string, string | { resource: string; field?: string }>;
 }
 
+export interface KilnVMResourceConfig {
+  autostart?: boolean;
+  disk?: string;
+  diskSize?: string | number;
+  diskSizeMB?: number;
+  memoryMB?: number;
+  name?: string;
+  networkId?: string;
+  profile?: string;
+  vcpus?: number;
+}
+
+export interface PostgresResourceConfig {
+  kind: "postgres";
+  data?: "reuse" | "reset" | "rebuild";
+  database?: string;
+  extensions?: string[];
+  password?: string;
+  port?: number;
+  user?: string;
+  version?: string;
+  vm?: KilnVMResourceConfig;
+}
+
+export interface ServerResourceConfig {
+  kind: "server";
+  vm?: KilnVMResourceConfig;
+}
+
+export type ResourceConfig = PostgresResourceConfig | ServerResourceConfig;
+
 export interface LocalEnvironmentConfig {
   kind: "local";
   data?: "reuse" | "reset" | "rebuild";
+  driver?: "host" | "kiln";
   env?: Record<string, string>;
+  kiln?: KilnLocalEnvironmentConfig;
   portOffset?: number;
+  productionLike?: boolean;
+  publicHost?: string;
+  resources?: Record<string, ResourceConfig>;
   target: string;
 }
 
@@ -294,6 +331,34 @@ export interface LocalEnvironmentOptions extends Omit<LocalEnvironmentConfig, "k
   env?: PresetEnvConfig;
 }
 
+export interface KilnLocalEnvironmentConfig {
+  api?: {
+    apiUrl?: string;
+    token?: string;
+  };
+  network?: {
+    attachExistingVMs?: string[];
+    cidr?: string;
+    id?: string;
+    name?: string;
+  };
+  vm?: {
+    autostart?: boolean;
+    disk?: string;
+    diskSize?: string | number;
+    diskSizeMB?: number;
+    memoryMB?: number;
+    name?: string;
+    networkId?: string;
+    profile?: string;
+    vcpus?: number;
+  };
+  workspace?: {
+    exclude?: string[];
+    remotePath?: string;
+  };
+}
+
 export interface TestkitFileMetadata {
   locks?: string[];
   skip?: string | { reason: string };
@@ -568,6 +633,17 @@ export declare const database: {
     }
   ): ServiceConfig;
 };
+export declare const resource: {
+  postgres(options?: Omit<PostgresResourceConfig, "kind">): PostgresResourceConfig;
+  server(options?: Omit<ServerResourceConfig, "kind">): ServerResourceConfig;
+  field(resourceName: string, field?: string): string;
+  url(resourceName: string): string;
+  host(resourceName: string): string;
+  port(resourceName: string): string;
+  database(resourceName: string): string;
+  user(resourceName: string): string;
+  password(resourceName: string): string;
+};
 export declare const step: {
   command(run: string, options?: TemplateLifecycleStepOptions): TemplateCommandStepConfig;
   module(target: string, options?: TemplateLifecycleStepOptions): TemplateModuleStepConfig;
@@ -584,6 +660,7 @@ export declare const ui: {
 };
 export declare const environment: {
   local(options: LocalEnvironmentOptions): LocalEnvironmentConfig;
+  productionLike(options: LocalEnvironmentOptions): LocalEnvironmentConfig;
 };
 export declare const auth: {
   fixture(options: { contract: JsonSessionContract; topology: AuthTopology }): AuthFixture;

package/lib/config-api/index.mjs

@@ -33,6 +33,33 @@ function postgresDatabase(options = {}) {
   };
 }
 
+function postgresResource(options = {}) {
+  return {
+    kind: "postgres",
+    version: options.version || "16",
+    database: options.database || options.name || "app",
+    user: options.user || "app",
+    ...(options.password ? { password: options.password } : {}),
+    ...(options.port ? { port: options.port } : {}),
+    ...(options.vm ? { vm: { ...options.vm } } : {}),
+    ...(options.data ? { data: options.data } : {}),
+    ...(options.extensions ? { extensions: [...options.extensions] } : {}),
+  };
+}
+
+function serverResource(options = {}) {
+  return {
+    kind: "server",
+    ...(options.vm ? { vm: { ...options.vm } } : {}),
+  };
+}
+
+function resourceField(resourceName, field = "url") {
+  const normalizedResourceName = normalizeDatabaseEnvToken(resourceName, "resource name", false);
+  const normalizedField = normalizeDatabaseEnvToken(field, "resource field", false);
+  return `{resource:${normalizedResourceName}:${normalizedField}}`;
+}
+
 function buildDatabaseTemplateConfig(options = {}) {
   for (const legacyKey of ["schema"]) {
     if (Object.prototype.hasOwnProperty.call(options, legacyKey)) {
@@ -412,6 +439,30 @@ export const database = {
   fixture: postgresFixture,
 };
 
+export const resource = {
+  postgres: postgresResource,
+  server: serverResource,
+  field: resourceField,
+  url(resourceName) {
+    return resourceField(resourceName, "url");
+  },
+  host(resourceName) {
+    return resourceField(resourceName, "host");
+  },
+  port(resourceName) {
+    return resourceField(resourceName, "port");
+  },
+  database(resourceName) {
+    return resourceField(resourceName, "database");
+  },
+  user(resourceName) {
+    return resourceField(resourceName, "user");
+  },
+  password(resourceName) {
+    return resourceField(resourceName, "password");
+  },
+};
+
 export const step = {
   command: commandStep,
   module: moduleStep,
@@ -456,6 +507,13 @@ function localEnvironment(options = {}) {
 
 export const environment = {
   local: localEnvironment,
+  productionLike(options = {}) {
+    return localEnvironment({
+      driver: "kiln",
+      ...options,
+      productionLike: true,
+    });
+  },
 };
 
 export const auth = {
@@ -497,7 +555,7 @@ function normalizePresetEnv(env) {
   if (typeof env !== "object" || Array.isArray(env)) {
     throw new Error("Preset env must be an object");
   }
-  const allowedKeys = new Set(["values", "databases"]);
+  const allowedKeys = new Set(["values", "databases", "resources"]);
   const unexpectedKeys = Object.keys(env).filter((key) => !allowedKeys.has(key));
   if (unexpectedKeys.length > 0) {
     throw new Error(
@@ -508,9 +566,12 @@ function normalizePresetEnv(env) {
   const values = env.values && typeof env.values === "object" && !Array.isArray(env.values) ? env.values : {};
   const databases =
     env.databases && typeof env.databases === "object" && !Array.isArray(env.databases) ? env.databases : {};
+  const resources =
+    env.resources && typeof env.resources === "object" && !Array.isArray(env.resources) ? env.resources : {};
 
   return {
     ...expandDatabaseBindings(databases),
+    ...expandResourceBindings(resources),
     ...values,
   };
 }
@@ -533,6 +594,22 @@ function expandDatabaseBindings(bindings) {
   return env;
 }
 
+function expandResourceBindings(bindings) {
+  const env = {};
+  for (const [envName, binding] of Object.entries(bindings || {})) {
+    if (typeof binding === "string") {
+      const [resourceName, field = "url"] = binding.split(".");
+      env[envName] = resourceField(resourceName, field);
+      continue;
+    }
+    if (!binding || typeof binding !== "object" || Array.isArray(binding)) {
+      throw new Error(`env.resources.${envName} must be a string or object`);
+    }
+    env[envName] = resourceField(binding.resource, binding.field || "url");
+  }
+  return env;
+}
+
 function normalizeDatabaseEnvToken(value, label, sanitize = true) {
   const raw = String(value || "").trim();
   const normalized = sanitize

package/lib/docker-compat/matrix.mjs

@@ -0,0 +1,135 @@
+export const DEFAULT_DOCKER_COMPAT_MATRIX = Object.freeze([
+  dockerCompatEntry({ dockerVersion: "24.0.9", image: "docker:24.0.9-dind" }),
+  dockerCompatEntry({ dockerVersion: "25.0.5", image: "docker:25.0.5-dind" }),
+  dockerCompatEntry({ dockerVersion: "26.1.4", image: "docker:26.1.4-dind" }),
+  dockerCompatEntry({ dockerVersion: "27.5.1", image: "docker:27.5.1-dind" }),
+  dockerCompatEntry({ dockerVersion: "28.5.2", image: "docker:28.5.2-dind" }),
+  dockerCompatEntry({ dockerVersion: "29.0.0", image: "docker:29.0.0-dind" }),
+]);
+
+export function dockerCompatEntry(entry = {}) {
+  const dockerVersion = normalizeNonEmptyString(entry.dockerVersion, "dockerVersion");
+  const image = normalizeNonEmptyString(entry.image, "image");
+  return Object.freeze({
+    dockerVersion,
+    image,
+    label: entry.label || `Docker ${dockerVersion}`,
+    rootfsSizeMB: normalizePositiveInteger(entry.rootfsSizeMB ?? 4096, "rootfsSizeMB"),
+    vcpus: normalizePositiveInteger(entry.vcpus ?? 1, "vcpus"),
+    memoryMB: normalizePositiveInteger(entry.memoryMB ?? 2048, "memoryMB"),
+  });
+}
+
+export function selectDockerCompatMatrix(matrix = DEFAULT_DOCKER_COMPAT_MATRIX, selection = []) {
+  const requested = normalizeSelection(selection);
+  if (requested.length === 0) return [...matrix];
+
+  const byVersion = new Map(matrix.map((entry) => [entry.dockerVersion, entry]));
+  const byLabel = new Map(matrix.map((entry) => [entry.label, entry]));
+  const selected = [];
+  const unknown = [];
+
+  for (const key of requested) {
+    const entry = byVersion.get(key) || byLabel.get(key);
+    if (entry) {
+      selected.push(entry);
+    } else {
+      unknown.push(key);
+    }
+  }
+
+  if (unknown.length > 0) {
+    throw new Error(`Unknown Docker compatibility matrix selection: ${unknown.join(", ")}`);
+  }
+  return selected;
+}
+
+export function parseDockerCompatSelection(value) {
+  if (Array.isArray(value)) return normalizeSelection(value);
+  return normalizeSelection(String(value || "").split(","));
+}
+
+export function buildDockerCompatDockerfile(entry) {
+  const normalized = dockerCompatEntry(entry);
+  return [
+    `FROM ${normalized.image}`,
+    "RUN apk add --no-cache postgresql-client",
+    "ENV DOCKER_TLS_CERTDIR=",
+    "ENTRYPOINT []",
+    "CMD [\"dockerd-entrypoint.sh\"]",
+    "",
+  ].join("\n");
+}
+
+export function buildDockerCompatProbeCommand(entry, options = {}) {
+  const normalized = dockerCompatEntry(entry);
+  const postgresImage = options.postgresImage || "pgvector/pgvector:pg16";
+  const containerName = options.containerName || `testkit-docker-compat-${normalized.dockerVersion.replaceAll(".", "-")}`;
+  return [
+    "set -eu",
+    "deadline=$(($(date +%s) + 90))",
+    "until docker version >/tmp/testkit-docker-version.txt 2>/tmp/testkit-docker-version.err; do",
+    "  if [ \"$(date +%s)\" -ge \"$deadline\" ]; then",
+    "    cat /tmp/testkit-docker-version.err >&2 || true",
+    "    exit 1",
+    "  fi",
+    "  sleep 1",
+    "done",
+    "actual=$(docker version --format '{{.Server.Version}}')",
+    `case "$actual" in ${shellCasePattern(normalized.dockerVersion)}*) ;; *) echo "expected Docker ${normalized.dockerVersion}, got $actual" >&2; exit 1 ;; esac`,
+    `docker rm -f ${shellQuote(containerName)} >/dev/null 2>&1 || true`,
+    [
+      "docker run -d",
+      "--name",
+      shellQuote(containerName),
+      "-e",
+      "POSTGRES_USER=testkit",
+      "-e",
+      "POSTGRES_PASSWORD=testkit",
+      "-e",
+      "POSTGRES_DB=postgres",
+      "-p",
+      "127.0.0.1::5432",
+      shellQuote(postgresImage),
+    ].join(" "),
+    "ready_deadline=$(($(date +%s) + 120))",
+    "until docker exec " + shellQuote(containerName) + " pg_isready -U testkit -d postgres >/dev/null 2>&1; do",
+    "  if [ \"$(date +%s)\" -ge \"$ready_deadline\" ]; then",
+    "    docker logs " + shellQuote(containerName) + " >&2 || true",
+    "    docker rm -f " + shellQuote(containerName) + " >/dev/null 2>&1 || true",
+    "    exit 1",
+    "  fi",
+    "  sleep 1",
+    "done",
+    "published_port=$(docker inspect --format '{{(index (index .NetworkSettings.Ports \"5432/tcp\") 0).HostPort}}' " + shellQuote(containerName) + ")",
+    "test -n \"$published_port\"",
+    "docker rm -f " + shellQuote(containerName) + " >/dev/null",
+    "echo \"Docker $actual compatibility probe passed\"",
+  ].join("\n");
+}
+
+function normalizeSelection(selection) {
+  return selection.map((entry) => String(entry || "").trim()).filter(Boolean);
+}
+
+function normalizeNonEmptyString(value, name) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${name} is required`);
+  return normalized;
+}
+
+function normalizePositiveInteger(value, name) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+  return parsed;
+}
+
+function shellQuote(value) {
+  return "'" + String(value).replaceAll("'", "'\"'\"'") + "'";
+}
+
+function shellCasePattern(value) {
+  return String(value).replaceAll(".", "\\.");
+}

package/lib/kiln/client.mjs

@@ -0,0 +1,120 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+export class KilnClient {
+  constructor(options = {}) {
+    const config = readKilnConfig();
+    this.apiUrl = String(options.apiUrl || process.env.KILN_API_URL || config.api_url || "").replace(/\/+$/, "");
+    this.token = String(options.token || process.env.KILN_TOKEN || config.token || "");
+    if (!this.apiUrl) throw new Error("Kiln API URL is not configured; run kiln login or set KILN_API_URL");
+    if (!this.token) throw new Error("Kiln token is not configured; run kiln login or set KILN_TOKEN");
+  }
+
+  async request(method, requestPath, body = null) {
+    const response = await fetch(`${this.apiUrl}${requestPath}`, {
+      method,
+      headers: {
+        authorization: `Bearer ${this.token}`,
+        ...(body ? { "content-type": "application/json" } : {}),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await response.text();
+    if (!response.ok) {
+      throw new Error(`${method} ${requestPath} returned ${response.status}: ${text.trim()}`);
+    }
+    if (!text || response.status === 204) return null;
+    return JSON.parse(text);
+  }
+
+  getVM(ref) {
+    return this.request("GET", `/vms/${encodeURIComponent(ref)}`);
+  }
+
+  listVMs() {
+    return this.request("GET", "/vms");
+  }
+
+  createVM(req) {
+    return this.request("POST", "/vms", req);
+  }
+
+  startVM(ref) {
+    return this.request("POST", `/vms/${encodeURIComponent(ref)}/start`);
+  }
+
+  stopVM(ref) {
+    return this.request("POST", `/vms/${encodeURIComponent(ref)}/stop`);
+  }
+
+  deleteVM(ref) {
+    return this.request("DELETE", `/vms/${encodeURIComponent(ref)}`);
+  }
+
+  attachVMNetwork(ref, networkId) {
+    return this.request("POST", `/vms/${encodeURIComponent(ref)}/network`, { network_id: networkId });
+  }
+
+  listNetworks() {
+    return this.request("GET", "/networks");
+  }
+
+  createNetwork(req) {
+    return this.request("POST", "/networks", req);
+  }
+
+  deleteNetwork(ref) {
+    return this.request("DELETE", `/networks/${encodeURIComponent(ref)}`);
+  }
+
+  execVM(ref, command) {
+    return this.request("POST", `/vms/${encodeURIComponent(ref)}/exec`, { command });
+  }
+
+  ensureAppliance(req) {
+    return this.request("POST", "/appliances/ensure", req);
+  }
+
+  getAppliance(ref) {
+    return this.request("GET", `/appliances/${encodeURIComponent(ref)}`);
+  }
+
+  listAppliances() {
+    return this.request("GET", "/appliances");
+  }
+
+  stopAppliance(ref) {
+    return this.request("POST", `/appliances/${encodeURIComponent(ref)}/stop`);
+  }
+
+  deleteAppliance(ref) {
+    return this.request("DELETE", `/appliances/${encodeURIComponent(ref)}`);
+  }
+
+  sshKey(machineId) {
+    return this.requestRaw("GET", `/machines/${encodeURIComponent(machineId)}/ssh-key`);
+  }
+
+  async requestRaw(method, requestPath) {
+    const response = await fetch(`${this.apiUrl}${requestPath}`, {
+      method,
+      headers: { authorization: `Bearer ${this.token}` },
+    });
+    const text = await response.text();
+    if (!response.ok) {
+      throw new Error(`${method} ${requestPath} returned ${response.status}: ${text.trim()}`);
+    }
+    return text;
+  }
+}
+
+function readKilnConfig() {
+  const configHome = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  const configPath = path.join(configHome, "kiln", "config.json");
+  try {
+    return JSON.parse(fs.readFileSync(configPath, "utf8"));
+  } catch {
+    return {};
+  }
+}