@elench/testkit 0.1.117 → 0.1.119

package/README.md

@@ -325,13 +325,24 @@ stable build-and-start flows.
 
 `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` refreshes
-`.testkit/db/<service>/source-schema.sql` from the source database when needed,
-applies that cached schema to the local template DB, runs local template setup,
-and verifies that the replayed local schema still matches the source dump. If
-local replay differs, Testkit refreshes from the source once and retries. If it
-still differs, the run fails with schema diagnostics under
-`.testkit/results/schema`.
+source database as the schema source of truth. A normal `testkit run` resolves a
+commit-aware source schema cache under
+`.testkit/db/<service>/source-schemas/`, applies that cached schema to the local
+template DB, runs local template setup, and verifies that the replayed local
+schema still matches the source dump. If local replay differs, Testkit refreshes
+from the source once for the current cache key and retries. If it still differs,
+the run fails with schema diagnostics under `.testkit/results/schema`.
+
+Source schema cache keys are derived automatically from repo state:
+
+- clean git worktrees use `commits/<sha>`
+- dirty git worktrees use `dirty/<sha>-<fingerprint>`
+- non-git directories use `nogit/<fingerprint>`
+
+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
+fingerprint so local experiments cannot overwrite a clean commit baseline.
 
 Template setup executes in three explicit phases:
 
@@ -349,11 +360,12 @@ exiting cannot be refreshed at the midpoint.
 Source schema refreshes are intentionally single-connection and pooler-safe.
 If a Neon pooled source URL is configured, Testkit rewrites it to the matching
 direct Neon endpoint before running `pg_dump` and records the original/resolved
-host classifications in `.testkit/db/<service>/source-schema.meta.json`. Unknown
-PgBouncer/pooler URLs fail closed; configure a direct source URL for those
-providers. Concurrent refreshes for the same service are serialized with a
-cache-local lock so multiple Testkit processes do not stampede the source
-database.
+host classifications beside the resolved cache entry. Unknown PgBouncer/pooler
+URLs fail closed; configure a direct source URL for those providers. Concurrent
+refreshes for the same service and cache key are serialized with a cache-local
+lock so multiple Testkit processes do not stampede the source database. Testkit
+also maintains `.testkit/db/<service>/source-schemas/index.json` and prunes old
+inactive cache entries automatically.
 
 For most repos, prefer declarative step objects directly inside
 `database.postgres({ template: ... })` and `runtime.prepare.steps`.
@@ -695,6 +707,8 @@ services that define `database: database.postgres(...)`.
 - runtime databases are cloned from templates when binding is `per-runtime`
 - shared databases are reused when binding is `shared`
 - source schema caches are refreshed only from the configured source database
+- clean commits, dirty worktrees, and non-git directories get separate source
+  schema cache entries automatically
 - template fingerprints are derived automatically from env files, source schema
   cache, migrate/seed config, and repo contents
 
@@ -711,6 +725,7 @@ npm test
 npm run test:unit
 npm run test:integration
 npm run test:system
