@elench/testkit 0.1.88 → 0.1.90

package/README.md

@@ -65,8 +65,8 @@ npx @elench/testkit cleanup
 
 # Inspect the latest run artifact through the assistant
 npx @elench/testkit assistant --message '/inspect "__testkit__/health/health.int.testkit.ts"'
-npx @elench/testkit assistant --pane artifacts --message '/inspect "__testkit__/health/health.int.testkit.ts"'
-npx @elench/testkit assistant --pane logs --message '/inspect "__testkit__/health/health.int.testkit.ts"'
+npx @elench/testkit assistant --message '/artifacts "__testkit__/health/health.int.testkit.ts"'
+npx @elench/testkit assistant --message "/logs api"
 
 # Automatic regression intelligence
 # Configure testkit.regressions.json and testkit classifies new vs known regressions automatically during runs
@@ -75,12 +75,23 @@ npx @elench/testkit assistant --pane logs --message '/inspect "__testkit__/healt
 npx @elench/testkit db snapshot capture --service api --output scripts/testkit/schema-baseline.sql
 ```
 
-`testkit` is now assistant-first in an interactive TTY. The assistant keeps a
-chat transcript and a live workbench around the current run artifact, selected
-file, logs, setup operations, and emitted artifacts. Batch `run` output stays
-intentionally short: one line per completed file, a concise failure block, and
-a final summary. Service logs, captured runtime output, emitted artifacts, and
-assistant-visible run state are persisted under `.testkit/results/`.
+`testkit` is now assistant-first in an interactive TTY, but the interactive
+assistant is provider-native. `testkit` boots a real Codex CLI or Claude CLI
+session, writes local context files under `.testkit/assistant/`, places a
+repo-local `testkit` wrapper on the provider `PATH`, and then hands the
+terminal to the provider. That means the cursor, transcript, approvals, and
+conversation UX come from the provider itself, while `testkit` contributes
+repo context, durable run artifacts, focused detail/log/artifact/setup text
+files, and a stable local command surface.
+
+The non-interactive `assistant --message ...` mode remains available for one
+hosted turn at a time. It is useful in scripts and tests, but it is not the
+primary interactive UX.
+
+Batch `run` output stays intentionally short: one line per completed file, a
+concise failure block, and a final summary. Service logs, captured runtime
+output, emitted artifacts, and assistant-visible run state are persisted under
+`.testkit/results/`.
 
 `testkit discover` also maintains a small durable per-test history index at
 `.testkit/history/tests.json`. The index tracks first/last seen timestamps,

package/lib/cli/agents/index.mjs

@@ -20,7 +20,22 @@ export function resolvePreferredProvider(preferred = null, env = process.env) {
   throw new Error("Neither codex nor claude was found on PATH");
 }
 
+export function resolveProviderBinary(provider, env = process.env) {
+  const override = env?.[provider === "codex" ? "TESTKIT_CODEX_BIN" : "TESTKIT_CLAUDE_BIN"];
+  if (override) return override;
+  return provider;
+}
+
 export function isProviderInstalled(provider, env = process.env) {
+  const override = env?.[provider === "codex" ? "TESTKIT_CODEX_BIN" : "TESTKIT_CLAUDE_BIN"];
+  if (override) {
+    try {
+      fs.accessSync(override, fs.constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  }
   const pathValue = env.PATH || "";
   const candidates = pathValue.split(path.delimiter).filter(Boolean);
   const fileNames =
@@ -41,24 +56,48 @@ export function isProviderInstalled(provider, env = process.env) {
   return false;
 }
 
-export function startAgentSession({ provider = "auto", cwd, prompt, onEvent, purpose = "investigate" } = {}) {
-  const resolvedProvider = resolvePreferredProvider(provider);
+export function startAgentSession({
+  provider = "auto",
+  cwd,
+  prompt,
+  onEvent,
+  purpose = "assistant",
+  env = process.env,
+} = {}) {
+  const resolvedProvider = resolvePreferredProvider(provider, env);
+  const command = resolveProviderBinary(resolvedProvider, env);
   if (resolvedProvider === "claude") {
-    return startClaudeHostedSession({ cwd, prompt, onEvent, purpose });
+    return startClaudeHostedSession({ command, cwd, prompt, onEvent, purpose });
   }
-  return startCodexHostedSession({ cwd, prompt, onEvent, purpose });
+  return startCodexHostedSession({ command, cwd, prompt, onEvent, purpose });
 }
 
-export function startInteractiveAgentHandoff({ provider = "auto", cwd, prompt } = {}) {
-  const resolvedProvider = resolvePreferredProvider(provider);
-  const command = resolvedProvider;
-  const args = prompt ? [prompt] : [];
+export function startInteractiveProviderSession({
+  provider = "auto",
+  cwd,
+  prompt,
+  env = process.env,
+} = {}) {
+  const resolvedProvider = resolvePreferredProvider(provider, env);
+  const command = resolveProviderBinary(resolvedProvider, env);
+  const args = buildInteractiveProviderArgs(resolvedProvider, prompt);
   const child = spawn(command, args, {
     cwd,
+    env,
     stdio: "inherit",
   });
   return new Promise((resolve, reject) => {
     child.on("error", reject);
-    child.on("close", (code) => resolve({ provider: resolvedProvider, exitCode: code ?? 0 }));
+    child.on("close", (code) =>
+      resolve({
+        provider: resolvedProvider,
+        exitCode: code ?? 0,
+      })
+    );
   });
 }
+
+export function buildInteractiveProviderArgs(provider, prompt = null) {
+  if (!prompt) return [];
+  return [prompt];
+}

package/lib/cli/agents/providers/claude.mjs

@@ -7,7 +7,7 @@ import {
   extractTextFragments,
 } from "./shared.mjs";
 
-export function startClaudeHostedSession({ cwd, prompt, onEvent, purpose = "investigate" } = {}) {
+export function startClaudeHostedSession({ command = "claude", cwd, prompt, onEvent, purpose = "assistant" } = {}) {
   const args = [
     "-p",
     "--output-format",
@@ -15,13 +15,13 @@ export function startClaudeHostedSession({ cwd, prompt, onEvent, purpose = "inve
     "--include-partial-messages",
   ];
 
-  if (purpose === "investigate" || purpose === "assistant") {
+  if (purpose === "assistant") {
     args.push("--permission-mode", "plan");
   }
 
   args.push(prompt);
 
-  const child = execa("claude", args, {
+  const child = execa(command, args, {
     cwd,
     stdout: "pipe",
     stderr: "pipe",

package/lib/cli/agents/providers/codex.mjs

@@ -11,18 +11,18 @@ import {
   readTextFileIfPresent,
 } from "./shared.mjs";
 
-export function startCodexHostedSession({ cwd, prompt, onEvent, purpose = "investigate" } = {}) {
+export function startCodexHostedSession({ command = "codex", cwd, prompt, onEvent, purpose = "assistant" } = {}) {
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-codex-"));
   const outputFile = path.join(tempDir, "final-message.txt");
   const args = ["exec", "--json", "-o", outputFile];
 
-  if (purpose === "investigate" || purpose === "assistant") {
+  if (purpose === "assistant") {
     args.push("-s", "read-only");
   }
 
   args.push(prompt);
 
-  const child = execa("codex", args, {
+  const child = execa(command, args, {
     cwd,
     stdout: "pipe",
     stderr: "pipe",

package/lib/cli/assistant/bootstrap.mjs

@@ -0,0 +1,248 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { readContextContent } from "../context-resources.mjs";
+
+export function prepareAssistantBootstrap({
+  productDir,
+  inspectState,
+  initialPrompt = null,
+} = {}) {
+  const contextDir = path.join(productDir, ".testkit", "assistant");
+  const binDir = path.join(contextDir, "bin");
+  fs.mkdirSync(binDir, { recursive: true });
+
+  const snapshot = inspectState?.getSnapshot?.() || {};
+  const commandLogPath = path.join(contextDir, "commands.jsonl");
+  const contextPath = path.join(contextDir, "context.md");
+  const summaryPath = path.join(contextDir, "latest-run-summary.json");
+  const selectionPath = path.join(contextDir, "current-selection.json");
+  const commandsPath = path.join(contextDir, "commands.md");
+  const focusedDetailPath = path.join(contextDir, "focused-detail.txt");
+  const focusedLogsPath = path.join(contextDir, "focused-logs.txt");
+  const focusedArtifactsPath = path.join(contextDir, "focused-artifacts.txt");
+  const focusedSetupPath = path.join(contextDir, "focused-setup.txt");
+  const wrapperPath = path.join(binDir, "testkit");
+
+  const detailContent = readContextContent({ productDir, snapshot, mode: "detail", logTail: 12 });
+  const logsContent = readContextContent({ productDir, snapshot, mode: "logs", logTail: 12 });
+  const artifactsContent = readContextContent({ productDir, snapshot, mode: "artifacts", logTail: 12 });
+  const setupContent = readContextContent({ productDir, snapshot, mode: "setup", logTail: 12 });
+
+  writeJson(summaryPath, {
+    summaryRows: snapshot.summaryData?.rows || [],
+    phase: snapshot.phase || null,
+    artifactPath: path.join(productDir, ".testkit", "results", "latest.json"),
+  });
+  writeJson(selectionPath, serializeSelection(snapshot.selectedEntry || null));
+  fs.writeFileSync(commandsPath, buildCommandsMarkdown(), "utf8");
+  fs.writeFileSync(focusedDetailPath, `${detailContent.lines.join("\n")}\n`, "utf8");
+  fs.writeFileSync(focusedLogsPath, `${logsContent.lines.join("\n")}\n`, "utf8");
+  fs.writeFileSync(focusedArtifactsPath, `${artifactsContent.lines.join("\n")}\n`, "utf8");
+  fs.writeFileSync(focusedSetupPath, `${setupContent.lines.join("\n")}\n`, "utf8");
+  fs.writeFileSync(contextPath, buildContextMarkdown(productDir, snapshot, {
+    contextPath,
+    summaryPath,
+    selectionPath,
+    commandsPath,
+    commandLogPath,
+    focusedDetailPath,
+    focusedLogsPath,
+    focusedArtifactsPath,
+    focusedSetupPath,
+  }), "utf8");
+  fs.writeFileSync(wrapperPath, buildWrapperScript({
+    cliPath: resolveCliPath(),
+    commandLogPath,
+  }), { encoding: "utf8", mode: 0o755 });
+  fs.chmodSync(wrapperPath, 0o755);
+
+  return {
+    contextDir,
+    contextPath,
+    summaryPath,
+    selectionPath,
+    commandsPath,
+    commandLogPath,
+    focusedDetailPath,
+    focusedLogsPath,
+    focusedArtifactsPath,
+    focusedSetupPath,
+    binDir,
+    env: {
+      TESTKIT_ASSISTANT_CONTEXT_DIR: contextDir,
+      TESTKIT_ASSISTANT_CONTEXT_PATH: contextPath,
+      TESTKIT_ASSISTANT_COMMAND_LOG: commandLogPath,
+      TESTKIT_NO_ASSISTANT_DEFAULT: "1",
+    },
+    prompt: buildStartupPrompt({ initialPrompt }),
+  };
+}
+
+function resolveCliPath() {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "bin", "testkit.mjs");
+}
+
+function buildWrapperScript({ cliPath, commandLogPath } = {}) {
+  return `#!/usr/bin/env node
+import { appendFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+import { spawnSync } from "child_process";
+
+const CLI_PATH = ${JSON.stringify(cliPath)};
+const COMMAND_LOG = ${JSON.stringify(commandLogPath)};
+const argv = process.argv.slice(2);
+const commandId = \`cmd-\${Date.now()}-\${Math.random().toString(36).slice(2, 10)}\`;
+
+function log(event) {
+  try {
+    mkdirSync(dirname(COMMAND_LOG), { recursive: true });
+    appendFileSync(COMMAND_LOG, JSON.stringify({
+      timestamp: new Date().toISOString(),
+      ...event,
+    }) + "\\n");
+  } catch {
+    // Ignore assistant command log failures.
+  }
+}
+
+log({
+  type: "command_start",
+  command: "testkit",
+  commandId,
+  cwd: process.cwd(),
+  argv,
+});
+
+const result = spawnSync(process.execPath, [CLI_PATH, ...argv], {
+  cwd: process.cwd(),
+  env: {
+    ...process.env,
+    TESTKIT_NO_ASSISTANT_DEFAULT: "1",
+    TESTKIT_ASSISTANT_COMMAND_ID: commandId,
+    TESTKIT_ASSISTANT_COMMAND_LOG: COMMAND_LOG,
+  },
+  stdio: "inherit",
+});
+
+log({
+  type: "command_exit",
+  command: "testkit",
+  commandId,
+  cwd: process.cwd(),
+  argv,
+  code: result.status ?? null,
+  signal: result.signal ?? null,
+});
+
+if (result.error) {
+  throw result.error;
+}
+process.exit(result.status ?? 0);
+`;
+}
+
+function buildStartupPrompt({ initialPrompt } = {}) {
+  if (initialPrompt) {
+    return [
+      "You are operating inside a testkit-managed repository.",
+      "Read .testkit/assistant/context.md before taking action.",
+      "Use the local `testkit` command on PATH for runs, discovery, status, and doctor checks.",
+      `User request: ${String(initialPrompt).trim()}`,
+    ].join("\n");
+  }
+
+  return [
+    "You are operating inside a testkit-managed repository.",
+    "Read .testkit/assistant/context.md before taking action.",
+    "Use the local `testkit` command on PATH for runs, discovery, status, and doctor checks.",
+    "Respond with a brief readiness note and wait for the user's next request.",
+  ].join("\n");
+}
+
+function buildContextMarkdown(productDir, snapshot, paths) {
+  const rows = snapshot.summaryData?.rows || [];
+  const selection = snapshot.selectedEntry;
+  const lines = [
+    "# Testkit Assistant Context",
+    "",
+    `- Product directory: ${productDir}`,
+    `- Context file: ${paths.contextPath}`,
+    `- Run summary JSON: ${paths.summaryPath}`,
+    `- Current selection JSON: ${paths.selectionPath}`,
+    `- Command reference: ${paths.commandsPath}`,
+    `- Command log: ${paths.commandLogPath}`,
+    `- Focused detail: ${paths.focusedDetailPath}`,
+    `- Focused logs: ${paths.focusedLogsPath}`,
+    `- Focused artifacts: ${paths.focusedArtifactsPath}`,
+    `- Focused setup: ${paths.focusedSetupPath}`,
+    "",
+    "## Latest run summary",
+  ];
+
+  if (rows.length === 0) {
+    lines.push("- No persisted run artifact is currently loaded.");
+  } else {
+    for (const [label, value] of rows) {
+      lines.push(`- ${label}: ${value}`);
+    }
+  }
+
+  lines.push("", "## Current selection");
+  if (!selection) {
+    lines.push("- No focused file or service.");
+  } else {
+    lines.push(`- Kind: ${selection.kind}`);
+    if (selection.serviceName) lines.push(`- Service: ${selection.serviceName}`);
+    if (selection.type) lines.push(`- Type: ${selection.type}`);
+    if (selection.suiteName) lines.push(`- Suite: ${selection.suiteName}`);
+    if (selection.filePath) lines.push(`- File: ${selection.filePath}`);
+    if (selection.status) lines.push(`- Status: ${selection.status}`);
+  }
+
+  lines.push(
+    "",
+    "## Guidance",
+    "- Use `testkit run --dir . --type <type>` to run suites.",
+    "- Use `testkit status --dir .` to inspect local state.",
+    "- Use `testkit discover --dir .` to inspect managed test coverage.",
+    "- The `testkit` command on PATH is already wired to this local package.",
+    "- Reuse the focused context text files under .testkit/assistant/ before rereading artifacts manually.",
+    "- Avoid launching nested `testkit assistant` sessions from inside the provider.",
+    ""
+  );
+
+  return lines.join("\n");
+}
+
+function buildCommandsMarkdown() {
+  return [
+    "# Testkit Commands",
+    "",
+    "- `testkit run --dir . --type int`",
+    "- `testkit run --dir . --type e2e`",
+    "- `testkit run --dir . --file path/to/file.testkit.ts`",
+    "- `testkit discover --dir .`",
+    "- `testkit status --dir .`",
+    "- `testkit doctor --dir .`",
+    "- `testkit destroy --dir .`",
+    "",
+  ].join("\n");
+}
+
+function serializeSelection(entry) {
+  if (!entry) return null;
+  return {
+    kind: entry.kind || null,
+    serviceName: entry.serviceName || null,
+    type: entry.type || null,
+    suiteName: entry.suiteName || null,
+    filePath: entry.filePath || null,
+    status: entry.status || null,
+    label: entry.label || null,
+  };
+}
+
+function writeJson(filePath, value) {
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2), "utf8");
+}

