@elench/testkit 0.1.89 → 0.1.91

package/README.md

@@ -75,13 +75,20 @@ 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 assistant-first in an interactive TTY. The interactive assistant
+is a testkit-owned chat shell with a bottom composer, provider-backed
+reasoning, repo context files under `.testkit/assistant/`, and inline tool
+blocks for command execution. Natural-language turns still go through Codex or
+Claude, but `testkit` owns the transcript, command execution surface, and
+rendering around `testkit`, `npm`, and `npx` commands.
+
+The non-interactive `assistant --message ...` mode uses the same provider/tool
+engine 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

@@ -1,6 +1,5 @@
 import fs from "fs";
 import path from "path";
-import { spawn } from "child_process";
 import { startClaudeHostedSession } from "./providers/claude.mjs";
 import { startCodexHostedSession } from "./providers/codex.mjs";
 
@@ -20,7 +19,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 +55,18 @@ 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 });
-}
-
-export function startInteractiveAgentHandoff({ provider = "auto", cwd, prompt } = {}) {
-  const resolvedProvider = resolvePreferredProvider(provider);
-  const command = resolvedProvider;
-  const args = prompt ? [prompt] : [];
-  const child = spawn(command, args, {
-    cwd,
-    stdio: "inherit",
-  });
-  return new Promise((resolve, reject) => {
-    child.on("error", reject);
-    child.on("close", (code) => resolve({ provider: resolvedProvider, exitCode: code ?? 0 }));
-  });
+  return startCodexHostedSession({ command, cwd, prompt, onEvent, purpose });
 }

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/app.mjs

