march-cli 0.1.0

package/src/session/tree.mjs

@@ -0,0 +1,42 @@
+export function buildSessionTree(sessions) {
+  const nodes = new Map();
+  for (const session of sessions) {
+    nodes.set(session.id, { ...session, children: [] });
+  }
+
+  const roots = [];
+  for (const node of nodes.values()) {
+    const parent = node.parentSessionId ? nodes.get(node.parentSessionId) : null;
+    if (parent) {
+      parent.children.push(node);
+    } else {
+      roots.push(node);
+    }
+  }
+
+  const bySavedAtDesc = (a, b) => (b.savedAt ?? "").localeCompare(a.savedAt ?? "");
+  const sortDeep = (items) => {
+    items.sort(bySavedAtDesc);
+    for (const item of items) sortDeep(item.children);
+  };
+  sortDeep(roots);
+  return roots;
+}
+
+export function formatSessionTree(sessions, currentSessionId = null) {
+  const roots = buildSessionTree(sessions);
+  if (roots.length === 0) return ["(no saved sessions)"];
+
+  const lines = [];
+  const visit = (node, depth) => {
+    const marker = node.id === currentSessionId ? "*" : "-";
+    const savedAt = node.savedAt?.slice(0, 19) ?? "?";
+    const indent = "  ".repeat(depth);
+    lines.push(`${indent}${marker} ${node.id}  ${node.turnCount ?? 0}t  ${savedAt}`);
+    for (const child of node.children) visit(child, depth + 1);
+  };
+
+  for (const root of roots) visit(root, 0);
+  lines.push("(* = current session)");
+  return lines;
+}

package/src/shell/cli-runtime.mjs

@@ -0,0 +1,11 @@
+import { createShellRuntime } from "./runtime.mjs";
+import { createNodePtyAdapterFactory } from "./node-pty-adapter.mjs";
+
+export function createCliShellRuntime({ cwd = process.cwd(), env = process.env } = {}) {
+  return createShellRuntime({
+    createPty: createNodePtyAdapterFactory({
+      defaultCwd: cwd,
+      defaultEnv: env,
+    }),
+  });
+}

package/src/shell/hints.mjs

@@ -0,0 +1,12 @@
+export function formatShellHints(shellRuntime, { limit = 5 } = {}) {
+  const shells = (shellRuntime?.listShells?.() ?? []).filter((shell) => shell.status !== "killed").slice(0, limit);
+  if (shells.length === 0) return "";
+  const lines = ["[shell_hints]"];
+  for (const shell of shells) {
+    const args = shell.args?.length ? ` ${shell.args.join(" ")}` : "";
+    const count = shell.scrollbackLineCount ?? shell.lineCount ?? 0;
+    lines.push(`- ${shell.id} ${shell.name} ${shell.status} command: ${shell.command}${args} cwd: ${shell.cwd} lines: ${count}`);
+  }
+  lines.push("Use terminal_read or terminal_snapshot to inspect shell output.");
+  return lines.join("\n");
+}

package/src/shell/node-pty-adapter.mjs

