march-cli 0.1.21 → 0.1.23

package/README.md

@@ -0,0 +1,88 @@
+<p align="center">
+  <img src="docs/assets/march-banner.png" alt="March CLI banner" width="800">
+</p>
+
+<p align="center"><strong>Forget Skills. Embrace Memory. Keep your model in the sweet spot.</strong></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/march-cli"><img alt="npm" src="https://img.shields.io/npm/v/march-cli?style=flat-square" /></a>
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> |
+  <a href="README.zh.md">简体中文</a>
+</p>
+
+---
+
+### Installation
+
+```bash
+npm install -g march-cli
+```
+
+### Why Token Efficient?
+
+March is obsessively token-efficient. After each turn, context resets to ~8K — we **discard** all intermediate execution and keep only two things: the user's question and the AI's final response.
+
+Most agents fight context bloat with compression, truncation, retrieval, summarization. March's answer: just throw away what you don't need.
+
+The result:
+
+- **91% cache hit rate**, individual model calls rarely exceed 50K tokens
+- Context never grows unbounded — **no context rot**
+- Your model always operates in the sweet spot, not drowning in 100K of noise
+
+### Memory System
+
+March has a built-in memory system. Anything you tell March — preferences, project conventions, technical decisions — it remembers. When you need it again, March **automatically recalls** relevant memories during its thinking process. No manual search required.
+
+#### No Skill Files
+
+The problem with Skill systems: Skill files inject context upfront. What happens when you have too many?
+
+March takes a different approach: every memory is a "latent skill," recalled on-demand rather than always sitting in context. What you've discussed is the best prompt.
+
+#### Managing Memories
+
+March stores memories as Markdown files under `~/.march/March Memories/`. You can directly edit, delete, or add files — March auto-detects changes.
+
+### Built-in Capabilities
+
+**Image Generation**: If you have access to ChatGPT Codex, March can generate images directly — no extra API keys or third-party services.
+
+**Web Search**: Connect SuperGrok and **all your configured models** gain web search. March dispatches Grok to search and injects results into the current conversation.
+
+**More Search**: Tavily Search and Brave Search are built in.
+
+### Configuration
+
+March uses `~/.march/config.json` (global) or `<project>/.march/config.json` (project-level) for model and provider configuration. Compatible with any OpenAI-compatible API.
+
+```json
+{
+  "provider": "openai",
+  "model": "gpt-5.1"
+}
+```
+
+See the [docs](docs/custom-provider.md) for custom providers, multi-model setup, and more.
+
+### FAQ
+
+#### How is this different from Claude Code?
+
+March is similarly capable but takes a fundamentally different approach to context. Instead of keeping everything in context and relying on compression, March resets context each turn — you get ~8K clean context every time, with 91% cache hit rate. March also replaces Skill files with a built-in memory system that recalls on demand.
+
+#### How is this different from OpenCode?
+
+Both are open source, terminal-native agents. March's key differentiators: extreme token efficiency via per-turn context reset, a built-in Markdown memory system with automatic recall, and the philosophy that memories should be recalled on-demand — not injected upfront like Skills.
+
+### Documentation
+
+- [Full Documentation](docs/) — configuration, context management, memory system
+- [Custom Provider](docs/custom-provider.md) — connect local models or third-party APIs
+- [Context Management](docs/context-core.md) — March's context architecture explained
+- [Memory System](docs/markdown-memory-system.md) — storage and recall mechanism
+
+

package/README.zh.md