+npm run test:live:github
 npm run test:live:neon
 npm run test:database-version:compat
 ```

package/lib/app/doctor.mjs

@@ -1,16 +1,14 @@
-import fs from "fs";
 import path from "path";
-import ts from "typescript";
 import { discoverTests } from "../discovery/index.mjs";
 import { loadConfigContext } from "../config/index.mjs";
 import { runTestkitTypecheck } from "./typecheck.mjs";
-import { findConfigFile } from "../config/config-loader.mjs";
+import { runLint } from "../lint/index.mjs";
 
 export async function runDoctor(options = {}) {
   const checks = [];
   const productDir = options.dir ? path.resolve(process.cwd(), options.dir) : process.cwd();
 
-  await loadConfigContext({ dir: productDir });
+  const context = await loadConfigContext({ dir: productDir });
   checks.push({
     code: "config-load",
     level: "pass",
@@ -29,26 +27,18 @@ export async function runDoctor(options = {}) {
     details: discoveryErrors,
   });
 
-  const playwrightViolations = findPlaywrightRuntimeImportViolations(productDir);
-  checks.push({
-    code: "ui-runtime-imports",
-    level: playwrightViolations.length === 0 ? "pass" : "fail",
-    message:
-      playwrightViolations.length === 0
-        ? "No runtime @playwright/test imports found in testkit UI suites"
-        : `Found ${playwrightViolations.length} UI runtime import violation(s); import from @elench/testkit/ui instead`,
-    details: playwrightViolations,
+  const lint = await runLint({
+    dir: productDir,
+    ...(context.config?.lint || {}),
   });
-
-  const configImportViolations = findConfigImportViolations(productDir);
   checks.push({
-    code: "config-import-hygiene",
-    level: configImportViolations.length === 0 ? "pass" : "fail",
+    code: "lint",
+    level: lint.ok ? "pass" : "fail",
     message:
-      configImportViolations.length === 0
-        ? "Repo config does not import __testkit__ helper modules"
-        : `Found ${configImportViolations.length} repo config import violation(s)`,
-    details: configImportViolations,
+      lint.ok
+        ? `No Testkit lint violations across ${lint.summary.testkitFiles} suite file(s)`
+        : `Found ${lint.summary.violations} Testkit lint violation(s)`,
+    details: lint.violations,
   });
 
   const hasBrowserOrNextWork = discovery.files.some((entry) => entry.type === "ui");
@@ -88,95 +78,3 @@ export async function runDoctor(options = {}) {
     checks,
   };
 }
-
-function findPlaywrightRuntimeImportViolations(productDir) {
-  const violations = [];
-  for (const absolutePath of collectFiles(productDir)) {
-    const sourceText = fs.readFileSync(absolutePath, "utf8");
-    const sourceFile = ts.createSourceFile(absolutePath, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-
-    for (const statement of sourceFile.statements) {
-      if (!ts.isImportDeclaration(statement)) continue;
-      if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
-      if (statement.moduleSpecifier.text !== "@playwright/test") continue;
-      const clause = statement.importClause;
-      if (clause?.isTypeOnly) continue;
-      if (!clause) {
-        violations.push(relativeViolation(productDir, absolutePath, sourceFile, statement));
-        continue;
-      }
-      if (clause.name) {
-        violations.push(relativeViolation(productDir, absolutePath, sourceFile, statement));
-        continue;
-      }
-      if (!clause.namedBindings) {
-        violations.push(relativeViolation(productDir, absolutePath, sourceFile, statement));
-        continue;
-      }
-      if (ts.isNamespaceImport(clause.namedBindings)) {
-        violations.push(relativeViolation(productDir, absolutePath, sourceFile, statement));
-        continue;
-      }
-      if (clause.namedBindings.elements.some((entry) => !entry.isTypeOnly)) {
-        violations.push(relativeViolation(productDir, absolutePath, sourceFile, statement));
-      }
-    }
-  }
-  return violations;
-}
-
-function findConfigImportViolations(productDir) {
-  const configFile = findConfigFile(productDir);
-  if (!configFile || !fs.existsSync(configFile)) return [];
-
-  const sourceText = fs.readFileSync(configFile, "utf8");
-  const sourceFile = ts.createSourceFile(configFile, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-  const violations = [];
-
-  for (const statement of sourceFile.statements) {
-    if (!ts.isImportDeclaration(statement)) continue;
-    if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
-    const specifier = statement.moduleSpecifier.text;
-    if (!isRepoLocalConfigImportViolation(specifier)) continue;
-    const position = sourceFile.getLineAndCharacterOfPosition(statement.getStart(sourceFile));
-    violations.push({
-      file: path.relative(productDir, configFile).split(path.sep).join("/"),
-      line: position.line + 1,
-      specifier,
-      snippet: statement.getText(sourceFile),
-    });
-  }
-
-  return violations;
-}
-
-function collectFiles(rootDir, out = []) {
-  if (!fs.existsSync(rootDir)) return out;
-  for (const entry of fs.readdirSync(rootDir, { withFileTypes: true })) {
-    const absolutePath = path.join(rootDir, entry.name);
-    if (entry.isDirectory()) {
-      if (entry.name === "node_modules" || entry.name === ".git" || entry.name === ".testkit") continue;
-      collectFiles(absolutePath, out);
-      continue;
-    }
-    if (entry.isFile() && (entry.name.endsWith(".ui.testkit.ts") || entry.name.endsWith(".ui.testkit.ts"))) {
-      out.push(absolutePath);
-    }
-  }
-  return out.sort((left, right) => left.localeCompare(right));
-}
-
-function isRepoLocalConfigImportViolation(specifier) {
-  if (typeof specifier !== "string") return false;
-  if (!specifier.startsWith(".") && !specifier.startsWith("/")) return false;
-  return specifier.includes("__testkit__");
-}
-
-function relativeViolation(productDir, absolutePath, sourceFile, statement) {
-  const position = sourceFile.getLineAndCharacterOfPosition(statement.getStart(sourceFile));
-  return {
-    file: path.relative(productDir, absolutePath).split(path.sep).join("/"),
-    line: position.line + 1,
-    snippet: statement.getText(sourceFile),
-  };
-}

package/lib/cli/assistant/command-observer.mjs

@@ -3,7 +3,7 @@ import path from "path";
 import { isAssistantRunCommand } from "./command-classifier.mjs";
 
 const POLL_INTERVAL_MS = 150;
-const OBSERVED_KINDS = new Set(["run", "discover", "status", "doctor", "typecheck"]);
+const OBSERVED_KINDS = new Set(["run", "discover", "status", "doctor", "lint", "typecheck"]);
 
 export function createAssistantCommandObserver({
   productDir,

package/lib/cli/assistant/context-pack.mjs

@@ -1,6 +1,6 @@
 import fs from "fs";
 import path from "path";
-import { fileURLToPath, pathToFileURL } from "url";
+import { fileURLToPath } from "url";
 import { readContextContent, buildContextSelection } from "../../results/context.mjs";
 import { assistantSessionPaths, createAssistantSessionId } from "./session-paths.mjs";
 import {
@@ -88,7 +88,6 @@ export function prepareAssistantContextPack({
     );
     if (!fs.existsSync(wrapperPath)) fs.writeFileSync(wrapperPath, buildWrapperScript({
       cliPath: resolveCliPath(),
-      classifierUrl: resolveClassifierUrl(),
       sessionId,
       resultDir,
       commandLogPath,
@@ -165,16 +164,11 @@ function resolveCliPath() {
   return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "bin", "testkit.mjs");
 }
 
-function resolveClassifierUrl() {
-  return pathToFileURL(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "command-classifier.mjs")).href;
-}
-
-function buildWrapperScript({ cliPath, classifierUrl, sessionId, resultDir, commandLogPath } = {}) {
+function buildWrapperScript({ cliPath, sessionId, resultDir, commandLogPath } = {}) {
   return `#!/usr/bin/env node