@@ -0,0 +1,81 @@
+import pty from "node-pty";
+
+export function createNodePtyAdapterFactory({
+  ptyModule = pty,
+  defaultCwd = process.cwd(),
+  defaultEnv = process.env,
+  platform = process.platform,
+} = {}) {
+  return function createNodePtyAdapter({
+    command,
+    args = [],
+    cwd = defaultCwd,
+    env = defaultEnv,
+    cols = 80,
+    rows = 24,
+    onData,
+    onExit,
+    onError,
+  }) {
+    const resolved = resolveShellCommand({ command, args, platform });
+    let term;
+    try {
+      term = ptyModule.spawn(resolved.command, resolved.args, {
+        name: "xterm-color",
+        cols,
+        rows,
+        cwd,
+        env,
+      });
+    } catch (error) {
+      onError?.(error);
+      throw error;
+    }
+
+    let disposed = false;
+    const disposeTerminal = () => {
+      if (disposed) return;
+      disposed = true;
+      // node-pty's Windows kill path can emit noisy AttachConsole failures after
+      // a natural exit. Closing the backing socket releases Node handles without
+      // forcing the PTY helper down the kill path.
+      if (typeof term._socket?.destroy === "function") {
+        term._socket.destroy();
+      } else if (typeof term.destroy === "function") {
+        term.destroy();
+      } else if (typeof term.kill === "function") {
+        term.kill();
+      }
+    };
+
+    term.onData?.((chunk) => onData?.(chunk));
+    term.onExit?.((event) => {
+      onExit?.(event);
+      disposeTerminal();
+    });
+
+    return {
+      write: (text) => term.write(String(text ?? "")),
+      resize: (nextCols, nextRows) => term.resize?.(nextCols, nextRows),
+      kill: () => disposeTerminal(),
+      dispose: () => disposeTerminal(),
+    };
+  };
+}
+
+export function resolveShellCommand({ command, args = [], platform = process.platform }) {
+  if (command) return { command: normalizeWindowsShellCommand(command, platform), args: [...args] };
+  if (platform === "win32") {
+    return { command: "powershell.exe", args: ["-NoLogo", "-NoProfile"] };
+  }
+  return { command: process.env.SHELL || "sh", args: [] };
+}
+
+function normalizeWindowsShellCommand(command, platform) {
+  if (platform !== "win32") return command;
+  const normalized = String(command).trim().toLowerCase();
+  if (normalized === "powershell") return "powershell.exe";
+  if (normalized === "pwsh") return "pwsh.exe";
+  if (normalized === "cmd") return "cmd.exe";
+  return command;
+}

package/src/shell/runtime-state.mjs

