@elench/testkit 0.1.85 → 0.1.87

package/README.md

@@ -56,11 +56,11 @@ npx @elench/testkit destroy
 npx @elench/testkit cleanup
 
 # Inspect the latest run artifact
-npx @elench/testkit show
-npx @elench/testkit show __testkit__/health/health.int.testkit.ts
-npx @elench/testkit artifacts __testkit__/health/health.int.testkit.ts
-npx @elench/testkit logs __testkit__/health/health.int.testkit.ts
-npx @elench/testkit watch
+npx @elench/testkit inspect
+npx @elench/testkit inspect --file __testkit__/health/health.int.testkit.ts
+npx @elench/testkit inspect --pane artifacts --file __testkit__/health/health.int.testkit.ts
+npx @elench/testkit inspect --pane logs --file __testkit__/health/health.int.testkit.ts
+npx @elench/testkit inspect --live
 
 # Automatic regression intelligence
 # Configure testkit.regressions.json and testkit classifies new vs known regressions automatically during runs
@@ -72,8 +72,7 @@ npx @elench/testkit db snapshot capture --service api --output scripts/testkit/s
 `testkit` now keeps the default terminal output intentionally short: one line
 per completed file, a concise failure block, and a final summary. Service logs,
 captured runtime output, emitted artifacts, and user-visible LLM responses are
-persisted under `.testkit/results/` and inspected on demand with `show`,
-`artifacts`, `logs`, or `watch`.
+persisted under `.testkit/results/` and inspected on demand with `inspect`.
 
 `testkit discover` also maintains a small durable per-test history index at
 `.testkit/history/tests.json`. The index tracks first/last seen timestamps,
