march-cli 0.1.0

package/src/cli/input/autocomplete.mjs

@@ -0,0 +1,106 @@
+import { join } from "node:path";
+import { readdirSync } from "node:fs";
+import { CombinedAutocompleteProvider } from "@earendil-works/pi-tui";
+
+const MARCH_COMMANDS = [
+  { name: "new", description: "Start a new pi session" },
+  { name: "exit", description: "Exit March" },
+  { name: "quit", description: "Exit March" },
+  { name: "help", description: "Show available commands" },
+  { name: "model", description: "Open model selector" },
+  { name: "models", description: "List available models" },
+  { name: "session", description: "Open previous session selector" },
+  { name: "save", description: "Show auto-save status" },
+  { name: "name", description: "Show or set session name" },
+  { name: "copy", description: "Copy last assistant response to clipboard" },
+  { name: "thinking", description: "Open thinking selector" },
+  { name: "thinking list", description: "List available thinking levels" },
+  { name: "mouse", description: "Toggle mouse wheel and TUI selection copy" },
+  { name: "hotkeys", description: "Show keyboard shortcuts and input prefixes" },
+  { name: "templates", description: "List project prompt templates" },
+  { name: "export jsonl", description: "Export current session turns as JSONL" },
+  { name: "export html", description: "Export current session turns as HTML" },
+  { name: "export gist html", description: "Share current session HTML as a private GitHub Gist" },
+  { name: "export gist jsonl", description: "Share current session JSONL as a private GitHub Gist" },
+  { name: "settings", description: "Show or edit global/project settings" },
+  { name: "shell", description: "List shells or inspect shell output" },
+  { name: "shell spawn", description: "Start a default PTY shell" },
+];
+
+export function buildMarchCommands(promptTemplates = []) {
+  const templateCommands = promptTemplates
+    .map((template) => ({
+      name: typeof template === "string" ? template : template.name,
+      description: "Expand prompt template",
+    }))
+    .filter((command) => command.name && !command.name.startsWith("/"));
+  return [...MARCH_COMMANDS, ...templateCommands];
+}
+
+export class MarchAutocompleteProvider {
+  constructor(commands, cwd) {
+    this.base = new CombinedAutocompleteProvider(commands, cwd);
+    this.cwd = cwd;
+  }
+
+  async getSuggestions(lines, cursorLine, cursorCol, options) {
+    const suggestions = await this.base.getSuggestions(lines, cursorLine, cursorCol, options);
+    if (suggestions) return suggestions;
+    return this.getAtFileSuggestions(lines, cursorLine, cursorCol);
+  }
+
+  applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+    return this.base.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+  }
+
+  shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+    return this.base.shouldTriggerFileCompletion(lines, cursorLine, cursorCol);
+  }
+
+  getAtFileSuggestions(lines, cursorLine, cursorCol) {
+    const currentLine = lines[cursorLine] || "";
+    const textBeforeCursor = currentLine.slice(0, cursorCol);
+    const match = textBeforeCursor.match(/(?:^|[\s([{])(@[^\s]*)$/);
+    if (!match) return null;
+
+    const prefix = match[1];
+    const query = prefix.slice(1);
+    const displayDotSlash = query.startsWith("./");
+    const normalizedQuery = query.replace(/^[.][/\\]/, "").replace(/\\/g, "/").toLowerCase();
+    const items = [];
+    const skip = new Set([".git", "node_modules"]);
+
+    const walk = (dir, relative = "", depth = 0) => {
+      if (items.length >= 50 || depth > 5) return;
+      let entries;
+      try {
+        entries = readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        if (items.length >= 50) return;
+        if (skip.has(entry.name)) continue;
+        const rel = relative ? `${relative}/${entry.name}` : entry.name;
+        const isDirectory = entry.isDirectory();
+        const relForMatch = rel.toLowerCase();
+        if (!normalizedQuery || relForMatch.includes(normalizedQuery)) {
+          const displayPath = `${displayDotSlash ? "./" : ""}${rel}${isDirectory ? "/" : ""}`;
+          items.push({
+            value: `@${displayPath}`,
+            label: `${entry.name}${isDirectory ? "/" : ""}`,
+            description: displayPath,
+          });
+        }
+        if (isDirectory) {
+          walk(join(dir, entry.name), rel, depth + 1);
+        }
+      }
+    };
+
+    walk(this.cwd);
+    if (items.length === 0) return null;
+    items.sort((a, b) => a.description.localeCompare(b.description));
+    return { items, prefix };
+  }
+}

package/src/cli/input/external-editor.mjs

@@ -0,0 +1,39 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export function openTextInExternalEditor({
+  text = "",
+  editorCommand = getExternalEditorCommand(),
+  now = () => Date.now(),
+  spawn = spawnSync,
+  tempDir = tmpdir(),
+} = {}) {
+  if (!editorCommand) {
+    return { ok: false, error: "No editor configured. Set $VISUAL or $EDITOR." };
+  }
+
+  const tmpFile = join(tempDir, `march-editor-${now()}.md`);
+  try {
+    writeFileSync(tmpFile, String(text ?? ""), "utf8");
+    const [bin, ...args] = editorCommand.split(" ");
+    const result = spawn(bin, [...args, tmpFile], {
+      stdio: "inherit",
+      shell: process.platform === "win32",
+    });
+    if (result.status !== 0) {
+      return { ok: false, error: `Editor exited with status ${result.status ?? "unknown"}` };
+    }
+    return {
+      ok: true,
+      text: readFileSync(tmpFile, "utf8").replace(/\n$/, ""),
+    };
+  } finally {
+    try { unlinkSync(tmpFile); } catch {}
+  }
+}
+
+export function getExternalEditorCommand(env = process.env) {
+  return env.VISUAL || env.EDITOR || "";
+}

package/src/cli/input/history-store.mjs

@@ -0,0 +1,35 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+const HISTORY_VERSION = 1;
+const MAX_HISTORY_ITEMS = 100;
+
+export function createInputHistoryStore({ path, maxItems = MAX_HISTORY_ITEMS } = {}) {
+  return {
+    load() {
+      if (!path || !existsSync(path)) return [];
+      try {
+        const data = JSON.parse(readFileSync(path, "utf8"));
+        const items = Array.isArray(data?.items) ? data.items : [];
+        return normalizeItems(items, maxItems);
+      } catch {
+        return [];
+      }
+    },
+
+    save(items) {
+      if (!path) return;
+      const normalized = normalizeItems(items, maxItems);
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, `${JSON.stringify({ version: HISTORY_VERSION, items: normalized }, null, 2)}\n`, "utf8");
+    },
+  };
+}
+
+function normalizeItems(items, maxItems) {
+  return items
+    .filter((item) => typeof item === "string")
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .slice(0, maxItems);
+}

package/src/cli/input/image-clipboard.mjs

@@ -0,0 +1,55 @@
+import { spawnSync } from "node:child_process";
+
+const WINDOWS_CLIPBOARD_IMAGE_SCRIPT = `
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+if (-not [System.Windows.Forms.Clipboard]::ContainsImage()) {
+  [Console]::Error.WriteLine("clipboard does not contain an image")
+  exit 2
+}
+$image = [System.Windows.Forms.Clipboard]::GetImage()
+$stream = New-Object System.IO.MemoryStream
+$image.Save($stream, [System.Drawing.Imaging.ImageFormat]::Png)
+[Convert]::ToBase64String($stream.ToArray())
+`.trim();
+
+export function readClipboardImage({
+  platform = process.platform,
+  spawnSyncImpl = spawnSync,
+} = {}) {
+  if (platform !== "win32") {
+    return { ok: false, message: `clipboard image paste is not supported on ${platform}` };
+  }
+
+  const result = spawnSyncImpl("powershell.exe", [
+    "-NoProfile",
+    "-Sta",
+    "-NonInteractive",
+    "-Command",
+    WINDOWS_CLIPBOARD_IMAGE_SCRIPT,
+  ], {
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  if (result.error) return { ok: false, message: result.error.message };
+  if (result.status !== 0) {
+    const stderr = String(result.stderr || "").trim();
+    return { ok: false, message: stderr || `powershell.exe exited ${result.status}` };
+  }
+
+  const data = String(result.stdout || "").trim();
+  if (!isBase64(data)) return { ok: false, message: "clipboard image output was not valid base64" };
+  return {
+    ok: true,
+    mimeType: "image/png",
+    data,
+  };
+}
+
+export function getWindowsClipboardImageScript() {
+  return WINDOWS_CLIPBOARD_IMAGE_SCRIPT;
+}
+
+function isBase64(value) {
+  return value.length > 0 && /^[A-Za-z0-9+/]+={0,2}$/.test(value);
+}

package/src/cli/input/keybinding-dispatch.mjs

@@ -0,0 +1,76 @@
+import { matchesKey } from "@earendil-works/pi-tui";
+import { DEFAULT_KEYBINDINGS, KEYBINDING_ACTIONS } from "./keybindings.mjs";
+
+export const TERMINAL_KEY_SEQUENCES = Object.freeze({
+  Esc: "\x1b",
+  Tab: "\t",
+  "Shift+Tab": "\x1b[Z",
+  ...Object.fromEntries(
+    Array.from({ length: 26 }, (_, index) => {
+      const letter = String.fromCharCode("A".charCodeAt(0) + index);
+      return [`Ctrl+${letter}`, String.fromCharCode(index + 1)];
+    })
+  ),
+  ...Object.fromEntries(
+    Array.from({ length: 26 }, (_, index) => {
+      const letter = String.fromCharCode("A".charCodeAt(0) + index);
+      return [`Alt+${letter}`, `\x1b${letter.toLowerCase()}`];
+    })
+  ),
+});
+
+export function createKeybindingDispatcher({
+  keybindings = DEFAULT_KEYBINDINGS,
+  handlers = {},
+  isAutocompleteOpen = () => false,
+  hasOverlay = () => false,
+} = {}) {
+  const bindings = buildBindings(keybindings);
+
+  return {
+    dispatch(data) {
+      const action = findMatchingAction(data, bindings);
+      if (!action) return undefined;
+
+      if (action === "interrupt") return runHandler(handlers[action]);
+      if (action === "abort" && isAutocompleteOpen()) return undefined;
+      if (action === "toggleMode" && isAutocompleteOpen()) return undefined;
+      if (hasOverlay()) return undefined;
+
+      return runHandler(handlers[action]);
+    },
+  };
+}
+
+function runHandler(handler) {
+  if (typeof handler !== "function") return undefined;
+  handler();
+  return { consume: true };
+}
+
+function buildBindings(keybindings) {
+  const bindings = [];
+  const claimed = new Set();
+  for (const action of Object.keys(KEYBINDING_ACTIONS)) {
+    const key = keybindings[action] ?? DEFAULT_KEYBINDINGS[action];
+    const keyId = toPiTuiKeyId(key);
+    const sequence = TERMINAL_KEY_SEQUENCES[key];
+    if (!keyId || claimed.has(keyId)) continue;
+    claimed.add(keyId);
+    bindings.push({ action, keyId, sequence });
+  }
+  return bindings;
+}
+
+function findMatchingAction(data, bindings) {
+  for (const binding of bindings) {
+    if (binding.sequence && data === binding.sequence) return binding.action;
+    if (matchesKey(data, binding.keyId)) return binding.action;
+  }
+  return null;
+}
+
+function toPiTuiKeyId(key) {
+  if (key === "Esc") return "escape";
+  return String(key).toLowerCase();
+}

package/src/cli/input/keybindings.mjs

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export const DEFAULT_KEYBINDINGS = Object.freeze({
+  abort: "Esc",
+  interrupt: "Ctrl+C",
+  toggleMode: "Tab",
+  cycleThinking: "Shift+Tab",
+  thinkingSelector: "Ctrl+T",
+  modelSelector: "Ctrl+L",
+  externalEditor: "Ctrl+G",
+  toggleToolOutput: "Ctrl+O",
+  toggleShellDrawer: "Alt+S",
+  nextShell: "Alt+N",
+  shellScrollUp: "Alt+K",
+  shellScrollDown: "Alt+J",
+  outputScrollUp: "PageUp",
+  outputScrollDown: "PageDown",
+  pasteImage: "Alt+V",
+});
+
+export const KEYBINDING_ACTIONS = Object.freeze({
+  abort: "Abort current turn; cancel retry wait",
+  interrupt: "Abort current turn; press twice to exit when idle",
+  toggleMode: "Toggle Do/Discuss mode",
+  cycleThinking: "Open thinking selector",
+  thinkingSelector: "Open thinking selector",
+  modelSelector: "Open model selector",
+  externalEditor: "Open external editor ($VISUAL or $EDITOR)",
+  toggleToolOutput: "Toggle tool output collapsed/expanded",
+  toggleShellDrawer: "Toggle right-side shell pane",
+  nextShell: "Select next shell in pane",
+  shellScrollUp: "Scroll shell pane up",
+  shellScrollDown: "Scroll shell pane down",
+  outputScrollUp: "Scroll output buffer up",
+  outputScrollDown: "Scroll output buffer down",
+  pasteImage: "Paste clipboard image as attachment",
+});
+
+export function loadKeybindings(cwd) {
+  return loadKeybindingsFromPath(resolve(cwd, ".march", "keybindings.json"));
+}
+
+export function loadKeybindingsFromPath(path) {
+  if (!existsSync(path)) {
+    return { keybindings: { ...DEFAULT_KEYBINDINGS }, diagnostics: [] };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return normalizeKeybindings(parsed, path);
+  } catch (err) {
+    return {
+      keybindings: { ...DEFAULT_KEYBINDINGS },
+      diagnostics: [{ type: "warning", message: `Failed to load keybindings.json: ${err.message}`, path }],
+    };
+  }
+}
+
+export function normalizeKeybindings(parsed, path = "keybindings.json") {
+  const diagnostics = [];
+  const keybindings = { ...DEFAULT_KEYBINDINGS };
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return {
+      keybindings,
+      diagnostics: [{ type: "warning", message: "keybindings.json must be an object", path }],
+    };
+  }
+
+  for (const [action, key] of Object.entries(parsed)) {
+    if (!Object.hasOwn(KEYBINDING_ACTIONS, action)) {
+      diagnostics.push({ type: "warning", message: `Unknown keybinding action: ${action}`, path });
+      continue;
+    }
+    if (!isSupportedKey(key)) {
+      diagnostics.push({ type: "warning", message: `Unsupported keybinding for ${action}: ${String(key)}`, path });
+      continue;
+    }
+    keybindings[action] = key;
+  }
+
+  return { keybindings, diagnostics };
+}
+
+export function formatKeybindingLines(keybindings = DEFAULT_KEYBINDINGS) {
+  return Object.entries(KEYBINDING_ACTIONS).map(([action, description]) =>
+    `  ${padKey(keybindings[action] ?? DEFAULT_KEYBINDINGS[action])} ${description}`
+  );
+}
+
+function isSupportedKey(key) {
+  return typeof key === "string" && /^(Esc|Tab|Shift\+Tab|Ctrl\+[A-Z]|Alt\+[A-Z]|PageUp|PageDown)$/.test(key);
+}
+
+function padKey(key) {
+  return key.padEnd(10, " ");
+}

package/src/cli/input/mode-state.mjs

@@ -0,0 +1,43 @@
+export const MODES = Object.freeze({
+  DO: "do",
+  DISCUSS: "discuss",
+});
+
+export function createModeState({ initial = MODES.DO } = {}) {
+  let mode = normalizeMode(initial);
+  return {
+    get: () => mode,
+    toggle() {
+      mode = mode === MODES.DO ? MODES.DISCUSS : MODES.DO;
+      return mode;
+    },
+    set(nextMode) {
+      mode = normalizeMode(nextMode);
+      return mode;
+    },
+  };
+}
+
+export function appendModeReminder(prompt, mode = MODES.DO) {
+  return `${prompt}\n\n${formatModeReminder(mode)}`;
+}
+
+export function formatModeLabel(mode = MODES.DO) {
+  return normalizeMode(mode) === MODES.DISCUSS ? "Discuss" : "Do";
+}
+
+export function formatModeReminder(mode = MODES.DO) {
+  if (normalizeMode(mode) === MODES.DISCUSS) {
+    return "<mode>\n" +
+      "You are in discuss mode. Do not edit files, write files, apply patches, commit, or run commands that modify system state. " +
+      "You may inspect, analyze, ask clarifying questions, and propose a plan.\n" +
+      "</mode>";
+  }
+  return "<mode>\n" +
+    "You are in do mode. You may implement changes when the user asks for execution, following normal permissions and project rules.\n" +
+    "</mode>";
+}
+
+function normalizeMode(mode) {
+  return mode === MODES.DISCUSS ? MODES.DISCUSS : MODES.DO;
+}

package/src/cli/input/prompt-templates.mjs

@@ -0,0 +1,84 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { basename, extname, join, resolve } from "node:path";
+
+const TEMPLATE_EXTENSIONS = new Set([".md", ".txt"]);
+const TEMPLATE_NAME_RE = /^[A-Za-z][A-Za-z0-9_-]*$/;
+
+export function loadPromptTemplates(cwd) {
+  return loadPromptTemplatesFromDir(resolve(cwd, ".march", "templates"));
+}
+
+export function loadPromptTemplatesFromDir(dir) {
+  if (!existsSync(dir)) return { templates: [], diagnostics: [] };
+
+  const templates = [];
+  const diagnostics = [];
+  for (const entry of safeReadDir(dir, diagnostics)) {
+    if (!entry.isFile()) continue;
+    const ext = extname(entry.name);
+    if (!TEMPLATE_EXTENSIONS.has(ext)) continue;
+    const name = basename(entry.name, ext);
+    const path = join(dir, entry.name);
+    if (!TEMPLATE_NAME_RE.test(name)) {
+      diagnostics.push({ type: "warning", message: `Skipped invalid template name: ${entry.name}`, path });
+      continue;
+    }
+    try {
+      templates.push({ name, path, body: readFileSync(path, "utf8") });
+    } catch (err) {
+      diagnostics.push({ type: "warning", message: `Failed to read template ${entry.name}: ${err.message}`, path });
+    }
+  }
+  templates.sort((a, b) => a.name.localeCompare(b.name));
+  return { templates, diagnostics };
+}
+
+export function expandPromptTemplate(input, templates = []) {
+  const match = input.match(/^\/([A-Za-z][A-Za-z0-9_-]*)(?:\s+([\s\S]*))?$/);
+  if (!match) return { type: "none" };
+  const template = templates.find((item) => item.name === match[1]);
+  if (!template) return { type: "none" };
+  const rawArgs = (match[2] || "").trim();
+  return {
+    type: "template",
+    name: template.name,
+    prompt: renderPromptTemplate(template.body, rawArgs),
+  };
+}
+
+export function renderPromptTemplate(body, rawArgs = "") {
+  const args = splitTemplateArgs(rawArgs);
+  return body.replace(/\{\{\s*(args|input|\d+)\s*\}\}/g, (_match, token) => {
+    if (token === "args" || token === "input") return rawArgs;
+    return args[Number(token) - 1] ?? "";
+  }).trim();
+}
+
+export function formatPromptTemplateLines(templates = [], diagnostics = []) {
+  const lines = ["Prompt templates:"];
+  if (templates.length === 0) {
+    lines.push("  (none)");
+  } else {
+    for (const template of templates) lines.push(`  /${template.name}`);
+  }
+  if (diagnostics.length > 0) {
+    lines.push("Template diagnostics:");
+    for (const diagnostic of diagnostics) {
+      lines.push(`  - ${diagnostic.type ?? "warning"}: ${diagnostic.message}`);
+    }
+  }
+  return lines;
+}
+
+function safeReadDir(dir, diagnostics) {
+  try {
+    return readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    diagnostics.push({ type: "warning", message: `Failed to read templates directory: ${err.message}`, path: dir });
+    return [];
+  }
+}
+
+function splitTemplateArgs(rawArgs) {
+  return rawArgs ? rawArgs.split(/\s+/).filter(Boolean) : [];
+}

package/src/cli/input/select-with-keyboard.mjs

@@ -0,0 +1,67 @@
+import { createInterface } from "node:readline";
+
+export async function selectWithKeyboard({ input = process.stdin, output = process.stdout, message, items }) {
+  if (!items.length) return null;
+  if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== "function") {
+    output.write(`${message}:\n`);
+    for (let i = 0; i < items.length; i++) output.write(`  ${i + 1}. ${items[i].label}\n`);
+    const answer = await readLine({ input, output, prompt: `Select (1-${items.length}): ` });
+    const index = Number.parseInt(String(answer).trim(), 10) - 1;
+    return items[index]?.value ?? null;
+  }
+
+  let selected = 0;
+  let renderedLines = 0;
+  const render = () => {
+    if (renderedLines > 0) output.write(`\x1b[${renderedLines}F`);
+    const lines = formatSelectionList({ message, items, selected });
+    for (const line of lines) output.write(`\x1b[2K\r${line}\n`);
+    renderedLines = lines.length;
+  };
+  return new Promise((resolve) => {
+    let finished = false;
+    const onData = (chunk) => {
+      const keys = chunk.toString("utf8").match(/\u001b\[[AB]|\r|\n|\u0003|\u001b/g) ?? [];
+      for (const key of keys) {
+        if (finished) return;
+        if (key === "\u0003" || key === "\u001b") finish(null);
+        else if (key === "\r" || key === "\n") finish(items[selected].value);
+        else if (key === "\u001b[A") { selected = (selected - 1 + items.length) % items.length; render(); }
+        else if (key === "\u001b[B") { selected = (selected + 1) % items.length; render(); }
+      }
+    };
+    const finish = (value) => {
+      finished = true;
+      input.off("data", onData);
+      input.setRawMode(false);
+      input.pause();
+      if (renderedLines > 0) output.write(`\x1b[${renderedLines}F`);
+      const lines = formatSelectionList({ message, items, selected, done: value != null });
+      for (const line of lines) output.write(`\x1b[2K\r${line}\n`);
+      resolve(value);
+    };
+    input.setRawMode(true);
+    input.resume();
+    input.on("data", onData);
+    render();
+  });
+}
+
+export function formatSelectionList({ message, items, selected, done = false }) {
+  const hint = done ? "selected" : "↑/↓, Enter";
+  const lines = [`${message} (${hint})`];
+  for (let i = 0; i < items.length; i++) {
+    const marker = i === selected ? "›" : " ";
+    const label = `${marker} ${items[i].label}`;
+    lines.push(i === selected ? `\x1b[7m${label}\x1b[0m` : label);
+  }
+  return lines;
+}
+
+function readLine({ input = process.stdin, output = process.stdout, prompt }) {
+  const rl = createInterface({ input, output });
+  return new Promise((resolve) => rl.question(prompt, (answer) => {
+    rl.close();
+    resolve(answer);
+  }));
+}