@elench/testkit 0.1.93 → 0.1.96

package/README.md

@@ -78,11 +78,23 @@ npx @elench/testkit db snapshot capture --service api --output scripts/testkit/s
 ```
 
 `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.
+opens with a repo-aware landing panel: provider/model, current directory,
+latest run result, focused file/service, regression counts, and suggested next
+prompts. The bottom composer is the primary interaction surface, and the status
+line shows approximate context remaining when the active provider/model window
+is known, for example `[~96% remaining]`.
+
+Natural-language turns still go through Codex or Claude, but `testkit` owns the
+transcript, command execution surface, context files under `.testkit/assistant/`,
+and rendering around `testkit`, `npm`, and `npx` commands. When the provider
+runs testkit-managed commands, the assistant records structured tool lifecycle
+blocks and refreshes the latest run artifact so follow-up questions can use the
+new result immediately.
+
+Assistant provider coverage is tested against the real `codex` and `claude`
+CLIs. The test suite assumes both are installed and authenticated; provider
+adapter, assistant shell, `shell_exec`, and real testkit-run coverage do not use
+provider stand-in binaries or simulated provider sessions.
 
 Assistant runtime settings are repo-local. Use `/provider`, `/model`,
 `/effort`, and `/settings` inside the assistant to inspect or change the active
@@ -90,7 +102,8 @@ provider runtime; changes are persisted to `.testkit/assistant/settings.json`.
 CLI flags such as `--provider`, `--model`, `--effort`, and repeatable
 `--provider-arg` override those settings for the current launch. The composer
 has an always-visible cursor and supports arrow keys, Home/End, Ctrl+A/Ctrl+E,
-Backspace, Delete, and Ctrl+D.
+Backspace, Delete, Ctrl+D, and Ctrl+L to clear the visible transcript. Ctrl+C
+quits the assistant.
 
 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