@@ -0,0 +1,126 @@
+const OSC_RE = /\x1b\][^\x07]*(?:\x07|\x1b\\)/g;
+const ANSI_RE = /\x1b(?:\][^\x07]*(?:\x07|\x1b\\)|[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g;
+
+export function findShellIdByName(shells, name) {
+  for (const shell of shells.values()) {
+    if (shell.name === name) return shell.id;
+  }
+  return null;
+}
+
+export function closeShellForReplacement(shells, shell) {
+  try {
+    shell.pty?.kill?.();
+    shell.screen?.dispose?.();
+  } finally {
+    shells.delete(shell.id);
+  }
+}
+
+export function stripAnsi(text) {
+  return String(text ?? "").replace(ANSI_RE, "");
+}
+
+export function appendOutput(shell, chunk, maxScrollbackLines) {
+  const raw = stripControlPayloads(String(chunk ?? ""));
+  shell.screen?.write?.(raw);
+  shell.rawChunks.push(raw);
+  if (shell.rawChunks.length > maxScrollbackLines * 4) {
+    shell.rawChunks = shell.rawChunks.slice(-(maxScrollbackLines * 4));
+  }
+
+  const plain = stripAnsi(raw).replace(/\r/g, "");
+  for (const line of plain.split("\n")) {
+    if (line === "") continue;
+    shell.plainLines.push(line);
+  }
+  if (shell.plainLines.length > maxScrollbackLines) {
+    shell.plainLines = shell.plainLines.slice(-maxScrollbackLines);
+  }
+}
+
+export function isPromptNoise(line, shell) {
+  const text = String(line ?? "").trim();
+  if (!text) return false;
+  if (process.platform === "win32" || /powershell|pwsh|cmd/i.test(shell.command)) {
+    if (/^(PS [A-Za-z]:\\.*>|[A-Za-z]:\\.*>)\s*$/.test(text)) return true;
+    if (/^(PS [A-Za-z]:\\.*>|[A-Za-z]:\\.*>)\s+/.test(text)) return true;
+  }
+  return /^[^#$>\n]{0,80}[$#>]\s*$/.test(text);
+}
+
+export function markExited(shell, event) {
+  if (shell.status === "killed") return;
+  shell.status = "exited";
+  shell.exitCode = event.exitCode ?? null;
+  shell.signal = event.signal ?? null;
+  shell.updatedAt = new Date().toISOString();
+}
+
+export function markFailed(shell, error) {
+  shell.status = "failed";
+  shell.error = error?.message ?? String(error);
+  shell.updatedAt = new Date().toISOString();
+}
+
+export function touch(shell, now) {
+  shell.updatedAt = now().toISOString();
+}
+
+export function requireShell(shells, id) {
+  const shell = shells.get(id);
+  if (!shell) throw new Error(`shell not found: ${id}`);
+  return shell;
+}
+
+export function publicShell(shell) {
+  const screenSnapshot = shell.screen?.snapshot?.() ?? null;
+  const visibleLineCount = screenSnapshot?.plain
+    ? screenSnapshot.plain.split("\n").filter((line) => line.length > 0).length
+    : 0;
+  return {
+    id: shell.id,
+    name: shell.name,
+    command: shell.command,
+    args: [...shell.args],
+    cwd: shell.cwd,
+    status: shell.status,
+    exitCode: shell.exitCode,
+    signal: shell.signal,
+    error: shell.error,
+    cols: shell.cols,
+    rows: shell.rows,
+    createdAt: shell.createdAt,
+    updatedAt: shell.updatedAt,
+    lineCount: shell.plainLines.length,
+    scrollbackLineCount: shell.plainLines.length,
+    visibleLineCount,
+  };
+}
+
+export function normalizeSize({ cols, rows, fallbackCols, fallbackRows }) {
+  return {
+    cols: normalizePositiveInt(cols, fallbackCols),
+    rows: normalizePositiveInt(rows, fallbackRows),
+  };
+}
+
+export function uniqueName(baseName, shells) {
+  const normalized = String(baseName || "shell").trim() || "shell";
+  const names = new Set([...shells.values()].map((shell) => shell.name));
+  if (!names.has(normalized)) return normalized;
+  for (let index = 2; ; index++) {
+    const candidate = `${normalized}-${index}`;
+    if (!names.has(candidate)) return candidate;
+  }
+}
+
+function stripControlPayloads(text) {
+  return String(text ?? "").replace(OSC_RE, "");
+}
+
+function normalizePositiveInt(value, fallback) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number <= 0) return Math.max(1, Math.trunc(Number(fallback) || 1));
+  return Math.max(1, Math.trunc(number));
+}

package/src/shell/runtime.mjs

