@elench/testkit 0.1.135 → 0.1.137

package/lib/database/fingerprint.mjs

@@ -1,7 +1,9 @@
 import crypto from "crypto";
-import fs from "fs";
-import path from "path";
 import { resolveServiceCwd } from "../config/paths.mjs";
+import {
+  appendFingerprintPathToHash,
+  normalizeFingerprintPolicy,
+} from "../repo/fingerprint-policy.mjs";
 import { collectTemplateInputs } from "./template-steps.mjs";
 import { appendSourceSchemaCacheToHash } from "./schema-source.mjs";
 
@@ -11,6 +13,7 @@ const LOCAL_USER = "testkit";
 export async function computeTemplateFingerprint(config, options = {}) {
   const hash = crypto.createHash("sha256");
   const db = config.testkit.database;
+  const fingerprints = normalizeFingerprintPolicy(config.testkit.fingerprints);
   hash.update(JSON.stringify({
     provider: db.provider,
     selectedBackend: db.selectedBackend,
@@ -20,48 +23,25 @@ export async function computeTemplateFingerprint(config, options = {}) {
   }));
 
   for (const envFile of config.testkit.envFiles || []) {
-    appendFileToHash(hash, config.productDir, resolveServiceCwd(config.productDir, envFile));
+    appendFileToHash(hash, config.productDir, resolveServiceCwd(config.productDir, envFile), fingerprints);
   }
   for (const input of collectTemplateInputs(config.productDir, db.template || {})) {
-    appendResolvedInputToHash(hash, config.productDir, input);
+    appendResolvedInputToHash(hash, config.productDir, input, fingerprints);
   }
   appendSourceSchemaCacheToHash(hash, config, options.sourceSchemaState || null);
 
   return hash.digest("hex");
 }
 
-export function appendInputToHash(hash, productDir, input) {
+export function appendInputToHash(hash, productDir, input, fingerprints = {}) {
   const absPath = resolveServiceCwd(productDir, input);
-  appendResolvedInputToHash(hash, productDir, absPath);
+  appendResolvedInputToHash(hash, productDir, absPath, normalizeFingerprintPolicy(fingerprints));
 }
 
-function appendResolvedInputToHash(hash, productDir, absPath) {
-  if (!fs.existsSync(absPath)) {
-    hash.update(`missing:${path.relative(productDir, absPath)}`);
-    return;
-  }
-
-  const stat = fs.statSync(absPath);
-  if (stat.isDirectory()) {
-    hash.update(`dir:${path.relative(productDir, absPath)}`);
-    for (const entry of fs.readdirSync(absPath).sort()) {
-      if (entry === ".git" || entry === "node_modules" || entry === ".testkit") continue;
-      appendResolvedInputToHash(hash, productDir, path.join(absPath, entry));
-    }
-    return;
-  }
-
-  appendFileToHash(hash, productDir, absPath);
+function appendResolvedInputToHash(hash, productDir, absPath, fingerprints) {
+  appendFingerprintPathToHash(hash, productDir, absPath, fingerprints);
 }
 
-export function appendFileToHash(hash, productDir, absPath) {
-  if (!fs.existsSync(absPath)) {
-    hash.update(`missing:${path.relative(productDir, absPath)}`);
-    return;
-  }
-  const stat = fs.statSync(absPath);
-  if (!stat.isFile()) return;
-
-  hash.update(`file:${path.relative(productDir, absPath)}:${stat.size}:${stat.mtimeMs}`);
-  hash.update(fs.readFileSync(absPath));
+export function appendFileToHash(hash, productDir, absPath, fingerprints = {}) {
+  appendFingerprintPathToHash(hash, productDir, absPath, normalizeFingerprintPolicy(fingerprints));
 }

package/lib/database/index.mjs

@@ -2,8 +2,6 @@ import fs from "fs";
 import path from "path";
 import { execa } from "execa";
 import {
-  appendFileToHash as appendFileToHashModel,
-  appendInputToHash as appendInputToHashModel,
   computeTemplateFingerprint as computeTemplateFingerprintModel,
 } from "./fingerprint.mjs";
 import {
@@ -44,6 +42,8 @@ const LOCAL_PASSWORD = "testkit";
 const LOCAL_ADMIN_DB = "postgres";
 const LOCAL_READY_TIMEOUT_MS = 60_000;
 const LOCAL_POLL_INTERVAL_MS = 1_000;
+const LOCAL_ADMIN_QUERY_RETRY_MS = 15_000;
+const LOCAL_ADMIN_QUERY_RETRY_INTERVAL_MS = 250;
 const LOCAL_DROP_DATABASE_TIMEOUT_MS = 15_000;
 const LOCAL_DROP_DATABASE_POLL_INTERVAL_MS = 250;
 
@@ -603,8 +603,31 @@ async function runAdminQuery(infra, args) {
     LOCAL_ADMIN_DB,
     ...args,
   ];
-  const { stdout } = await execa("docker", commandArgs);
-  return stdout;
+  const startedAt = Date.now();
+  while (true) {
+    try {
+      const { stdout } = await execa("docker", commandArgs);
+      return stdout;
+    } catch (error) {
+      if (
+        Date.now() - startedAt >= LOCAL_ADMIN_QUERY_RETRY_MS ||
+        !isTransientAdminQueryConnectionError(error)
+      ) {
+        throw error;
+      }
+      await sleep(LOCAL_ADMIN_QUERY_RETRY_INTERVAL_MS);
+    }
+  }
+}
+
+export function isTransientAdminQueryConnectionError(error) {
+  const text = `${error?.shortMessage || ""}\n${error?.stderr || ""}\n${error?.stdout || ""}\n${error?.message || ""}`;
+  return (
+    text.includes('connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed') ||
+    text.includes("No such file or directory") ||
+    text.includes("the database system is starting up") ||
+    text.includes("could not connect to server")
+  );
 }
 
 async function terminateDatabaseConnections(infra, dbName, runAdminQueryFn) {
@@ -642,14 +665,6 @@ async function computeTemplateFingerprint(config, options = {}) {
   return computeTemplateFingerprintModel(config, options);
 }
 
-function appendInputToHash(hash, productDir, input) {
-  return appendInputToHashModel(hash, productDir, input);
-}
-
-function appendFileToHash(hash, productDir, absPath) {
-  return appendFileToHashModel(hash, productDir, absPath);
-}
-
 function buildDatabaseUrl(infra, dbName) {
   return buildDatabaseUrlModel(infra, dbName);
 }

package/lib/database/schema-source.mjs

@@ -29,7 +29,9 @@ export function getSourceSchemaMetadataPath(config, options = {}) {
 }
 
 export function resolveSourceSchemaCacheLocation(config, options = {}) {
-  const repoState = options.repoState || collectRepoState(config.productDir);
+  const repoState = options.repoState || collectRepoState(config.productDir, {
+    fingerprints: config.testkit?.fingerprints,
+  });
   const rootDir = getSourceSchemaRootDir(config);
   const cacheDir = path.join(rootDir, ...repoState.cacheKey.split("/").map(sanitizePathSegment));
   return {

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/env/index.d.ts

@@ -30,6 +30,7 @@ export interface PostgresConnectionEnvValue {
 }
 
 export declare function isManagedRuntime(env?: NodeJS.ProcessEnv): boolean;
+export declare function managedRuntimeMode(env?: NodeJS.ProcessEnv): "test" | "local" | string | null;
 export declare function shouldLoadDotenv(env?: NodeJS.ProcessEnv): boolean;
 export declare function loadDotenvFiles(options?: LoadDotenvFilesOptions): {
   loaded: string[];

package/lib/env/index.mjs

@@ -9,6 +9,10 @@ export function isManagedRuntime(env = process.env) {
   return env?.TESTKIT_ACTIVE === "1";
 }
 
+export function managedRuntimeMode(env = process.env) {
+  return isManagedRuntime(env) ? env?.TESTKIT_MODE || "test" : null;
+}
+
 export function shouldLoadDotenv(env = process.env) {
   return env?.NODE_ENV !== "production" && !isManagedRuntime(env);
 }
@@ -59,7 +63,7 @@ export function assertLocalDatabaseUrl(env = process.env, consumer = "This comma
   if (!LOCAL_DATABASE_PROTOCOLS.has(parsed.protocol) || !LOCAL_DATABASE_HOSTS.has(parsed.hostname)) {
     const location = `${parsed.protocol}//${parsed.hostname}${parsed.port ? `:${parsed.port}` : ""}`;
     throw new Error(
-      `${consumer} testkit runs require a local PostgreSQL DATABASE_URL. Refusing ${location}.`
+      `${consumer} managed Testkit runtime requires a local PostgreSQL DATABASE_URL. Refusing ${location}.`
     );
   }
 }

package/lib/kiln/client.mjs

@@ -0,0 +1,100 @@
+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 });
+  }
+
+  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 {};
+  }
+}