-import { spawnSync } from "child_process";
-import fs from "fs";
-import path from "path";
-import { classifyAssistantCommandKind } from ${JSON.stringify(classifierUrl)};
+const { spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
 
 const commandId = process.env.${ASSISTANT_COMMAND_ID_ENV} || \`cmd-\${Date.now()}-\${Math.random().toString(36).slice(2, 10)}\`;
 const commandLogPath = process.env.${ASSISTANT_COMMAND_LOG_ENV} || ${JSON.stringify(commandLogPath)};
@@ -231,6 +225,32 @@ function appendCommandLog(event) {
     // Command observation must not affect command execution.
   }
 }
+
+function classifyAssistantCommandKind(argv = []) {
+  const runShortcuts = new Set(["ui", "e2e", "scenario", "int", "dal", "load", "all"]);
+  const valueFlags = new Set([
+    "--dir",
+    "--service",
+    "--type",
+    "--suite",
+    "--file",
+    "--workers",
+    "--file-timeout-seconds",
+    "--seed",
+    "--output-mode",
+  ]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = String(argv[index] || "");
+    if (valueFlags.has(value)) {
+      index += 1;
+      continue;
+    }
+    if (!value.startsWith("-")) {
+      return runShortcuts.has(value) ? "run" : value;
+    }
+  }
+  return "run";
+}
 `;
 }
 

package/lib/cli/assistant/state.mjs

@@ -10,6 +10,7 @@ import { createRunState } from "../state/run/state.mjs";
 import { buildContextSelection } from "../../results/context.mjs";
 import { renderDiscoverResult } from "../renderers/discover/text.mjs";
 import { renderDoctorResult } from "../renderers/doctor/text.mjs";
+import { renderLintResult } from "../renderers/lint/text.mjs";
 import { renderStatusResult } from "../renderers/status/text.mjs";
 import { renderTypecheckResult } from "../renderers/typecheck/text.mjs";
 import { isProviderInstalled } from "./providers/index.mjs";
@@ -1092,6 +1093,7 @@ function renderObservedCommandResult(command) {
     return normalizeRenderedLines((result.results || []).flatMap((entry) => renderStatusResult(entry)));
   }
   if (command.kind === "doctor") return normalizeRenderedLines(renderDoctorResult(result));