@@ -0,0 +1,244 @@
+import { randomUUID } from "node:crypto";
+import { createTerminalScreenBuffer } from "./screen-buffer.mjs";
+import {
+  appendOutput,
+  closeShellForReplacement,
+  findShellIdByName,
+  isPromptNoise,
+  markExited,
+  markFailed,
+  normalizeSize,
+  publicShell,
+  requireShell,
+  stripAnsi,
+  touch,
+  uniqueName,
+} from "./runtime-state.mjs";
+
+export { stripAnsi } from "./runtime-state.mjs";
+
+export function createShellRuntime({
+  createPty,
+  now = () => new Date(),
+  maxScrollbackLines = 200,
+  idFactory = () => randomUUID().slice(0, 8),
+  defaultCommand = process.platform === "win32" ? "powershell.exe" : process.env.SHELL || "sh",
+  defaultArgs = process.platform === "win32" ? ["-NoLogo", "-NoProfile"] : [],
+  defaultCols = 120,
+  defaultRows = 24,
+  createScreenBuffer = createTerminalScreenBuffer,
+} = {}) {
+  if (typeof createPty !== "function") {
+    throw new Error("createPty is required");
+  }
+
+  const shells = new Map();
+
+  function spawnShell({
+    name,
+    command,
+    args = [],
+    cwd = process.cwd(),
+    env = process.env,
+    cols = defaultCols,
+    rows = defaultRows,
+    nameConflict = "suffix",
+  } = {}) {
+    const resolvedCommand = command || defaultCommand;
+    const resolvedArgs = command ? args : (args.length ? args : defaultArgs);
+    const baseName = String(name || resolvedCommand || "shell").trim() || "shell";
+    const existing = shells.get(findShellIdByName(shells, baseName));
+    if (existing && nameConflict === "reuse") {
+      return publicShell(existing);
+    }
+    if (existing && nameConflict === "replace") {
+      closeShellForReplacement(shells, existing);
+    }
+    const size = normalizeSize({ cols, rows, fallbackCols: defaultCols, fallbackRows: defaultRows });
+    const id = idFactory();
+    const shell = {
+      id,
+      name: uniqueName(baseName, shells),
+      command: resolvedCommand,
+      args: [...resolvedArgs],
+      cwd,
+      status: "starting",
+      exitCode: null,
+      signal: null,
+      error: null,
+      cols: size.cols,
+      rows: size.rows,
+      createdAt: now().toISOString(),
+      updatedAt: now().toISOString(),
+      rawChunks: [],
+      plainLines: [],
+      screen: createScreenBuffer({ cols: size.cols, rows: size.rows }),
+      pty: null,
+    };
+    shells.set(id, shell);
+
+    try {
+      shell.pty = createPty({
+        command: resolvedCommand,
+        args: shell.args,
+        cwd,
+        env,
+        cols: shell.cols,
+        rows: shell.rows,
+        onData: (chunk) => appendOutput(shell, chunk, maxScrollbackLines),
+        onExit: (event = {}) => markExited(shell, event),
+        onError: (error) => markFailed(shell, error),
+      });
+      shell.status = "running";
+      touch(shell, now);
+    } catch (error) {
+      markFailed(shell, error);
+    }
+
+    return publicShell(shell);
+  }
+
+  function sendShell(id, text) {
+    const shell = requireShell(shells, id);
+    if (shell.status !== "running") {
+      return { ok: false, error: `shell ${id} is ${shell.status}`, shell: publicShell(shell) };
+    }
+    shell.pty.write(String(text ?? ""));
+    touch(shell, now);
+    return { ok: true, shell: publicShell(shell) };
+  }
+
+  function resizeShell(id, { cols, rows } = {}) {
+    const shell = requireShell(shells, id);
+    const size = normalizeSize({ cols, rows, fallbackCols: shell.cols, fallbackRows: shell.rows });
+    if (shell.cols === size.cols && shell.rows === size.rows) {
+      return { ok: true, changed: false, shell: publicShell(shell) };
+    }
+    if (shell.status !== "running" && shell.status !== "starting") {
+      return { ok: false, changed: false, error: `shell ${id} is ${shell.status}`, shell: publicShell(shell) };
+    }
+    if (typeof shell.pty?.resize !== "function") {
+      return { ok: false, changed: false, error: `shell ${id} does not support resize`, shell: publicShell(shell) };
+    }
+    try {
+      shell.pty.resize(size.cols, size.rows);
+    } catch (error) {
+      shell.status = "failed";
+      shell.error = `resize failed: ${error?.message ?? String(error)}`;
+      touch(shell, now);
+      return { ok: false, changed: true, error: shell.error, shell: publicShell(shell) };
+    }
+    shell.cols = size.cols;
+    shell.rows = size.rows;
+    shell.screen?.resize?.(shell.cols, shell.rows);
+    touch(shell, now);
+    return { ok: true, changed: true, shell: publicShell(shell) };
+  }
+
+  function killShell(id) {
+    const shell = requireShell(shells, id);
+    if (shell.status !== "running" && shell.status !== "starting") {
+      return { ok: false, error: `shell ${id} is ${shell.status}`, shell: publicShell(shell) };
+    }
+    shell.status = "killed";
+    touch(shell, now);
+    try {
+      shell.pty?.kill?.();
+    } catch (error) {
+      shell.status = "failed";
+      shell.error = `kill failed: ${error?.message ?? String(error)}`;
+      touch(shell, now);
+      return { ok: false, error: shell.error, shell: publicShell(shell) };
+    }
+    return { ok: true, shell: publicShell(shell) };
+  }
+
+  function listShells() {
+    return [...shells.values()].map(publicShell);
+  }
+
+  function getShell(id) {
+    const shell = shells.get(id);
+    return shell ? publicShell(shell) : null;
+  }
+
+  function searchShell(id, pattern, { source = "auto", includePrompts = false } = {}) {
+    const shell = requireShell(shells, id);
+    const needle = String(pattern ?? "");
+    const screenLines = shell.screen?.snapshot?.().plain?.split("\n") ?? [];
+    const scrollbackLines = shell.plainLines;
+    const lines = source === "screen" ? screenLines : source === "scrollback" ? scrollbackLines : screenLines;
+    let matches = findLineMatches(lines, needle, shell, includePrompts);
+    let resolvedSource = source === "auto" ? "screen" : source;
+    if (source === "auto" && matches.length === 0) {
+      matches = findLineMatches(scrollbackLines, needle, shell, includePrompts);
+      resolvedSource = "scrollback";
+    }
+    return { shell: publicShell(shell), matches, source: resolvedSource };
+  }
+
+  function findLineMatches(lines, needle, shell, includePrompts) {
+    return lines
+      .map((line, index) => ({ index, line }))
+      .filter(({ line }) => includePrompts || !isPromptNoise(line, shell))
+      .filter(({ line }) => line.includes(needle));
+  }
+
+  function snapshotShell(id) {
+    const shell = requireShell(shells, id);
+    return {
+      shell: publicShell(shell),
+      ansi: shell.rawChunks.join(""),
+      plain: shell.plainLines.join("\n"),
+      screen: shell.screen?.snapshot?.() ?? null,
+    };
+  }
+
+  function clearShell(id) {
+    const shell = requireShell(shells, id);
+    shell.rawChunks = [];
+    shell.plainLines = [];
+    shell.screen?.dispose?.();
+    shell.screen = createScreenBuffer({ cols: shell.cols, rows: shell.rows });
+    touch(shell, now);
+    return { ok: true, shell: publicShell(shell) };
+  }
+
+  function killAll() {
+    const results = [];
+    for (const shell of shells.values()) {
+      if (shell.status === "running" || shell.status === "starting") {
+        results.push(killShell(shell.id));
+      }
+    }
+    return results;
+  }
+
+  function dispose() {
+    const results = killAll();
+    for (const shell of shells.values()) {
+      try {
+        shell.pty?.dispose?.();
+        shell.screen?.dispose?.();
+      } catch (error) {
+        shell.error = `dispose failed: ${error?.message ?? String(error)}`;
+        touch(shell, now);
+      }
+    }
+    return results;
+  }
+
+  return {
+    spawnShell,
+    sendShell,
+    resizeShell,
+    killShell,
+    killAll,
+    listShells,
+    getShell,
+    searchShell,
+    snapshotShell,
+    clearShell,
+    dispose,
+  };
+}

