@elench/testkit 0.1.118 → 0.1.119

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/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/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/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-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("'", "''")}'`;
+}

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

@@ -9,9 +9,9 @@ export interface DatabaseTemplateConfig {
 
 export interface DatabaseTemplateOptions {
   inputs?: string[];
-  migrate?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[];
-  seed?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[];
-  verify?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[];
+  migrate?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
+  seed?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
+  verify?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
 }
 
 export interface DatabaseSourceSchemaOptions {
@@ -26,6 +26,7 @@ export interface DatabaseSourceSchemaConfig extends DatabaseSourceSchemaOptions
 }
 
 export interface TemplateStepBaseConfig {
+  args?: unknown;
   cwd?: string;
   inputs?: string[];
 }
@@ -50,6 +51,8 @@ export type TemplateLifecycleStepConfig =
   | TemplateSqlFileStepConfig
   | TemplateModuleStepConfig;
 
+export interface TemplateLifecycleStepOptions extends TemplateStepBaseConfig {}
+
 export interface TscBuildConfig {
   kind: "tsc";
   cwd?: string;
@@ -379,6 +382,8 @@ export interface NodeAppOptions extends Omit<ServiceConfig, "local" | "runtime"
 }
 
 export interface NextAppOptions extends Omit<ServiceConfig, "local" | "runtime" | "env"> {
+  api?: string | { baseUrl: string };
+  auth?: "disabled-clerk" | { kind: "disabled-clerk" };
   baseUrl?: string;
   build?: BuildConfig | null;
   buildInputs?: string[];
@@ -413,6 +418,14 @@ export interface TestkitConfig {
   };
 }
 
+export interface NodeNextPresetOptions {
+  fileTimeoutSeconds?: number;
+  install?: "require-host" | "download";
+  node?: string;
+  npm?: string;
+  workers?: number;
+}
+
 export declare function defineConfig<T extends TestkitConfig>(config: T): T;
 export declare function defineFile<T extends TestkitFileMetadata>(metadata: T): T;
 export declare const app: {
@@ -423,19 +436,39 @@ export declare const database: {
   schema: {
     fromEnv(envName: string, options?: DatabaseSourceSchemaOptions): DatabaseSourceSchemaConfig;
   };
+  steps: {
+    materializePostgresBinding(options?: unknown): TemplateModuleStepConfig;
+    verifySeed(options?: unknown): TemplateModuleStepConfig;
+  };
   postgres(
     options?: Omit<LocalDatabaseConfig, "provider" | "template"> & {
+      inputs?: string[];
+      migrate?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
+      seed?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
       template?: DatabaseTemplateOptions;
+      verify?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
     }
   ): LocalDatabaseConfig;
   fixture(
     options?: Omit<LocalDatabaseConfig, "provider" | "template"> & {
+      inputs?: string[];
+      migrate?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
+      seed?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
       template?: DatabaseTemplateOptions;
+      verify?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
       discovery?: DiscoveryConfig;
       envFiles?: string[];
     }
   ): ServiceConfig;
 };
+export declare const step: {
+  command(run: string, options?: TemplateLifecycleStepOptions): TemplateCommandStepConfig;
+  module(target: string, options?: TemplateLifecycleStepOptions): TemplateModuleStepConfig;
+  sqlFile(path: string, options?: TemplateLifecycleStepOptions): TemplateSqlFileStepConfig;
+};
+export declare const presets: {
+  nodeNext(options?: NodeNextPresetOptions): Pick<TestkitConfig, "execution" | "toolchains">;
+};
 export declare const toolchain: {
   node(options?: NodeToolchainConfig): NodeToolchainConfig;
 };