@elench/testkit 0.1.97 → 0.1.99

package/README.md

@@ -87,14 +87,14 @@ 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.
+runs testkit-managed commands, the assistant observes real Testkit command
+executions through command sidecars and run artifacts, then refreshes the latest
+run state 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.
+adapter, assistant shell, command-observation, 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
@@ -105,9 +105,9 @@ has an always-visible cursor and supports arrow keys, Home/End, Ctrl+A/Ctrl+E,
 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
-it is not the primary interactive UX.
+The non-interactive `assistant --message ...` mode uses the same provider
+command-observation path 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

package/lib/app/browser-bridge.mjs

@@ -1,6 +1,6 @@
 import { loadConfigContext, resolveProductDir } from "../config/index.mjs";
 import { discoverTests } from "../discovery/index.mjs";
-import { loadCurrentRunArtifact } from "../cli/viewer.mjs";
+import { loadCurrentRunArtifact } from "../results/artifacts.mjs";
 
 export async function loadBrowserBridgeContext(options = {}) {
   const productDir = resolveProductDir(process.cwd(), options.dir);

package/lib/cli/assistant/actions.mjs

@@ -0,0 +1,333 @@
+import fs from "fs";
+import path from "path";
+import { loadCurrentRunArtifact, loadLatestRunArtifact, resolveFileSubject } from "../../results/artifacts.mjs";
+import { readContextContent } from "../../results/context.mjs";
+import { buildRunRequest, executeRunRequest } from "../operations/run/operation.mjs";
+import { executeDiscoverOperation } from "../operations/discover/operation.mjs";
+import { executeDoctorOperation } from "../operations/doctor/operation.mjs";
+import { executeStatusOperation } from "../operations/status/operation.mjs";
+import { renderDiscoverResult } from "../renderers/discover/text.mjs";
+import { renderDoctorResult } from "../renderers/doctor/text.mjs";
+import { renderStatusResult } from "../renderers/status/text.mjs";
+import { createRunSession } from "../renderers/run/interactive.mjs";
+import { loadCliConfig } from "../config.mjs";
+
+const FILE_LINE_LIMIT = 160;
+
+export async function executeAssistantAction(type, args = {}, context = {}) {
+  switch (type) {
+    case "inspect":
+      return readContextAction({ file: args.file || null, mode: "detail" }, context);
+    case "logs":
+      return readContextAction({ service: args.service || null, mode: "logs" }, context);
+    case "artifacts":
+      return readContextAction({ file: args.file || null, mode: "artifacts" }, context);
+    case "setup":
+      return readContextAction({ service: args.service || null, mode: "setup" }, context);
+    case "file":
+      return readFileAction({ path: args.file || args.path }, context);
+    case "service":
+      return readContextAction({ service: args.service, mode: "detail" }, context);
+    case "status":
+      return statusAction(args, context);
+    case "discover":
+      return discoverAction(args, context);
+    case "doctor":
+      return doctorAction(args, context);
+    case "run":
+      return runAction(args.options || args, context);
+    default:
+      throw new Error(`Unsupported assistant action "${type}"`);
+  }
+}
+
+function readContextAction(args, context) {
+  if (args.file || args.path) {
+    ensureArtifactLoaded(context);
+    const artifact = context.runState.getSnapshot().runArtifact;
+    const subject = resolveFileSubject(artifact, args.file || args.path, args.service || null);
+    context.runState.revealFile(subject.service.name, subject.file.path);
+  } else if (args.service) {
+    ensureArtifactLoaded(context);
+    if (!context.runState.revealService(args.service)) {
+      throw new Error(`Unknown service "${args.service}"`);
+    }
+  }
+
+  const content = readContextContent({
+    productDir: context.productDir,
+    snapshot: context.runState.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 readFileAction(args, context) {
+  const file = String(args.path || args.file || "").trim();
+  if (!file) throw new Error("read_file requires a path");
+  const resolved = path.resolve(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 runAction(args, context) {
+  const normalizedArgs = normalizeRunActionArgs(args, context.productDir);
+  const request = await buildRunRequest(normalizedArgs, null, context.productDir, context.productDir);
+  const runSession = createRunSession({
+    productDir: request.productDir,
+    stderr: process.stderr,
+    config: loadCliConfig(request.productDir),
+  });
+  const invocationId = `slash-run-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+  const rawCommand = buildRunCommandLine(normalizedArgs);
+  context.commandLog?.appendCommandLog({
+    type: "command_start",
+    command: "testkit",
+    commandId: invocationId,
+    cwd: context.productDir,
+    raw: rawCommand,
+  });
+  context.onEvent?.({
+    type: "run-session-start",
+    tool: "run",
+    invocationId,
+    session: runSession,
+  });
+
+  try {
+    const result = await executeRunRequest(request, {
+      outputMode: "compact",
+      terminal: {
+        stdout: process.stdout,
+        stderr: process.stderr,
+        stdin: process.stdin,
+        env: context.env,
+      },
+      attachedRunSession: runSession,
+    });
+    context.runState.hydrateFromArtifact(result.runArtifact);
+    context.commandLog?.refresh?.();
+    context.commandLog?.appendCommandLog({
+      type: "command_exit",
+      command: "testkit",
+      commandId: invocationId,
+      cwd: context.productDir,
+      raw: rawCommand,
+      code: result.exitCode ?? 0,
+      signal: null,
+    });
+    context.onEvent?.({
+      type: "run-session-end",
+      tool: "run",
+      invocationId,
+      session: runSession,
+    });
+    return {
+      ok: (result.exitCode ?? 0) === 0,
+      title: buildRunTitle(normalizedArgs),
+      text: [`Running ${rawCommand}`, formatRunSessionText(runSession)].filter(Boolean).join("\n"),
+      data: {
+        exitCode: result.exitCode ?? 0,
+        summaryRows: runSession.getSnapshot().summaryData?.rows || [],
+      },
+    };
+  } catch (error) {
+    context.commandLog?.appendCommandLog({
+      type: "command_exit",
+      command: "testkit",
+      commandId: invocationId,
+      cwd: context.productDir,
+      raw: rawCommand,
+      code: error?.exitCode ?? 1,
+      signal: error?.signal ?? null,
+    });
+    context.onEvent?.({
+      type: "run-session-end",
+      tool: "run",
+      invocationId,
+      session: runSession,
+    });
+    throw error;
+  }
+}
+
+async function discoverAction(args, context) {
+  const flags = {
+    dir: context.productDir,
+    service: normalizeOptionalString(args.service),
+    type: normalizeStringArray(args.type),
+    suite: normalizeStringArray(args.suite),
+    file: normalizeStringArray(args.file || args.path),
+    "runnable-only": Boolean(args.runnableOnly || args["runnable-only"]),
+    strict: Boolean(args.strict),
+    output: normalizeOptionalString(args.output),
+  };
+  const result = await executeDiscoverOperation(flags, context.productDir);
+  return {
+    ok: true,
+    title: "testkit discover",
+    text: renderDiscoverResult(result, { outputMode: args.outputMode || "compact" }).join("\n"),
+    data: result,
+  };
+}
+
+async function statusAction(args, context) {
+  const results = await executeStatusOperation({
+    dir: context.productDir,
+    service: normalizeOptionalString(args.service),
+  });
+  return {
+    ok: true,
+    title: "testkit status",
+    text: results.flatMap(renderStatusResult).join("\n"),
+    data: { results },
+  };
+}
+
+async function doctorAction(args, context) {
+  const result = await executeDoctorOperation({
+    dir: context.productDir,
+    typecheck: args.typecheck == null ? true : Boolean(args.typecheck),
+  });
+  return {
+    ok: result.ok,
+    title: "testkit doctor",
+    text: renderDoctorResult(result).join("\n"),
+    data: result,
+  };
+}
+
+function normalizeRunActionArgs(args, productDir) {
+  return {
+    dir: productDir,
+    service: normalizeOptionalString(args.service),
+    type: normalizeStringArray(args.type),
+    suite: normalizeStringArray(args.suite),
+    file: normalizeStringArray(args.file || args.path),
+    workers: normalizeOptionalString(args.workers),
+    "file-timeout-seconds": normalizeOptionalString(args.fileTimeoutSeconds || args["file-timeout-seconds"]),
+    shard: normalizeOptionalString(args.shard),
+    seed: normalizeOptionalString(args.seed),
+    "write-status": Boolean(args.writeStatus || args["write-status"]),
+    "allow-partial-status": Boolean(args.allowPartialStatus || args["allow-partial-status"]),
+    "ignore-skip-rules": Boolean(args.ignoreSkipRules || args["ignore-skip-rules"]),
+    "output-mode": "compact",
+    debug: false,
+  };
+}
+
+function buildRunTitle(args) {
+  const types = args.type?.length ? args.type.join(",") : "all";
+  return `testkit run ${types}`;
+}
+
+function buildRunCommandLine(args) {
+  const parts = ["testkit", "run"];
+  if (args.type?.length === 1) parts.push(args.type[0]);
+  parts.push("--dir", ".");
+  if (args.type?.length !== 1) {
+    for (const type of args.type || []) parts.push("--type", type);
+  }
+  for (const suite of args.suite || []) parts.push("--suite", suite);
+  for (const file of args.file || []) parts.push("--file", file);
+  if (args.service) parts.push("--service", args.service);
+  return parts.join(" ");
+}
+
+function formatRunSessionText(runSession) {
+  const snapshot = runSession.getSnapshot();
+  const fileLines = collectRunTreeFiles(snapshot.services || [])
+    .map((entry) => `${formatRunStatus(entry.status)} ${entry.serviceName} ${entry.type} ${entry.filePath || entry.path}`);
+  const rows = snapshot.summaryData?.rows || [];
+  const summaryLines = rows.map(([label, value]) => `${label}: ${value}`);
+  const lines = [...fileLines, ...summaryLines];
+  return lines.length > 0 ? lines.join("\n") : "Run complete.";
+}
+
+function collectRunTreeFiles(services) {
+  const files = [];
+  for (const service of services || []) {
+    for (const typeNode of service.types || []) {
+      for (const suite of typeNode.suites || []) {
+        for (const file of suite.files || []) {
+          files.push(file);
+        }
+      }
+    }
+  }
+  return files;
+}
+
+function formatRunStatus(status) {
+  if (status === "passed") return "PASS";
+  if (status === "failed") return "FAIL";
+  if (status === "skipped") return "SKIP";
+  if (status === "running") return "RUN";
+  if (status === "not_run") return "NOT_RUN";
+  return "PENDING";
+}
+
+function ensureArtifactLoaded(context) {
+  const snapshot = context.runState.getSnapshot();
+  if (snapshot.runArtifact) return snapshot.runArtifact;
+  try {
+    context.runState.hydrateFromArtifact(loadCurrentRunArtifact(context.productDir));
+  } catch {
+    context.runState.hydrateFromArtifact(loadLatestRunArtifact(context.productDir));
+  }
+  return context.runState.getSnapshot().runArtifact;
+}
+
+function normalizeContextMode(mode) {
+  if (mode === "logs" || mode === "artifacts" || mode === "setup") return mode;
+  return "detail";
+}
+
+function normalizeOptionalString(value) {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function normalizeStringArray(value) {
+  if (Array.isArray(value)) return value.flatMap((entry) => String(entry).split(",")).map((entry) => entry.trim()).filter(Boolean);
+  if (value == null) return [];
+  return String(value).split(",").map((entry) => entry.trim()).filter(Boolean);
+}

package/lib/cli/assistant/app.mjs

@@ -1,6 +1,7 @@
 import React, { createElement, useEffect, useMemo, useRef, useState } from "react";
 import { Box, Text, useApp, useBoxMetrics, useCursor, useInput, useStdout } from "ink";
-import { bold, cyan, dim, green, red, yellow } from "../presentation/colors.mjs";
+import { bold, cyan, dim, green, red, yellow } from "../terminal/colors.mjs";
+import { RunTreeView } from "../components/blocks/run-tree.mjs";
 import { getComposerDisplayModel } from "./composer.mjs";
 import { buildAssistantViewModel } from "./view-model.mjs";
 
@@ -49,6 +50,7 @@ export function AssistantApp({
     }),
     [snapshot, stdout?.columns]
   );
+  const runSession = assistantState.getLiveRunSession?.() || assistantState.getLastRunSession?.() || null;
 
   return createElement(
     Box,
@@ -63,6 +65,28 @@ export function AssistantApp({
     view.blocks.length === 0
       ? createElement(WelcomePanel, { view })
       : createElement(Transcript, { view }),
+    runSession
+      ? createElement(
+          Box,
+          { flexDirection: "column", marginTop: 1 },
+          createElement(Text, null, bold("Run Session")),
+          createElement(
+            Box,
+            {
+              borderStyle: "round",
+              flexDirection: "column",
+              paddingLeft: 1,
+              paddingRight: 1,
+            },
+            createElement(RunTreeView, {
+              runState: runSession.runState,
+              stdout,
+              productDir: runSession.productDir,
+              interactive: false,
+            })
+          )
+        )
+      : null,
     createElement(Text, null, ""),
     createElement(ComposerBar, { view, busy: snapshot.busy }),
     createElement(Text, null, dim(view.statusLine)),

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

@@ -0,0 +1,110 @@
+import fs from "fs";
+import path from "path";
+import { loadCurrentRunArtifact, loadLatestRunArtifact } from "../../results/artifacts.mjs";
+
+const POLL_INTERVAL_MS = 150;
+const OBSERVED_KINDS = new Set(["run", "discover", "status", "doctor", "typecheck"]);
+
+export function createAssistantCommandObserver({
+  productDir,
+  commandLog,
+  runState,
+  onEvent,
+  intervalMs = POLL_INTERVAL_MS,
+} = {}) {
+  const seenResultFiles = new Set();
+  let timer = null;
+  let running = false;
+  let lastArtifactSignature = null;
+
+  function start() {
+    if (running) return;
+    running = true;
+    lastArtifactSignature = readArtifactSignature();
+    scan();
+    timer = setInterval(scan, intervalMs);
+  }
+
+  function stop() {
+    running = false;
+    if (timer) clearInterval(timer);
+    timer = null;
+    scan();
+  }
+
+  function scan() {
+    observeCommandResults();
+    observeRunArtifact();
+  }
+
+  function observeCommandResults() {
+    const resultDir = commandLog?.resultDir;
+    if (!resultDir || !fs.existsSync(resultDir)) return;
+    const entries = fs.readdirSync(resultDir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .map((entry) => path.join(resultDir, entry.name))
+      .sort();
+
+    for (const filePath of entries) {
+      if (seenResultFiles.has(filePath)) continue;
+      seenResultFiles.add(filePath);
+      let document = null;
+      try {
+        document = JSON.parse(fs.readFileSync(filePath, "utf8"));
+      } catch {
+        continue;
+      }
+      if (!OBSERVED_KINDS.has(document.kind)) continue;
+      if (document.kind === "run") {
+        hydrateRunArtifact("command-result", document);
+      }
+      onEvent?.({
+        type: "observed-testkit-command",
+        command: document,
+      });
+    }
+  }
+
+  function observeRunArtifact() {
+    const signature = readArtifactSignature();
+    if (!signature) return;
+    if (signature === lastArtifactSignature) return;
+    lastArtifactSignature = signature;
+    hydrateRunArtifact("artifact", { artifactPath: signature.split(":")[0] });
+  }
+
+  function readArtifactSignature() {
+    const artifactPath = path.join(productDir, ".testkit", "results", "live.json");
+    const latestPath = path.join(productDir, ".testkit", "results", "latest.json");
+    const candidate = fs.existsSync(artifactPath) ? artifactPath : latestPath;
+    if (!fs.existsSync(candidate)) return null;
+    const stat = fs.statSync(candidate);
+    return `${candidate}:${stat.mtimeMs}:${stat.size}`;
+  }
+
+  function hydrateRunArtifact(source, command = null) {
+    let artifact = null;
+    try {
+      artifact = loadCurrentRunArtifact(productDir);
+    } catch {
+      try {
+        artifact = loadLatestRunArtifact(productDir);
+      } catch {
+        return;
+      }
+    }
+    runState?.hydrateFromArtifact?.(artifact);
+    onEvent?.({
+      type: "observed-run-artifact",
+      source,
+      artifact,
+      command,
+    });
+  }
+
+  return {
+    start,
+    stop,
+    scan,
+  };
+}

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

@@ -0,0 +1,167 @@
+import fs from "fs";
+import path from "path";
+
+export const ASSISTANT_SESSION_ENV = "TESTKIT_ASSISTANT_SESSION_ID";
+export const ASSISTANT_RESULT_DIR_ENV = "TESTKIT_ASSISTANT_RESULT_DIR";
+export const ASSISTANT_COMMAND_LOG_ENV = "TESTKIT_ASSISTANT_COMMAND_LOG";
+export const ASSISTANT_COMMAND_ID_ENV = "TESTKIT_ASSISTANT_COMMAND_ID";
+export const ASSISTANT_WRAPPER_LOGGED_ENV = "TESTKIT_ASSISTANT_WRAPPER_LOGGED";
+
+export function createAssistantCommandContext({
+  kind,
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  env = process.env,
+} = {}) {
+  const sessionId = env[ASSISTANT_SESSION_ENV] || null;
+  const resultDir = env[ASSISTANT_RESULT_DIR_ENV] || null;
+  const commandLogPath = env[ASSISTANT_COMMAND_LOG_ENV] || null;
+  if (!sessionId && !resultDir && !commandLogPath) return null;
+
+  const commandId = env[ASSISTANT_COMMAND_ID_ENV] || `cmd-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+  const startedAt = new Date().toISOString();
+  return {
+    sessionId,
+    resultDir,
+    commandLogPath,
+    commandId,
+    kind: kind || inferCommandKind(argv),
+    argv: Array.isArray(argv) ? argv.map(String) : [],
+    cwd,
+    startedAt,
+    wrapperLogged: env[ASSISTANT_WRAPPER_LOGGED_ENV] === "1",
+  };
+}
+
+export async function withAssistantCommandResult(kind, callback, options = {}) {
+  const context = createAssistantCommandContext({ ...options, kind });
+  if (!context) return callback();
+
+  if (!context.wrapperLogged) {
+    appendAssistantCommandLog(context, {
+      type: "command_start",
+      commandId: context.commandId,
+      command: "testkit",
+      kind: context.kind,
+      argv: context.argv,
+      cwd: context.cwd,
+    });
+  }
+
+  try {
+    const result = await callback();
+    const exitCode = inferExitCode(result);
+    writeAssistantCommandResult(context, {
+      ok: exitCode === 0,
+      exitCode,
+      result,
+    });
+    if (!context.wrapperLogged) {
+      appendAssistantCommandLog(context, {
+        type: "command_exit",
+        commandId: context.commandId,
+        command: "testkit",
+        kind: context.kind,
+        argv: context.argv,
+        cwd: context.cwd,
+        code: exitCode,
+        signal: null,
+      });
+    }
+    return result;
+  } catch (error) {
+    const exitCode = Number.isInteger(error?.exitCode) ? error.exitCode : 1;
+    writeAssistantCommandResult(context, {
+      ok: false,
+      exitCode,
+      error: serializeError(error),
+      result: error?.result || null,
+    });
+    if (!context.wrapperLogged) {
+      appendAssistantCommandLog(context, {
+        type: "command_exit",
+        commandId: context.commandId,
+        command: "testkit",
+        kind: context.kind,
+        argv: context.argv,
+        cwd: context.cwd,
+        code: exitCode,
+        signal: error?.signal || null,
+      });
+    }
+    throw error;
+  }
+}
+
+export function writeAssistantCommandResult(context, payload = {}) {
+  if (!context?.resultDir) return null;
+  try {
+    fs.mkdirSync(context.resultDir, { recursive: true });
+    const finishedAt = new Date().toISOString();
+    const document = {
+      schemaVersion: 1,
+      source: "testkit-command-result",
+      sessionId: context.sessionId,
+      commandId: context.commandId,
+      kind: context.kind,
+      argv: context.argv,
+      cwd: context.cwd,
+      startedAt: context.startedAt,
+      finishedAt,
+      ...payload,
+    };
+    const filePath = path.join(context.resultDir, `${safeFileSegment(context.commandId)}-${safeFileSegment(context.kind)}.json`);
+    fs.writeFileSync(filePath, `${JSON.stringify(document, null, 2)}\n`, "utf8");
+    return filePath;
+  } catch {
+    return null;
+  }
+}
+
+export function appendAssistantCommandLog(context, event) {
+  const commandLogPath = context?.commandLogPath || process.env[ASSISTANT_COMMAND_LOG_ENV] || null;
+  if (!commandLogPath || !event) return;
+  try {
+    fs.mkdirSync(path.dirname(commandLogPath), { recursive: true });
+    fs.appendFileSync(
+      commandLogPath,
+      `${JSON.stringify({ timestamp: new Date().toISOString(), sessionId: context?.sessionId || null, ...event })}\n`,
+      "utf8"
+    );
+  } catch {
+    // Command logging must never make a user command fail.
+  }
+}
+
+function inferCommandKind(argv) {
+  const positionals = (Array.isArray(argv) ? argv : []).filter((arg) => !String(arg).startsWith("-"));
+  return positionals[0] || "run";
+}
+
+function inferExitCode(result) {
+  if (Number.isInteger(result?.exitCode)) return result.exitCode;
+  if (result?.ok === false) return 1;
+  return 0;
+}
+
+function serializeError(error) {
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message,
+      stack: error.stack || null,
+    };
+  }
+  return {
+    name: "Error",
+    message: String(error),
+    stack: null,
+  };
+}
+
+function safeFileSegment(value) {
+  return String(value || "command")
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "command";
+}