package/lib/cli/assistant/interactive.mjs

@@ -0,0 +1,52 @@
+import path from "path";
+import { createInspectState } from "../tui/inspect-state.mjs";
+import { loadLatestRunArtifact, resolveFileSubject } from "../viewer.mjs";
+import { startInteractiveProviderSession } from "../agents/index.mjs";
+import { prepareAssistantBootstrap } from "./bootstrap.mjs";
+
+export async function runInteractiveAssistant({
+  productDir,
+  provider = "auto",
+  file = null,
+  service = null,
+  prompt = null,
+  env = process.env,
+} = {}) {
+  const inspectState = createInspectState({ dataSource: "artifact" });
+  try {
+    inspectState.hydrateFromArtifact(loadLatestRunArtifact(productDir));
+  } catch {
+    // No persisted artifact yet.
+  }
+
+  if (file) {
+    try {
+      const artifact = loadLatestRunArtifact(productDir);
+      const subject = resolveFileSubject(artifact, file, service || null);
+      inspectState.revealFile(subject.service.name, subject.file.path);
+    } catch {
+      // Ignore unresolved focus.
+    }
+  } else if (service) {
+    inspectState.revealService(service);
+  }
+
+  const bootstrap = prepareAssistantBootstrap({
+    productDir,
+    inspectState,
+    initialPrompt: prompt,
+  });
+
+  const sessionEnv = {
+    ...env,
+    ...bootstrap.env,
+    PATH: [bootstrap.binDir, env.PATH || ""].filter(Boolean).join(path.delimiter),
+  };
+
+  return startInteractiveProviderSession({
+    provider,
+    cwd: productDir,
+    prompt: bootstrap.prompt,
+    env: sessionEnv,
+  });
+}