@@ -0,0 +1,88 @@
+<p align="center">
+  <img src="docs/assets/march-banner.png" alt="March CLI banner" width="800">
+</p>
+
+<p align="center"><strong>忘记 Skill，拥抱记忆，让你的模型永远工作在甜点区。</strong></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/march-cli"><img alt="npm" src="https://img.shields.io/npm/v/march-cli?style=flat-square" /></a>
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> |
+  <a href="README.zh.md">简体中文</a>
+</p>
+
+---
+
+### 安装
+
+```bash
+npm install -g march-cli
+```
+
+### 为什么省 Token？
+
+March 极端地省 Token。每轮对话结束后，上下文回滚到约 8K——我们**丢弃**模型中间的所有执行过程，只保留两样东西：用户的问题和 AI 的最终回复。
+
+大多数 Agent 系统用压缩、裁剪、检索、摘要来对抗上下文膨胀。March 的答案是：直接扔掉不需要的。
+
+结果：
+
+- **缓存命中率 91%**，单次模型调用几乎不超过 50K
+- 上下文不会越聊越大，**不存在上下文腐烂**
+- 你的模型永远在甜点区工作，而不是在 100K 的噪音里大海捞针
+
+### 记忆系统
+
+March 内置了记忆系统。你在对话中告诉 March 的任何东西——偏好、项目约定、技术决策——它都能记住。当你再次需要时，March 会在思考过程中**自动召回**相关记忆，你不需要手动检索。
+
+#### 不需要 Skill 文件
+
+Skill 系统的问题是：Skill 文件在一开始就注入了上下文。Skill 多了怎么办？
+
+March 换了一种方式：每条记忆就是一条"潜在的 Skill"，由 March 在需要时动态召回，而不是常驻在上下文里。你聊过的内容就是最好的提示词。
+
+#### 管理记忆
+
+March 在 `~/.march/March Memories/` 目录下以 Markdown 文件存储记忆。你可以直接编辑、删除或新增这些文件，March 会自动感知变化。
+
+### 更多内置能力
+
+**生图**：如果你有 ChatGPT Codex 权限，March 可以直接生图，不需要额外的 API Key 或第三方服务。
+
+**联网搜索**：接入 SuperGrok 后，你配置的**所有模型**都会获得联网搜索能力——March 会派遣 Grok 去搜索，搜索结果注入当前对话。
+
+**更多搜索渠道**：Tavily Search、Brave Search 均已内置。
+
+### 配置
+
+March 通过 `~/.march/config.json`（全局）或 `<project>/.march/config.json`（项目级）配置模型和 provider。支持所有 OpenAI 兼容接口。
+
+```json
+{
+  "provider": "openai",
+  "model": "gpt-5.1"
+}
+```
+
+自定义 provider、多模型切换等详细配置见 [文档](docs/custom-provider.md)。
+
+### FAQ
+
+#### 和 Claude Code 有什么区别？
+
+March 能力相当，但上下文策略截然不同。Claude Code 尽量保留上下文并用压缩应对膨胀；March 每轮重置上下文——你每次拿到的是干净的 ~8K 上下文，缓存命中率 91%。March 还用内置记忆系统替代了 Skill 文件，记忆按需召回而不是常驻注入。
+
+#### 和 OpenCode 有什么区别？
+
+两者都是开源、终端原生的 Agent。March 的核心差异：极端的 Token 效率（每轮上下文重置）、内置 Markdown 记忆系统（自动召回），以及"记忆应该按需召回、而非像 Skill 一样提前注入"的设计哲学。
+
+### 文档
+
+- [完整文档](docs/) — 配置、上下文管理、记忆系统
+- [自定义 Provider](docs/custom-provider.md) — 接入本地模型或第三方 API
+- [上下文管理](docs/context-core.md) — March 的上下文架构详解
+- [记忆系统](docs/markdown-memory-system.md) — 记忆存储与召回机制
+
+

package/bin/march.mjs

@@ -1,13 +1,13 @@
-#!/usr/bin/env node
-
-const emitWarning = process.emitWarning;
-process.emitWarning = function filteredWarning(warning, ...args) {
-  const message = typeof warning === "string" ? warning : warning?.message;
-  const type = typeof warning === "string" ? args[0] : warning?.name;
-  if (type === "ExperimentalWarning" && String(message).includes("SQLite")) return;
-  return emitWarning.call(this, warning, ...args);
-};
-
-const { run } = await import("../src/main.mjs");
-const code = await run(process.argv.slice(2));
-process.exitCode = code;
+#!/usr/bin/env node
+
+const emitWarning = process.emitWarning;
+process.emitWarning = function filteredWarning(warning, ...args) {
+  const message = typeof warning === "string" ? warning : warning?.message;
+  const type = typeof warning === "string" ? args[0] : warning?.name;
+  if (type === "ExperimentalWarning" && String(message).includes("SQLite")) return;
+  return emitWarning.call(this, warning, ...args);
+};
+
+const { run } = await import("../src/main.mjs");
+const code = await run(process.argv.slice(2));
+process.exitCode = code;

package/package.json