@@ -268,7 +281,7 @@ File-local execution metadata now lives next to the test when possible:
 import { defineFile } from "@elench/testkit/config";
 
 export const testkit = defineFile({
-  skip: "Billing is still stubbed locally",
+  skip: "Billing is currently unavailable locally",
   locks: ["global-worker-loop"],
 });
 ```

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

@@ -4,7 +4,6 @@ import {
   buildStatusEvent,
   buildToolEvent,
   createHostedSessionRunner,
-  extractTextFragments,
 } from "./shared.mjs";
 
 export function startClaudeHostedSession({
@@ -21,6 +20,7 @@ export function startClaudeHostedSession({
     "-p",
     "--output-format",
     "stream-json",
+    "--verbose",
     "--include-partial-messages",
   ];
 
@@ -73,6 +73,25 @@ function parseClaudePayload(payload) {
     return events;
   }
 
+  if (type === "stream_event") {
+    const streamEvent = payload.event || {};
+    if (streamEvent.type === "content_block_delta" && streamEvent.delta?.type === "text_delta") {
+      const text = String(streamEvent.delta.text || "");
+      if (text) events.push({ type: "delta", text });
+      return events;
+    }
+    if (streamEvent.type === "tool_use" || streamEvent.content_block?.type === "tool_use") {
+      const tool = streamEvent.content_block || streamEvent;
+      const event = buildToolEvent(
+        tool.name || tool.tool_name || streamEvent.type,
+        tool.input ? JSON.stringify(tool.input) : null
+      );
+      if (event) events.push(event);
+      return events;
+    }
+    return events;
+  }
+
   if (type && /tool/i.test(type)) {
     const event = buildToolEvent(
       payload.name || payload.tool_name || payload.tool || type,
@@ -82,10 +101,14 @@ function parseClaudePayload(payload) {
     return events;
   }
 
-  const fragments = [...new Set(extractTextFragments(payload, []))];
-  if (fragments.length > 0) {
-    for (const fragment of fragments) {
-      events.push({ type: "delta", text: fragment });
+  if (type === "assistant") {
+    return events;
+  }
+
+  if (type === "result") {
+    if (payload.is_error || payload.subtype === "error") {
+      const event = buildErrorEvent(payload.result || payload.error || "Claude command failed");
+      if (event) events.push(event);
     }
     return events;
   }

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

@@ -36,6 +36,11 @@ export function createHostedSessionRunner({ provider, child, onEvent, parsePaylo
   const completion = (async () => {
     const result = await child;
     const finalText = (readFinalText ? readFinalText(result) : null) || assistantText.trim() || null;
+    if ((result.exitCode ?? 0) !== 0 && !finalText) {
+      const message = result.stderr || result.stdout || `${provider} exited with code ${result.exitCode ?? 1}`;
+      emit({ type: "error", message });
+      throw new Error(message);
+    }
     if (finalText) emit({ type: "final", text: finalText });
     emit({ type: "exit", code: result.exitCode ?? 0 });
     settled = true;

package/lib/cli/assistant/app.mjs

@@ -1,9 +1,10 @@
 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";
+import { Box, Text, useApp, useInput, useStdout } from "ink";
+import { bold, cyan, dim, green, red, yellow } from "../presentation/colors.mjs";
 import { getComposerRenderParts } from "./composer.mjs";
+import { buildAssistantViewModel } from "./view-model.mjs";
 
-const MAX_VISIBLE_MESSAGES = 22;
+const MAX_BLOCK_LINES = 18;
 
 export function AssistantApp({
   assistantState,
@@ -13,6 +14,7 @@ export function AssistantApp({
   onRequestClose,
 } = {}) {
   const { exit } = useApp();
+  const { stdout } = useStdout();
   const [snapshot, setSnapshot] = useState(() => assistantState.getSnapshot());
   const [initialPromptStarted, setInitialPromptStarted] = useState(false);
   const [initialPromptFinished, setInitialPromptFinished] = useState(false);
@@ -30,7 +32,7 @@ export function AssistantApp({
     Promise.resolve(assistantState.submitInput(initialPrompt)).finally(() => {
       setInitialPromptFinished(true);
     });
-  }, [assistantState, exit, exitAfterInitialPrompt, initialPrompt, initialPromptStarted, onRequestClose]);
+  }, [assistantState, initialPrompt, initialPromptStarted]);
 
   useEffect(() => {
     if (!exitAfterInitialPrompt || !initialPromptFinished || snapshot.busy) return;
@@ -40,9 +42,12 @@ export function AssistantApp({
     return () => clearTimeout(timer);
   }, [exit, exitAfterInitialPrompt, initialPromptFinished, onRequestClose, snapshot.busy]);
 
-  const visibleMessages = useMemo(
-    () => snapshot.messages.slice(-MAX_VISIBLE_MESSAGES),
-    [snapshot.messages]
+  const view = useMemo(
+    () => buildAssistantViewModel(snapshot, {
+      cwd: snapshot.productDir || process.cwd(),
+      terminalWidth: stdout?.columns || process.stdout?.columns || 100,
+    }),
+    [snapshot, stdout?.columns]
   );
 
   return createElement(
@@ -55,28 +60,15 @@ export function AssistantApp({
           onRequestClose,
         })
       : null,
-    createElement(Text, null, dim(buildHeader(snapshot))),
-    snapshot.notice ? createElement(Text, null, yellow(snapshot.notice)) : null,
+    view.blocks.length === 0
+      ? createElement(WelcomePanel, { view })
+      : createElement(Transcript, { view }),
     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)))
+    createElement(ComposerBar, { view, busy: snapshot.busy }),
+    createElement(Text, null, dim(view.statusLine)),
+    exitAfterInitialPrompt && initialPromptFinished && !snapshot.busy
+      ? createElement(Text, null, dim("initial prompt complete"))
+      : null
   );
 }
 
@@ -88,8 +80,8 @@ function AssistantInputHandler({ assistantState, snapshot, onRequestClose }) {
       (onRequestClose || exit)();
       return;
     }
-    if (input === "q" && !snapshot.busy && snapshot.composer.length === 0) {
-      (onRequestClose || exit)();
+    if (key.ctrl && input === "l" && !snapshot.busy) {
+      assistantState.clearMessages();
       return;
     }
     if (key.return) {
@@ -130,76 +122,113 @@ function AssistantInputHandler({ assistantState, snapshot, onRequestClose }) {
   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] || "")}`));
-  }
+function WelcomePanel({ view }) {
+  return createElement(
+    Box,
+    {
+      borderStyle: "round",
+      flexDirection: "column",
+      paddingLeft: 1,
+      paddingRight: 1,
+    },
+    createElement(Text, null, bold(view.title)),
+    createElement(Text, null, dim(view.welcome.subtitle)),
+    createElement(Text, null, ""),
+    ...view.welcome.rows.map(([label, value]) => (
+      createElement(Text, { key: label }, `${padLabel(label)} ${colorWelcomeValue(label, value)}`)
+    )),
+    createElement(Text, null, ""),
+    createElement(Text, null, bold("Try")),
+    ...view.welcome.suggestions.map((suggestion) => (
+      createElement(Text, { key: suggestion }, `  ${dim("›")} ${suggestion}`)
+    ))
+  );
+}
 
