@elench/testkit 0.1.51 → 0.1.53

package/lib/runner/services.mjs

@@ -6,16 +6,16 @@ import {
 } from "../toolchains/index.mjs";
 import { buildExecutionEnv, numericPortFromUrl } from "./template.mjs";
 import { DEFAULT_READY_TIMEOUT_MS, assertLocalServicePortsAvailable, isPortInUse, waitForReady } from "./readiness.mjs";
-import { killChildProcess, pipeOutput, startDetachedCommand, stopChildProcess, sleep } from "./processes.mjs";
+import { captureOutput, killChildProcess, startDetachedCommand, stopChildProcess, sleep } from "./processes.mjs";
 import { readDatabaseUrl } from "./state-io.mjs";
 
-export async function startLocalServices(runtimeConfigs, lifecycle) {
+export async function startLocalServices(runtimeConfigs, lifecycle, options = {}) {
   const started = [];
 
   try {
     for (const config of runtimeConfigs) {
       if (!config.testkit.local) continue;
-      const proc = await startLocalService(config, lifecycle);
+      const proc = await startLocalService(config, lifecycle, options);
       started.push(proc);
     }
   } catch (error) {
@@ -26,10 +26,10 @@ export async function startLocalServices(runtimeConfigs, lifecycle) {
   return started;
 }
 
-export async function startLocalService(config, lifecycle) {
+export async function startLocalService(config, lifecycle, options = {}) {
   const cwd = resolveServiceCwd(config.productDir, config.testkit.local.cwd);
   const resolvedToolchain = await resolveConfiguredToolchain(config);
-  await announceResolvedToolchain(config, resolvedToolchain);
+  await announceResolvedToolchain(config, resolvedToolchain, options.reporter);
   const env = applyToolchainEnv(
     buildExecutionEnv(config, config.testkit.local.env, process.env),
     resolvedToolchain
@@ -46,12 +46,29 @@ export async function startLocalService(config, lifecycle) {
 
   await assertLocalServicePortsAvailable(config, isPortInUse);
 
-  console.log(`Starting ${config.runtimeLabel}:${config.name}: ${config.testkit.local.start}`);
+  options.reporter?.localServiceStarting?.(config, config.testkit.local.start);
   const child = startDetachedCommand(config.testkit.local.start, cwd, env);
+  const logRecord = options.logRegistry?.ensureServiceLogRecord(config);
+  const liveWriter =
+    options.reporter?.outputMode === "debug"
+      ? (line) => options.reporter.writeDebugLine?.(line)
+      : null;
 
   const outputDrains = [
-    pipeOutput(child.stdout, `[${config.runtimeLabel}:${config.name}]`),
-    pipeOutput(child.stderr, `[${config.runtimeLabel}:${config.name}]`),
+    captureOutput(child.stdout, {
+      livePrefix: `[${config.runtimeLabel}:${config.name}]`,
+      liveWriter,
+      onLine(line) {
+        if (logRecord) options.logRegistry.append(logRecord, "stdout", line);
+      },
+    }),
+    captureOutput(child.stderr, {
+      livePrefix: `[${config.runtimeLabel}:${config.name}]`,
+      liveWriter,
+      onLine(line) {
+        if (logRecord) options.logRegistry.append(logRecord, "stderr", line);
+      },
+    }),
   ];
   lifecycle.registerService(config, child, cwd, () => {
     killChildProcess(child, "SIGTERM");

package/lib/runner/template-steps.mjs

@@ -23,14 +23,15 @@ const MODULE_RUNNER_ENTRY = path.join(
   "template-step-module-runner.mjs"
 );
 
-export async function runConfiguredSteps({ config, steps = [], env, labelPrefix }) {
+export async function runConfiguredSteps({ config, steps = [], env, labelPrefix, reporter = null }) {
   if (steps.length === 0) return;
   const resolvedToolchain = await resolveConfiguredToolchain(config);
-  await announceResolvedToolchain(config, resolvedToolchain);
+  await announceResolvedToolchain(config, resolvedToolchain, reporter);
 
   for (const [index, step] of steps.entries()) {
     const label = `${labelPrefix}:${config.name}:${index + 1}`;
-    console.log(`\n── ${label} ──`);
+    if (reporter?.phaseStarted) reporter.phaseStarted(label);
+    else console.log(`\n── ${label} ──`);
     await runConfiguredStep(config, step, env, resolvedToolchain);
   }
 }

package/lib/runner/worker-loop.mjs

@@ -23,10 +23,10 @@ export async function runWorker(
   lifecycle,
   claimNextTask,
   recordTaskOutcome,
-  recordGraphError
+  recordGraphError,
+  reporter = null
 ) {
   const startedAt = Date.now();
-  console.log(`\n══ worker ${worker.workerId} ══`);
   const errors = [];
 
   try {
@@ -69,8 +69,9 @@ export async function runWorker(
         }
         worker.currentGraphKey = task.graphKey;
         lease = await runtimeManager.acquire(task);
-        const outcome = await runTask(lease.context, task, lifecycle, lease);
+        const outcome = await runTask(lease.context, task, lifecycle, lease, reporter);
         recordTaskOutcome(trackers, outcome.task, outcome);
+        reporter?.taskFinished?.(outcome.task, outcome);
         timingUpdates.push({
           key: outcome.task.timingKey,
           durationMs: outcome.durationMs,
@@ -100,20 +101,20 @@ export async function runWorker(
   };
 }
 
-async function runTask(context, task, lifecycle, lease) {
+async function runTask(context, task, lifecycle, lease, reporter = null) {
   const targetConfig = context.configByName.get(task.targetName);
   if (!targetConfig) {
     throw new Error(`Runtime instance is missing target config "${task.targetName}"`);
   }
 
   if (task.framework === "playwright") {
-    return runPlaywrightTask(targetConfig, task, lifecycle, lease);
+    return runPlaywrightTask(targetConfig, task, lifecycle, lease, reporter);
   }
   if (task.type === "dal") {
-    return runDalTask(targetConfig, task, lifecycle, lease);
+    return runDalTask(targetConfig, task, lifecycle, lease, reporter);
   }
   if (task.framework === "k6" && HTTP_K6_TYPES.has(task.type)) {
-    return runHttpK6Task(targetConfig, task, lifecycle, lease);
+    return runHttpK6Task(targetConfig, task, lifecycle, lease, reporter);
   }
 
   throw new Error(

package/lib/setup/index.d.ts

@@ -1,18 +1,18 @@
 import type { AuthAdapter, HeaderBuilder, HttpSuiteConfig } from "../index";
 
-export interface LocalDatabaseConfig {
-  provider: "local";
-  binding?: "shared" | "per-runtime";
-  image?: string;
-  password?: string;
-  reset?: boolean;
-  template?: {
-    inputs?: string[];
-    migrate?: TemplateLifecycleStepConfig[];
-    seed?: TemplateLifecycleStepConfig[];
-    verify?: TemplateLifecycleStepConfig[];
-  };
-  user?: string;
+export interface DatabaseTemplateConfig {
+  inputs?: string[];
+  migrate?: TemplateLifecycleStepConfig[];
+  seed?: TemplateLifecycleStepConfig[];
+  verify?: TemplateLifecycleStepConfig[];
+}
+
+export interface SeededDatabaseTemplateOptions {
+  inputs?: string[];
+  schema?: string | TemplateSqlFileStepConfig;
+  migrate?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[];
+  seed?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[];
+  verify?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[];
 }
 
 export interface TemplateStepBaseConfig {
@@ -40,6 +40,16 @@ export type TemplateLifecycleStepConfig =
   | TemplateSqlFileStepConfig
   | TemplateModuleStepConfig;
 
+export interface LocalDatabaseConfig {
+  provider: "local";
+  binding?: "shared" | "per-runtime";
+  image?: string;
+  password?: string;
+  reset?: boolean;
+  template?: DatabaseTemplateConfig;
+  user?: string;
+}
+
 export interface SkipFileRule {
   path: string;
   reason: string;
@@ -161,6 +171,29 @@ export declare function moduleStep(
   specifier: string,
   options?: Omit<TemplateModuleStepConfig, "kind" | "specifier">
 ): TemplateModuleStepConfig;
+export declare function schemaSql(
+  filePath: string,
+  options?: Omit<TemplateSqlFileStepConfig, "kind" | "path">
+): TemplateSqlFileStepConfig;
+export declare function seedCommand(
+  cmd: string,
+  options?: Omit<TemplateCommandStepConfig, "kind" | "cmd">
+): TemplateCommandStepConfig;
+export declare function seedModule(
+  specifier: string,
+  options?: Omit<TemplateModuleStepConfig, "kind" | "specifier">
+): TemplateModuleStepConfig;
+export declare function verifyCommand(
+  cmd: string,
+  options?: Omit<TemplateCommandStepConfig, "kind" | "cmd">
+): TemplateCommandStepConfig;
+export declare function verifyModule(
+  specifier: string,
+  options?: Omit<TemplateModuleStepConfig, "kind" | "specifier">
+): TemplateModuleStepConfig;
+export declare function seededDatabaseTemplate(
+  options?: SeededDatabaseTemplateOptions
+): DatabaseTemplateConfig;
 export declare function nodeToolchain(options?: NodeToolchainConfig): NodeToolchainConfig;
 export declare function goService(options: ServiceConfig["local"] & {
   command?: string;

package/lib/setup/index.mjs

@@ -56,6 +56,40 @@ export function moduleStep(specifier, options = {}) {
   };
 }
 
+export function schemaSql(filePath, options = {}) {
+  return sqlFileStep(filePath, options);
+}
+
+export function seedCommand(cmd, options = {}) {
+  return commandStep(cmd, options);
+}
+
+export function seedModule(specifier, options = {}) {
+  return moduleStep(specifier, options);
+}
+
+export function verifyCommand(cmd, options = {}) {
+  return commandStep(cmd, options);
+}
+
+export function verifyModule(specifier, options = {}) {
+  return moduleStep(specifier, options);
+}
+
+export function seededDatabaseTemplate(options = {}) {
+  const migrate = normalizeTemplateStepList(options.migrate);
+  const seed = normalizeTemplateStepList(options.seed);
+  const verify = normalizeTemplateStepList(options.verify);
+  const schema = normalizeSchemaStep(options.schema);
+
+  return {
+    inputs: Array.isArray(options.inputs) ? [...options.inputs] : undefined,
+    migrate: schema ? [schema, ...migrate] : migrate,
+    seed,
+    verify,
+  };
+}
+
 export function nodeToolchain(options = {}) {
   return {
     kind: "node",
@@ -218,6 +252,19 @@ function requiredNumber(value, label) {
   return value;
 }
 
+function normalizeTemplateStepList(value) {
+  if (value == null) return [];
+  return Array.isArray(value) ? [...value] : [value];
+}
+
+function normalizeSchemaStep(value) {
+  if (value == null) return null;
+  if (typeof value === "string") {
+    return sqlFileStep(value);
+  }
+  return value;
+}
+
 function envValue(name) {
   const env = getRuntimeEnv();
   const value = env?.rawEnv?.[name] || env?.[name];

package/lib/setup/index.test.mjs

@@ -1,5 +1,16 @@
 import { describe, expect, it } from "vitest";
-import { goService, nextService, nodeToolchain, tsxService } from "./index.mjs";
+import {
+  goService,
+  nextService,
+  nodeToolchain,
+  schemaSql,
+  seedCommand,
+  seedModule,
+  seededDatabaseTemplate,
+  tsxService,
+  verifyCommand,
+  verifyModule,
+} from "./index.mjs";
 
 describe("setup helpers", () => {
   it("emits plain next start commands without an exec prefix", () => {
@@ -31,4 +42,101 @@ describe("setup helpers", () => {
       install: "download",
     });
   });
+
+  it("emits semantic database template steps using the underlying step shapes", () => {
+    expect(schemaSql("db/schema.sql")).toEqual({
+      kind: "sql-file",
+      path: "db/schema.sql",
+      cwd: undefined,
+      inputs: undefined,
+    });
+    expect(seedCommand("npm run db:seed")).toEqual({
+      kind: "command",
+      cmd: "npm run db:seed",
+      cwd: undefined,
+      inputs: undefined,
+    });
+    expect(seedModule("scripts/seed.ts#seed")).toEqual({
+      kind: "module",
+      specifier: "scripts/seed.ts#seed",
+      cwd: undefined,
+      inputs: undefined,
+    });
+    expect(verifyCommand("npm run db:verify")).toEqual({
+      kind: "command",
+      cmd: "npm run db:verify",
+      cwd: undefined,
+      inputs: undefined,
+    });
+    expect(verifyModule("scripts/verify.ts#verify")).toEqual({
+      kind: "module",
+      specifier: "scripts/verify.ts#verify",
+      cwd: undefined,
+      inputs: undefined,
+    });
+  });
+
+  it("builds a seeded database template from schema, seed, and verify intents", () => {
+    expect(
+      seededDatabaseTemplate({
+        inputs: ["db/schema.sql", "scripts/seed.ts"],
+        schema: "db/schema.sql",
+        seed: seedCommand("npm run db:seed"),
+        verify: verifyModule("scripts/verify.ts#verifySeed"),
+      })
+    ).toEqual({
+      inputs: ["db/schema.sql", "scripts/seed.ts"],
+      migrate: [
+        {
+          kind: "sql-file",
+          path: "db/schema.sql",
+          cwd: undefined,
+          inputs: undefined,
+        },
+      ],
+      seed: [
+        {
+          kind: "command",
+          cmd: "npm run db:seed",
+          cwd: undefined,
+          inputs: undefined,
+        },
+      ],
+      verify: [
+        {
+          kind: "module",
+          specifier: "scripts/verify.ts#verifySeed",
+          cwd: undefined,
+          inputs: undefined,
+        },
+      ],
+    });
+  });
+
+  it("prepends schema before explicit migrate steps and normalizes singletons to arrays", () => {
+    expect(
+      seededDatabaseTemplate({
+        schema: schemaSql("db/schema.sql", { cwd: "db" }),
+        migrate: seedCommand("echo migrate"),
+      })
+    ).toEqual({
+      inputs: undefined,
+      migrate: [
+        {
+          kind: "sql-file",
+          path: "db/schema.sql",
+          cwd: "db",
+          inputs: undefined,
+        },
+        {
+          kind: "command",
+          cmd: "echo migrate",
+          cwd: undefined,
+          inputs: undefined,
+        },
+      ],
+      seed: [],
+      verify: [],
+    });
+  });
 });

package/lib/toolchains/index.mjs

@@ -84,12 +84,15 @@ export async function resolveConfiguredToolchain(config, options = {}) {
   }
 }
 
-export async function announceResolvedToolchain(config, resolvedToolchain) {
+export async function announceResolvedToolchain(config, resolvedToolchain, reporter = null) {
   if (!resolvedToolchain || announcedToolchains.has(config)) return;
   announcedToolchains.add(config);
+  if (reporter?.toolchainResolved) {
+    reporter.toolchainResolved(config, resolvedToolchain);
+    return;
+  }
   console.log(
-    `[testkit] ${config.runtimeLabel || config.name}:${config.name} toolchain ` +
-      `${resolvedToolchain.summary}`
+    `[testkit] ${config.runtimeLabel || config.name}:${config.name} toolchain ${resolvedToolchain.summary}`
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "description": "CLI for discovering and running local HTTP, DAL, and Playwright test suites",
   "type": "module",
   "types": "./lib/index.d.ts",
@@ -26,6 +26,12 @@
   "bin": {
     "testkit": "bin/testkit.mjs"
   },
+  "oclif": {
+    "bin": "testkit",
+    "commands": "./lib/cli/commands",
+    "default": "run",
+    "topicSeparator": " "
+  },
   "scripts": {
     "test": "vitest run",
     "test:unit": "vitest run lib",
@@ -42,9 +48,11 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "cac": "^6.7.14",
+    "@oclif/core": "^4.10.6",
     "esbuild": "^0.25.11",
-    "execa": "^9.5.0"
+    "execa": "^9.5.0",
+    "ink": "^7.0.1",
+    "react": "^19.2.5"
   },
   "engines": {
     "node": ">=18"