march-cli 0.1.9 → 0.1.11

package/src/lsp/managed-node-server.mjs

@@ -0,0 +1,94 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { spawnCommand } from "../platform/spawn-command.mjs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const DEFAULT_CACHE_ROOT = join(homedir(), ".march", "lsp", "node");
+
+const MANAGED_PACKAGES = {
+  "typescript-language-server": ["typescript-language-server", "typescript"],
+  "vue-language-server": ["@vue/language-server", "typescript"],
+};
+
+const installs = new Map();
+
+export function getManagedNodeLspRoot() {
+  return process.env.MARCH_LSP_NODE_ROOT || DEFAULT_CACHE_ROOT;
+}
+
+export async function ensureManagedNodeCommand(name) {
+  if (!MANAGED_PACKAGES[name]) return null;
+  const root = getManagedNodeLspRoot();
+  const existing = findManagedBin(name, root);
+  if (existing) return { command: existing, root, installed: false };
+
+  await ensureManagedPackages(name, root);
+  const command = findManagedBin(name, root);
+  if (!command) throw new Error(`managed install did not provide ${name}`);
+  return { command, root, installed: true };
+}
+
+export async function ensureManagedTypeScript() {
+  const root = getManagedNodeLspRoot();
+  if (findManagedTypeScriptServer()) return { root, installed: false };
+  await installPackages(root, ["typescript"]);
+  if (!findManagedTypeScriptServer()) throw new Error("managed install did not provide typescript");
+  return { root, installed: true };
+}
+
+export function findManagedTypeScriptServer() {
+  const root = getManagedNodeLspRoot();
+  const tsserver = join(root, "node_modules", "typescript", "lib", "tsserver.js");
+  return existsSync(tsserver) ? tsserver : null;
+}
+
+export function findManagedTypeScriptSdk() {
+  const root = getManagedNodeLspRoot();
+  const lib = join(root, "node_modules", "typescript", "lib");
+  return existsSync(join(lib, "tsserverlibrary.js")) || existsSync(join(lib, "tsserver.js")) ? lib : null;
+}
+
+async function ensureManagedPackages(name, root) {
+  const key = `${root}:${name}`;
+  if (!installs.has(key)) {
+    installs.set(key, installPackages(root, MANAGED_PACKAGES[name]).finally(() => installs.delete(key)));
+  }
+  return await installs.get(key);
+}
+
+async function installPackages(root, packages) {
+  mkdirSync(root, { recursive: true });
+  const packageJson = join(root, "package.json");
+  if (!existsSync(packageJson)) writeFileSync(packageJson, JSON.stringify({ private: true, name: "march-managed-lsp" }, null, 2));
+  const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+  await run(npm, ["install", "--no-audit", "--no-fund", "--save-exact", ...packages], { cwd: root });
+}
+
+function findManagedBin(name, root) {
+  for (const bin of platformCommandNames(name)) {
+    const candidate = join(root, "node_modules", ".bin", bin);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function platformCommandNames(name) {
+  if (process.platform !== "win32") return [name];
+  return [`${name}.cmd`, `${name}.exe`, name];
+}
+
+function run(command, args, { cwd }) {
+  return new Promise((resolve, reject) => {
+    const child = spawnCommand(command, args, { cwd, stdio: ["ignore", "ignore", "pipe"], windowsHide: true });
+    let stderr = "";
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString("utf8");
+      if (stderr.length > 4000) stderr = stderr.slice(-4000);
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${command} ${args.join(" ")} failed with exit ${code}${stderr ? `: ${stderr.trim()}` : ""}`));
+    });
+  });
+}

package/src/lsp/path-match.mjs

@@ -0,0 +1,10 @@
+import { normalize } from "node:path";
+
+export function sameLspPath(left, right) {
+  return lspPathKey(left) === lspPathKey(right);
+}
+
+export function lspPathKey(path) {
+  const normalized = normalize(String(path ?? ""));
+  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}

package/src/lsp/servers.mjs

@@ -1,6 +1,8 @@
 import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { createRequire } from "node:module";
+import { ensureManagedNodeCommand, ensureManagedTypeScript, findManagedTypeScriptSdk, findManagedTypeScriptServer } from "./managed-node-server.mjs";
+import { resolveTypeScriptProjectRoot } from "./typescript-project-resolver.mjs";
 
 const NODE_ROOT_MARKERS = ["package-lock.json", "bun.lockb", "bun.lock", "pnpm-lock.yaml", "yarn.lock", "package.json"];
 
@@ -10,23 +12,28 @@ const LSP_SERVERS = [
     extensions: [".vue"],
     rootMarkers: NODE_ROOT_MARKERS,
     command: ["vue-language-server"],
+    managedCommand: "vue-language-server",
     args: ["--stdio"],
     initialization: ({ root, workspaceRoot }) => {
       const tsdk = resolveTypeScriptSdk({ root, workspaceRoot });
       return tsdk ? { typescript: { tsdk } } : null;
     },
+    managedTypeScript: true,
     missingInitialization: "missing project typescript SDK",
   },
   {
     id: "typescript",
     extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"],
     rootMarkers: NODE_ROOT_MARKERS,
+    projectRoot: resolveTypeScriptProjectRoot,
     command: ["typescript-language-server"],
+    managedCommand: "typescript-language-server",
     args: ["--stdio"],
     initialization: ({ root, workspaceRoot }) => {
       const tsserver = resolveTypeScriptServer({ root, workspaceRoot });
       return tsserver ? { tsserver: { path: tsserver } } : null;
     },
+    managedTypeScript: true,
     missingInitialization: "missing project typescript/tsserver.js",
   },
   {
@@ -129,23 +136,23 @@ const LSP_SERVERS = [
   },
 ];
 
-export function resolveLspServer({ filePath, workspaceRoot }) {
-  const result = resolveLspServerStatus({ filePath, workspaceRoot });
+export async function resolveLspServer({ filePath, workspaceRoot, onEvent = null } = {}) {
+  const result = await resolveLspServerStatus({ filePath, workspaceRoot, onEvent });
   return result.status === "available" ? result.server : null;
 }
 
-export function resolveLspServerStatus({ filePath, workspaceRoot }) {
+export async function resolveLspServerStatus({ filePath, workspaceRoot, onEvent = null } = {}) {
   const ext = extensionOf(filePath);
   const def = LSP_SERVERS.find((server) => server.extensions.includes(ext));
   if (!def) return { status: "unsupported", extension: ext };
 
-  const root = def.rootMarkers.length > 0
-    ? findNearestRoot(dirname(filePath), workspaceRoot, def.rootMarkers) ?? workspaceRoot
-    : workspaceRoot;
-  const command = findCommand(def.command, { root, workspaceRoot });
-  if (!command) {
-    return { status: "unavailable", id: def.id, root, reason: `missing ${def.command[0]}` };
-  }
+  const root = resolveServerRoot(def, { filePath, workspaceRoot });
+  const command = await resolveCommand(def, { root, workspaceRoot, onEvent });
+  if (command?.error) return { status: "unavailable", id: def.id, root, reason: command.error };
+  if (!command) return { status: "unavailable", id: def.id, root, reason: `missing ${def.command[0]}` };
+
+  const managedTypeScript = await ensureTypeScriptFallback(def, { root, workspaceRoot, onEvent });
+  if (managedTypeScript?.error) return { status: "unavailable", id: def.id, root, reason: managedTypeScript.error };
 
   const initialization = def.initialization?.({ root, workspaceRoot }) ?? {};
   if (initialization === null) {
@@ -153,7 +160,7 @@ export function resolveLspServerStatus({ filePath, workspaceRoot }) {
   }
   return {
     status: "available",
-    server: { id: def.id, command, args: def.args, root, initialization },
+    server: { id: def.id, command: command.command, args: def.args, root, initialization, managed: command.managed },
   };
 }
 
@@ -161,6 +168,42 @@ export function listLspServerDefinitions() {
   return LSP_SERVERS.map(({ id, extensions, rootMarkers, command, args }) => ({ id, extensions, rootMarkers, command, args }));
 }
 
+async function resolveCommand(def, { root, workspaceRoot, onEvent }) {
+  const local = findCommand(def.command, { root, workspaceRoot });
+  if (local) return { command: local, managed: false };
+  if (!def.managedCommand) return null;
+  onEvent?.({ status: "installing", id: def.id, root, reason: `installing ${def.managedCommand}` });
+  try {
+    const managed = await ensureManagedNodeCommand(def.managedCommand);
+    return { command: managed.command, managed: true };
+  } catch (err) {
+    const reason = err.message;
+    onEvent?.({ status: "failed", id: def.id, root, reason });
+    return { error: reason };
+  }
+}
+
+async function ensureTypeScriptFallback(def, { root, workspaceRoot, onEvent }) {
+  if (!def.managedTypeScript || resolveTypeScriptServer({ root, workspaceRoot })) return null;
+  onEvent?.({ status: "installing", id: def.id, root, reason: "installing typescript" });
+  try {
+    await ensureManagedTypeScript();
+    return null;
+  } catch (err) {
+    const reason = err.message;
+    onEvent?.({ status: "failed", id: def.id, root, reason });
+    return { error: reason };
+  }
+}
+
+function resolveServerRoot(def, { filePath, workspaceRoot }) {
+  const projectRoot = def.projectRoot?.({ filePath, workspaceRoot });
+  if (projectRoot) return projectRoot;
+  return def.rootMarkers.length > 0
+    ? findNearestRoot(dirname(filePath), workspaceRoot, def.rootMarkers) ?? workspaceRoot
+    : workspaceRoot;
+}
+
 function findCommand(names, { root, workspaceRoot }) {
   for (const name of names) {
     const hit = findBin(name, { root, workspaceRoot });
@@ -197,13 +240,13 @@ function findOnPath(names) {
 }
 
 function resolveTypeScriptServer({ root, workspaceRoot }) {
-  return resolveModuleFromRoots("typescript/lib/tsserver.js", { root, workspaceRoot });
+  return resolveModuleFromRoots("typescript/lib/tsserver.js", { root, workspaceRoot }) ?? findManagedTypeScriptServer();
 }
 
 function resolveTypeScriptSdk({ root, workspaceRoot }) {
   const serverLibrary = resolveModuleFromRoots("typescript/lib/tsserverlibrary.js", { root, workspaceRoot });
   const tsserver = serverLibrary ?? resolveTypeScriptServer({ root, workspaceRoot });
-  return tsserver ? dirname(tsserver) : null;
+  return tsserver ? dirname(tsserver) : findManagedTypeScriptSdk();
 }
 
 function resolveModuleFromRoots(id, { root, workspaceRoot }) {

package/src/lsp/service.mjs

@@ -13,8 +13,8 @@ export class LspService {
     this.announced = new Set();
   }
 
-  touchFile(path) {
-    const result = resolveLspServerStatus({ filePath: path, workspaceRoot: this.cwd });
+  async touchFile(path) {
+    const result = await resolveLspServerStatus({ filePath: path, workspaceRoot: this.cwd, onEvent: (event) => this.onEvent?.(event) });
     if (result.status === "unsupported") return result;
     if (result.status === "unavailable") {
       this.unavailable.set(result.id, result);
@@ -34,7 +34,7 @@ export class LspService {
       return { status: "starting", id: server.id, root: server.root };
     }
 
-    this.#emitOnce(`starting:${key}`, { status: "starting", id: server.id, root: server.root });
+    this.#emitOnce(`starting:${key}`, { status: "starting", id: server.id, root: server.root, managed: server.managed });
     const task = this.#startClient(server, key).then((client) => {
       client?.touchFile(path);
       return client;
@@ -47,7 +47,7 @@ export class LspService {
   }
 
   snapshot() {
-    const diagnostics = this.store.snapshot();
+    const storeSnapshot = this.store.snapshot();
     const servers = [
       ...[...this.clients.values()].map((client) => ({
         id: client.serverId,
@@ -61,7 +61,7 @@ export class LspService {
       })),
       ...this.unavailable.values(),
     ];
-    return { status: summarizeStatus(servers), diagnostics, servers };
+    return { status: summarizeStatus(servers), diagnostics: storeSnapshot.diagnostics, files: storeSnapshot.files, servers };
   }
 
   async dispose() {
@@ -81,7 +81,7 @@ export class LspService {
       await client.start();
       this.clients.set(key, client);
       this.unavailable.delete(server.id);
-      this.#emitOnce(`attached:${key}`, { status: "attached", id: server.id, root: server.root });
+      this.#emitOnce(`attached:${key}`, { status: "attached", id: server.id, root: server.root, managed: server.managed });
       return client;
     } catch (err) {
       client.status = "failed";

package/src/lsp/status-message.mjs

@@ -2,6 +2,7 @@ export function formatLspServiceEvent(event) {
   const id = event?.id ? String(event.id) : "server";
   if (event?.status === "attached") return `LSP attached: ${id}`;
   if (event?.status === "starting") return `LSP starting: ${id}`;
+  if (event?.status === "installing") return `LSP installing: ${id} - ${event.reason}`;
   if (event?.status === "failed") return `LSP failed: ${id} - ${event.reason}`;
   if (event?.status === "unavailable") return `LSP unavailable: ${id} - ${event.reason}`;
   return `LSP ${event?.status ?? "status"}: ${id}`;

package/src/lsp/typescript-project-resolver.mjs

@@ -0,0 +1,186 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+
+const CONFIG_RE = /^(?:tsconfig(?:\..+)?|jsconfig)\.json$/;
+const DEFAULT_EXCLUDES = ["node_modules", "bower_components", "jspm_packages"];
+const MATCH_EXTENSIONS = [".ts", ".tsx", ".d.ts", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"];
+
+export function resolveTypeScriptProjectRoot({ filePath, workspaceRoot }) {
+  const configs = findTypeScriptConfigs(dirname(filePath), workspaceRoot);
+  if (configs.length === 0) return null;
+
+  const included = configs.find((config) => configIncludesFile(config, filePath));
+  return dirname(included ?? configs[0]);
+}
+
+function findTypeScriptConfigs(start, stop) {
+  const configs = [];
+  let dir = resolve(start);
+  const boundary = resolve(stop);
+  for (;;) {
+    configs.push(...configFilesIn(dir));
+    if (dir === boundary || dirname(dir) === dir) return configs;
+    dir = dirname(dir);
+  }
+}
+
+function configFilesIn(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && CONFIG_RE.test(entry.name))
+    .map((entry) => entry.name)
+    .sort(configSort)
+    .map((name) => join(dir, name));
+}
+
+function configSort(a, b) {
+  return configRank(a) - configRank(b) || a.localeCompare(b);
+}
+
+function configRank(name) {
+  if (name === "tsconfig.json") return 0;
+  if (name === "jsconfig.json") return 1;
+  return 2;
+}
+
+function configIncludesFile(configPath, filePath) {
+  const config = readConfigChain(configPath);
+  if (!config) return false;
+
+  const exclude = config.exclude ?? DEFAULT_EXCLUDES.map((pattern) => ({ base: dirname(configPath), pattern }));
+  if (exclude.some(({ base, pattern }) => matchesPatternFromBase(filePath, base, pattern))) return false;
+
+  if (config.files) {
+    return config.files.some(({ base, pattern }) => normalizePath(relative(base, filePath)) === normalizePath(pattern));
+  }
+
+  if (config.include) {
+    return config.include.some(({ base, pattern }) => matchesPatternFromBase(filePath, base, pattern));
+  }
+
+  const file = normalizePath(relative(dirname(configPath), filePath));
+  return !isOutside(file) && MATCH_EXTENSIONS.some((ext) => file.endsWith(ext));
+}
+
+function readConfigChain(path, seen = new Set()) {
+  if (seen.has(path)) return null;
+  seen.add(path);
+
+  const raw = readConfig(path);
+  if (!raw) return null;
+  const base = resolveExtends(path, raw.extends, seen);
+  return {
+    files: patternList(raw.files, dirname(path)) ?? base?.files ?? null,
+    include: patternList(raw.include, dirname(path)) ?? base?.include ?? null,
+    exclude: patternList(raw.exclude, dirname(path)) ?? base?.exclude ?? null,
+  };
+}
+
+function resolveExtends(configPath, value, seen) {
+  if (typeof value !== "string" || !value.startsWith(".")) return null;
+  const resolved = resolve(dirname(configPath), value.endsWith(".json") ? value : `${value}.json`);
+  return existsSync(resolved) ? readConfigChain(resolved, seen) : null;
+}
+
+function readConfig(path) {
+  try {
+    return JSON.parse(stripJsonComments(readFileSync(path, "utf8")));
+  } catch {
+    return null;
+  }
+}
+
+function patternList(value, base) {
+  const items = arrayOfStrings(value);
+  return items ? items.map((pattern) => ({ base, pattern })) : null;
+}
+
+function arrayOfStrings(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : null;
+}
+
+function isOutside(path) {
+  return path === ".." || path.startsWith("../") || path.includes(":");
+}
+
+function matchesPatternFromBase(filePath, base, pattern) {
+  const file = normalizePath(relative(base, filePath));
+  return !isOutside(file) && matchesConfigPattern(file, pattern);
+}
+
+function matchesConfigPattern(file, pattern) {
+  const normalized = normalizePath(pattern);
+  if (!normalized.includes("*") && file === normalized) return true;
+  const glob = normalized.includes("*") ? normalized : `${trimSlash(normalized)}/**/*`;
+  return globToRegExp(glob).test(file);
+}
+
+function globToRegExp(glob) {
+  let source = "^";
+  for (let i = 0; i < glob.length; i += 1) {
+    const char = glob[i];
+    if (char === "*") {
+      if (glob[i + 1] === "*") {
+        i += 1;
+        if (glob[i + 1] === "/") {
+          i += 1;
+          source += "(?:.*/)?";
+        } else {
+          source += ".*";
+        }
+      } else {
+        source += "[^/]*";
+      }
+    } else if (char === "?") {
+      source += "[^/]";
+    } else {
+      source += escapeRegExp(char);
+    }
+  }
+  return new RegExp(`${source}$`);
+}
+
+function trimSlash(path) {
+  return path.replace(/\/+$/, "");
+}
+
+function normalizePath(path) {
+  return path.replaceAll("\\", "/");
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[|\\{}()[\]^$+*?.]/g, "\\$&");
+}
+
+function stripJsonComments(source) {
+  let out = "";
+  let inString = false;
+  let quote = "";
+  for (let i = 0; i < source.length; i += 1) {
+    const char = source[i];
+    const next = source[i + 1];
+    if (inString) {
+      out += char;
+      if (char === "\\") {
+        out += next ?? "";
+        i += 1;
+      } else if (char === quote) {
+        inString = false;
+      }
+    } else if (char === '"' || char === "'") {
+      inString = true;
+      quote = char;
+      out += char;
+    } else if (char === "/" && next === "/") {
+      while (i < source.length && source[i] !== "\n") i += 1;
+      out += "\n";
+    } else if (char === "/" && next === "*") {
+      i += 2;
+      while (i < source.length && !(source[i] === "*" && source[i + 1] === "/")) i += 1;
+      i += 1;
+    } else {
+      out += char;
+    }
+  }
+  return out.replace(/,\s*([}\]])/g, "$1");
+}

package/src/main.mjs

@@ -10,6 +10,7 @@ import { createInputHistoryStore } from "./cli/input/history-store.mjs";
 import { createModeState } from "./cli/input/mode-state.mjs";
 import { loadPromptTemplates } from "./cli/input/prompt-templates.mjs";
 import { runInteractiveRepl, runSingleShotPrompt } from "./cli/repl-loop.mjs";
+import { closeMarchRuntime } from "./cli/startup/runtime-close.mjs";
 import { createStatusLineUpdater } from "./cli/status-line-updater.mjs";
 import { wireTuiHandlers } from "./cli/tui/tui-handlers.mjs";
 import { createMarchAuthStorage } from "./auth/storage.mjs";
@@ -28,6 +29,7 @@ import { formatStartupBanner } from "./cli/startup/startup-banner.mjs";
 import { initializeMcp } from "./mcp/index.mjs";
 import { createWebToolsFromConfig } from "./web/tools.mjs";
 import { createModelContextDumper } from "./debug/model-context-dumper.mjs";
+import { createLogger, installProcessLogHandlers } from "./debug/logger.mjs";
 import { defaultCenterMemoryPath } from "./context/center-memory.mjs";
 import { runProviderConfigCommand } from "./provider/config-command.mjs";
 import { runWebSearchConfigCommand } from "./web/config-command.mjs";
@@ -68,6 +70,15 @@ export async function run(argv) {
 
   const stateRoot = join(homedir(), ".march");
   if (!existsSync(stateRoot)) mkdirSync(stateRoot, { recursive: true });
+  const logger = createLogger({ logDir: join(stateRoot, "logs") });
+  installProcessLogHandlers(logger);
+  logger.event("process.start", {
+    cwd,
+    argv,
+    version: process.version,
+    platform: process.platform,
+    logPath: logger.path,
+  });
 
   const provider = args.provider ?? config.provider ?? null;
   const serviceTier = config.serviceTier ?? null;
@@ -96,7 +107,6 @@ export async function run(argv) {
   const memoryStore = new MarkdownMemoryStore({ root: memoryRoot });
   const memoryTools = createMarkdownMemoryTools(memoryStore);
   const currentProject = basename(cwd);
-
   const shellRuntime = args.shellRuntime ? createCliShellRuntime({ cwd }) : null;
 
   // MCP: connect to configured MCP servers
@@ -182,9 +192,11 @@ export async function run(argv) {
     authStorage: authConfig.authStorage,
     maxTurns: config.maxTurns ?? undefined,
     trimBatch: config.trimBatch ?? undefined,
+    hostedTools: config.hostedTools,
     permissionController,
     modelContextDumper,
     turnNotifier,
+    logger,
     onModelPayload: ({ estimatedTokens }) => {
       refreshStatusBar?.({ contextTokens: estimatedTokens });
     },
@@ -235,8 +247,9 @@ export async function run(argv) {
       });
     } finally {
       turnRunning = false;
-      await closeMarchRuntime({ runner, memoryStore, ui, blankLine: true });
+      await closeMarchRuntime({ runner, memoryStore, ui, logger, blankLine: true });
     }
+    logger.event("process.exit", { code: 0 });
     return 0;
   }
 
@@ -264,32 +277,12 @@ export async function run(argv) {
       modeState,
     });
   } finally {
-    await closeMarchRuntime({ runner, memoryStore, ui });
+    await closeMarchRuntime({ runner, memoryStore, ui, logger });
   }
+  logger.event("process.exit", { code: 0 });
   return 0;
 }
 
-async function closeMarchRuntime({ runner, memoryStore, ui, blankLine = false }) {
-  let firstError = null;
-  try {
-    await runner.dispose();
-  } catch (err) {
-    firstError ??= err;
-  }
-  try {
-    memoryStore.close();
-  } catch (err) {
-    firstError ??= err;
-  }
-  try {
-    if (blankLine) ui.writeln("");
-    await ui.close();
-  } catch (err) {
-    firstError ??= err;
-  }
-  if (firstError) throw firstError;
-}
-
 function resolveMemoryRoot(configured, stateRoot) {
   if (configured) return resolve(String(configured));
   if (process.env.MARCH_MEMORY_ROOT) return resolve(process.env.MARCH_MEMORY_ROOT);

package/src/platform/spawn-command.mjs

@@ -0,0 +1,27 @@
+import { spawn } from "node:child_process";
+
+export function spawnCommand(command, args = [], options = {}) {
+  const resolved = resolveSpawnCommand(command, args);
+  return spawn(resolved.command, resolved.args, { ...options, ...resolved.options });
+}
+
+export function resolveSpawnCommand(command, args = []) {
+  if (process.platform !== "win32" || !isWindowsScriptCommand(command)) {
+    return { command, args };
+  }
+  // Node can fail to spawn .cmd/.bat directly on Windows; cmd.exe runs them reliably.
+  return {
+    command: "cmd.exe",
+    args: ["/d", "/s", "/c", `"${[quoteCmdArg(command), ...args.map(quoteCmdArg)].join(" ")}"`],
+    options: { windowsVerbatimArguments: true },
+  };
+}
+
+function isWindowsScriptCommand(command) {
+  const lower = command.toLowerCase();
+  return lower.endsWith(".cmd") || lower.endsWith(".bat");
+}
+
+function quoteCmdArg(value) {
+  return /[\s&()^|<>"%]/.test(value) ? `"${value.replaceAll('"', '""')}"` : value;
+}