@@ -0,0 +1,210 @@
+import React, { createElement, useEffect, useMemo, useState } from "react";
+import { Box, Text, useApp, useInput } from "ink";
+import { bold, dim, green, red, yellow } from "../presentation/colors.mjs";
+
+const MAX_VISIBLE_MESSAGES = 22;
+
+export function AssistantApp({
+  assistantState,
+  initialPrompt = null,
+  exitAfterInitialPrompt = false,
+  inputEnabled = true,
+  onRequestClose,
+} = {}) {
+  const { exit } = useApp();
+  const [snapshot, setSnapshot] = useState(() => assistantState.getSnapshot());
+  const [initialPromptStarted, setInitialPromptStarted] = useState(false);
+  const [initialPromptFinished, setInitialPromptFinished] = useState(false);
+
+  useEffect(() => {
+    const unsubscribe = assistantState.subscribe(() => {
+      setSnapshot(assistantState.getSnapshot());
+    });
+    return unsubscribe;
+  }, [assistantState]);
+
+  useEffect(() => {
+    if (!initialPrompt || initialPromptStarted) return;
+    setInitialPromptStarted(true);
+    Promise.resolve(assistantState.submitInput(initialPrompt)).finally(() => {
+      setInitialPromptFinished(true);
+    });
+  }, [assistantState, exit, exitAfterInitialPrompt, initialPrompt, initialPromptStarted, onRequestClose]);
+
+  useEffect(() => {
+    if (!exitAfterInitialPrompt || !initialPromptFinished || snapshot.busy) return;
+    const timer = setTimeout(() => {
+      (onRequestClose || exit)();
+    }, 40);
+    return () => clearTimeout(timer);
+  }, [exit, exitAfterInitialPrompt, initialPromptFinished, onRequestClose, snapshot.busy]);
+
+  const visibleMessages = useMemo(
+    () => snapshot.messages.slice(-MAX_VISIBLE_MESSAGES),
+    [snapshot.messages]
+  );
+
+  return createElement(
+    Box,
+    { flexDirection: "column" },
+    inputEnabled
+      ? createElement(AssistantInputHandler, {
+          assistantState,
+          snapshot,
+          onRequestClose,
+        })
+      : null,
+    createElement(Text, null, dim(buildHeader(snapshot))),
+    snapshot.notice ? createElement(Text, null, yellow(snapshot.notice)) : null,
+    createElement(Text, null, ""),
+    createElement(
+      Box,
+      { flexDirection: "column" },
+      ...visibleMessages.flatMap((message) => renderMessage(message))
+    ),
+    createElement(Text, null, ""),
+    createElement(
+      Box,
+      {
+        borderStyle: "round",
+        flexDirection: "column",
+        paddingLeft: 1,
+        paddingRight: 1,
+      },
+      createElement(Text, null, dim("Message")),
+      renderComposer(snapshot)
+    ),
+    createElement(Text, null, ""),
+    createElement(Text, null, dim(buildFooter(snapshot, initialPromptFinished)))
+  );
+}
+
+function AssistantInputHandler({ assistantState, snapshot, onRequestClose }) {
+  const { exit } = useApp();
+
+  useInput((input, key) => {
+    if (key.ctrl && input === "c") {
+      (onRequestClose || exit)();
+      return;
+    }
+    if (input === "q" && !snapshot.busy && snapshot.composer.length === 0) {
+      (onRequestClose || exit)();
+      return;
+    }
+    if (key.return) {
+      if (!snapshot.busy) {
+        void assistantState.submitCurrentComposer();
+      }
+      return;
+    }
+    if (key.leftArrow) {
+      assistantState.moveComposerCursor(-1);
+      return;
+    }
+    if (key.rightArrow) {
+      assistantState.moveComposerCursor(1);
+      return;
+    }
+    if (key.home || (key.ctrl && input === "a")) {
+      assistantState.moveComposerCursorToStart();
+      return;
+    }
+    if (key.end || (key.ctrl && input === "e")) {
+      assistantState.moveComposerCursorToEnd();
+      return;
+    }
+    if (key.backspace || key.delete) {
+      assistantState.backspaceComposer();
+      return;
+    }
+    if (key.ctrl && input === "d") {
+      assistantState.deleteComposer();
+      return;
+    }
+    if (isPrintableInput(input, key)) {
+      assistantState.insertComposer(input);
+    }
+  });
+
+  return null;
+}
+
+function renderMessage(message) {
+  const prefix = rolePrefix(message);
+  const lines = String(message.text || "").split(/\r?\n/);
+  const rendered = [];
+  if (message.title) {
+    rendered.push(createElement(Text, { key: `${message.id}-title` }, `${prefix} ${bold(message.title)}`));
+  } else if (lines.length > 0) {
+    rendered.push(createElement(Text, { key: `${message.id}-first` }, `${prefix} ${colorForRole(message.role)(lines[0] || "")}`));
+  }
+
+  const remainingLines = message.title ? lines : lines.slice(1);
+  for (let index = 0; index < remainingLines.length; index += 1) {
+    rendered.push(
+      createElement(
+        Text,
+        { key: `${message.id}-line-${index}` },
+        `${message.title ? "  " : "    "}${remainingLines[index]}`
+      )
+    );
+  }
+  rendered.push(createElement(Text, { key: `${message.id}-gap` }, ""));
+  return rendered;
+}
+
+function renderComposer(snapshot) {
+  const composer = snapshot.composer || "";
+  const cursor = snapshot.composerCursor ?? composer.length;
+  const before = composer.slice(0, cursor);
+  const current = composer[cursor] || " ";
+  const after = composer.slice(cursor + (composer[cursor] ? 1 : 0));
+  const placeholder = composer.length === 0 ? dim("Ask testkit to run or inspect something...") : "";
+  if (composer.length === 0) {
+    return createElement(Text, null, placeholder);
+  }
+  return createElement(
+    Text,
+    null,
+    before,
+    createElement(Text, { inverse: true }, current),
+    after
+  );
+}
+
+function buildHeader(snapshot) {
+  const status = snapshot.busy ? snapshot.activeStatus || "working" : "ready";
+  const provider = snapshot.provider || "auto";
+  const context = snapshot.context?.selection?.filePath || snapshot.context?.selection?.serviceName || "no focus";
+  return `testkit assistant · ${provider} · ${status} · ${context}`;
+}
+
+function buildFooter(snapshot, promptFinished) {
+  if (promptFinished && snapshot.messages.length > 0) {
+    return "initial prompt complete";
+  }
+  if (snapshot.busy) {
+    return "Enter disabled while the provider is responding · Ctrl+C quit";
+  }
+  return "Enter send · Ctrl+A/Ctrl+E move cursor · Backspace delete · q quit";
+}
+
+function rolePrefix(message) {
+  if (message.role === "user") return green("you>");
+  if (message.role === "assistant") return bold("ai>");
+  if (message.role === "tool") return yellow("tool>");
+  return red("sys>");
+}
+
+function colorForRole(role) {
+  if (role === "user") return green;
+  if (role === "tool") return yellow;
+  if (role === "system") return red;
+  return (value) => value;
+}
+
+function isPrintableInput(input, key) {
+  if (!input) return false;
+  if (key.ctrl || key.meta || key.escape || key.tab) return false;
+  return input >= " ";
+}

package/lib/cli/assistant/context-pack.mjs