+  if (command.kind === "lint") return normalizeRenderedLines(renderLintResult(result));
   if (command.kind === "typecheck") return normalizeRenderedLines(renderTypecheckResult(result));
   return [];
 }

package/lib/cli/commands/lint.mjs

@@ -0,0 +1,37 @@
+import { Command, Flags } from "@oclif/core";
+import { executeLintOperation } from "../operations/lint/operation.mjs";
+import { renderLintResult } from "../renderers/lint/text.mjs";
+import { withAssistantCommandResult } from "../assistant/command-results.mjs";
+
+export default class LintCommand extends Command {
+  static summary = "Run built-in Testkit repository hygiene checks";
+
+  static enableJsonFlag = true;
+
+  static flags = {
+    dir: Flags.string({
+      description: "Product directory",
+    }),
+  };
+
+  async run() {
+    return withAssistantCommandResult("lint", async () => {
+      const { flags } = await this.parse(LintCommand);
+      const result = await executeLintOperation(flags);
+
+      if (!this.jsonEnabled()) {
+        for (const line of renderLintResult(result)) {
+          this.log(line);
+        }
+      }
+
+      if (!result.ok) {
+        const error = new Error("testkit lint failed");
+        error.result = result;
+        throw error;
+      }
+
+      return result;
+    });
+  }
+}

package/lib/cli/entrypoint.mjs

@@ -13,6 +13,7 @@ export function normalizeCliArgs(argv) {
     "discover",
     "typecheck",
     "doctor",
+    "lint",
     "browser",
     "db",
   ]);

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

@@ -4,7 +4,7 @@ import path from "path";
 import { loadManagedConfigs, resolveTargetConfig, collectRequiredConfigs, topologicallySortConfigs } from "../../../../../app/configs.mjs";
 import { resolveProductDir } from "../../../../../config/index.mjs";
 import { prepareDatabaseRuntime } from "../../../../../database/index.mjs";
-import { forceRefreshSourceSchemaCache, getSourceSchemaCachePath } from "../../../../../database/schema-source.mjs";
+import { forceRefreshSourceSchemaCache } from "../../../../../database/schema-source.mjs";
 import { createRunReporter } from "../../../../renderers/run/text-reporter.mjs";
 import { createRunLogRegistry } from "../../../../../runner/logs.mjs";
 import { createSetupOperationRegistry } from "../../../../../runner/setup-operations.mjs";
@@ -40,13 +40,15 @@ export async function executeDatabaseSchemaRefreshOperation(options = {}) {
       logRegistry,
       setupRegistry,
     });