package/lib/cli/assistant/prompt-builder.mjs

@@ -1,4 +1,4 @@
-import { buildInspectPaneContent } from "../tui/detail-pane.mjs";
+import { readContextContent } from "../context-resources.mjs";
 import { buildAssistantResponseContract } from "./protocol.mjs";
 
 export function buildAssistantPrompt({
@@ -9,7 +9,7 @@ export function buildAssistantPrompt({
   userMessage,
 } = {}) {
   const selectionSummary = buildSelectionSummary(snapshot);
-  const panePreview = buildPanePreview(productDir, snapshot);
+  const focusPreview = buildFocusPreview(productDir, snapshot);
   const summaryRows = snapshot?.summaryData?.rows || [];
 
   return [
@@ -24,8 +24,8 @@ export function buildAssistantPrompt({
     "Current selection:",
     selectionSummary,
     "",
-    "Current pane preview:",
-    ...(panePreview.length > 0 ? panePreview : ["(empty)"]),
+    "Current focus preview:",
+    ...(focusPreview.length > 0 ? focusPreview : ["(empty)"]),
     "",
     "Recent conversation:",
     ...formatTranscript(transcript),
@@ -52,18 +52,18 @@ function buildSelectionSummary(snapshot) {
   return entry.label || "Unknown selection.";
 }
 
-function buildPanePreview(productDir, snapshot) {
+function buildFocusPreview(productDir, snapshot) {
   if (!productDir || !snapshot) return [];
   try {
-    const pane = buildInspectPaneContent({
+    const content = readContextContent({
       productDir,
       snapshot,
-      paneMode: snapshot.paneMode || "detail",
+      mode: "detail",
       logTail: 8,
     });
-    return (pane.lines || []).slice(0, 24).map((line) => `- ${line}`);
+    return (content.lines || []).slice(0, 24).map((line) => `- ${line}`);
   } catch (error) {
-    return [`(pane unavailable: ${error instanceof Error ? error.message : String(error)})`];
+    return [`(focus unavailable: ${error instanceof Error ? error.message : String(error)})`];
   }
 }
 

package/lib/cli/assistant/session.mjs

@@ -9,6 +9,7 @@ export async function runAssistantConversationTurn({
   transcript,
   userMessage,
   provider = "auto",
+  env = process.env,
   configs,
   onStatus,
   onToolEvent,
@@ -34,13 +35,14 @@ export async function runAssistantConversationTurn({
       userMessage,
     });
 
-    onStatus?.(`Thinking with ${resolvePreferredProvider(provider)}...`);
+    onStatus?.(`Thinking with ${resolvePreferredProvider(provider, env)}...`);
     const events = [];
     const session = startAgentSession({
       provider,
       cwd: productDir,
       prompt,
       purpose: "assistant",
+      env,
       onEvent(event) {
         events.push(event);
         if (event.type === "status" || event.type === "tool") onStatus?.(formatProviderEvent(event));
@@ -60,6 +62,7 @@ export async function runAssistantConversationTurn({
         role: "tool",
         text: toolText,
         toolName: envelope.tool,
+        title: toolResult.title || envelope.tool,
         data: toolResult.data || null,
       });
       currentTranscript.push({

package/lib/cli/assistant/slash-commands.mjs

@@ -1,5 +1,4 @@
 const RUN_TYPES = new Set(["int", "e2e", "scenario", "dal", "load", "pw", "all"]);
-const PANES = new Set(["detail", "artifacts", "logs", "setup"]);
 const PROVIDERS = new Set(["auto", "claude", "codex"]);
 
 export function parseSlashCommand(input) {
@@ -20,14 +19,6 @@ export function parseSlashCommand(input) {
     return { type: "provider", provider };
   }
 
-  if (command === "pane") {
-    const pane = tokens[0] || "detail";
-    if (!PANES.has(pane)) {
-      throw new Error(`/pane expects one of: ${[...PANES].join(", ")}`);
-    }
-    return { type: "pane", pane };
-  }
-
   if (command === "file" || command === "focus") {
     if (!tokens[0]) throw new Error(`/${command} expects a file path`);
     return { type: "file", file: tokens.join(" ") };
@@ -45,6 +36,27 @@ export function parseSlashCommand(input) {
     };
   }
 
+  if (command === "logs") {
+    return {
+      type: "logs",
+      service: tokens[0] || null,
+    };
+  }
+
+  if (command === "artifacts") {
+    return {
+      type: "artifacts",
+      file: tokens[0] || null,
+    };
+  }
+
+  if (command === "setup") {
+    return {
+      type: "setup",
+      service: tokens[0] || null,
+    };
+  }
+
   if (command === "status") return { type: "status" };
   if (command === "discover") return { type: "discover" };
   if (command === "doctor") return { type: "doctor" };
@@ -64,8 +76,10 @@ export function formatSlashHelpLines() {
     "/run [type] [--service name] [--file path] [--suite selector]",
     "/file <path>",
     "/service <name>",
-    "/pane <detail|artifacts|logs|setup>",
     "/inspect [path]",
+    "/logs [service]",
+    "/artifacts [path]",
+    "/setup [service]",
     "/discover",
     "/status",
     "/doctor",