package/src/shell/screen-buffer.mjs

@@ -0,0 +1,136 @@
+import headless from "@xterm/headless";
+
+const { Terminal } = headless;
+
+export function createTerminalScreenBuffer({ cols = 80, rows = 24 } = {}) {
+  const terminal = new Terminal({
+    allowProposedApi: true,
+    cols: normalizePositiveInt(cols, 80),
+    rows: normalizePositiveInt(rows, 24),
+    scrollback: 0,
+  });
+
+  let pendingWrites = 0;
+
+  return {
+    write(data) {
+      pendingWrites += 1;
+      terminal.write(String(data ?? ""), () => {
+        pendingWrites = Math.max(0, pendingWrites - 1);
+      });
+    },
+    resize(nextCols, nextRows) {
+      terminal.resize(
+        normalizePositiveInt(nextCols, terminal.cols),
+        normalizePositiveInt(nextRows, terminal.rows),
+      );
+    },
+    snapshot() {
+      const lines = readViewportLines(terminal);
+      return {
+        cols: terminal.cols,
+        rows: terminal.rows,
+        pendingWrites,
+        plain: lines.map((line) => line.plain).join("\n"),
+        ansi: lines.map((line) => line.ansi).join("\n"),
+      };
+    },
+    dispose() {
+      terminal.dispose();
+    },
+  };
+}
+
+function readViewportLines(terminal) {
+  const buffer = terminal.buffer.active;
+  const start = buffer.baseY;
+  const rows = [];
+  for (let y = start; y < start + terminal.rows; y++) {
+    const line = buffer.getLine(y);
+    rows.push(line ? lineToSnapshot(line) : { plain: "", ansi: "" });
+  }
+  return trimTrailingBlankRows(rows);
+}
+
+function lineToSnapshot(line) {
+  const end = findContentEnd(line);
+  if (end === 0) return { plain: "", ansi: "" };
+
+  const plain = line.translateToString(false, 0, end);
+  let ansi = "";
+  let activeStyle = "";
+  for (let x = 0; x < end; x++) {
+    const cell = line.getCell(x);
+    if (!cell || cell.getWidth() === 0) continue;
+    const chars = cell.getChars() || " ";
+    const style = cellToSgr(cell);
+    if (style !== activeStyle) {
+      if (activeStyle) ansi += "\x1b[0m";
+      if (style) ansi += style;
+      activeStyle = style;
+    }
+    ansi += chars;
+  }
+  if (activeStyle) ansi += "\x1b[0m";
+  return { plain, ansi };
+}
+
+function findContentEnd(line) {
+  for (let x = line.length - 1; x >= 0; x--) {
+    const cell = line.getCell(x);
+    if (cell?.getChars()) return x + cell.getWidth();
+  }
+  return 0;
+}
+
+function cellToSgr(cell) {
+  if (cell.isAttributeDefault()) return "";
+  const codes = [];
+  if (cell.isBold()) codes.push(1);
+  if (cell.isDim()) codes.push(2);
+  if (cell.isItalic()) codes.push(3);
+  if (cell.isUnderline()) codes.push(4);
+  if (cell.isBlink()) codes.push(5);
+  if (cell.isInverse()) codes.push(7);
+  if (cell.isInvisible()) codes.push(8);
+  if (cell.isStrikethrough()) codes.push(9);
+  if (cell.isOverline()) codes.push(53);
+  pushColorCodes(codes, cell, "fg");
+  pushColorCodes(codes, cell, "bg");
+  return codes.length ? `\x1b[${codes.join(";")}m` : "";
+}
+
+function pushColorCodes(codes, cell, target) {
+  const isFg = target === "fg";
+  const isDefault = isFg ? cell.isFgDefault() : cell.isBgDefault();
+  if (isDefault) return;
+
+  const color = isFg ? cell.getFgColor() : cell.getBgColor();
+  const base = isFg ? 30 : 40;
+  const brightBase = isFg ? 90 : 100;
+  if (isFg ? cell.isFgRGB() : cell.isBgRGB()) {
+    codes.push(isFg ? 38 : 48, 2, (color >> 16) & 255, (color >> 8) & 255, color & 255);
+    return;
+  }
+  if (isFg ? cell.isFgPalette() : cell.isBgPalette()) {
+    if (color < 8) {
+      codes.push(base + color);
+    } else if (color < 16) {
+      codes.push(brightBase + color - 8);
+    } else {
+      codes.push(isFg ? 38 : 48, 5, color);
+    }
+  }
+}
+
+function trimTrailingBlankRows(rows) {
+  let end = rows.length;
+  while (end > 0 && rows[end - 1].plain === "") end -= 1;
+  return rows.slice(0, end);
+}
+
+function normalizePositiveInt(value, fallback) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number <= 0) return Math.max(1, Math.trunc(Number(fallback) || 1));
+  return Math.max(1, Math.trunc(number));
+}