@elench/testkit 0.1.89 → 0.1.90

package/README.md

@@ -75,13 +75,22 @@ npx @elench/testkit assistant --message "/logs api"
 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 is a
-single chat surface with a bottom composer. It keeps the current run artifact,
-selected file, logs, setup operations, and emitted artifacts as hidden context
-and pulls them into the conversation inline when needed. 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` 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

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 { readAssistantContent } from "./content.mjs";
+import { readContextContent } from "../context-resources.mjs";
 import { buildAssistantResponseContract } from "./protocol.mjs";
 
 export function buildAssistantPrompt({
@@ -55,13 +55,9 @@ function buildSelectionSummary(snapshot) {
 function buildFocusPreview(productDir, snapshot) {
   if (!productDir || !snapshot) return [];
   try {
-    const content = readAssistantContent({
+    const content = readContextContent({
       productDir,
-      inspectState: {
-        getSnapshot() {
-          return snapshot;
-        },
-      },
+      snapshot,
       mode: "detail",
       logTail: 8,
     });

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));

package/lib/cli/assistant/state.mjs

@@ -1,6 +1,6 @@
 import { loadCurrentRunArtifact, loadLatestRunArtifact } from "../viewer.mjs";
 import { createInspectState } from "../tui/inspect-state.mjs";
-import { buildAssistantContext } from "./content.mjs";
+import { buildContextSelection } from "../context-resources.mjs";
 import { parseSlashCommand, formatSlashHelpLines } from "./slash-commands.mjs";
 import { executeAssistantTool } from "./tool-registry.mjs";
 import { runAssistantConversationTurn } from "./session.mjs";
@@ -10,6 +10,7 @@ export function createAssistantState({
   provider = "auto",
   dataSource = "artifact",
   configs = [],
+  env = process.env,
 } = {}) {
   const inspectState = createInspectState({ dataSource });
 
@@ -160,6 +161,7 @@ export function createAssistantState({
           transcript: messages.map((entry) => ({ role: entry.role, text: entry.text })),
           userMessage: trimmed,
           provider: providerName,
+          env,
           configs,
           onStatus(status) {
             activeStatus = status;
@@ -184,7 +186,7 @@ export function createAssistantState({
 
     getSnapshot() {
       return {
-        context: buildAssistantContext(inspectState.getSnapshot()),
+        context: buildContextSelection(inspectState.getSnapshot()),
         messages: [...messages],
         composer,
         notice,

package/lib/cli/assistant/tool-registry.mjs

@@ -5,9 +5,9 @@ import { resolveRequestedFiles } from "../args.mjs";
 import { buildDiscoveryReportLines } from "../presentation/discovery-reporter.mjs";
 import { loadCurrentRunArtifact, loadLatestRunArtifact, resolveFileSubject } from "../viewer.mjs";
 import {
-  formatAssistantToolText,
-  readAssistantContent,
-} from "./content.mjs";
+  formatContextToolText,
+  readContextContent,
+} from "../context-resources.mjs";
 import { createAssistantRunReporter } from "./tool-run-reporter.mjs";
 import { buildRunRequest } from "../command-helpers.mjs";
 import * as runner from "../../runner/index.mjs";
@@ -131,16 +131,16 @@ function focusServiceTool(args, context) {
 }
 
 function inspectFocusTool(_args, context) {
-  const content = readAssistantContent({
+  const content = readContextContent({
     productDir: context.productDir,
-    inspectState: context.inspectState,
+    snapshot: context.inspectState.getSnapshot(),
     mode: "detail",
     logTail: 12,
   });
   return {
     ok: true,
     title: content.title,
-    text: formatAssistantToolText(content.title, content.lines),
+    text: formatContextToolText(content.title, content.lines),
     data: {
       title: content.title,
       lines: content.lines,
@@ -157,16 +157,16 @@ function readLogsTool(args, context) {
       throw new Error(`Unknown service "${args.service}"`);
     }
   }
-  const content = readAssistantContent({
+  const content = readContextContent({
     productDir: context.productDir,
-    inspectState: context.inspectState,
+    snapshot: context.inspectState.getSnapshot(),
     mode: "logs",
     logTail: args.logTail == null ? 12 : Number(args.logTail),
   });
   return {
     ok: true,
     title: content.title,
-    text: formatAssistantToolText(content.title, content.lines),
+    text: formatContextToolText(content.title, content.lines),
     data: {
       title: content.title,
       lines: content.lines,
@@ -183,16 +183,16 @@ function readArtifactsTool(args, context) {
     const subject = resolveFileSubject(artifact, args.file || args.path, args.service || null);
     context.inspectState.revealFile(subject.service.name, subject.file.path);
   }
-  const content = readAssistantContent({
+  const content = readContextContent({
     productDir: context.productDir,
-    inspectState: context.inspectState,
+    snapshot: context.inspectState.getSnapshot(),
     mode: "artifacts",
     logTail: 12,
   });
   return {
     ok: true,
     title: content.title,
-    text: formatAssistantToolText(content.title, content.lines),
+    text: formatContextToolText(content.title, content.lines),
     data: {
       title: content.title,
       lines: content.lines,
@@ -209,16 +209,16 @@ function readSetupTool(args, context) {
       throw new Error(`Unknown service "${args.service}"`);
     }
   }
-  const content = readAssistantContent({
+  const content = readContextContent({
     productDir: context.productDir,
-    inspectState: context.inspectState,
+    snapshot: context.inspectState.getSnapshot(),
     mode: "setup",
     logTail: 12,
   });
   return {
     ok: true,
     title: content.title,
-    text: formatAssistantToolText(content.title, content.lines),
+    text: formatContextToolText(content.title, content.lines),
     data: {
       title: content.title,
       lines: content.lines,
@@ -255,7 +255,7 @@ function showStatusTool(_args, context) {
   return {
     ok: true,
     title: "Status",
-    text: formatAssistantToolText("Status", lines),
+    text: formatContextToolText("Status", lines),
     data: { lines },
   };
 }
@@ -272,7 +272,7 @@ async function runDoctorTool(args, context) {
   return {
     ok: result.ok,
     title: "Doctor",
-    text: formatAssistantToolText("Doctor", lines),
+    text: formatContextToolText("Doctor", lines),
     data: result,
   };
 }