@elench/testkit 0.1.97 → 0.1.99

package/lib/{cli/context-resources.mjs → results/context.mjs}

@@ -7,7 +7,7 @@ import {
   getSetupOperationsForService,
   loadCurrentRunArtifact,
   resolveFileSubject,
-} from "./viewer.mjs";
+} from "./artifacts.mjs";
 import { formatDuration } from "../runner/formatting.mjs";
 import { readLogTail } from "../runner/logs.mjs";
 

package/lib/runner/maintenance.mjs

@@ -1,15 +1,15 @@
 import fs from "fs";
 import {
   cleanupOrphanedLocalInfrastructure,
+  collectServiceDatabaseStatus,
   destroyRuntimeDatabase,
   destroyServiceDatabaseCache,
   isDatabaseStateDir,
-  showServiceDatabaseStatus,
 } from "../database/index.mjs";
 import { cleanupRuns, formatRunSummary } from "./lifecycle.mjs";
-import { printRunStatus } from "./readiness.mjs";
+import { buildRunStatusLines } from "./readiness.mjs";
 import { findGraphDirsForService, findRuntimeStateDirs } from "./state.mjs";
-import { printStateDir } from "./state-io.mjs";
+import { collectStateDirLines } from "./state-io.mjs";
 
 export async function destroy(config) {
   await cleanupRuns(config.productDir, { includeActive: true });
@@ -35,38 +35,49 @@ export async function destroy(config) {
 }
 
 export function showStatus(config) {
-  printRunStatus(config.productDir);
+  const lines = [...buildRunStatusLines(config.productDir)];
   const graphDirs = findGraphDirsForService(config.productDir, config.name);
   const hasDirectState = fs.existsSync(config.stateDir);
   const hasGraphState = graphDirs.length > 0;
 
   if (!hasDirectState && !hasGraphState) {
-    console.log("No state — run tests first.");
+    lines.push("No state — run tests first.");
   } else {
     if (hasDirectState) {
-      console.log("  service-state/");
-      printStateDir(config.stateDir, "    ");
+      lines.push("  service-state/");
+      lines.push(...collectStateDirLines(config.stateDir, "    "));
     }
     for (const graphDir of graphDirs) {
-      console.log(`  graph-state/${graphDir.split("/").at(-1)}/`);
-      printStateDir(graphDir, "    ");
+      lines.push(`  graph-state/${graphDir.split("/").at(-1)}/`);
+      lines.push(...collectStateDirLines(graphDir, "    "));
     }
   }
 
-  showServiceDatabaseStatus(config.productDir, config.name);
+  lines.push(...collectServiceDatabaseStatus(config.productDir, config.name));
+  return {
+    name: config.name,
+    lines,
+  };
 }
 
 export async function cleanup(productDir) {
   const summary = await cleanupRuns(productDir, { includeActive: false });
   if (summary.cleaned.length === 0 && summary.skippedActive.length === 0) {
-    console.log("No stale runs to clean.");
-    return;
+    return {
+      ...summary,
+      lines: ["No stale runs to clean."],
+    };
   }
 
+  const lines = [];
   for (const manifest of summary.cleaned) {
-    console.log(`Cleaned stale run ${formatRunSummary(manifest)}`);
+    lines.push(`Cleaned stale run ${formatRunSummary(manifest)}`);
   }
   for (const manifest of summary.skippedActive) {
-    console.log(`Active run still present: ${formatRunSummary(manifest)}`);
+    lines.push(`Active run still present: ${formatRunSummary(manifest)}`);
   }
+  return {
+    ...summary,
+    lines,
+  };
 }

package/lib/runner/readiness.mjs

@@ -96,11 +96,11 @@ export async function isPortInUse({ host, port }) {
   });
 }
 