@@ -1,43 +1,43 @@
-{
-  "name": "march-cli",
-  "version": "0.1.21",
-  "description": "March CLI — terminal-native coding agent with context reconstruction",
-  "type": "module",
-  "main": "./src/main.mjs",
-  "bin": {
-    "march": "bin/march.mjs"
-  },
-  "files": [
-    "bin/",
-    "src/"
-  ],
-  "scripts": {
-    "dev": "cd .. && node march-cli/bin/march.mjs",
-    "test": "node test/smoke.test.mjs",
-    "test:fast": "node test/fast.test.mjs",
-    "test:real": "npm run test:shell-runtime-real && npm run test:shell-tui-real && npm run test:tui-key-real",
-    "test:shell-runtime-real": "node test/shell-real-runtime.acceptance.mjs",
-    "test:shell-tui-real": "node test/shell-tui-real.acceptance.mjs",
-    "test:tui-key-real": "node test/tui-key-real.acceptance.mjs",
-    "context": "cd .. && node march-cli/bin/march.mjs --dump-context",
-    "notify:experiment": "node scripts/notify-experiment.mjs",
-    "publish:env": "node scripts/npm-publish-from-env.mjs"
-  },
-  "dependencies": {
-    "@earendil-works/pi-ai": "^0.74.0",
-    "@earendil-works/pi-coding-agent": "^0.74.0",
-    "@earendil-works/pi-tui": "^0.74.0",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "@xterm/headless": "^5.5.0",
-    "marked": "^18.0.3",
-    "node-notifier": "^10.0.1",
-    "node-pty": "^1.1.0",
-    "typebox": "^1.0.58",
-    "undici": "^7.25.0",
-    "web-tree-sitter": "^0.26.8",
-    "ws": "^8.20.1"
-  },
-  "optionalDependencies": {
-    "@vscode/ripgrep": "^1.18.0"
-  }
-}
+{
+  "name": "march-cli",
+  "version": "0.1.23",
+  "description": "March CLI — terminal-native coding agent with context reconstruction",
+  "type": "module",
+  "main": "./src/main.mjs",
+  "bin": {
+    "march": "bin/march.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "scripts": {
+    "dev": "cd .. && node march-cli/bin/march.mjs",
+    "test": "node test/smoke.test.mjs",
+    "test:fast": "node test/fast.test.mjs",
+    "test:real": "npm run test:shell-runtime-real && npm run test:shell-tui-real && npm run test:tui-key-real",
+    "test:shell-runtime-real": "node test/shell-real-runtime.acceptance.mjs",
+    "test:shell-tui-real": "node test/shell-tui-real.acceptance.mjs",
+    "test:tui-key-real": "node test/tui-key-real.acceptance.mjs",
+    "context": "cd .. && node march-cli/bin/march.mjs --dump-context",
+    "notify:experiment": "node scripts/notify-experiment.mjs",
+    "publish:env": "node scripts/npm-publish-from-env.mjs"
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "^0.74.0",
+    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@earendil-works/pi-tui": "^0.74.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@xterm/headless": "^5.5.0",
+    "marked": "^18.0.3",
+    "node-notifier": "^10.0.1",
+    "node-pty": "^1.1.0",
+    "typebox": "^1.0.58",
+    "undici": "^7.25.0",
+    "web-tree-sitter": "^0.26.8",
+    "ws": "^8.20.1"
+  },
+  "optionalDependencies": {
+    "@vscode/ripgrep": "^1.18.0"
+  }
+}

package/src/agent/command-exec-tool.mjs

