@elench/testkit 0.1.94 → 0.1.96

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

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

@@ -16,8 +16,11 @@ export function buildAssistantPrompt({
     "You are Testkit Assistant.",
     "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 shell_exec when the user asks to run tests or inspect the working repo.",
+    "For testkit work, invoke the local `testkit` command directly, for example `testkit run --dir . --type e2e` or `testkit discover --dir .`.",
+    "Do not wrap testkit with pnpm, npm, yarn, bun, or npx unless the user explicitly asks for that exact package-manager command.",
     "Use read_context before repeating artifact/log inspection work, and use read_file/search_repo when you need codebase context.",
+    "After a tool result, describe only what the tool result actually says. Do not invent filesystem, sandbox, package-manager, or permission errors.",
     buildAssistantResponseContract({ tools }),
     "",
     "Current run summary:",

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

@@ -5,6 +5,7 @@ import { loadCurrentRunArtifact, loadLatestRunArtifact, resolveFileSubject } fro
 import {
   readContextContent,
 } from "../context-resources.mjs";
+import { extractShellCommand, planShellCommand } from "./command-plan.mjs";
 
 const COMMAND_OUTPUT_LIMIT = 14_000;
 const COMMAND_LINE_LIMIT = 220;
@@ -14,7 +15,7 @@ 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.",
+      description: "Execute a shell command inside the repository. Use local testkit commands for testkit work.",
     },
     {
       name: "read_context",
@@ -48,10 +49,10 @@ export async function executeAssistantTool(name, argumentsObject, context) {
 }
 
 async function shellExecTool(args, context) {
-  const command = String(args.command || "").trim();
+  const command = extractShellCommand(args).trim();
   if (!command) throw new Error("shell_exec requires a command string");
 
-  const shellCommand = classifyShellCommand(command);
+  const shellCommand = planShellCommand(command);
   const commandId = `cmd-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
   context.commandLog?.appendCommandLog({
     type: "command_start",
@@ -59,17 +60,22 @@ async function shellExecTool(args, context) {
     commandId,
     cwd: context.productDir,
     raw: command,
+    executable: shellCommand.executableCommand,
+    normalized: shellCommand.normalized,
   });
   context.onEvent?.({
     type: "tool-start",
     tool: "shell_exec",
-    command,
+    command: shellCommand.executableCommand,
+    rawCommand: command,
     title: shellCommand.title,
     testkitRelated: shellCommand.testkitRelated,
-    message: `Running ${shellCommand.display}`,
+    message: shellCommand.normalized
+      ? `Running ${shellCommand.displayCommand} (${shellCommand.normalizationReason})`
+      : `Running ${shellCommand.displayCommand}`,
   });
 
-  const result = await execaCommand(command, {
+  const result = await execaCommand(shellCommand.executableCommand, {
     cwd: context.productDir,
     reject: false,
     shell: true,
@@ -87,18 +93,21 @@ async function shellExecTool(args, context) {
     commandId,
     cwd: context.productDir,
     raw: command,
+    executable: shellCommand.executableCommand,
+    normalized: shellCommand.normalized,
     code: result.exitCode ?? 0,
     signal: result.signal ?? null,
   });
   context.onEvent?.({
     type: "tool-exit",
     tool: "shell_exec",
-    command,
+    command: shellCommand.executableCommand,
+    rawCommand: command,
     title: shellCommand.title,
     testkitRelated: shellCommand.testkitRelated,
     code: result.exitCode ?? 0,
     signal: result.signal ?? null,
-    message: `${shellCommand.display} exited ${result.exitCode ?? 0}`,
+    message: `${shellCommand.displayCommand} exited ${result.exitCode ?? 0}`,
   });
 
   if (shellCommand.testkitRelated) {
@@ -106,13 +115,15 @@ async function shellExecTool(args, context) {
   }
   context.commandLog?.refresh?.();
 
-  const lines = formatCommandResult(command, result, shellCommand);
+  const lines = formatCommandResult(result, shellCommand);
   return {
     ok: (result.exitCode ?? 0) === 0,
     title: shellCommand.title,
     text: lines.join("\n"),
     data: {
       command,
+      executableCommand: shellCommand.executableCommand,
+      normalizedCommand: shellCommand.normalized,
       stdout: result.stdout || "",
       stderr: result.stderr || "",
       exitCode: result.exitCode ?? 0,
@@ -216,42 +227,11 @@ async function searchRepoTool(args, context) {
   };
 }
 
-function classifyShellCommand(command) {
-  const normalized = command.trim();
-  if (/^(testkit)\b/.test(normalized)) {
-    return {
-      command: "testkit",
-      display: normalized,
-      title: "testkit command",
-      testkitRelated: true,
-    };
+function formatCommandResult(result, shellCommand) {
+  const lines = [`$ ${shellCommand.displayCommand}`];
+  if (shellCommand.normalized) {
+    lines.push(`normalized from: ${shellCommand.rawCommand}`);
   }
-  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 = [];

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

@@ -1,6 +1,6 @@
 {
   "name": "@elench/next-analysis",
-  "version": "0.1.94",
+  "version": "0.1.96",
   "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.94",
+  "version": "0.1.96",
   "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.94"
+    "@elench/testkit-protocol": "0.1.96"
   },
   "private": false
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-protocol",
-  "version": "0.1.94",
+  "version": "0.1.96",
   "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.94",
+  "version": "0.1.96",
   "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.94",
+  "version": "0.1.96",
   "description": "Assistant-first CLI for running, inspecting, and debugging local testkit suites",
   "type": "module",
   "workspaces": [
@@ -83,10 +83,10 @@
   },
   "dependencies": {
     "@babel/code-frame": "^7.29.0",
-    "@elench/next-analysis": "0.1.94",
-    "@elench/testkit-bridge": "0.1.94",
-    "@elench/testkit-protocol": "0.1.94",
-    "@elench/ts-analysis": "0.1.94",
+    "@elench/next-analysis": "0.1.96",
+    "@elench/testkit-bridge": "0.1.96",
+    "@elench/testkit-protocol": "0.1.96",
+    "@elench/ts-analysis": "0.1.96",
     "@oclif/core": "^4.10.6",
     "esbuild": "^0.25.11",
     "execa": "^9.5.0",