-export function printRunStatus(productDir) {
+export function buildRunStatusLines(productDir) {
   const manifests = listRunManifests(productDir);
-  if (manifests.length === 0) return;
+  if (manifests.length === 0) return [];
 
-  console.log("  runs/");
+  const lines = ["  runs/"];
   for (const manifest of manifests) {
     const state = isPidRunning(manifest.pid) ? "active" : "stale";
     const ports = [
@@ -110,8 +110,9 @@ export function printRunStatus(productDir) {
         )
       ),
     ];
-    console.log(
+    lines.push(
       `    ${manifest.runId}: ${state} pid=${manifest.pid}${ports.length > 0 ? ` ports=${ports.join(",")}` : ""}`
     );
   }
+  return lines;
 }

package/lib/runner/state-io.mjs

@@ -33,16 +33,22 @@ export function readStateValue(filePath) {
   return fs.readFileSync(filePath, "utf8").trim();
 }
 
-export function printStateDir(dir, indent) {
+export function collectStateDirLines(dir, indent = "") {
+  const lines = [];
+  appendStateDirLines(lines, dir, indent);
+  return lines;
+}
+
+function appendStateDirLines(lines, dir, indent) {
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const filePath = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      console.log(`${indent}${entry.name}/`);
-      printStateDir(filePath, `${indent}  `);
+      lines.push(`${indent}${entry.name}/`);
+      appendStateDirLines(lines, filePath, `${indent}  `);
       continue;
     }
     const value =
       entry.name === "password" ? "********" : fs.readFileSync(filePath, "utf8").trim();
-    console.log(`${indent}${entry.name}: ${value}`);
+    lines.push(`${indent}${entry.name}: ${value}`);
   }
 }

package/node_modules/@elench/next-analysis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/next-analysis",
-  "version": "0.1.97",
+  "version": "0.1.99",
   "description": "SWC-backed Next.js source analysis primitives for Erench tools",
   "type": "module",
   "exports": {

package/node_modules/@elench/testkit-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-bridge",
-  "version": "0.1.97",
+  "version": "0.1.99",
   "description": "Browser bridge helpers for testkit",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,7 +22,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@elench/testkit-protocol": "0.1.97"
+    "@elench/testkit-protocol": "0.1.99"
   },
   "private": false
 }

package/node_modules/@elench/testkit-protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-protocol",
-  "version": "0.1.97",
+  "version": "0.1.99",
   "description": "Shared browser protocol for testkit bridge and extension consumers",
   "type": "module",
   "main": "./dist/index.js",