@@ -423,15 +422,49 @@ const suite = defineHttpSuite({ profile: "defaultAuth" }, ({ actor, actors, req
 DAL suites:
 
 ```ts
-import { defineDalSuite } from "@elench/testkit";
+import { defineDalFixtures, defineDalSuite } from "@elench/testkit";
+
+const fixtures = defineDalFixtures(({ db, fixtureScope }) => ({
+  widget() {
+    return fixtureScope.seed("widget", "primary", { name: "Primary Widget" }, () => {
+      const widgetId = fixtureScope.id("widget");
+      db.exec(`
+        INSERT INTO widgets (id, name)
+        VALUES ('${widgetId}', 'Primary Widget')
+      `);
+      return { widgetId };
+    });
+  },
+}));
 
-const suite = defineDalSuite(({ db }) => {
-  db.query("select 1");
+const suite = defineDalSuite({ fixtures }, ({ db, fixtureScope, fixtures }) => {
+  const widget = fixtures.widget();
+  db.query(`select id from widgets where id = '${widget.widgetId}'`);
+  fixtureScope.records();
 });
 
 export default suite;
 ```
 
+`defineDalFixtures(...)` is the package-owned DAL seeding model. It gives every
+suite a deterministic `fixtureScope` with:
+
+- `fixtureScope.id(label)` / `uuid(label)`
+- `fixtureScope.slug(label)`
+- `fixtureScope.email(label)`
+- `fixtureScope.string(label, options)`
+- `fixtureScope.token(label)`
+- `fixtureScope.seed(kind, key, signature, create)`
+- `fixtureScope.records()`
+
+`testkit` enforces strict fixture behavior:
+
+- one logical fixture per `kind + key`
+- identical reseeds reuse the same seeded value
+- conflicting reseeds fail immediately
+- dependency cycles fail immediately
+- seeded fixture records are persisted as a `testkit.dal-fixtures` artifact
+
 Scenario suites:
 
 ```ts

package/lib/cli/commands/inspect.mjs

@@ -0,0 +1,124 @@
+import React, { createElement } from "react";
+import { Command, Flags } from "@oclif/core";
+import { render } from "ink";
+import { sharedFlags } from "../command-helpers.mjs";
+import { loadCurrentRunArtifact, loadLatestRunArtifact, resolveFileSubject } from "../viewer.mjs";
+import { createInspectState } from "../tui/inspect-state.mjs";
+import { InspectApp } from "../tui/inspect-app.mjs";
+import { buildInspectPaneContent } from "../tui/detail-pane.mjs";
+import { hydrateInspectStateFromArtifact } from "../tui/inspect-artifact-adapter.mjs";
+
+export default class InspectCommand extends Command {
+  static summary = "Inspect the latest run or a live run in one unified interface";
+
+  static enableJsonFlag = true;
+
+  static flags = {
+    ...sharedFlags,
+    file: Flags.string({
+      description: "File path to inspect; defaults to the first failed file",
+    }),
+    live: Flags.boolean({
+      description: "Inspect the live run artifact instead of the latest completed run",
+      default: false,
+    }),
+    pane: Flags.string({
+      description: "Initial pane",
+      options: ["detail", "artifacts", "logs", "setup"],
+      default: "detail",
+    }),
+    "log-tail": Flags.integer({
+      description: "Number of backend log lines to include in detail/log panes",
+      default: 12,
+    }),
+  };
+
+  async run() {
+    const { flags } = await this.parse(InspectCommand);
+    const productDir = flags.dir || process.cwd();
+    const interactive = process.stdout.isTTY && !this.jsonEnabled();
+
+    if (!interactive) {
+      const artifact = loadArtifact(productDir, flags.live);
+      const inspectState = createInspectState({ dataSource: flags.live ? "live" : "artifact" });
+      hydrateInspectStateFromArtifact(inspectState, artifact);
+      inspectState.setPaneMode(flags.pane);
+      applyInitialSelection(inspectState, artifact, flags.file || null, flags.service || null);
+      const snapshot = inspectState.getSnapshot();
+      const pane = buildInspectPaneContent({
+        productDir,
+        snapshot,
+        paneMode: flags.pane,
+        logTail: flags["log-tail"],
+      });
+      const payload = {
+        source: flags.live ? "live" : "latest",
+        pane: flags.pane,
+        selection: snapshot.selectedEntry,
+        lines: pane.lines,
+        data: pane.data,
+      };
+      if (!this.jsonEnabled()) {
+        for (const line of pane.lines) {
+          this.log(line);
+        }
+      }
+      return payload;
+    }
+
+    const artifact = loadArtifact(productDir, flags.live);
+    const inspectState = createInspectState({ dataSource: flags.live ? "live" : "artifact" });
+    hydrateInspectStateFromArtifact(inspectState, artifact);
+    inspectState.setPaneMode(flags.pane);
+    applyInitialSelection(inspectState, artifact, flags.file || null, flags.service || null);
+
+    const app = render(
+      createElement(InspectApp, {
+        inspectState,
+        stdout: process.stdout,
+        productDir,
+      }),
+      { stdout: process.stdout, exitOnCtrlC: false }
+    );
+
+    let interval = null;
+    if (flags.live) {
+      interval = setInterval(() => {
+        try {
+          const liveArtifact = loadCurrentRunArtifact(productDir);
+          hydrateInspectStateFromArtifact(inspectState, liveArtifact);
+          inspectState.setPaneMode(flags.pane);
+          applyInitialSelection(inspectState, liveArtifact, flags.file || null, flags.service || null);
+        } catch {
+          // Ignore polling misses while the live artifact is being rewritten.
+        }
+      }, 1000);
+    }
+
+    try {
+      await app.waitUntilExit();
+    } finally {
+      if (interval) clearInterval(interval);
+    }
+
+    return {
+      source: flags.live ? "live" : "latest",
+      pane: flags.pane,
+    };
+  }
+}
+
+function loadArtifact(productDir, live) {
+  return live ? loadCurrentRunArtifact(productDir) : loadLatestRunArtifact(productDir);
+}
+
+function applyInitialSelection(inspectState, artifact, fileSelector, serviceFilter) {
+  if (fileSelector) {
+    const subject = resolveFileSubject(artifact, fileSelector, serviceFilter || null);
+    inspectState.revealFile(subject.service.name, subject.file.path);
+    return;
+  }
+  if (serviceFilter) {
+    inspectState.revealService(serviceFilter);
+  }
+}

package/lib/cli/entrypoint.mjs

@@ -1,13 +1,10 @@
 export function normalizeCliArgs(argv) {
   const topLevelCommands = new Set([
     "run",
+    "inspect",
     "status",
     "destroy",
     "cleanup",
-    "show",
-    "logs",
-    "artifacts",
-    "watch",
     "discover",
     "typecheck",
     "doctor",
@@ -40,6 +37,7 @@ export function normalizeCliArgs(argv) {
     "--log-tail",
     "--provider",
     "--message",
+    "--pane",
   ]);
   const positionals = findPositionals(argv, valueFlags);
   const firstPositional = positionals[0] || null;

package/lib/cli/presentation/tree-reporter.mjs

@@ -1,21 +1,27 @@
 import React, { createElement } from "react";
 import { render } from "ink";
-import { createRunSessionState } from "../tui/run-session-state.mjs";
-import { RunSessionApp } from "../tui/run-session-app.mjs";
+import { createInspectState } from "../tui/inspect-state.mjs";
+import { InspectApp } from "../tui/inspect-app.mjs";
+import {
+  applyReporterPlans,
+  applyReporterRunSummary,
+  applyReporterTaskFinished,
+  applyReporterTaskStarted,
+} from "../tui/inspect-live-adapter.mjs";
 import { suiteSelectionType } from "../../runner/suite-selection.mjs";
 import { startHostedInvestigation } from "../agents/investigate.mjs";
 import { createInvestigationInterpreter } from "../agents/investigation-interpreter.mjs";
 import { writeInvestigationLog } from "../agents/investigation-log.mjs";
 
 export function createTreeReporter({ stdout = process.stdout, stderr = process.stderr, productDir } = {}) {
-  const sessionState = createRunSessionState();
+  const inspectState = createInspectState({ dataSource: "live" });
   let activeAgentSession = null;
   let activeInterpreter = null;
   let investigationToken = 0;
 
   const app = render(
-    createElement(RunSessionApp, {
-      sessionState,
+    createElement(InspectApp, {
+      inspectState,
       stdout,
       productDir,
       onInvestigate: startInvestigation,
@@ -31,36 +37,36 @@ export function createTreeReporter({ stdout = process.stdout, stderr = process.s
     outputMode: "compact",
 
     setServicePlans(plans) {
-      sessionState.initFromPlans(plans);
+      applyReporterPlans(inspectState, plans);
     },
 
     setTotalFileCount(count) {
-      sessionState.setTotalFileCount(count);
+      inspectState.setTotalFileCount(count);
     },
 
     setRegressionCatalog(document) {
-      sessionState.setRegressionCatalog(document);
+      inspectState.setRegressionCatalog(document);
     },
 
     serviceSkipped(config, reason) {
-      sessionState.markServiceSkipped(config.name, reason);
+      inspectState.markServiceSkipped(config.name, reason);
     },
 
     plannedSkip(entry) {
-      sessionState.markPlannedSkip(entry);
+      inspectState.markPlannedSkip(entry);
     },
 
     taskStarted(task, _config) {
       const suiteKey = `${task.displayType || suiteSelectionType(task.type, task.framework)}:${task.suiteName}`;
-      sessionState.markFileRunning(task.serviceName, suiteKey, task.file);
+      applyReporterTaskStarted(inspectState, task, suiteKey);
     },
 
     taskFinished(task, outcome) {
-      sessionState.markFileFinished(task, outcome);
+      applyReporterTaskFinished(inspectState, task, outcome);
     },
 
     runtimeError(task, message) {
-      sessionState.markRuntimeError(task, message);
+      inspectState.markRuntimeError(task, message);
     },
 
     setupOperationFinished(_operation) {
@@ -68,7 +74,7 @@ export function createTreeReporter({ stdout = process.stdout, stderr = process.s
     },
 
     phaseStarted(label) {
-      sessionState.setPhase(label);
+      inspectState.setPhase(label);
     },
 
     toolchainResolved() {},
@@ -78,7 +84,7 @@ export function createTreeReporter({ stdout = process.stdout, stderr = process.s
     telemetry() {},
 
     runSummary(results, durationMs, regressionReport) {
-      sessionState.finish(results, durationMs, regressionReport);
+      applyReporterRunSummary(inspectState, results, durationMs, regressionReport);
     },
 
     error(message) {
@@ -93,19 +99,19 @@ export function createTreeReporter({ stdout = process.stdout, stderr = process.s
   };
 
   async function startInvestigation({ provider = "auto", userMessage } = {}) {
-    const snapshot = sessionState.getSnapshot();
+    const snapshot = inspectState.getSnapshot();
     if (!snapshot.selectedFailure) {
-      sessionState.setNotice("No failed file is selected for investigation.");
+      inspectState.setNotice("No failed file is selected for investigation.");
       return;
     }
     if (activeAgentSession) {
-      sessionState.setNotice("An investigation is already running.");
+      inspectState.setNotice("An investigation is already running.");
       return;
     }
 
     const token = ++investigationToken;
     let finalDelivered = false;
-    sessionState.beginInvestigation({ provider, userMessage });
+    inspectState.beginInvestigation({ provider, userMessage });
 
     try {
       activeInterpreter = createInvestigationInterpreter();
@@ -119,7 +125,7 @@ export function createTreeReporter({ stdout = process.stdout, stderr = process.s
           if (token !== investigationToken) return;
           if (event.type === "final") finalDelivered = true;
           const presentation = activeInterpreter?.consumeProviderEvent(event) || null;
-          sessionState.recordInvestigationProgress(event, presentation);
+          inspectState.recordInvestigationProgress(event, presentation);
         },
       });
       const result = await activeAgentSession.completion;
@@ -128,21 +134,21 @@ export function createTreeReporter({ stdout = process.stdout, stderr = process.s
       if (result.finalText && !finalDelivered) {
         const finalEvent = { type: "final", text: result.finalText };
         const presentation = activeInterpreter?.consumeProviderEvent(finalEvent) || null;
-        sessionState.recordInvestigationProgress(finalEvent, presentation);
+        inspectState.recordInvestigationProgress(finalEvent, presentation);
       }
       if (result.cancelled) {
-        sessionState.cancelAgentSession("Cancelled investigation.");
+        inspectState.cancelAgentSession("Cancelled investigation.");
         persistInvestigationLog();
         activeInterpreter = null;
         return;
       }
       if (result.exitCode !== 0 && !result.finalText) {
-        sessionState.failAgentSession(result.stderr || `Agent exited with code ${result.exitCode}`);
+        inspectState.failAgentSession(result.stderr || `Agent exited with code ${result.exitCode}`);
         persistInvestigationLog();
         activeInterpreter = null;
         return;
       }
-      sessionState.completeAgentSession({
+      inspectState.completeAgentSession({
         finalText: result.finalText,
         exitCode: result.exitCode,
       });
@@ -151,7 +157,7 @@ export function createTreeReporter({ stdout = process.stdout, stderr = process.s
     } catch (error) {
       if (token !== investigationToken) return;
       activeAgentSession = null;
-      sessionState.failAgentSession(error);
+      inspectState.failAgentSession(error);
       persistInvestigationLog();
       activeInterpreter = null;
     }
@@ -159,13 +165,13 @@ export function createTreeReporter({ stdout = process.stdout, stderr = process.s
 
   function cancelInvestigation() {
     if (!activeAgentSession) {
-      sessionState.returnToSummary();
+      inspectState.returnToSummary();
       return;
     }
     investigationToken += 1;
     activeAgentSession.cancel();
     activeAgentSession = null;
-    sessionState.cancelAgentSession("Cancelled investigation.");
+    inspectState.cancelAgentSession("Cancelled investigation.");
     persistInvestigationLog();
     activeInterpreter = null;
   }
@@ -180,7 +186,7 @@ export function createTreeReporter({ stdout = process.stdout, stderr = process.s
   }
 
   function persistInvestigationLog() {
-    const snapshot = sessionState.getSnapshot();
+    const snapshot = inspectState.getSnapshot();
     if (!snapshot.selectedFailure || !snapshot.agentSession) return;
     writeInvestigationLog({
       productDir,

package/lib/cli/tui/detail-pane.mjs

@@ -0,0 +1,161 @@
+import path from "path";
+import {
+  collectArtifactEntries,
+  formatArtifactPreview,
+  formatFileDetail,
+  getServiceLogRefs,
+  getSetupOperationsForService,
+  loadCurrentRunArtifact,
+  resolveFileSubject,
+} from "../viewer.mjs";
+import { formatDuration } from "../../runner/formatting.mjs";
+import { readLogTail } from "../../runner/logs.mjs";
+
+export function buildInspectPaneContent({ productDir, snapshot, paneMode = "detail", logTail = 12 } = {}) {
+  const selectedEntry = snapshot.selectedEntry || null;
+  if (!selectedEntry) {
+    return { title: "Selection", lines: ["No entry selected."], data: null };
+  }
+
+  const runArtifact = resolveArtifact(productDir, snapshot);
+  const subject = resolveSubject(runArtifact, selectedEntry);
+
+  if (paneMode === "artifacts") {
+    return buildArtifactsPane(productDir, runArtifact, selectedEntry, subject);
+  }
+  if (paneMode === "logs") {
+    return buildLogsPane(productDir, runArtifact, selectedEntry, logTail);
+  }
+  if (paneMode === "setup") {
+    return buildSetupPane(productDir, runArtifact, selectedEntry);
+  }
+  return buildDetailPane(productDir, runArtifact, selectedEntry, subject, logTail);
+}
+
+function buildDetailPane(productDir, runArtifact, entry, subject, logTail) {
+  if (subject && runArtifact) {
+    return {
+      title: "Detail",
+      lines: formatFileDetail(productDir, runArtifact, subject, { logTail }),
+      data: subject,
+    };
+  }
+
+  return {
+    title: "Detail",
+    lines: formatAggregateDetail(entry),
+    data: entry,
+  };
+}
+
+function buildArtifactsPane(productDir, runArtifact, entry, subject) {
+  if (!runArtifact || !subject) {
+    return {
+      title: "Artifacts",
+      lines: ["Artifacts are available for file selections from a persisted run artifact."],
+      data: [],
+    };
+  }
+
+  const entries = collectArtifactEntries(productDir, runArtifact, subject.file.path, subject.service.name).map((item) => ({
+    service: item.service.name,
+    suite: `${item.suite.type}:${item.suite.name}`,
+    file: item.file.path,
+    name: item.artifactRef.name,
+    kind: item.artifactRef.kind,
+    summary: item.artifactRef.summary,
+    path: item.artifactRef.path,
+    preview: formatArtifactPreview(item.payload, 6),
+  }));
+
+  if (entries.length === 0) {
+    return { title: "Artifacts", lines: ["No artifacts were persisted for the selected file."], data: [] };
+  }
+
+  const lines = [];
+  for (const item of entries) {
+    lines.push(`${item.name}${item.kind ? ` [${item.kind}]` : ""}`);
+    if (item.summary) lines.push(`  ${item.summary}`);
+    for (const line of item.preview) lines.push(`  ${line}`);
+    lines.push(`  ${item.path}`);
+  }
+  return { title: "Artifacts", lines, data: entries };
+}
+
+function buildLogsPane(productDir, runArtifact, entry, tail) {
+  if (!runArtifact) {
+    return { title: "Logs", lines: ["Backend logs are available only from persisted run artifacts."], data: [] };
+  }
+  const serviceName = entry.serviceName;
+  const logs = getServiceLogRefs(runArtifact, serviceName).map((item) => ({
+    ...item,
+    lines: readLogTail(path.join(productDir, item.path), tail),
+  }));
+  if (logs.length === 0) {
+    return { title: "Logs", lines: ["No backend logs were recorded for the selected service."], data: [] };
+  }
+  const lines = [];
+  for (const item of logs) {
+    lines.push(item.runtimeLabel);
+    lines.push(`  ${item.path}`);
+    for (const line of item.lines) lines.push(`  ${line}`);
+  }
+  return { title: "Logs", lines, data: logs };
+}
+
+function buildSetupPane(productDir, runArtifact, entry) {
+  if (!runArtifact) {
+    return { title: "Setup", lines: ["Setup operations are available only from persisted run artifacts."], data: [] };
+  }
+  const operations = getSetupOperationsForService(runArtifact, entry.serviceName);
+  if (operations.length === 0) {
+    return { title: "Setup", lines: ["No setup operations were recorded for the selected service."], data: [] };
+  }
+  const lines = [];
+  for (const operation of operations) {
+    const duration = operation.durationMs == null ? "" : ` ${formatDuration(operation.durationMs)}`;
+    const summary = operation.summary ? ` ${operation.summary}` : "";
+    lines.push(`${operation.status} ${operation.stage}${duration}${summary}`);
+    if (operation.error) lines.push(`  ${operation.error}`);
+    if (operation.logRef?.path) lines.push(`  ${operation.logRef.path}`);
+  }
+  return { title: "Setup", lines, data: operations };
+}
+
+function resolveArtifact(productDir, snapshot) {
+  if (snapshot.runArtifact) return snapshot.runArtifact;
+  try {
+    return loadCurrentRunArtifact(productDir);
+  } catch {
+    return null;
+  }
+}
+
+function resolveSubject(runArtifact, entry) {
+  if (!runArtifact || !entry || entry.kind !== "file") return null;
+  try {
+    return resolveFileSubject(runArtifact, entry.filePath, entry.serviceName);
+  } catch {
+    return null;
+  }
+}
+
+function formatAggregateDetail(entry) {
+  const lines = [`Kind: ${entry.kind}`];
+  if (entry.serviceName) lines.push(`Service: ${entry.serviceName}`);
+  if (entry.type) lines.push(`Type: ${entry.type}`);
+  if (entry.suiteName) lines.push(`Suite: ${entry.suiteName}`);
+  if (entry.filePath) lines.push(`File: ${entry.filePath}`);
+  if (entry.status) lines.push(`Status: ${entry.status}`);
+  if (entry.summary) {
+    lines.push(
+      `Files: ${entry.summary.total} total · ${entry.summary.passed} passed · ${entry.summary.failed} failed · ${entry.summary.skipped} skipped · ${entry.summary.notRun} not run`
+    );
+    if (entry.summary.durationMs > 0) {
+      lines.push(`Duration: ${formatDuration(entry.summary.durationMs)}`);
+    }
+  }
+  if (entry.skipReason) lines.push(`Skip reason: ${entry.skipReason}`);
+  if (entry.error) lines.push(`Error: ${entry.error}`);
+  return lines;
+}

package/lib/cli/tui/filter-bar.mjs

@@ -0,0 +1,12 @@
+import React, { createElement } from "react";
+import { Text } from "ink";
+import { bold, dim } from "../presentation/colors.mjs";
+
+export function FilterBar({ filter } = {}) {
+  if (!filter?.active) return null;
+  return createElement(
+    Text,
+    null,
+    `${bold("/")}${filter.query}${dim(`  ${filter.count} ${filter.count === 1 ? "match" : "matches"}`)}`
+  );
+}