@@ -0,0 +1,191 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { readContextContent, buildContextSelection } from "../context-resources.mjs";
+
+export function prepareAssistantContextPack({
+  productDir,
+  inspectState,
+} = {}) {
+  const contextDir = path.join(productDir, ".testkit", "assistant");
+  const binDir = path.join(contextDir, "bin");
+  fs.mkdirSync(binDir, { recursive: true });
+
+  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");
+
+  function refresh() {
+    const snapshot = inspectState?.getSnapshot?.() || {};
+    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, buildContextSelection(snapshot));
+    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() }), {
+      encoding: "utf8",
+      mode: 0o755,
+    });
+    fs.chmodSync(wrapperPath, 0o755);
+  }
+
+  refresh();
+
+  return {
+    contextDir,
+    contextPath,
+    summaryPath,
+    selectionPath,
+    commandsPath,
+    commandLogPath,
+    focusedDetailPath,
+    focusedLogsPath,
+    focusedArtifactsPath,
+    focusedSetupPath,
+    binDir,
+    wrapperPath,
+    refresh,
+    appendCommandLog(event) {
+      if (!event || typeof event !== "object") return;
+      try {
+        fs.appendFileSync(
+          commandLogPath,
+          `${JSON.stringify({ timestamp: new Date().toISOString(), ...event })}\n`,
+          "utf8"
+        );
+      } catch {
+        // Ignore assistant command log failures.
+      }
+    },
+  };
+}
+
+function resolveCliPath() {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "bin", "testkit.mjs");
+}
+
+function buildWrapperScript({ cliPath } = {}) {
+  return `#!/usr/bin/env node
+import { spawnSync } from "child_process";
+
+const result = spawnSync(process.execPath, [${JSON.stringify(cliPath)}, ...process.argv.slice(2)], {
+  cwd: process.cwd(),
+  env: {
+    ...process.env,
+    TESTKIT_NO_ASSISTANT_DEFAULT: "1",
+  },
+  stdio: "inherit",
+});
+
+if (result.error) {
+  throw result.error;
+}
+process.exit(result.status ?? 0);
+`;
+}
+
+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 shell commands like `npm run testkit`, `npx testkit`, or `testkit run --dir . --type <type>` when you need to execute tests.",
+    "- Use the command log and focused context files before rereading artifacts manually.",
+    "- Prefer repo-local commands over guessing project-specific wrappers.",
+    ""
+  );
+
+  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 .`",
+    "- `npm run testkit`",
+    "- `npx testkit --dir . --type e2e`",
+    "",
+  ].join("\n");
+}
+
+function writeJson(filePath, value) {
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2), "utf8");
+}

package/lib/cli/assistant/interactive.mjs

@@ -0,0 +1,53 @@
+import React, { createElement } from "react";
+import { render } from "ink";
+import { createAssistantState } from "./state.mjs";
+import { AssistantApp } from "./app.mjs";
+import { loadLatestRunArtifact, resolveFileSubject } from "../viewer.mjs";
+
+export async function runInteractiveAssistant({
+  productDir,
+  provider = "auto",
+  file = null,
+  service = null,
+  prompt = null,
+  env = process.env,
+  configs = [],
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  const assistantState = createAssistantState({
+    productDir,
+    provider,
+    configs,
+    env,
+  });
+
+  await assistantState.loadLatestArtifact();
+  if (file) {
+    try {
+      const artifact = loadLatestRunArtifact(productDir);
+      const subject = resolveFileSubject(artifact, file, service || null);
+      assistantState.revealFile(subject.service.name, subject.file.path);
+    } catch {
+      // Ignore unresolved focus.
+    }
+  } else if (service) {
+    assistantState.revealService(service);
+  }
+
+  const app = render(
+    createElement(AssistantApp, {
+      assistantState,
+      initialPrompt: prompt,
+      exitAfterInitialPrompt: Boolean(prompt),
+      inputEnabled: Boolean(process.stdin.isTTY),
+    }),
+    {
+      stdout,
+      stderr,
+      exitOnCtrlC: false,
+    }
+  );
+
+  return app.waitUntilExit();
+}

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({
@@ -14,8 +14,10 @@ export function buildAssistantPrompt({
 
   return [
     "You are Testkit Assistant.",
-    "You help users run tests, inspect failures, read artifacts/logs, and explain the current local test state.",
-    "Prefer using tools when the user is asking testkit to inspect or run something.",
+    "You help users run tests, inspect failures, read logs and artifacts, and navigate the current local test state.",
+    "All user natural-language requests must be handled through your own reasoning plus the available tools.",
+    "Prefer real repository commands through shell_exec when the user asks to run tests or inspect the working repo.",
+    "Use read_context before repeating artifact/log inspection work, and use read_file/search_repo when you need codebase context.",
     buildAssistantResponseContract({ tools }),
     "",
     "Current run summary:",
@@ -55,13 +57,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,7 +9,9 @@ export async function runAssistantConversationTurn({
   transcript,
   userMessage,
   provider = "auto",
+  env = process.env,
   configs,
+  commandLog,
   onStatus,
   onToolEvent,
 } = {}) {
@@ -18,6 +20,8 @@ export async function runAssistantConversationTurn({
     productDir,
     inspectState,
     configs,
+    env,
+    commandLog,
     onEvent: onToolEvent,
   };
 
@@ -34,13 +38,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));