wispy-cli 1.1.2 → 1.2.2

package/core/harness.mjs

@@ -0,0 +1,531 @@
+/**
+ * core/harness.mjs — Execution Harness for Wispy
+ *
+ * Mediates ALL tool execution with:
+ * - Permission checks (auto/notify/approve)
+ * - Dry-run simulation
+ * - Pre/post snapshots + unified diffs
+ * - Execution receipts
+ * - Audit logging
+ * - Event emission for TUI/channel approval UX
+ *
+ * v1.2.0
+ */
+
+import { EventEmitter } from "node:events";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+
+import { EVENT_TYPES } from "./audit.mjs";
+
+// ── Receipt ────────────────────────────────────────────────────────────────────
+
+export class Receipt {
+  constructor() {
+    this.id = generateId();
+    this.timestamp = new Date().toISOString();
+    this.sessionId = null;
+    this.toolName = null;
+    this.args = {};
+    this.permissionLevel = "auto";
+    this.approved = null;   // null = not needed, true/false = approval result
+    this.dryRun = false;
+    this.duration = 0;
+    this.success = false;
+    this.result = null;
+    this.diff = null;       // { before, after, unified } for file ops
+    this.error = null;
+  }
+
+  toMarkdown() {
+    const icon = this.success ? "✅" : "❌";
+    const dryTag = this.dryRun ? " [DRY RUN]" : "";
+    const lines = [
+      `${icon} **${this.toolName}**${dryTag}`,
+      `- ID: \`${this.id}\``,
+      `- Time: ${new Date(this.timestamp).toLocaleTimeString()}`,
+      `- Duration: ${this.duration}ms`,
+      `- Permission: ${this.permissionLevel}`,
+    ];
+
+    if (this.approved !== null) {
+      lines.push(`- Approved: ${this.approved ? "✅ yes" : "❌ no"}`);
+    }
+
+    if (this.error) {
+      lines.push(`- Error: ${this.error}`);
+    }
+
+    if (this.diff?.unified) {
+      const stats = diffStats(this.diff.unified);
+      lines.push(`- Changes: +${stats.added} lines, -${stats.removed} lines`);
+      lines.push("", "```diff", this.diff.unified.slice(0, 2000), "```");
+    }
+
+    return lines.join("\n");
+  }
+
+  toJSON() {
+    return {
+      id: this.id,
+      timestamp: this.timestamp,
+      sessionId: this.sessionId,
+      toolName: this.toolName,
+      args: this.args,
+      permissionLevel: this.permissionLevel,
+      approved: this.approved,
+      dryRun: this.dryRun,
+      duration: this.duration,
+      success: this.success,
+      result: this.result,
+      diff: this.diff,
+      error: this.error,
+    };
+  }
+}
+
+// ── HarnessResult ──────────────────────────────────────────────────────────────
+
+export class HarnessResult {
+  constructor({ result, receipt, denied = false, dryRun = false }) {
+    this.result = result;
+    this.receipt = receipt;
+    this.denied = denied;
+    this.dryRun = dryRun;
+    this.success = receipt?.success ?? (!denied);
+  }
+}
+
+// ── Sandbox modes ─────────────────────────────────────────────────────────────
+
+// Which tools get file snapshots (pre/post diff)
+const FILE_SNAPSHOT_TOOLS = new Set(["write_file", "file_edit"]);
+
+// File-path arg for each tool (to know what to snapshot)
+function getFilePath(toolName, args) {
+  if (toolName === "write_file" || toolName === "file_edit" || toolName === "read_file") {
+    return args.path;
+  }
+  return null;
+}
+
+// Resolve a file path the same way tools.mjs does
+function resolvePath(p) {
+  if (!p) return null;
+  let resolved = p.replace(/^~/, os.homedir());
+  if (!path.isAbsolute(resolved)) resolved = path.resolve(process.cwd(), resolved);
+  return resolved;
+}
+
+// ── Unified diff (no external deps) ──────────────────────────────────────────
+
+/**
+ * Compute a simple unified diff between two strings.
+ * Returns unified diff string.
+ */
+export function computeUnifiedDiff(before, after, filePath = "file") {
+  if (before === after) return "";
+
+  const beforeLines = before ? before.split("\n") : [];
+  const afterLines = after ? after.split("\n") : [];
+
+  // LCS-based diff — simple Myers-like algorithm
+  const hunks = computeHunks(beforeLines, afterLines, 3);
+
+  if (hunks.length === 0) return "";
+
+  const lines = [
+    `--- a/${filePath}`,
+    `+++ b/${filePath}`,
+  ];
+
+  for (const hunk of hunks) {
+    lines.push(hunk.header);
+    lines.push(...hunk.lines);
+  }
+
+  return lines.join("\n");
+}
+
+function computeHunks(oldLines, newLines, context = 3) {
+  // Build edit script using simple LCS
+  const edits = shortestEditScript(oldLines, newLines);
+
+  if (edits.length === 0) return [];
+
+  // Group edits into hunks with context
+  const hunks = [];
+  let i = 0;
+
+  while (i < edits.length) {
+    if (edits[i].type === "equal") { i++; continue; }
+
+    // Found a change — build a hunk
+    const hunkStart = i;
+    const hunkEdits = [edits[i]];
+    i++;
+
+    // Extend hunk while changes are within 2*context of each other
+    while (i < edits.length) {
+      if (edits[i].type !== "equal") {
+        hunkEdits.push(edits[i]);
+        i++;
+      } else {
+        // Count consecutive equal lines
+        let equalCount = 0;
+        let j = i;
+        while (j < edits.length && edits[j].type === "equal") { equalCount++; j++; }
+        if (equalCount <= 2 * context && j < edits.length && edits[j].type !== "equal") {
+          // Merge into current hunk
+          hunkEdits.push(...edits.slice(i, j));
+          i = j;
+        } else {
+          break;
+        }
+      }
+    }
+
+    // Compute old/new line ranges
+    let oldStart = null; let oldCount = 0;
+    let newStart = null; let newCount = 0;
+    const hunkLines = [];
+
+    // Add leading context
+    const firstEdit = hunkEdits[0];
+    const ctxStart = Math.max(0, firstEdit.oldIdx - context);
+    oldStart = ctxStart + 1; // 1-indexed
+    newStart = firstEdit.newIdx - (firstEdit.oldIdx - ctxStart) + 1; // 1-indexed
+    for (let k = ctxStart; k < firstEdit.oldIdx; k++) {
+      hunkLines.push(` ${oldLines[k]}`);
+      oldCount++; newCount++;
+    }
+
+    // Add the hunk edits
+    for (const edit of hunkEdits) {
+      if (edit.type === "equal") {
+        hunkLines.push(` ${oldLines[edit.oldIdx]}`);
+        oldCount++; newCount++;
+      } else if (edit.type === "delete") {
+        hunkLines.push(`-${oldLines[edit.oldIdx]}`);
+        oldCount++;
+      } else if (edit.type === "insert") {
+        hunkLines.push(`+${newLines[edit.newIdx]}`);
+        newCount++;
+      }
+    }
+
+    // Add trailing context
+    const lastEdit = hunkEdits[hunkEdits.length - 1];
+    const lastOldIdx = lastEdit.type === "insert" ? lastEdit.oldIdx : lastEdit.oldIdx + 1;
+    const ctxEnd = Math.min(oldLines.length, lastOldIdx + context);
+    for (let k = lastOldIdx; k < ctxEnd; k++) {
+      hunkLines.push(` ${oldLines[k]}`);
+      oldCount++; newCount++;
+    }
+
+    hunks.push({
+      header: `@@ -${oldStart},${oldCount} +${newStart},${newCount} @@`,
+      lines: hunkLines,
+    });
+  }
+
+  return hunks;
+}
+
+function shortestEditScript(oldLines, newLines) {
+  // Simple O(nd) diff using dynamic programming LCS
+  const m = oldLines.length;
+  const n = newLines.length;
+
+  // Build LCS table
+  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i = m - 1; i >= 0; i--) {
+    for (let j = n - 1; j >= 0; j--) {
+      if (oldLines[i] === newLines[j]) {
+        dp[i][j] = dp[i + 1][j + 1] + 1;
+      } else {
+        dp[i][j] = Math.max(dp[i + 1][j], dp[i][j + 1]);
+      }
+    }
+  }
+
+  // Trace back
+  const edits = [];
+  let i = 0; let j = 0;
+  while (i < m || j < n) {
+    if (i < m && j < n && oldLines[i] === newLines[j]) {
+      edits.push({ type: "equal", oldIdx: i, newIdx: j });
+      i++; j++;
+    } else if (j < n && (i >= m || dp[i][j + 1] >= dp[i + 1][j])) {
+      edits.push({ type: "insert", oldIdx: i, newIdx: j });
+      j++;
+    } else {
+      edits.push({ type: "delete", oldIdx: i, newIdx: j });
+      i++;
+    }
+  }
+
+  return edits;
+}
+
+function diffStats(unifiedDiff) {
+  let added = 0; let removed = 0;
+  for (const line of unifiedDiff.split("\n")) {
+    if (line.startsWith("+") && !line.startsWith("+++")) added++;
+    else if (line.startsWith("-") && !line.startsWith("---")) removed++;
+  }
+  return { added, removed };
+}
+
+// ── ID generation (no uuid dep needed) ───────────────────────────────────────
+
+function generateId() {
+  const ts = Date.now().toString(36);
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `rcpt-${ts}-${rand}`;
+}
+
+// ── Dry-run simulation ────────────────────────────────────────────────────────
+
+function simulateDryRun(toolName, args) {
+  switch (toolName) {
+    case "write_file":
+      return {
+        success: true,
+        dryRun: true,
+        preview: `Would write ${(args.content ?? "").length} chars to: ${args.path}`,
+        content: args.content,
+        path: args.path,
+      };
+
+    case "file_edit":
+      return {
+        success: true,
+        dryRun: true,
+        preview: `Would replace text in: ${args.path}`,
+        old_text: args.old_text,
+        new_text: args.new_text,
+        path: args.path,
+      };
+
+    case "run_command":
+      return {
+        success: true,
+        dryRun: true,
+        preview: `Would execute: ${args.command}`,
+        command: args.command,
+      };
+
+    case "git":
+      return {
+        success: true,
+        dryRun: true,
+        preview: `Would run: git ${args.command}`,
+        command: args.command,
+      };
+
+    default:
+      return {
+        success: true,
+        dryRun: true,
+        preview: `Would call ${toolName} with ${JSON.stringify(args).slice(0, 100)}`,
+      };
+  }
+}
+
+// ── Harness class ──────────────────────────────────────────────────────────────
+
+export class Harness extends EventEmitter {
+  /**
+   * @param {import('./tools.mjs').ToolRegistry} toolRegistry
+   * @param {import('./permissions.mjs').PermissionManager} permissions
+   * @param {import('./audit.mjs').AuditLog} audit
+   * @param {object} config
+   */
+  constructor(toolRegistry, permissions, audit, config = {}) {
+    super();
+    this.tools = toolRegistry;
+    this.permissions = permissions;
+    this.audit = audit;
+    this.config = config;
+
+    // Sandbox config per-tool: "preview" | "diff" | null
+    this._sandboxModes = {
+      run_command: "preview",
+      write_file: "diff",
+      file_edit: "diff",
+      git: "preview",
+    };
+  }
+
+  /**
+   * Main entry point — replaces direct tool.execute() calls.
+   *
+   * @param {string} toolName
+   * @param {object} args
+   * @param {object} context - { sessionId, userId, channel, dryRun?, executeToolFn }
+   * @returns {HarnessResult}
+   */
+  async execute(toolName, args, context = {}) {
+    const receipt = new Receipt();
+    receipt.toolName = toolName;
+    receipt.args = args;
+    receipt.sessionId = context.sessionId ?? null;
+    receipt.dryRun = context.dryRun ?? false;
+
+    const callStart = Date.now();
+
+    // ── 1. Permission check ──────────────────────────────────────────────────
+    const permResult = await this.permissions.check(toolName, args, context);
+    receipt.permissionLevel = permResult.level ?? "auto";
+
+    if (!permResult.allowed) {
+      receipt.approved = false;
+      receipt.success = false;
+      receipt.error = permResult.reason ?? "Permission denied";
+      receipt.duration = Date.now() - callStart;
+
+      this.audit.log({
+        type: EVENT_TYPES.APPROVAL_DENIED,
+        sessionId: context.sessionId,
+        tool: toolName,
+        args,
+      }).catch(() => {});
+
+      this.emit("tool:denied", { toolName, args, receipt, context });
+
+      return new HarnessResult({ result: { success: false, error: receipt.error, denied: true }, receipt, denied: true });
+    }
+
+    if (permResult.needsApproval) {
+      receipt.approved = permResult.approved;
+    }
+
+    // ── 2. Dry-run mode ──────────────────────────────────────────────────────
+    if (receipt.dryRun) {
+      const preview = simulateDryRun(toolName, args);
+
+      // For file edits in dry-run, compute the diff
+      if (FILE_SNAPSHOT_TOOLS.has(toolName)) {
+        const filePath = getFilePath(toolName, args);
+        if (filePath) {
+          const resolved = resolvePath(filePath);
+          let before = "";
+          try { before = await readFile(resolved, "utf8"); } catch {}
+
+          let after = before;
+          if (toolName === "write_file") {
+            after = args.content ?? "";
+          } else if (toolName === "file_edit") {
+            after = before.replace(args.old_text ?? "", args.new_text ?? "");
+          }
+
+          const unified = computeUnifiedDiff(before, after, filePath);
+          receipt.diff = { before, after, unified };
+          preview.diff = receipt.diff;
+        }
+      }
+
+      receipt.success = true;
+      receipt.result = preview;
+      receipt.duration = Date.now() - callStart;
+
+      this.emit("tool:dryrun", { toolName, args, preview, receipt, context });
+
+      return new HarnessResult({ result: preview, receipt, dryRun: true });
+    }
+
+    // ── 3. Pre-snapshot ──────────────────────────────────────────────────────
+    let beforeContent = null;
+    if (FILE_SNAPSHOT_TOOLS.has(toolName)) {
+      const filePath = getFilePath(toolName, args);
+      if (filePath) {
+        const resolved = resolvePath(filePath);
+        try { beforeContent = await readFile(resolved, "utf8"); } catch { beforeContent = ""; }
+      }
+    }
+
+    // ── 4. Emit tool:start ───────────────────────────────────────────────────
+    this.emit("tool:start", { toolName, args, context });
+
+    this.audit.log({
+      type: EVENT_TYPES.TOOL_CALL,
+      sessionId: context.sessionId,
+      tool: toolName,
+      args,
+      permissionLevel: receipt.permissionLevel,
+    }).catch(() => {});
+
+    // ── 5. Execute ───────────────────────────────────────────────────────────
+    let result;
+    try {
+      if (context.executeToolFn) {
+        result = await context.executeToolFn(toolName, args);
+      } else {
+        result = await this.tools.execute(toolName, args);
+      }
+      receipt.success = result?.success !== false;
+      receipt.result = result;
+    } catch (err) {
+      receipt.success = false;
+      receipt.error = err.message;
+      receipt.duration = Date.now() - callStart;
+
+      this.audit.log({
+        type: EVENT_TYPES.ERROR,
+        sessionId: context.sessionId,
+        tool: toolName,
+        message: err.message,
+        duration: receipt.duration,
+      }).catch(() => {});
+
+      this.emit("tool:error", { toolName, args, error: err, receipt, context });
+
+      return new HarnessResult({ result: { success: false, error: err.message }, receipt });
+    }
+
+    // ── 6. Post-snapshot ─────────────────────────────────────────────────────
+    if (FILE_SNAPSHOT_TOOLS.has(toolName) && receipt.success) {
+      const filePath = getFilePath(toolName, args);
+      if (filePath) {
+        const resolved = resolvePath(filePath);
+        let afterContent = "";
+        try { afterContent = await readFile(resolved, "utf8"); } catch {}
+
+        const unified = computeUnifiedDiff(beforeContent ?? "", afterContent, filePath);
+        receipt.diff = { before: beforeContent ?? "", after: afterContent, unified };
+      }
+    }
+
+    // ── 7. Duration ──────────────────────────────────────────────────────────
+    receipt.duration = Date.now() - callStart;
+
+    // ── 8. Audit ─────────────────────────────────────────────────────────────
+    this.audit.log({
+      type: EVENT_TYPES.TOOL_RESULT,
+      sessionId: context.sessionId,
+      tool: toolName,
+      result: JSON.stringify(result).slice(0, 500),
+      duration: receipt.duration,
+    }).catch(() => {});
+
+    // ── 9. Emit tool:complete ────────────────────────────────────────────────
+    this.emit("tool:complete", { toolName, args, result, receipt, context });
+
+    return new HarnessResult({ result, receipt });
+  }
+
+  /**
+   * Set sandbox mode for a tool.
+   * @param {string} toolName
+   * @param {"preview"|"diff"|null} mode
+   */
+  setSandboxMode(toolName, mode) {
+    this._sandboxModes[toolName] = mode;
+  }
+
+  getSandboxMode(toolName) {
+    return this._sandboxModes[toolName] ?? null;
+  }
+}

package/core/index.mjs

@@ -17,3 +17,5 @@ export { PermissionManager, DEFAULT_POLICIES, BUILT_IN_SCOPES } from "./permissi
 export { AuditLog, EVENT_TYPES, getAuditLog } from "./audit.mjs";
 export { WispyServer } from "./server.mjs";
 export { NodeManager, CAPABILITIES } from "./nodes.mjs";
+export { Harness, Receipt, HarnessResult, computeUnifiedDiff } from "./harness.mjs";
+export { DeployManager } from "./deploy.mjs";