package/node_modules/@elench/ts-analysis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/ts-analysis",
-  "version": "0.1.97",
+  "version": "0.1.99",
   "description": "TypeScript compiler-backed source analysis primitives for Erench tools",
   "type": "module",
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit",
-  "version": "0.1.97",
+  "version": "0.1.99",
   "description": "Assistant-first CLI for running, inspecting, and debugging local testkit suites",
   "type": "module",
   "workspaces": [
@@ -58,12 +58,11 @@
   "scripts": {
     "build:packages": "npm --workspace packages/testkit-protocol run build && npm --workspace packages/ts-analysis run build && npm --workspace packages/next-analysis run build && npm --workspace packages/testkit-bridge run build",
     "typecheck:packages": "npm --workspace packages/testkit-protocol run typecheck && npm --workspace packages/ts-analysis run typecheck && npm --workspace packages/next-analysis run typecheck && npm --workspace packages/testkit-bridge run typecheck && npm --workspace packages/testkit-extension run compile",
-    "test": "npm run build:packages && vitest run",
+    "test": "npm run build:packages && vitest run && node scripts/live-sandbox/harness.mjs",
     "test:audit": "node scripts/test-boundary-audit.mjs",
     "test:unit": "npm run build:packages && npm run test:audit && vitest run --config vitest.unit.config.mjs",
     "test:integration": "npm run build:packages && vitest run test/integration",
-    "test:system": "npm run build:packages && vitest run test/system --passWithNoTests",
-    "test:live-providers": "npm run build:packages && vitest run --config vitest.live.config.mjs --passWithNoTests"
+    "test:system": "npm run build:packages && vitest run test/system --passWithNoTests"
   },
   "files": [
     "bin/",
@@ -84,10 +83,10 @@
   },
   "dependencies": {
     "@babel/code-frame": "^7.29.0",
-    "@elench/next-analysis": "0.1.97",
-    "@elench/testkit-bridge": "0.1.97",
-    "@elench/testkit-protocol": "0.1.97",
-    "@elench/ts-analysis": "0.1.97",
+    "@elench/next-analysis": "0.1.99",
+    "@elench/testkit-bridge": "0.1.99",
+    "@elench/testkit-protocol": "0.1.99",
+    "@elench/ts-analysis": "0.1.99",
     "@oclif/core": "^4.10.6",
     "esbuild": "^0.25.11",
     "execa": "^9.5.0",

package/lib/cli/assistant/protocol.mjs

@@ -1,67 +0,0 @@
-export function buildAssistantResponseContract({ tools = [] } = {}) {
-  return [
-    "Respond with exactly one JSON object and no surrounding commentary.",
-    'Use {"type":"answer","message":"..."} when you can answer directly.',
-    'Use {"type":"tool","tool":"<name>","arguments":{...},"commentary":"..."} when you need testkit to act before you answer.',
-    "Only request one tool at a time.",
-    `Available tools: ${tools.map((tool) => tool.name).join(", ") || "none"}.`,
-  ].join("\n");
-}
-
-export function parseAssistantEnvelope(text) {
-  const raw = String(text || "").trim();
-  if (!raw) {
-    return {
-      type: "answer",
-      message: "",
-    };
-  }
-
-  const candidate = extractJsonObject(raw);
-  if (!candidate) {
-    return {
-      type: "answer",
-      message: raw,
-    };
-  }
-
-  try {
-    const parsed = JSON.parse(candidate);
-    if (parsed?.type === "tool" && parsed.tool) {
-      return {
-        type: "tool",
-        tool: String(parsed.tool),
-        arguments: normalizePlainObject(parsed.arguments),
-        commentary: parsed.commentary ? String(parsed.commentary) : "",
-      };
-    }
-    if (parsed?.type === "answer") {
-      return {
-        type: "answer",
-        message: parsed.message ? String(parsed.message) : "",
-      };
-    }
-  } catch {
-    // Fall through to raw answer.
-  }
-
-  return {
-    type: "answer",
-    message: raw,
-  };
-}
-
-function extractJsonObject(text) {
-  const fencedMatch = text.match(/```json\s*([\s\S]*?)```/i);
-  if (fencedMatch?.[1]) return fencedMatch[1].trim();
-
-  const start = text.indexOf("{");
-  const end = text.lastIndexOf("}");
-  if (start < 0 || end <= start) return null;
-  return text.slice(start, end + 1);
-}
-
-function normalizePlainObject(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
-  return value;
-}

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

@@ -1,318 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { execaCommand } from "execa";
-import { loadCurrentRunArtifact, loadLatestRunArtifact, resolveFileSubject } from "../viewer.mjs";
-import {
-  readContextContent,
-} from "../context-resources.mjs";
-
-const COMMAND_OUTPUT_LIMIT = 14_000;
-const COMMAND_LINE_LIMIT = 220;
-const FILE_LINE_LIMIT = 160;
-
-export function listAssistantTools() {
-  return [
-    {
-      name: "shell_exec",
-      description: "Execute a shell command inside the repository. Prefer real repo commands such as npm, npx, and testkit.",
-    },
-    {
-      name: "read_context",
-      description: "Read testkit-managed context such as focused detail, logs, artifacts, setup, or run summary.",
-    },
-    {
-      name: "read_file",
-      description: "Read a local file with optional start and end lines.",
-    },
-    {
-      name: "search_repo",
-      description: "Search the repository with ripgrep and return matching lines.",
-    },
-  ];
-}
-
-export async function executeAssistantTool(name, argumentsObject, context) {
-  const args = argumentsObject && typeof argumentsObject === "object" ? argumentsObject : {};
-  switch (name) {
-    case "shell_exec":
-      return shellExecTool(args, context);
-    case "read_context":
-      return readContextTool(args, context);
-    case "read_file":
-      return readFileTool(args, context);
-    case "search_repo":
-      return searchRepoTool(args, context);
-    default:
-      throw new Error(`Unknown assistant tool "${name}"`);
-  }
-}
-
-async function shellExecTool(args, context) {
-  const command = String(args.command || "").trim();
-  if (!command) throw new Error("shell_exec requires a command string");
-
-  const shellCommand = classifyShellCommand(command);
-  const commandId = `cmd-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
-  context.commandLog?.appendCommandLog({
-    type: "command_start",
-    command: shellCommand.command,
-    commandId,
-    cwd: context.productDir,
-    raw: command,
-  });
-  context.onEvent?.({
-    type: "tool-start",
-    tool: "shell_exec",
-    command,
-    title: shellCommand.title,
-    testkitRelated: shellCommand.testkitRelated,
-    message: `Running ${shellCommand.display}`,
-  });
-
-  const result = await execaCommand(command, {
-    cwd: context.productDir,
-    reject: false,
-    shell: true,
-    env: {
-      ...process.env,
-      ...context.env,
-      PATH: [context.commandLog?.binDir, context.env?.PATH, process.env.PATH].filter(Boolean).join(path.delimiter),
-      TESTKIT_NO_ASSISTANT_DEFAULT: "1",
-    },
-  });
-
-  context.commandLog?.appendCommandLog({
-    type: "command_exit",
-    command: shellCommand.command,
-    commandId,
-    cwd: context.productDir,
-    raw: command,
-    code: result.exitCode ?? 0,
-    signal: result.signal ?? null,
-  });
-  context.onEvent?.({
-    type: "tool-exit",
-    tool: "shell_exec",
-    command,
-    title: shellCommand.title,
-    testkitRelated: shellCommand.testkitRelated,
-    code: result.exitCode ?? 0,
-    signal: result.signal ?? null,
-    message: `${shellCommand.display} exited ${result.exitCode ?? 0}`,
-  });
-
-  if (shellCommand.testkitRelated) {
-    refreshArtifactSelection(context);
-  }
-  context.commandLog?.refresh?.();
-
-  const lines = formatCommandResult(command, result, shellCommand);
-  return {
-    ok: (result.exitCode ?? 0) === 0,
-    title: shellCommand.title,
-    text: lines.join("\n"),
-    data: {
-      command,
-      stdout: result.stdout || "",
-      stderr: result.stderr || "",
-      exitCode: result.exitCode ?? 0,
-      signal: result.signal ?? null,
-      testkitRelated: shellCommand.testkitRelated,
-    },
-  };
-}
-
-function readContextTool(args, context) {
-  if (args.file || args.path) {
-    ensureArtifactLoaded(context);
-    const artifact = context.inspectState.getSnapshot().runArtifact;
-    const subject = resolveFileSubject(artifact, args.file || args.path, args.service || null);
-    context.inspectState.revealFile(subject.service.name, subject.file.path);
-  } else if (args.service) {
-    ensureArtifactLoaded(context);
-    if (!context.inspectState.revealService(args.service)) {
-      throw new Error(`Unknown service "${args.service}"`);
-    }
-  }
-
-  const content = readContextContent({
-    productDir: context.productDir,
-    snapshot: context.inspectState.getSnapshot(),
-    mode: normalizeContextMode(args.mode),
-    logTail: args.logTail == null ? 12 : Number(args.logTail),
-  });
-  context.commandLog?.refresh?.();
-  return {
-    ok: true,
-    title: content.title,
-    text: content.lines.join("\n"),
-    data: {
-      title: content.title,
-      lines: content.lines,
-      selection: content.selection,
-      mode: content.mode,
-    },
-  };
-}
-
-function readFileTool(args, context) {
-  const file = String(args.path || args.file || "").trim();
-  if (!file) throw new Error("read_file requires a path");
-  const resolved = resolveRepoPath(context.productDir, file);
-  if (!resolved.startsWith(path.resolve(context.productDir))) {
-    throw new Error("read_file only supports paths inside the current repository");
-  }
-  if (!fs.existsSync(resolved)) {
-    throw new Error(`File not found: ${file}`);
-  }
-  const startLine = Math.max(1, Number(args.startLine || args.start || 1) || 1);
-  const requestedEnd = Number(args.endLine || args.end || startLine + FILE_LINE_LIMIT - 1) || startLine + FILE_LINE_LIMIT - 1;
-  const endLine = Math.max(startLine, Math.min(requestedEnd, startLine + FILE_LINE_LIMIT - 1));
-  const lines = fs.readFileSync(resolved, "utf8").split(/\r?\n/);
-  const selected = [];
-  for (let lineNumber = startLine; lineNumber <= Math.min(endLine, lines.length); lineNumber += 1) {
-    selected.push(`${lineNumber}: ${lines[lineNumber - 1]}`);
-  }
-  const title = `File ${path.relative(context.productDir, resolved) || path.basename(resolved)}`;
-  return {
-    ok: true,
-    title,
-    text: selected.join("\n"),
-    data: {
-      path: resolved,
-      relativePath: path.relative(context.productDir, resolved),
-      startLine,
-      endLine,
-      lines: selected,
-    },
-  };
-}
-
-async function searchRepoTool(args, context) {
-  const query = String(args.query || args.pattern || "").trim();
-  if (!query) throw new Error("search_repo requires a query");
-  const result = await execaCommand(
-    `rg --line-number --smart-case --hidden --glob '!node_modules' --glob '!.git' ${shellQuote(query)} .`,
-    {
-      cwd: context.productDir,
-      reject: false,
-      shell: true,
-    }
-  );
-  const combined = truncateLines((result.stdout || "").split(/\r?\n/).filter(Boolean), COMMAND_LINE_LIMIT);
-  const lines =
-    combined.length > 0
-      ? combined
-      : [`No matches for ${query}`];
-  return {
-    ok: (result.exitCode ?? 1) === 0,
-    title: `Search ${query}`,
-    text: lines.join("\n"),
-    data: {
-      query,
-      matches: combined,
-      exitCode: result.exitCode ?? 1,
-    },
-  };
-}
-
-function classifyShellCommand(command) {
-  const normalized = command.trim();
-  if (/^(testkit)\b/.test(normalized)) {
-    return {
-      command: "testkit",
-      display: normalized,
-      title: "testkit command",
-      testkitRelated: true,
-    };
-  }
-  if (/^(npx)\s+testkit\b/.test(normalized)) {
-    return {
-      command: "npx testkit",
-      display: normalized,
-      title: "npx testkit",
-      testkitRelated: true,
-    };
-  }
-  if (/^(npm)\s+run\s+testkit\b/.test(normalized) || /^(npm)\s+run\s+testkit:/.test(normalized)) {
-    return {
-      command: "npm run testkit",
-      display: normalized,
-      title: "npm testkit script",
-      testkitRelated: true,
-    };
-  }
-  return {
-    command: normalized.split(/\s+/)[0] || "command",
-    display: normalized,
-    title: "Shell command",
-    testkitRelated: false,
-  };
-}
-
-function formatCommandResult(command, result, shellCommand) {
-  const lines = [`$ ${command}`];
-  const stdout = (result.stdout || "").trim();
-  const stderr = (result.stderr || "").trim();
-  const merged = [];
-  if (stdout) merged.push(...stdout.split(/\r?\n/));
-  if (stderr) merged.push(...stderr.split(/\r?\n/).map((line) => `stderr: ${line}`));
-  if (merged.length === 0) {
-    merged.push(`exit ${result.exitCode ?? 0}`);
-  }
-  const trimmed = truncateLines(merged, COMMAND_LINE_LIMIT).map((line) => truncateText(line, COMMAND_OUTPUT_LIMIT));
-  lines.push(...trimmed);
-  if ((result.exitCode ?? 0) !== 0) {
-    lines.push(`exit code: ${result.exitCode ?? 0}`);
-  } else if (!shellCommand.testkitRelated) {
-    lines.push("exit code: 0");
-  }
-  return lines;
-}
-
-function truncateLines(lines, limit) {
-  if (lines.length <= limit) return lines;
-  return [...lines.slice(0, limit - 1), `… ${lines.length - limit + 1} more lines omitted`];
-}
-
-function truncateText(value, maxLength) {
-  const normalized = String(value || "");
-  if (normalized.length <= maxLength) return normalized;
-  return `${normalized.slice(0, maxLength - 1)}…`;
-}
-
-function resolveRepoPath(productDir, file) {
-  return path.resolve(productDir, file);
-}
-
-function shellQuote(value) {
-  return `'${String(value).replace(/'/g, `'\\''`)}'`;
-}
-
-function normalizeContextMode(mode) {
-  if (mode === "logs" || mode === "artifacts" || mode === "setup") return mode;
-  return "detail";
-}
-
-function ensureArtifactLoaded(context) {
-  const snapshot = context.inspectState.getSnapshot();
-  if (snapshot.runArtifact) return snapshot.runArtifact;
-  try {
-    context.inspectState.hydrateFromArtifact(loadCurrentRunArtifact(context.productDir));
-  } catch {
-    context.inspectState.hydrateFromArtifact(loadLatestRunArtifact(context.productDir));
-  }
-  return context.inspectState.getSnapshot().runArtifact;
-}
-
-function refreshArtifactSelection(context) {
-  try {
-    context.inspectState.hydrateFromArtifact(loadCurrentRunArtifact(context.productDir));
-  } catch {
-    try {
-      context.inspectState.hydrateFromArtifact(loadLatestRunArtifact(context.productDir));
-    } catch {
-      // Ignore missing artifacts.
-    }
-  }
-}