jules-orchestrator-kit 0.29.0 → 0.31.0

package/src/ux/diff-viewer.mjs

@@ -0,0 +1,289 @@
+import { sanitizeControlChars } from "./renderer.mjs";
+import { clipText } from "./layout.mjs";
+
+/**
+ * @typedef {Object} DiffLine
+ * @property {"context" | "add" | "delete" | "header" | "no-newline"} kind
+ * @property {number} [oldLine]
+ * @property {number} [newLine]
+ * @property {string} text
+ */
+
+/**
+ * @typedef {Object} DiffHunk
+ * @property {string} header
+ * @property {number} oldStart
+ * @property {number} oldCount
+ * @property {number} newStart
+ * @property {number} newCount
+ * @property {DiffLine[]} lines
+ */
+
+/**
+ * @typedef {Object} DiffFile
+ * @property {string} oldPath
+ * @property {string} newPath
+ * @property {"added" | "modified" | "deleted" | "renamed" | "binary"} status
+ * @property {DiffHunk[]} hunks
+ * @property {number} additions
+ * @property {number} deletions
+ */
+
+/**
+ * @typedef {Object} DiffDocument
+ * @property {DiffFile[]} files
+ * @property {boolean} truncated
+ * @property {number} totalBytes
+ */
+
+/**
+ * Parse unified diff text into structured DiffDocument.
+ * @param {string} text
+ * @param {Object} [options]
+ * @param {number} [options.maxBytes=1000000]
+ * @param {number} [options.maxFiles=100]
+ * @param {number} [options.maxLines=5000]
+ * @returns {DiffDocument}
+ */
+export function parseUnifiedDiff(text, options = {}) {
+  const maxBytes = options.maxBytes ?? 1_000_000;
+  const maxFiles = options.maxFiles ?? 100;
+  const maxLines = options.maxLines ?? 5000;
+
+  let truncated = false;
+  text = typeof text === "string" ? text : String(text || "");
+  const totalBytes = Buffer.byteLength(text, "utf-8");
+  const byteLimit = Number.isFinite(maxBytes) ? Math.max(0, Math.floor(maxBytes)) : 1_000_000;
+
+  if (totalBytes > byteLimit) {
+    text = Buffer.from(text, "utf-8").subarray(0, byteLimit).toString("utf-8");
+    truncated = true;
+  }
+
+  const rawLines = text.split(/\r?\n/);
+  const files = [];
+
+  let currentFile = null;
+  let currentHunk = null;
+  let oldLineNum = 0;
+  let newLineNum = 0;
+  let lineCount = 0;
+
+  for (let rawIndex = 0; rawIndex < rawLines.length; rawIndex++) {
+    const rawLine = rawLines[rawIndex];
+    if (lineCount >= maxLines) {
+      truncated = true;
+      break;
+    }
+    lineCount++;
+
+    const line = sanitizeControlChars(rawLine);
+    if (line === "" && rawLine === "" && rawIndex === rawLines.length - 1) {
+      continue;
+    }
+
+    if (line.startsWith("diff --git ")) {
+      if (files.length >= maxFiles) {
+        truncated = true;
+        break;
+      }
+      const parts = line.split(" ");
+      const oldPath = parts[2] ? parts[2].replace(/^a\//, "") : "";
+      const newPath = parts[3] ? parts[3].replace(/^b\//, "") : "";
+
+      currentFile = {
+        oldPath,
+        newPath,
+        status: "modified",
+        hunks: [],
+        additions: 0,
+        deletions: 0,
+      };
+      files.push(currentFile);
+      currentHunk = null;
+      continue;
+    }
+
+    if (!currentFile && (line.startsWith("--- ") || line.startsWith("+++ "))) {
+      currentFile = {
+        oldPath: "",
+        newPath: "",
+        status: "modified",
+        hunks: [],
+        additions: 0,
+        deletions: 0,
+      };
+      files.push(currentFile);
+    }
+    if (!currentFile) continue;
+
+    if (!currentHunk && line.startsWith("--- ")) {
+      currentFile.oldPath = line.slice(4).replace(/^a\//, "");
+      continue;
+    }
+    if (!currentHunk && line.startsWith("+++ ")) {
+      currentFile.newPath = line.slice(4).replace(/^b\//, "");
+      continue;
+    }
+
+    if (line.startsWith("new file mode ")) {
+      currentFile.status = "added";
+      continue;
+    }
+    if (line.startsWith("deleted file mode ")) {
+      currentFile.status = "deleted";
+      continue;
+    }
+    if (line.startsWith("similarity index ") || line.startsWith("rename from ") || line.startsWith("rename to ")) {
+      currentFile.status = "renamed";
+      if (line.startsWith("rename from ")) currentFile.oldPath = line.slice("rename from ".length);
+      if (line.startsWith("rename to ")) currentFile.newPath = line.slice("rename to ".length);
+      continue;
+    }
+    if (line.startsWith("Binary files ")) {
+      currentFile.status = "binary";
+      continue;
+    }
+
+    // Hunk header: @@ -oldStart,oldCount +newStart,newCount @@
+    const hunkMatch = line.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
+    if (hunkMatch) {
+      oldLineNum = parseInt(hunkMatch[1], 10);
+      const oldCount = hunkMatch[2] !== undefined ? parseInt(hunkMatch[2], 10) : 1;
+      newLineNum = parseInt(hunkMatch[3], 10);
+      const newCount = hunkMatch[4] !== undefined ? parseInt(hunkMatch[4], 10) : 1;
+
+      currentHunk = {
+        header: line,
+        oldStart: oldLineNum,
+        oldCount,
+        newStart: newLineNum,
+        newCount,
+        lines: [],
+      };
+      currentFile.hunks.push(currentHunk);
+      continue;
+    }
+
+    if (!currentHunk) continue;
+
+    if (line.startsWith("+")) {
+      currentFile.additions++;
+      currentHunk.lines.push({
+        kind: "add",
+        newLine: newLineNum++,
+        text: line.slice(1),
+      });
+    } else if (line.startsWith("-")) {
+      currentFile.deletions++;
+      currentHunk.lines.push({
+        kind: "delete",
+        oldLine: oldLineNum++,
+        text: line.slice(1),
+      });
+    } else if (line.startsWith("\\ No newline")) {
+      currentHunk.lines.push({
+        kind: "no-newline",
+        text: line,
+      });
+    } else {
+      currentHunk.lines.push({
+        kind: "context",
+        oldLine: oldLineNum++,
+        newLine: newLineNum++,
+        text: line.startsWith(" ") ? line.slice(1) : line,
+      });
+    }
+  }
+
+  return { files, truncated, totalBytes };
+}
+
+/**
+ * Render unified diff view frame.
+ * @param {DiffDocument} document
+ * @param {Record<string, any>} state
+ * @param {import("./capabilities.mjs").TerminalCapabilities} caps
+ * @returns {import("./renderer.mjs").RenderFrame}
+ */
+export function renderDiffView(document, state, caps) {
+  const width = caps.columns || 80;
+  const height = caps.rows || 24;
+
+  const fileIdx = Math.max(0, Math.min((document.files.length || 1) - 1, state.fileIdx || 0));
+  const currentFile = document.files[fileIdx];
+
+  const lines = [];
+
+  // Header line
+  const title = ` Diff · File [${fileIdx + 1}/${document.files.length || 0}] ${currentFile ? currentFile.newPath || currentFile.oldPath : ""} `;
+  lines.push({
+    runs: [
+      { text: clipText(title, width), style: { fg: "cyan", bold: true, inverse: true } },
+    ],
+  });
+
+  if (!currentFile) {
+    lines.push({ runs: [{ text: "No files changed.", style: { dim: true } }] });
+    return { width, height, lines };
+  }
+
+  // File summary line
+  const metaStr = ` Status: ${currentFile.status.toUpperCase()}  +${currentFile.additions} -${currentFile.deletions} `;
+  lines.push({ runs: [{ text: metaStr, style: { fg: "yellow" } }] });
+
+  let lineOffset = state.lineOffset || 0;
+  let renderCount = 0;
+  const maxBodyLines = height - 3;
+
+  for (const hunk of currentFile.hunks) {
+    if (renderCount >= maxBodyLines) break;
+
+    // Hunk header line
+    lines.push({
+      runs: [{ text: clipText(hunk.header, width), style: { fg: "cyan", dim: true } }],
+    });
+    renderCount++;
+
+    for (const line of hunk.lines) {
+      if (renderCount >= maxBodyLines) break;
+
+      if (lineOffset > 0) {
+        lineOffset--;
+        continue;
+      }
+
+      const oldNumStr = line.oldLine !== undefined ? String(line.oldLine).padStart(5) : "     ";
+      const newNumStr = line.newLine !== undefined ? String(line.newLine).padStart(5) : "     ";
+      const numCol = `${oldNumStr} | ${newNumStr} | `;
+
+      /** @type {import("./renderer.mjs").TextStyle} */
+      let style = { fg: "default" };
+      let prefix = " ";
+
+      if (line.kind === "add") {
+        style = { fg: "green" };
+        prefix = "+";
+      } else if (line.kind === "delete") {
+        style = { fg: "red" };
+        prefix = "-";
+      }
+
+      const lineText = clipText(`${numCol}${prefix}${line.text}`, width);
+      lines.push({ runs: [{ text: lineText, style }] });
+      renderCount++;
+    }
+  }
+
+  // Footer keybindings line
+  lines.push({
+    runs: [
+      {
+        text: clipText("[/]: switch file  n/N: hunk  Up/Down: scroll  q: exit", width),
+        style: { fg: "cyan", dim: true },
+      },
+    ],
+  });
+
+  return { width, height, lines };
+}

package/src/ux/key-decoder.mjs

@@ -0,0 +1,281 @@
+import { StringDecoder } from "node:string_decoder";
+
+/**
+ * @typedef {"up" | "down" | "left" | "right" | "page-up" | "page-down" | "home" | "end" | "space" | "enter" | "tab" | "shift-tab" | "escape" | "ctrl-c" | "backspace" | "delete" | "character" | "unknown"} KeyName
+ */
+
+/**
+ * @typedef {Object} KeyEvent
+ * @property {KeyName} name
+ * @property {string} sequence
+ * @property {string} [text]
+ * @property {boolean} ctrl
+ * @property {boolean} alt
+ * @property {boolean} shift
+ * @property {number} timestampMs
+ */
+
+const SEQUENCE_MAP = new Map([
+  // Arrow keys
+  ["\x1b[A", { name: "up", ctrl: false, alt: false, shift: false }],
+  ["\x1bOA", { name: "up", ctrl: false, alt: false, shift: false }],
+  ["\x1b[B", { name: "down", ctrl: false, alt: false, shift: false }],
+  ["\x1bOB", { name: "down", ctrl: false, alt: false, shift: false }],
+  ["\x1b[C", { name: "right", ctrl: false, alt: false, shift: false }],
+  ["\x1bOC", { name: "right", ctrl: false, alt: false, shift: false }],
+  ["\x1b[D", { name: "left", ctrl: false, alt: false, shift: false }],
+  ["\x1bOD", { name: "left", ctrl: false, alt: false, shift: false }],
+
+  // Home / End
+  ["\x1b[H", { name: "home", ctrl: false, alt: false, shift: false }],
+  ["\x1bOH", { name: "home", ctrl: false, alt: false, shift: false }],
+  ["\x1b[1~", { name: "home", ctrl: false, alt: false, shift: false }],
+  ["\x1b[7~", { name: "home", ctrl: false, alt: false, shift: false }],
+  ["\x1b[F", { name: "end", ctrl: false, alt: false, shift: false }],
+  ["\x1bOF", { name: "end", ctrl: false, alt: false, shift: false }],
+  ["\x1b[4~", { name: "end", ctrl: false, alt: false, shift: false }],
+  ["\x1b[8~", { name: "end", ctrl: false, alt: false, shift: false }],
+
+  // Navigation
+  ["\x1b[5~", { name: "page-up", ctrl: false, alt: false, shift: false }],
+  ["\x1b[6~", { name: "page-down", ctrl: false, alt: false, shift: false }],
+  ["\x1b[Z", { name: "shift-tab", ctrl: false, alt: false, shift: true }],
+  ["\x1b[3~", { name: "delete", ctrl: false, alt: false, shift: false }],
+
+  // Single-byte controls
+  ["\r", { name: "enter", ctrl: false, alt: false, shift: false }],
+  ["\n", { name: "enter", ctrl: false, alt: false, shift: false }],
+  ["\t", { name: "tab", ctrl: false, alt: false, shift: false }],
+  ["\x03", { name: "ctrl-c", ctrl: true, alt: false, shift: false }],
+  ["\x7f", { name: "backspace", ctrl: false, alt: false, shift: false }],
+  ["\x08", { name: "backspace", ctrl: false, alt: false, shift: false }],
+  [" ", { name: "space", text: " ", ctrl: false, alt: false, shift: false }],
+]);
+
+/**
+ * Create an incremental sequence key decoder.
+ * @param {Object} [options]
+ * @param {number} [options.escapeTimeoutMs=30]
+ * @param {number} [options.maxBufferBytes=1024]
+ */
+export function createKeyDecoder(options = {}) {
+  const escapeTimeoutMs = options.escapeTimeoutMs ?? 30;
+  const maxBufferBytes = options.maxBufferBytes ?? 1024;
+
+  const utf8Decoder = new StringDecoder("utf8");
+  let buffer = "";
+  let lastTimeMs = 0;
+
+  function appendChunk(chunk) {
+    if (Buffer.isBuffer(chunk) || chunk instanceof Uint8Array) {
+      buffer += utf8Decoder.write(chunk);
+    } else if (chunk !== null && chunk !== undefined) {
+      buffer += String(chunk);
+    }
+
+    while (Buffer.byteLength(buffer, "utf8") > maxBufferBytes) {
+      const firstCodePoint = buffer.codePointAt(0);
+      buffer = buffer.slice(firstCodePoint > 0xffff ? 2 : 1);
+    }
+  }
+
+  /**
+   * Process a single token from buffer.
+   * @param {number} nowMs
+   * @returns {{ event: KeyEvent, consumed: number } | null}
+   */
+  function tryDecodeToken(nowMs) {
+    if (!buffer) return null;
+
+    // Check exact sequence mappings
+    for (const [seq, meta] of SEQUENCE_MAP.entries()) {
+      if (buffer.startsWith(seq)) {
+        return {
+          event: {
+            name: meta.name,
+            sequence: seq,
+            text: meta.text,
+            ctrl: meta.ctrl,
+            alt: meta.alt,
+            shift: meta.shift,
+            timestampMs: nowMs,
+          },
+          consumed: seq.length,
+        };
+      }
+    }
+
+    // Handle ESC prefix sequences
+    if (buffer[0] === "\x1b") {
+      if (buffer === "\x1b") {
+        // Wait for timeout to distinguish standalone ESC
+        if (nowMs - lastTimeMs >= escapeTimeoutMs) {
+          return {
+            event: {
+              name: "escape",
+              sequence: "\x1b",
+              ctrl: false,
+              alt: false,
+              shift: false,
+              timestampMs: nowMs,
+            },
+            consumed: 1,
+          };
+        }
+        // Needs more input
+        return null;
+      }
+
+      // CSI or SS3 sequence parsing: ESC [ ... or ESC O ...
+      if (buffer[1] === "[" || buffer[1] === "O") {
+        let idx = 2;
+        while (idx < buffer.length) {
+          const charCode = buffer.charCodeAt(idx);
+          // Sequence terminator char is usually between 0x40 ('@') and 0x7E ('~')
+          if (charCode >= 0x40 && charCode <= 0x7e) {
+            const seq = buffer.slice(0, idx + 1);
+            const matched = SEQUENCE_MAP.get(seq);
+            if (matched) {
+              return {
+                event: {
+                  name: matched.name,
+                  sequence: seq,
+                  text: matched.text,
+                  ctrl: matched.ctrl,
+                  alt: matched.alt,
+                  shift: matched.shift,
+                  timestampMs: nowMs,
+                },
+                consumed: seq.length,
+              };
+            }
+            // Unknown CSI/SS3 sequence - sanitize and emit as unknown
+            return {
+              event: {
+                name: "unknown",
+                sequence: seq,
+                text: seq.replace(/\x1b/g, "^["),
+                ctrl: false,
+                alt: false,
+                shift: false,
+                timestampMs: nowMs,
+              },
+              consumed: seq.length,
+            };
+          }
+          idx++;
+        }
+        // Incomplete CSI/SS3 sequence in buffer, wait unless buffer exceeded cap
+        if (Buffer.byteLength(buffer, "utf8") < maxBufferBytes) {
+          return null;
+        }
+      }
+
+      // Alt+Character (ESC followed by a single printable character)
+      const altChar = Array.from(buffer.slice(1))[0];
+      if (altChar && altChar.codePointAt(0) >= 0x20 && altChar.codePointAt(0) <= 0x7e) {
+        const seq = `\x1b${altChar}`;
+        return {
+          event: {
+            name: altChar === " " ? "space" : "character",
+            sequence: seq,
+            text: altChar,
+            ctrl: false,
+            alt: true,
+            shift: false,
+            timestampMs: nowMs,
+          },
+          consumed: seq.length,
+        };
+      }
+    }
+
+    // Ctrl+Key (ASCII 1..26 except TAB \t, CR \r, LF \n, ETX \x03)
+    const code = buffer.charCodeAt(0);
+    if (code >= 1 && code <= 26 && code !== 9 && code !== 10 && code !== 13) {
+      const char = String.fromCharCode(code + 96);
+      return {
+        event: {
+          name: "character",
+          sequence: buffer[0],
+          text: char,
+          ctrl: true,
+          alt: false,
+          shift: false,
+          timestampMs: nowMs,
+        },
+        consumed: 1,
+      };
+    }
+
+    // Printable single character or Unicode scalar
+    const firstCodePoint = buffer.codePointAt(0) || 0;
+    const firstChar = String.fromCodePoint(firstCodePoint);
+    if (firstCodePoint >= 0x20) {
+      return {
+        event: {
+          name: firstChar === " " ? "space" : "character",
+          sequence: firstChar,
+          text: firstChar,
+          ctrl: false,
+          alt: false,
+          shift: false,
+          timestampMs: nowMs,
+        },
+        consumed: firstChar.length,
+      };
+    }
+
+    // Fallback unknown control byte
+    return {
+      event: {
+        name: "unknown",
+        sequence: firstChar,
+        ctrl: false,
+        alt: false,
+        shift: false,
+        timestampMs: nowMs,
+      },
+      consumed: firstChar.length,
+    };
+  }
+
+  return {
+    /**
+     * Push incoming chunk bytes/string and return decoded KeyEvents.
+     * @param {Buffer | string} chunk
+     * @param {number} [nowMs]
+     * @returns {KeyEvent[]}
+     */
+    push(chunk, nowMs = Date.now()) {
+      appendChunk(chunk);
+      lastTimeMs = nowMs;
+
+      const events = [];
+      let result = tryDecodeToken(nowMs);
+      while (result) {
+        events.push(result.event);
+        buffer = buffer.slice(result.consumed);
+        result = tryDecodeToken(nowMs);
+      }
+      return events;
+    },
+
+    /**
+     * Flush remaining buffer (e.g. after timeout).
+     * @param {number} [nowMs]
+     * @returns {KeyEvent[]}
+     */
+    flush(nowMs = Date.now()) {
+      const events = [];
+      let result = tryDecodeToken(nowMs + escapeTimeoutMs + 1);
+      while (result) {
+        events.push(result.event);
+        buffer = buffer.slice(result.consumed);
+        result = tryDecodeToken(nowMs + escapeTimeoutMs + 1);
+      }
+      buffer = "";
+      return events;
+    },
+  };
+}