-  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]}`
-      )
-    );
+function Transcript({ view }) {
+  return createElement(
+    Box,
+    { flexDirection: "column" },
+    createElement(Text, null, bold(view.title)),
+    createElement(Text, null, dim(view.welcome.rows.find(([label]) => label === "Provider")?.[1] || "")),
+    createElement(Text, null, ""),
+    view.notice ? createElement(Text, null, yellow(view.notice)) : null,
+    ...view.blocks.flatMap((block) => renderBlock(block))
+  );
+}
+
+function renderBlock(block) {
+  const lines = String(block.text || "").split(/\r?\n/);
+  const visibleLines = lines.length > MAX_BLOCK_LINES
+    ? [...lines.slice(0, MAX_BLOCK_LINES - 1), `… ${lines.length - MAX_BLOCK_LINES + 1} more lines omitted`]
+    : lines;
+  const marker = colorMarker(block);
+  const title = block.title ? ` ${bold(block.title)}` : "";
+  const first = visibleLines[0] || "";
+  const rendered = [
+    createElement(Text, { key: `${block.id}-first` }, `${marker}${title}${title && first ? " " : ""}${colorBlockText(block, first)}`),
+  ];
+
+  for (let index = 1; index < visibleLines.length; index += 1) {
+    rendered.push(createElement(Text, { key: `${block.id}-${index}` }, `  ${visibleLines[index]}`));
   }
-  rendered.push(createElement(Text, { key: `${message.id}-gap` }, ""));
+  rendered.push(createElement(Text, { key: `${block.id}-gap` }, ""));
   return rendered;
 }
 
-function renderComposer(snapshot) {
+function ComposerBar({ view, busy }) {
   const { before, current, after, empty } = getComposerRenderParts({
-    text: snapshot.composer || "",
-    cursor: snapshot.composerCursor ?? 0,
+    text: view.composer.text,
+    cursor: view.composer.cursor,
   });
+  const prompt = cyan("❯");
+  const promptText = empty ? dim(`${view.composer.placeholder} `) : before;
   return createElement(
-    Text,
-    null,
-    empty ? dim("Ask testkit to run or inspect something... ") : before,
-    createElement(Text, { inverse: true }, current),
-    after
+    Box,
+    {
+      borderStyle: "single",
+      borderLeft: false,
+      borderRight: false,
+      paddingTop: 0,
+      paddingBottom: 0,
+    },
+    createElement(
+      Text,
+      null,
+      `${prompt} `,
+      promptText,
+      createElement(Text, { inverse: true }, current),
+      after,
+      busy ? dim("  provider responding") : ""
+    )
   );
 }
 
-function buildHeader(snapshot) {
-  const status = snapshot.busy ? snapshot.activeStatus || "working" : "ready";
-  const provider = snapshot.provider || "auto";
-  const resolvedProvider = snapshot.resolvedProvider && snapshot.resolvedProvider !== provider ? `→${snapshot.resolvedProvider}` : "";
-  const model = snapshot.model ? ` · ${snapshot.model}` : "";
-  const effort = snapshot.effort ? ` · ${snapshot.effort}` : "";
-  const context = snapshot.context?.selection?.filePath || snapshot.context?.selection?.serviceName || "no focus";
-  return `testkit assistant · ${provider}${resolvedProvider}${model}${effort} · ${status} · ${context}`;
+function padLabel(label) {
+  return `${dim(String(label).padEnd(10, " "))}`;
 }
 
-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 · arrows/Home/End move cursor · Backspace/Delete edit · /settings · q quit";
+function colorWelcomeValue(label, value) {
+  if (label === "Latest" && /^FAILED\b/.test(String(value))) return red(value);
+  if (label === "Latest" && /^PASSED\b/.test(String(value))) return green(value);
+  if (label === "Issues" && value !== "None detected") return yellow(value);
+  if (label === "Provider") return cyan(value);
+  return value;
 }
 
-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 colorMarker(block) {
+  if (block.kind === "user") return cyan(block.marker);
+  if (block.kind === "system") return red(block.marker);
+  if (block.kind === "tool-running") return yellow(block.marker);
+  if (block.kind === "testkit-run") return green(block.marker);
+  return block.marker;
 }
 
-function colorForRole(role) {
-  if (role === "user") return green;
-  if (role === "tool") return yellow;
-  if (role === "system") return red;
-  return (value) => value;
+function colorBlockText(block, text) {
+  if (block.kind === "user") return text;
+  if (block.kind === "system") return red(text);
+  if (block.kind === "tool-running") return yellow(text);
+  return text;
 }
 
 function isPrintableInput(input, key) {

package/lib/cli/assistant/command-plan.mjs

@@ -0,0 +1,227 @@
+const TESTKIT_TYPES = new Set(["int", "e2e", "scenario", "dal", "load", "pw", "all"]);
+const TESTKIT_DIR_COMMANDS = new Set(["run", "discover", "status", "doctor", "destroy", "cleanup", "typecheck"]);
+const PACKAGE_RUNNERS = new Set(["npx", "pnpm", "npm", "yarn", "bun"]);
+
+export function extractShellCommand(args = {}) {
+  if (!args || typeof args !== "object") return "";
+  const value =
+    args.command ??
+    args.cmd ??
+    args.commandString ??
+    args.shellCommand ??
+    args.input ??
+    args.script ??
+    "";
+  if (Array.isArray(value)) return value.map((part) => shellEscapeArg(part)).join(" ");
+  return String(value || "");
+}
+
+export function planShellCommand(rawCommand) {
+  const raw = String(rawCommand || "").trim();
+  if (!raw) {
+    return {
+      executableCommand: "",
+      rawCommand: raw,
+      displayCommand: raw,
+      command: "",
+      title: "Shell command",
+      testkitRelated: false,
+      normalized: false,
+    };
+  }
+
+  const testkit = planTestkitCommand(raw);
+  if (testkit) return testkit;
+
+  const testkitScript = planTestkitPackageScript(raw);
+  if (testkitScript) return testkitScript;
+
+  return {
+    executableCommand: raw,
+    rawCommand: raw,
+    displayCommand: raw,
+    command: firstCommandToken(raw),
+    title: "Shell command",
+    testkitRelated: false,
+    normalized: false,
+  };
+}
+
+function planTestkitPackageScript(raw) {
+  if (containsShellControl(raw)) return null;
+  const tokens = tokenizeShellWords(raw);
+  if (!tokens || tokens.length < 3) return null;
+  if (tokens[0] !== "npm" || tokens[1] !== "run") return null;
+  if (tokens[2] !== "testkit" && !tokens[2].startsWith("testkit:")) return null;
+  return {
+    executableCommand: raw,
+    rawCommand: raw,
+    displayCommand: raw,
+    command: "npm run testkit",
+    title: "npm testkit script",
+    testkitRelated: true,
+    normalized: false,
+  };
+}
+
+function planTestkitCommand(raw) {
+  if (containsShellControl(raw)) return null;
+  const tokens = tokenizeShellWords(raw);
+  if (!tokens || tokens.length === 0) return null;
+
+  const extracted = extractTestkitInvocation(tokens);
+  if (!extracted) return null;
+
+  const canonicalArgs = canonicalizeTestkitArgs(extracted.args);
+  const executableCommand = ["testkit", ...canonicalArgs].map(shellEscapeArg).join(" ");
+  const wasNormalized = executableCommand !== raw;
+  return {
+    executableCommand,
+    rawCommand: raw,
+    displayCommand: executableCommand,
+    command: "testkit",
+    title: "testkit command",
+    testkitRelated: true,
+    normalized: wasNormalized,
+    normalizationReason: wasNormalized ? extracted.reason : null,
+  };
+}
+
+function extractTestkitInvocation(tokens) {
+  if (tokens[0] === "testkit") {
+    return {
+      args: tokens.slice(1),
+      reason: "canonicalized local testkit invocation",
+    };
+  }
+
+  if (!PACKAGE_RUNNERS.has(tokens[0])) return null;
+
+  if (tokens[0] === "npm" && ["exec", "x"].includes(tokens[1])) {
+    const index = findPackageTarget(tokens, 2);
+    if (index >= 0) return { args: tokens.slice(index + 1), reason: "replaced npm exec testkit with local testkit" };
+  }
+
+  if (tokens[0] === "npx") {
+    const index = findPackageTarget(tokens, 1);
+    if (index >= 0) return { args: tokens.slice(index + 1), reason: "replaced npx testkit with local testkit" };
+  }
+
+  if (tokens[0] === "pnpm" && ["exec", "dlx"].includes(tokens[1])) {
+    const index = findPackageTarget(tokens, 2);
+    if (index >= 0) return { args: tokens.slice(index + 1), reason: "replaced pnpm testkit launcher with local testkit" };
+  }
+
+  if (tokens[0] === "yarn" && tokens[1] === "testkit") {
+    return { args: tokens.slice(2), reason: "replaced yarn testkit launcher with local testkit" };
+  }
+
+  if (tokens[0] === "bun" && ["x", "run"].includes(tokens[1])) {
+    const index = findPackageTarget(tokens, 2);
+    if (index >= 0) return { args: tokens.slice(index + 1), reason: "replaced bun testkit launcher with local testkit" };
+  }
+
+  return null;
+}
+
+function canonicalizeTestkitArgs(inputArgs) {
+  const args = [...inputArgs];
+  if (args.length === 0) return [];
+
+  if (TESTKIT_TYPES.has(args[0])) {
+    return withDir(["run", "--type", args[0], ...args.slice(1)]);
+  }
+
+  if (!TESTKIT_DIR_COMMANDS.has(args[0])) {
+    return args;
+  }
+
+  if (args[0] === "run") {
+    const runArgs = [...args];
+    if (TESTKIT_TYPES.has(runArgs[1])) {
+      const type = runArgs.splice(1, 1)[0];
+      if (!hasFlag(runArgs, "--type", "-t")) runArgs.splice(1, 0, "--type", type);
+    }
+    return withDir(runArgs);
+  }
+
+  return withDir(args);
+}
+
+function withDir(args) {
+  if (hasFlag(args, "--dir", "-d") || args.includes("--help") || args.includes("-h")) return args;
+  const [command, ...rest] = args;
+  return [command, "--dir", ".", ...rest];
+}
+
+function hasFlag(args, longFlag, shortFlag) {
+  return args.some((arg) => arg === longFlag || arg.startsWith(`${longFlag}=`) || arg === shortFlag);
+}
+
+function findPackageTarget(tokens, startIndex) {
+  for (let index = startIndex; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === "--") continue;
+    if (token === "testkit" || token === "@elench/testkit") return index;
+    if (!token.startsWith("-")) return -1;
+  }
+  return -1;
+}
+
+function firstCommandToken(command) {
+  const tokens = tokenizeShellWords(command);
+  return tokens?.[0] || command.split(/\s+/)[0] || "command";
+}
+
+function containsShellControl(command) {
+  return /[\n;&|<>`]/.test(command);
+}
+
+function tokenizeShellWords(command) {
+  const words = [];
+  let current = "";
+  let quote = null;
+  let escaping = false;
+
+  for (const char of String(command)) {
+    if (escaping) {
+      current += char;
+      escaping = false;
+      continue;
+    }
+    if (char === "\\") {
+      escaping = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) {
+        quote = null;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      quote = char;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (current) {
+        words.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += char;
+  }
+
+  if (escaping || quote) return null;
+  if (current) words.push(current);
+  return words;
+}
+
+function shellEscapeArg(value) {
+  const stringValue = String(value);
+  if (/^[a-zA-Z0-9._:@/%+=,-]+$/.test(stringValue)) return stringValue;
+  return `'${stringValue.replace(/'/g, `'\\''`)}'`;
+}

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

@@ -160,7 +160,9 @@ function buildContextMarkdown(productDir, snapshot, paths) {
   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 local `testkit` command directly when you need to execute or inspect tests.",
+    "- Preferred commands: `testkit run --dir . --type <type>`, `testkit discover --dir .`, `testkit status --dir .`, and `testkit doctor --dir .`.",
+    "- Do not launch testkit through pnpm, npm, yarn, bun, or npx unless the user explicitly asks for that exact package-manager command.",
     "- Use the command log and focused context files before rereading artifacts manually.",
     "- Prefer repo-local commands over guessing project-specific wrappers.",
     ""
@@ -180,8 +182,6 @@ function buildCommandsMarkdown() {
     "- `testkit status --dir .`",
     "- `testkit doctor --dir .`",
     "- `testkit destroy --dir .`",
-    "- `npm run testkit`",
-    "- `npx testkit --dir . --type e2e`",
     "",
   ].join("\n");
 }