@@ -1,168 +1,172 @@
-import { spawn, spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { defineTool } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { toolText } from "./tool-result.mjs";
-import { stripAnsi } from "../text/ansi.mjs";
-
-const OUTPUT_LIMIT = 64 * 1024;
-const DEFAULT_COMMAND_TIMEOUT_SECONDS = 60;
-const COMMAND_KILL_GRACE_MS = 1000;
-
-export function createCommandExecTool({ cwd }) {
-  return defineTool({
-    name: "command_exec",
-    label: "Command Exec",
-    description: "Run a one-shot command in the project directory. Use terminal_* for interactive or long-running processes.",
-    parameters: Type.Object({
-      command: Type.String({ description: "Command to execute" }),
-      shell: Type.Optional(Type.String({ description: "auto (default), bash, or powershell" })),
-      timeout: Type.Optional(Type.Number({ description: "Timeout in seconds; default 60", default: DEFAULT_COMMAND_TIMEOUT_SECONDS })),
-    }),
-    execute: async (_toolCallId, params, signal) => executeCommand({ cwd, signal, ...params }),
-  });
-}
-
-export async function executeCommand({ cwd, command, shell = "auto", timeout = DEFAULT_COMMAND_TIMEOUT_SECONDS, signal, spawnImpl = spawn, killProcessTreeImpl = killProcessTree, forceSettleMs = COMMAND_KILL_GRACE_MS }) {
-  let resolved;
-  try {
-    resolved = resolveCommandShell(shell);
-  } catch (err) {
-    return toolText(`Error: ${err.message}`, { error: true });
-  }
-
-  const timeoutSeconds = Math.max(0.001, Number(timeout) || DEFAULT_COMMAND_TIMEOUT_SECONDS);
-  const timeoutMs = timeoutSeconds * 1000;
-  const result = await spawnCommand(spawnImpl, resolved.bin, [...resolved.args, String(command ?? "")], {
-    cwd,
-    timeoutMs,
-    signal,
-    windowsHide: true,
-    killProcessTreeImpl,
-    forceSettleMs,
-  });
-  if (result.error) {
-    const detail = result.timedOut ? ` (timed out after ${timeoutSeconds}s)` : "";
-    return toolText(`Error: ${result.error.message}${detail}`, { error: true });
-  }
-  const stdout = stripAnsi(result.stdout ?? "");
-  const stderr = stripAnsi(result.stderr ?? "");
-  const output = formatCommandOutput({ stdout, stderr, status: result.status });
-  return toolText(output, {
-    status: result.status,
-    stdout,
-    stderr,
-    shell: resolved.name,
-    error: result.status !== 0,
-  });
-}
-
-function spawnCommand(spawnImpl, bin, args, options) {
-  return new Promise((resolve) => {
-    let stdout = "";
-    let stderr = "";
-    let settled = false;
-    let timedOut = false;
-    let aborted = false;
-    let forceTimer = null;
-    const child = spawnImpl(bin, args, {
-      cwd: options.cwd,
-      windowsHide: options.windowsHide,
-      detached: process.platform !== "win32",
-    });
-    const timer = setTimeout(() => {
-      timedOut = true;
-      terminateChild(new Error("Command timed out"));
-    }, options.timeoutMs);
-    const onAbort = () => {
-      aborted = true;
-      terminateChild(new Error("Command aborted"));
-    };
-    if (options.signal?.aborted) queueMicrotask(onAbort);
-    else options.signal?.addEventListener?.("abort", onAbort, { once: true });
-
-    child.stdout?.setEncoding?.("utf8");
-    child.stderr?.setEncoding?.("utf8");
-    child.stdout?.on?.("data", (chunk) => { stdout = appendLimited(stdout, chunk); });
-    child.stderr?.on?.("data", (chunk) => { stderr = appendLimited(stderr, chunk); });
-    child.once?.("error", (error) => finish({ error }));
-    child.once?.("close", (status, signal) => finish({ status, signal }));
-
-    function terminateChild(error) {
-      if (settled) return;
-      options.killProcessTreeImpl?.(child);
-      forceTimer ??= setTimeout(() => finish({ error }), options.forceSettleMs);
-    }
-
-    function finish(result) {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      clearTimeout(forceTimer);
-      options.signal?.removeEventListener?.("abort", onAbort);
-      const error = result.error ?? (timedOut ? Object.assign(new Error("Command timed out"), { code: "ETIMEDOUT" }) : null) ?? (aborted ? Object.assign(new Error("Command aborted"), { code: "ABORT_ERR" }) : null);
-      resolve({ ...result, error, stdout, stderr, timedOut, aborted });
-    }
-  });
-}
-
-function killProcessTree(child, platform = process.platform) {
-  if (!child?.pid) {
-    child?.kill?.("SIGTERM");
-    return;
-  }
-  if (platform === "win32") {
-    try {
-      spawnSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { windowsHide: true, stdio: "ignore", timeout: 5000 });
-      return;
-    } catch {}
-  }
-  try {
-    process.kill(-child.pid, "SIGTERM");
-    return;
-  } catch {}
-  child.kill?.("SIGTERM");
-}
-
-function appendLimited(current, chunk) {
-  const next = current + String(chunk ?? "");
-  return next.length <= OUTPUT_LIMIT ? next : next.slice(-OUTPUT_LIMIT);
-}
-
-export function resolveCommandShell(shell = "auto", platform = process.platform) {
-  const normalized = String(shell ?? "auto").trim().toLowerCase();
-  if (normalized === "powershell" || (normalized === "auto" && platform === "win32")) {
-    return { name: "powershell", bin: findPowerShell() ?? "powershell.exe", args: ["-NoProfile", "-Command"] };
-  }
-  if (normalized === "bash" || normalized === "auto") {
-    return { name: "bash", bin: "bash", args: ["-lc"] };
-  }
-  throw new Error(`unsupported shell: ${shell}`);
-}
-
-function findPowerShell() {
-  for (const name of ["pwsh.exe", "powershell.exe"]) {
-    try {
-      const result = spawnSync("where", [name], { encoding: "utf-8", timeout: 5000, windowsHide: true });
-      if (result.status === 0 && result.stdout) {
-        const first = result.stdout.trim().split(/\r?\n/)[0];
-        if (first && existsSync(first)) return first;
-      }
-    } catch {}
-  }
-  return null;
-}
-
-function formatCommandOutput({ stdout, stderr, status }) {
-  const parts = [];
-  if (stdout) parts.push(stdout.trimEnd());
-  if (stderr) parts.push(stderr.trimEnd());
-  if (status && status !== 0) parts.push(`exit ${status}`);
-  const output = parts.filter(Boolean).join("\n");
-  return output ? truncateOutput(output) : "(no output)";
-}
-
-function truncateOutput(text) {
-  if (text.length <= OUTPUT_LIMIT) return text;
-  return `${text.slice(-OUTPUT_LIMIT)}\n... (truncated to last ${OUTPUT_LIMIT} chars)`;
-}
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { toolText } from "./tool-result.mjs";
+import { stripAnsi } from "../text/ansi.mjs";
+
+const OUTPUT_LIMIT = 64 * 1024;
+const DEFAULT_COMMAND_TIMEOUT_SECONDS = 60;
+const COMMAND_KILL_GRACE_MS = 1000;
+
+export function createCommandExecTool({ cwd }) {
+  return defineTool({
+    name: "command_exec",
+    label: "Command Exec",
+    description: "Run a one-shot command in the project directory. Use terminal_* for interactive or long-running processes.",
+    parameters: Type.Object({
+      command: Type.String({ description: "Command to execute" }),
+      shell: Type.Optional(Type.String({ description: "auto (default), bash, or powershell" })),
+      timeout: Type.Optional(Type.Number({ description: "Timeout in seconds; default 60", default: DEFAULT_COMMAND_TIMEOUT_SECONDS })),
+    }),
+    execute: async (_toolCallId, params, signal) => executeCommand({ cwd, signal, ...params }),
+  });
+}
+
+export async function executeCommand({ cwd, command, shell = "auto", timeout = DEFAULT_COMMAND_TIMEOUT_SECONDS, signal, spawnImpl = spawn, killProcessTreeImpl = killProcessTree, forceSettleMs = COMMAND_KILL_GRACE_MS }) {
+  let resolved;
+  try {
+    resolved = resolveCommandShell(shell);
+  } catch (err) {
+    return toolText(`Error: ${err.message}`, { error: true });
+  }
+
+  const timeoutSeconds = Math.max(0.001, Number(timeout) || DEFAULT_COMMAND_TIMEOUT_SECONDS);
+  const timeoutMs = timeoutSeconds * 1000;
+  const result = await spawnCommand(spawnImpl, resolved.bin, [...resolved.args, String(command ?? "")], {
+    cwd,
+    timeoutMs,
+    signal,
+    windowsHide: true,
+    killProcessTreeImpl,
+    forceSettleMs,
+  });
+  if (result.error) {
+    const detail = result.timedOut ? ` (timed out after ${timeoutSeconds}s)` : "";
+    return toolText(`Error: ${result.error.message}${detail}`, { error: true });
+  }
+  const stdout = stripAnsi(result.stdout ?? "");
+  const stderr = stripAnsi(result.stderr ?? "");
+  const output = formatCommandOutput({ stdout, stderr, status: result.status });
+  return toolText(output, {
+    status: result.status,
+    stdout,
+    stderr,
+    shell: resolved.name,
+    error: result.status !== 0,
+  });
+}
+
+function spawnCommand(spawnImpl, bin, args, options) {
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let timedOut = false;
+    let aborted = false;
+    let forceTimer = null;
+    const child = spawnImpl(bin, args, {
+      cwd: options.cwd,
+      windowsHide: options.windowsHide,
+      detached: process.platform !== "win32",
+    });
+    const timer = setTimeout(() => {
+      timedOut = true;
+      terminateChild(new Error("Command timed out"));
+    }, options.timeoutMs);
+    const onAbort = () => {
+      aborted = true;
+      terminateChild(new Error("Command aborted"));
+    };
+    if (options.signal?.aborted) queueMicrotask(onAbort);
+    else options.signal?.addEventListener?.("abort", onAbort, { once: true });
+
+    child.stdout?.setEncoding?.("utf8");
+    child.stderr?.setEncoding?.("utf8");
+    child.stdout?.on?.("data", (chunk) => { stdout = appendLimited(stdout, chunk); });
+    child.stderr?.on?.("data", (chunk) => { stderr = appendLimited(stderr, chunk); });
+    child.once?.("error", (error) => finish({ error }));
+    child.once?.("close", (status, signal) => finish({ status, signal }));
+
+    function terminateChild(error) {
+      if (settled) return;
+      forceTimer ??= setTimeout(() => finish({ error }), options.forceSettleMs);
+      try {
+        options.killProcessTreeImpl?.(child);
+      } catch {}
+    }
+
+    function finish(result) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      clearTimeout(forceTimer);
+      options.signal?.removeEventListener?.("abort", onAbort);
+      const error = result.error ?? (timedOut ? Object.assign(new Error("Command timed out"), { code: "ETIMEDOUT" }) : null) ?? (aborted ? Object.assign(new Error("Command aborted"), { code: "ABORT_ERR" }) : null);
+      resolve({ ...result, error, stdout, stderr, timedOut, aborted });
+    }
+  });
+}
+
+export function killProcessTree(child, platform = process.platform, spawnImpl = spawn) {
+  if (!child?.pid) {
+    child?.kill?.("SIGTERM");
+    return;
+  }
+  if (platform === "win32") {
+    try {
+      const killer = spawnImpl("taskkill", ["/PID", String(child.pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" });
+      killer?.on?.("error", () => child.kill?.("SIGTERM"));
+      killer?.unref?.();
+      return;
+    } catch {}
+  }
+  try {
+    process.kill(-child.pid, "SIGTERM");
+    return;
+  } catch {}
+  child.kill?.("SIGTERM");
+}
+
+function appendLimited(current, chunk) {
+  const next = current + String(chunk ?? "");
+  return next.length <= OUTPUT_LIMIT ? next : next.slice(-OUTPUT_LIMIT);
+}
+
+export function resolveCommandShell(shell = "auto", platform = process.platform) {
+  const normalized = String(shell ?? "auto").trim().toLowerCase();
+  if (normalized === "powershell" || (normalized === "auto" && platform === "win32")) {
+    return { name: "powershell", bin: findPowerShell() ?? "powershell.exe", args: ["-NoProfile", "-Command"] };
+  }
+  if (normalized === "bash" || normalized === "auto") {
+    return { name: "bash", bin: "bash", args: ["-lc"] };
+  }
+  throw new Error(`unsupported shell: ${shell}`);
+}
+
+function findPowerShell() {
+  for (const name of ["pwsh.exe", "powershell.exe"]) {
+    try {
+      const result = spawnSync("where", [name], { encoding: "utf-8", timeout: 5000, windowsHide: true });
+      if (result.status === 0 && result.stdout) {
+        const first = result.stdout.trim().split(/\r?\n/)[0];
+        if (first && existsSync(first)) return first;
+      }
+    } catch {}
+  }
+  return null;
+}
+
+function formatCommandOutput({ stdout, stderr, status }) {
+  const parts = [];
+  if (stdout) parts.push(stdout.trimEnd());
+  if (stderr) parts.push(stderr.trimEnd());
+  if (status && status !== 0) parts.push(`exit ${status}`);
+  const output = parts.filter(Boolean).join("\n");
+  return output ? truncateOutput(output) : "(no output)";
+}
+
+function truncateOutput(text) {
+  if (text.length <= OUTPUT_LIMIT) return text;
+  return `${text.slice(-OUTPUT_LIMIT)}\n... (truncated to last ${OUTPUT_LIMIT} chars)`;
+}