-    const outputPath = getSourceSchemaCachePath(resolvedTarget);
+    const outputPath = state.cachePath;
     return {
       ok: true,
       productDir,
       service: target.name,
       outputPath,
       outputLabel: path.relative(productDir, outputPath) || path.basename(outputPath),
+      cacheKey: state.cacheKey,
+      cacheKind: state.cacheKind,
       envName: state.envName || null,
       sourceUrl: state.refreshInfo?.metadata?.sourceUrl || null,
       reusedExistingRefresh: Boolean(state.refreshInfo?.reusedExistingRefresh),

package/lib/cli/operations/lint/operation.mjs

@@ -0,0 +1,12 @@
+import { runLint } from "../../../lint/index.mjs";
+import { loadTestkitConfig } from "../../../config/config-loader.mjs";
+import { resolveProductDir } from "../../../config/paths.mjs";
+
+export async function executeLintOperation(flags = {}) {
+  const productDir = resolveProductDir(process.cwd(), flags.dir);
+  const { config } = await loadTestkitConfig(productDir);
+  return runLint({
+    dir: productDir,
+    ...(config.lint || {}),
+  });
+}

package/lib/cli/renderers/db-schema/text.mjs

@@ -1,5 +1,8 @@
 export function renderDatabaseSchemaRefreshResult(result) {
   const lines = [`Refreshed ${result.outputLabel}`];
+  if (result.cacheKey) {
+    lines.push(`Cache key ${result.cacheKey}`);
+  }
   if (result.sourceUrl?.rewritten && result.sourceUrl.originalClassification === "neon-pooler") {
     lines.push("Source schema URL uses Neon pooler; Testkit used the direct endpoint for pg_dump.");
   }

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

@@ -2,6 +2,11 @@ export function renderDoctorResult(result) {
   const lines = [`testkit doctor ${result.ok ? "passed" : "failed"} for ${result.productDir}`];
   for (const check of result.checks || []) {
     lines.push(`${check.level.toUpperCase()} ${check.code} ${check.message}`);
+    for (const detail of (check.details || []).slice(0, 5)) {
+      if (detail?.ruleId) {
+        lines.push(`  ${detail.ruleId} ${detail.file}:${detail.line} ${detail.message}`);
+      }
+    }
   }
   return lines;
 }

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

@@ -0,0 +1,20 @@
+export function renderLintResult(result) {
+  const lines = [
+    `testkit lint ${result.ok ? "passed" : "failed"} for ${result.productDir}`,
+    `Checked ${result.summary.files} source file(s), ${result.summary.testkitFiles} testkit suite file(s).`,
+  ];
+
+  if (result.violations.length === 0) {
+    return lines;
+  }
+
+  lines.push("");
+  for (const violation of result.violations) {
+    const location = violation.line ? `${violation.file}:${violation.line}` : violation.file;
+    lines.push(`${location} ${violation.ruleId}: ${violation.message}`);
+    if (violation.snippet) {
+      lines.push(`  ${violation.snippet}`);
+    }
+  }
+  return lines;
+}

package/lib/config/database.mjs

@@ -66,8 +66,7 @@ function normalizeSourceSchemaConfig(value, serviceName) {
   if (value === undefined) {
     return {
       kind: "auto",
-      cachePath: null,
-      refresh: { mode: "always" },
+      refresh: { mode: "auto" },
       unavailable: "auto",
       verify: true,
     };
@@ -79,13 +78,17 @@ function normalizeSourceSchemaConfig(value, serviceName) {
   if (kind !== "env") {
     throw new Error(`Service "${serviceName}" database.sourceSchema.kind must be "env"`);
   }
+  if (Object.prototype.hasOwnProperty.call(value, "cachePath")) {
+    throw new Error(
+      `Service "${serviceName}" database.sourceSchema.cachePath has been removed. Testkit now manages commit-scoped source schema caches automatically.`
+    );
+  }
   if (typeof value.env !== "string" || value.env.trim().length === 0) {
     throw new Error(`Service "${serviceName}" database.sourceSchema.env must be a non-empty string`);
   }
   return {
     kind,
     env: value.env.trim(),
-    cachePath: normalizeOptionalString(value.cachePath, `Service "${serviceName}" database.sourceSchema.cachePath`),
     refresh: normalizeSourceSchemaRefresh(value.refresh, serviceName),
     unavailable: normalizeSourceSchemaUnavailable(value.unavailable, serviceName),
     verify: value.verify !== false,
@@ -93,7 +96,8 @@ function normalizeSourceSchemaConfig(value, serviceName) {
 }
 
 function normalizeSourceSchemaRefresh(value, serviceName) {
-  if (value == null || value === "always") return { mode: "always" };
+  if (value == null || value === "auto") return { mode: "auto" };
+  if (value === "always") return { mode: "always" };
   if (typeof value === "object" && !Array.isArray(value)) {
     const ttlSeconds = value.ttlSeconds;
     if (!Number.isInteger(ttlSeconds) || ttlSeconds < 0) {
@@ -101,7 +105,7 @@ function normalizeSourceSchemaRefresh(value, serviceName) {
     }
     return { mode: "ttl", ttlSeconds };
   }
-  throw new Error(`Service "${serviceName}" database.sourceSchema.refresh must be "always" or { ttlSeconds }`);
+  throw new Error(`Service "${serviceName}" database.sourceSchema.refresh must be "auto", "always", or { ttlSeconds }`);
 }
 
 function normalizeSourceSchemaUnavailable(value, serviceName) {
@@ -110,11 +114,3 @@ function normalizeSourceSchemaUnavailable(value, serviceName) {
   }
   throw new Error(`Service "${serviceName}" database.sourceSchema.unavailable must be "auto", "fail", or "warn-cache"`);
 }
-
-function normalizeOptionalString(value, label) {
-  if (value == null) return null;
-  if (typeof value !== "string" || value.trim().length === 0) {
-    throw new Error(`${label} must be a non-empty string`);
-  }
-  return value.trim();
-}

package/lib/config-api/database-steps.mjs

@@ -0,0 +1,132 @@
+import { execa } from "execa";
+
+export async function verifySeed(context = {}) {
+  const args = context.args || {};
+  const table = requireIdentifier(args.table, "verifySeed.args.table");
+  const where = normalizeOptionalSql(args.where);
+  const minRows = normalizeNonNegativeInteger(args.minRows ?? 1, "verifySeed.args.minRows");
+  const databaseUrl = requireDatabaseUrl(context);
+  const query = `select count(*)::int from ${table}${where ? ` where ${where}` : ""}`;
+  const count = Number(await runScalar(databaseUrl, query, context));
+
+  if (!Number.isInteger(count) || count < minRows) {
+    throw new Error(`Expected at least ${minRows} row(s) in ${table}, found ${count || 0}`);
+  }
+}
+
+export async function materializePostgresBinding(context = {}) {
+  const args = context.args || {};
+  const table = requireIdentifier(args.table, "materializePostgresBinding.args.table");
+  const keyColumn = requireIdentifier(
+    args.keyColumn || "slug",
+    "materializePostgresBinding.args.keyColumn"
+  );
+  const key = normalizeRequiredValue(args.key, "materializePostgresBinding.args.key");
+  const values = normalizeObject(args.values, "materializePostgresBinding.args.values");
+  const databaseUrl = requireDatabaseUrl(context);
+
+  const columns = Object.keys(values);
+  if (columns.length === 0) {
+    throw new Error("materializePostgresBinding.args.values must contain at least one column");
+  }
+
+  const assignments = columns.map((column) => {
+    const identifier = requireIdentifier(column, `materializePostgresBinding.args.values.${column}`);
+    return `${identifier} = ${toSqlLiteral(values[column])}`;
+  });
+  const query =
+    `with updated as (update ${table} set ${assignments.join(", ")} ` +
+    `where ${keyColumn} = ${toSqlLiteral(key)} returning 1) select count(*)::int from updated`;
+  const result = await runPsql(databaseUrl, query, context);
+  const updated = Number(String(result.stdout || "").trim() || "0");
+  if (updated !== 1) {
+    throw new Error(`Expected to materialize 1 ${table} row for ${keyColumn}=${key}, updated ${updated || 0}`);
+  }
+}
+
+function requireDatabaseUrl(context) {
+  const databaseUrl = String(context.databaseUrl || context.env?.DATABASE_URL || "").trim();
+  if (!databaseUrl) {
+    throw new Error("Database template step requires DATABASE_URL");
+  }
+  return databaseUrl;
+}
+
+async function runScalar(databaseUrl, query, context) {
+  const result = await runPsql(databaseUrl, query, context);
+  return String(result.stdout || "").trim();
+}
+
+async function runPsql(databaseUrl, query, context) {
+  const result = await execa(
+    "psql",
+    [
+      databaseUrl,
+      "-v",
+      "ON_ERROR_STOP=1",
+      "-X",
+      "-q",
+      "-t",
+      "-A",
+      "-c",
+      query,
+    ],
+    {
+      cwd: context.cwd || context.productDir || process.cwd(),
+      env: context.env || process.env,
+      stdout: "pipe",
+      stderr: "pipe",
+      reject: false,
+    }
+  );
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr || result.shortMessage || `psql failed with exit code ${result.exitCode}`);
+  }
+  return result;
+}
+
+function requireIdentifier(value, label) {
+  const normalized = String(value || "").trim();
+  if (!/^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)?$/.test(normalized)) {
+    throw new Error(`${label} must be a SQL identifier or schema-qualified identifier`);
+  }
+  return normalized;
+}
+
+function normalizeOptionalSql(value) {
+  if (value == null || value === "") return "";
+  const normalized = String(value).trim();
+  if (!normalized || /;|--|\/\*/.test(normalized)) {
+    throw new Error("verifySeed.args.where must be a single SQL predicate without comments or semicolons");
+  }
+  return normalized;
+}
+
+function normalizeNonNegativeInteger(value, label) {
+  const normalized = Number(value);
+  if (!Number.isInteger(normalized) || normalized < 0) {
+    throw new Error(`${label} must be a non-negative integer`);
+  }
+  return normalized;
+}
+
+function normalizeObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value;
+}
+
+function normalizeRequiredValue(value, label) {
+  if (value == null || String(value).length === 0) {
+    throw new Error(`${label} is required`);
+  }
+  return value;
+}
+
+function toSqlLiteral(value) {
+  if (value === null) return "null";
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  if (typeof value === "boolean") return value ? "true" : "false";
+  return `'${String(value).replaceAll("'", "''")}'`;
+}