@elench/testkit 0.1.135 → 0.1.137

package/README.md

@@ -62,6 +62,13 @@ npx @elench/testkit status
 npx @elench/testkit destroy
 npx @elench/testkit cleanup
 
+# Local production environment
+npx @elench/testkit local up
+npx @elench/testkit local status
+npx @elench/testkit local env --service frontend
+npx @elench/testkit local logs --service frontend
+npx @elench/testkit local down
+
 # Inspect the latest run artifact through the assistant
 npx @elench/testkit assistant --message '/inspect "__testkit__/health/health.int.testkit.ts"'
 npx @elench/testkit assistant --message '/artifacts "__testkit__/health/health.int.testkit.ts"'
@@ -222,6 +229,7 @@ import {
   database,
   defineConfig,
   defineFile,
+  environment,
   toolchain,
 } from "@elench/testkit/config";
 
@@ -238,6 +246,9 @@ export default defineConfig({
       cacheTtlSeconds: 900,
     },
   },
+  fingerprints: {
+    exclude: ["next-env.d.ts"],
+  },
   toolchains: {
     frontendNode: toolchain.node({
       cwd: "frontend",
@@ -245,6 +256,12 @@ export default defineConfig({
       install: "download",
     }),
   },
+  environments: {
+    local: environment.local({
+      target: "frontend",
+      data: "reuse",
+    }),
+  },
   services: {
     api: app.node({
       cwd: ".",
@@ -314,6 +331,7 @@ for:
 - named HTTP suite profiles
 - automatic regression classification for new vs known failures
 - optional GitHub-backed regression issue sync
+- repo-level fingerprint include/exclude policy
 - repo-declared suite/file skip policies with explicit reasons
 - telemetry upload configuration
 
@@ -323,6 +341,18 @@ inputs, and writes cache state under the service runtime directory. This is the
 right way to move expensive browser targets from `next dev` / watch mode to
 stable build-and-start flows.
 
+`testkit local` starts the same service graph as a persistent local production
+environment instead of a test run. It provisions local databases, runs template
+setup, runs `runtime.prepare`, starts dependent services, and records state
+under `.testkit/environments/<name>/` rather than `.testkit/_runs`. Local
+environment processes receive `TESTKIT_ACTIVE=1`, `TESTKIT_MODE=local`, and
+`TESTKIT_LOCAL_ENV=<name>`. Use `data: "reuse"` for fast restarts against the
+existing local runtime database, `data: "reset"` to refresh runtime databases
+from their templates on each launch, or `--rebuild` to destroy and recreate the
+environment state. Testkit only supports local environments here; it does not
+copy production data and it refuses managed runtime database URLs that are not
+loopback PostgreSQL URLs.
+
 `database.template` is the database-side equivalent for reusable template DB
 state. When `database.sourceSchema` is configured, Testkit treats the configured
 source database as the schema source of truth. A normal `testkit run` resolves a
@@ -339,6 +369,14 @@ Source schema cache keys are derived automatically from repo state:
 - dirty git worktrees use `dirty/<sha>-<fingerprint>`
 - non-git directories use `nogit/<fingerprint>`
 
+Dirty worktree fingerprints use Git's own ignore engine for untracked files, so
+normal `.gitignore` rules are respected. Testkit-owned outputs are always
+excluded from fingerprints: `.testkit/`, `.next-testkit/`, and
+`testkit.status.json`. `testkit.config.ts` is normal repo configuration and is
+not excluded automatically. For user-managed generated files, add repo-level
+`fingerprints.exclude` patterns; `fingerprints.include` can opt specific paths
+back in below an excluded directory.
+
 Branch names and worktree paths are recorded as metadata but do not affect clean
 commit cache keys, so branch renames and clean worktrees at the same commit
 reuse the same source schema. Dirty worktrees are isolated by content

package/lib/cli/commands/local/down.mjs

@@ -0,0 +1,37 @@
+import { Args, Command, Flags } from "@oclif/core";
+import { sharedFlags } from "../../command-flags.mjs";
+import { localDown } from "../../../local/orchestrator.mjs";
+import { withAssistantCommandResult } from "../../assistant/command-results.mjs";
+
+export default class LocalDownCommand extends Command {
+  static summary = "Stop a local production environment";
+
+  static enableJsonFlag = true;
+
+  static args = {
+    name: Args.string({ required: false, description: "Environment name" }),
+  };
+
+  static flags = {
+    ...sharedFlags,
+    "destroy-state": Flags.boolean({
+      description: "Remove environment runtime state and databases after stopping",
+      default: false,
+    }),
+  };
+
+  async run() {
+    return withAssistantCommandResult("local down", async () => {
+      const { args, flags } = await this.parse(LocalDownCommand);
+      const result = await localDown({
+        dir: flags.dir,
+        name: args.name || "local",
+        destroyState: flags["destroy-state"],
+      });
+      if (!this.jsonEnabled()) {
+        for (const line of result.lines || []) this.log(line);
+      }
+      return { ok: true, result };
+    });
+  }
+}

package/lib/cli/commands/local/env.mjs

@@ -0,0 +1,31 @@
+import { Args, Command } from "@oclif/core";
+import { sharedFlags } from "../../command-flags.mjs";
+import { localEnv } from "../../../local/orchestrator.mjs";
+import { withAssistantCommandResult } from "../../assistant/command-results.mjs";
+
+export default class LocalEnvCommand extends Command {
+  static summary = "Print resolved environment variables for a local service";
+
+  static enableJsonFlag = true;
+
+  static args = {
+    name: Args.string({ required: false, description: "Environment name" }),
+  };
+
+  static flags = sharedFlags;
+
+  async run() {
+    return withAssistantCommandResult("local env", async () => {
+      const { args, flags } = await this.parse(LocalEnvCommand);
+      const result = await localEnv({
+        dir: flags.dir,
+        name: args.name || "local",
+        service: flags.service,
+      });
+      if (!this.jsonEnabled()) {
+        for (const line of result.lines || []) this.log(line);
+      }
+      return { ok: true, result };
+    });
+  }
+}

package/lib/cli/commands/local/logs.mjs

@@ -0,0 +1,35 @@
+import { Args, Command, Flags } from "@oclif/core";
+import { sharedFlags } from "../../command-flags.mjs";
+import { localLogs } from "../../../local/orchestrator.mjs";
+import { withAssistantCommandResult } from "../../assistant/command-results.mjs";
+
+export default class LocalLogsCommand extends Command {
+  static summary = "Show local production environment logs";
+
+  static enableJsonFlag = true;
+
+  static args = {
+    name: Args.string({ required: false, description: "Environment name" }),
+  };
+
+  static flags = {
+    ...sharedFlags,
+    lines: Flags.integer({ description: "Number of lines to show", default: 200 }),
+  };
+
+  async run() {
+    return withAssistantCommandResult("local logs", async () => {
+      const { args, flags } = await this.parse(LocalLogsCommand);
+      const result = await localLogs({
+        dir: flags.dir,
+        name: args.name || "local",
+        service: flags.service,
+        lines: flags.lines,
+      });
+      if (!this.jsonEnabled()) {
+        for (const line of result.lines || []) this.log(line);
+      }
+      return { ok: true, result };
+    });
+  }
+}

package/lib/cli/commands/local/shell.mjs

@@ -0,0 +1,49 @@
+import { Command } from "@oclif/core";
+import { sharedFlags } from "../../command-flags.mjs";
+import { localShell } from "../../../local/orchestrator.mjs";
+import { withAssistantCommandResult } from "../../assistant/command-results.mjs";
+
+export default class LocalShellCommand extends Command {
+  static summary = "Run a command with a local service environment";
+
+  static strict = false;
+
+  static enableJsonFlag = true;
+
+  static flags = sharedFlags;
+
+  async run() {
+    return withAssistantCommandResult("local shell", async () => {
+      const { flags } = await this.parse(LocalShellCommand);
+      const separatorIndex = this.argv.indexOf("--");
+      const beforeSeparator = separatorIndex >= 0 ? this.argv.slice(0, separatorIndex) : this.argv;
+      const command = separatorIndex >= 0 ? this.argv.slice(separatorIndex + 1) : [];
+      const result = await localShell({
+        dir: flags.dir,
+        name: extractEnvironmentName(beforeSeparator) || "local",
+        service: flags.service,
+        command,
+      });
+      if (!this.jsonEnabled()) {
+        if (result.stdout) this.log(result.stdout.trimEnd());
+        if (result.stderr) this.error(result.stderr.trimEnd(), { exit: false });
+      }
+      this.exit(result.code);
+      return { ok: result.code === 0, result };
+    });
+  }
+}
+
+function extractEnvironmentName(args) {
+  const valueFlags = new Set(["--dir", "--service"]);
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (valueFlags.has(value)) {
+      index += 1;
+      continue;
+    }
+    if (value.startsWith("-")) continue;
+    return value;
+  }
+  return null;
+}

package/lib/cli/commands/local/status.mjs

@@ -0,0 +1,34 @@
+import { Args, Command } from "@oclif/core";
+import { sharedFlags } from "../../command-flags.mjs";
+import { localStatus } from "../../../local/orchestrator.mjs";
+import { withAssistantCommandResult } from "../../assistant/command-results.mjs";
+
+export default class LocalStatusCommand extends Command {
+  static summary = "Show local production environments";
+
+  static enableJsonFlag = true;
+
+  static args = {
+    name: Args.string({ required: false, description: "Environment name" }),
+  };
+
+  static flags = sharedFlags;
+
+  async run() {
+    return withAssistantCommandResult("local status", async () => {
+      const { args, flags } = await this.parse(LocalStatusCommand);
+      const result = await localStatus({ dir: flags.dir, name: args.name || null });
+      if (!this.jsonEnabled()) {
+        if (result.environments) {
+          if (result.environments.length === 0) this.log("Local Environments: none");
+          for (const environment of result.environments) {
+            for (const line of environment.lines || []) this.log(line);
+          }
+        } else {
+          for (const line of result.lines || []) this.log(line);
+        }
+      }
+      return { ok: true, result };
+    });
+  }
+}

package/lib/cli/commands/local/up.mjs

@@ -0,0 +1,39 @@
+import { Args, Command, Flags } from "@oclif/core";
+import { sharedFlags } from "../../command-flags.mjs";
+import { localUp } from "../../../local/orchestrator.mjs";
+import { withAssistantCommandResult } from "../../assistant/command-results.mjs";
+
+export default class LocalUpCommand extends Command {
+  static summary = "Start a local production environment";
+
+  static enableJsonFlag = true;
+
+  static args = {
+    name: Args.string({ required: false, description: "Environment name" }),
+  };
+
+  static flags = {
+    ...sharedFlags,
+    reset: Flags.boolean({ description: "Reset runtime databases from their templates", default: false }),
+    rebuild: Flags.boolean({ description: "Destroy and rebuild environment runtime state", default: false }),
+    "port-offset": Flags.integer({ description: "Add an offset to configured local ports" }),
+  };
+
+  async run() {
+    return withAssistantCommandResult("local up", async () => {
+      const { args, flags } = await this.parse(LocalUpCommand);
+      const result = await localUp({
+        dir: flags.dir,
+        name: args.name || "local",
+        service: flags.service,
+        reset: flags.reset,
+        rebuild: flags.rebuild,
+        portOffset: flags["port-offset"],
+      });
+      if (!this.jsonEnabled()) {
+        for (const line of result.lines || []) this.log(line);
+      }
+      return { ok: true, result };
+    });
+  }
+}

package/lib/cli/entrypoint.mjs

@@ -14,6 +14,7 @@ export function normalizeCliArgs(argv) {
     "typecheck",
     "doctor",
     "lint",
+    "local",
     "browser",
     "db",
     "guard",
@@ -43,6 +44,8 @@ export function normalizeCliArgs(argv) {
     "--prompt",
     "--command",
     "--use",
+    "--port-offset",
+    "--lines",
   ]);
   const positionals = findPositionals(argv, valueFlags);
   const firstPositional = positionals[0] || null;
@@ -134,6 +137,9 @@ function reorderCommandArgs(args, positionals) {
   if (positionals[0]?.value === "browser" && positionals[1]) {
     commandTokens.push(positionals[1]);
   }
+  if (positionals[0]?.value === "local" && positionals[1]) {
+    commandTokens.push(positionals[1]);
+  }
   const commandIndexes = new Set(commandTokens.map((token) => token.index));
   return [
     ...commandTokens.map((token) => token.value),

package/lib/cli/renderers/status/text.mjs

@@ -24,6 +24,20 @@ export function renderStatusResult(result) {
     lines.push(`  ... ${(result.runs.runs.length - 5)} more run${result.runs.runs.length - 5 === 1 ? "" : "s"}`);
   }
 
+  lines.push("", "Local Environments");
+  if ((result.localEnvironments?.environments || []).length === 0) {
+    lines.push("  none");
+  } else {
+    lines.push(`  active: ${result.localEnvironments?.active || 0}`);
+    for (const environment of result.localEnvironments.environments.slice(0, 5)) {
+      const ports = environment.ports?.length ? ` ports=${environment.ports.join(",")}` : "";
+      lines.push(`  ${environment.name}: ${environment.status} target=${environment.target || "unknown"}${ports}`);
+    }
+    if (result.localEnvironments.environments.length > 5) {
+      lines.push(`  ... ${result.localEnvironments.environments.length - 5} more environment${result.localEnvironments.environments.length - 5 === 1 ? "" : "s"}`);
+    }
+  }
+
   lines.push("", "Runtime Graphs");
   if ((result.runtimeGraphs || []).length === 0) {
     lines.push("  none");

package/lib/config/index.mjs

@@ -5,6 +5,7 @@ import { loadTestkitConfig } from "./config-loader.mjs";
 import { normalizeToolchainRegistry } from "../toolchains/index.mjs";
 import { loadTestFileMetadataMap } from "../discovery/file-metadata.mjs";
 import { mergeDiscoveryConfigs } from "../discovery/path-policy.mjs";
+import { normalizeFingerprintPolicy } from "../repo/fingerprint-policy.mjs";
 import { normalizeDatabaseConfig } from "./database.mjs";
 import { normalizeRepoDiscoveryConfig, normalizeServiceDiscoveryConfig } from "./discovery-config.mjs";
 import { inferEnvFiles, loadServiceEnv, parseDotenv } from "./env.mjs";
@@ -32,6 +33,8 @@ export async function loadConfigContext(opts = {}) {
   const execution = normalizeRepoExecution(config.execution);
   const regressions = normalizeRegressionsConfig(config.regressions);
   const toolchains = normalizeToolchainRegistry(config.toolchains);
+  const environments = normalizeEnvironmentRegistry(config.environments);
+  const fingerprints = normalizeFingerprintPolicy(config.fingerprints);
   const discoveryConfig = normalizeRepoDiscoveryConfig(config.discovery);
   const explicitServices = config.services || {};
   const discovery = discoverProject(productDir, explicitServices, {
@@ -56,6 +59,8 @@ export async function loadConfigContext(opts = {}) {
         discovery: discoveryConfig,
         regressions,
         toolchains,
+        environments,
+        fingerprints,
         explicitService: explicitServices[name] || {},
         discoveredService: discovery.services[name] || null,
         suites: discovery.suitesByService[name] || {},
@@ -70,9 +75,11 @@ export async function loadConfigContext(opts = {}) {
     config,
     configFile,
     execution,
+    environments,
     discovery: discoveryConfig,
     regressions,
     toolchains,
+    fingerprints,
     explicitServices,
     discovery,
     configs,
@@ -104,6 +111,8 @@ function normalizeServiceConfig({
   discovery,
   regressions,
   toolchains,
+  environments,
+  fingerprints,
   explicitService,
   discoveredService,
   suites,
@@ -168,12 +177,157 @@ function normalizeServiceConfig({
       runtime,
       browser,
       ui: config.ui || null,
+      environments,
+      fingerprints,
       fileMetadataByPath: serviceFileMetadata,
       local,
     },
   };
 }
 
+function normalizeEnvironmentRegistry(environments = {}) {
+  if (!environments || typeof environments !== "object" || Array.isArray(environments)) {
+    throw new Error("testkit.config.ts environments must be an object");
+  }
+  return Object.fromEntries(
+    Object.entries(environments).map(([name, environment]) => [
+      normalizeEnvironmentName(name),
+      normalizeEnvironmentConfig(name, environment),
+    ])
+  );
+}
+
+function normalizeEnvironmentName(name) {
+  const normalized = String(name || "").trim();
+  if (!/^[A-Za-z0-9_-]+$/.test(normalized)) {
+    throw new Error(`Environment name "${name}" must contain only letters, numbers, underscores, or dashes`);
+  }
+  return normalized;
+}
+
+function normalizeEnvironmentConfig(name, environment) {
+  if (!environment || typeof environment !== "object" || Array.isArray(environment)) {
+    throw new Error(`Environment "${name}" must be an object`);
+  }
+  if ((environment.kind || "local") !== "local") {
+    throw new Error(`Environment "${name}" uses unsupported kind "${environment.kind}"`);
+  }
+  const target = String(environment.target || "").trim();
+  if (!target) {
+    throw new Error(`Environment "${name}" requires target`);
+  }
+  const data = environment.data || "reuse";
+  if (!["reuse", "reset", "rebuild"].includes(data)) {
+    throw new Error(`Environment "${name}" data must be one of: reuse, reset, rebuild`);
+  }
+  const portOffset = environment.portOffset == null ? 0 : Number(environment.portOffset);
+  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),
+    ...(environment.publicHost ? { publicHost: String(environment.publicHost) } : {}),
+    ...(kiln ? { kiln } : {}),
+  };
+}
+
+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 } } : {}),
+  };
+}
+
+function normalizeEnvironmentEnv(env) {
+  if (!env) return {};
+  if (typeof env !== "object" || Array.isArray(env)) {
+    throw new Error("Environment env must be an object");
+  }
+  const hasPresetShape =
+    Object.prototype.hasOwnProperty.call(env, "values") ||
+    Object.prototype.hasOwnProperty.call(env, "databases");
+  if (!hasPresetShape) {
+    return Object.fromEntries(
+      Object.entries(env).map(([key, value]) => [key, String(value)])
+    );
+  }
+  const allowedKeys = new Set(["values", "databases"]);
+  const unexpectedKeys = Object.keys(env).filter((key) => !allowedKeys.has(key));
+  if (unexpectedKeys.length > 0) {
+    throw new Error(
+      `Environment env only supports "values" and "databases". Received unexpected key(s): ${unexpectedKeys.join(", ")}`
+    );
+  }
+  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 : {};
+  return {
+    ...expandDatabaseBindings(databases),
+    ...Object.fromEntries(Object.entries(values).map(([key, value]) => [key, String(value)])),
+  };
+}
+
+function expandDatabaseBindings(bindings) {
+  const env = {};
+  for (const [name, binding] of Object.entries(bindings || {})) {
+    if (!binding || typeof binding !== "object" || Array.isArray(binding)) {
+      throw new Error(`env.databases.${name} must be an object`);
+    }
+    const prefix = normalizeDatabaseEnvToken(binding.prefix, `env.databases.${name}.prefix`);
+    const serviceName = normalizeDatabaseEnvToken(binding.service, `env.databases.${name}.service`, false);
+    env[`${prefix}_DATABASE_HOST`] = `{dbHost:${serviceName}}`;
+    env[`${prefix}_DATABASE_PORT`] = `{dbPort:${serviceName}}`;
+    env[`${prefix}_DATABASE_NAME`] = `{dbName:${serviceName}}`;
+    env[`${prefix}_DATABASE_USER`] = `{dbUser:${serviceName}}`;
+    env[`${prefix}_DATABASE_PASSWORD`] = `{dbPassword:${serviceName}}`;
+    env[`${prefix}_DATABASE_SSL`] = "0";
+  }
+  return env;
+}
+
+function normalizeDatabaseEnvToken(value, label, sanitize = true) {
+  const raw = String(value || "").trim();
+  const normalized = sanitize
+    ? raw.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "")
+    : raw;
+  if (!normalized) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return normalized;
+}
+
 function normalizeLocalConfig(name, explicitService, discoveredService, productDir) {
   if (Object.prototype.hasOwnProperty.call(explicitService, "local")) {
     if (explicitService.local === false) {

package/lib/config/validation.mjs

@@ -3,6 +3,15 @@ import { validateConfiguredCollection } from "../shared/configured-steps.mjs";
 
 export function validateConfigCoverage(configs) {
   const names = new Set(configs.map((config) => config.name));
+  const environments = configs[0]?.testkit?.environments || {};
+  for (const [environmentName, environment] of Object.entries(environments)) {
+    if (!names.has(environment.target)) {
+      const available = [...names].sort().join(", ");
+      throw new Error(
+        `Environment "${environmentName}" targets unknown service "${environment.target}". Available: ${available}`
+      );
+    }
+  }
   for (const config of configs) {
     for (const depName of config.testkit.dependsOn || []) {
       if (!names.has(depName)) {

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

@@ -153,6 +153,11 @@ export interface TestkitExecutionConfig {
   fileTimeoutSeconds?: number;
 }
 
+export interface FingerprintConfig {
+  exclude?: string[];
+  include?: string[];
+}
+
 export interface BrowserServiceConfig {
   origins?: string[];
 }
@@ -277,6 +282,49 @@ export interface PresetEnvConfig {
   databases?: Record<string, DatabaseBindingEnvConfig>;
 }
 
+export interface LocalEnvironmentConfig {
+  kind: "local";
+  data?: "reuse" | "reset" | "rebuild";
+  driver?: "host" | "kiln";
+  env?: Record<string, string>;
+  kiln?: KilnLocalEnvironmentConfig;
+  portOffset?: number;
+  publicHost?: string;
+  target: string;
+}
+
+export interface LocalEnvironmentOptions extends Omit<LocalEnvironmentConfig, "kind" | "env"> {
+  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 };
@@ -477,6 +525,8 @@ export interface NextAppOptions extends Omit<ServiceConfig, "local" | "runtime"
 export interface TestkitConfig {
   discovery?: DiscoveryConfig;
   execution?: TestkitExecutionConfig;
+  environments?: Record<string, LocalEnvironmentConfig>;
+  fingerprints?: FingerprintConfig;
   lint?: TestkitLintConfig;
   profiles?: {
     http?: Record<string, HttpSuiteConfig<any>>;
@@ -563,6 +613,9 @@ export declare const toolchain: {
 export declare const ui: {
   auth(options?: UiAuthConfig): UiConfig;
 };
+export declare const environment: {
+  local(options: LocalEnvironmentOptions): LocalEnvironmentConfig;
+};
 export declare const auth: {
   fixture(options: { contract: JsonSessionContract; topology: AuthTopology }): AuthFixture;
   contracts: {

package/lib/config-api/index.mjs

@@ -444,6 +444,20 @@ export const ui = {
   auth: uiAuth,
 };
 
+function localEnvironment(options = {}) {
+  const { env, ...rest } = options;
+  return {
+    kind: "local",
+    data: "reuse",
+    ...rest,
+    ...(env !== undefined ? { env: normalizePresetEnv(env) } : {}),
+  };
+}
+
+export const environment = {
+  local: localEnvironment,
+};
+
 export const auth = {
   fixture: createAuthFixture,
   contracts: {