@hncode/hncode 0.5.2 → 0.5.5

package/src/tools/fetch-url.js

@@ -1,6 +1,8 @@
 // FetchURL tool — fetch a web page's main text content (Node built-in fetch, no deps).
 
 import os from 'node:os';
+import http from 'node:http';
+import https from 'node:https';
 
 const MAX_BYTES = 200 * 1024; // generous cap for large pages
 
@@ -42,6 +44,100 @@ function rejectUrl(raw) {
   return null; // ok
 }
 
+/**
+ * A browser-ish header set.
+ *
+ * `Accept` is part of it: a request with a UA but an empty Accept still looks like a script to some
+ * servers, and they answer 406 or 429.
+ */
+const HEADERS = {
+  'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+  Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,text/plain;q=0.8,*/*;q=0.5',
+  'Accept-Language': 'en-US,en;q=0.9,zh-CN;q=0.8',
+};
+
+/** How long to wait before retrying a rate-limited request. */
+const RETRY_AFTER_MS = 1500;
+
+/**
+ * Fetch with the browser headers, retrying a 429 once.
+ *
+ * One retry after a short pause turns a transient rate limit into a success; a second immediate attempt
+ * would only count as another request against the limit.
+ */
+/**
+ * Fetch with the browser headers, retrying a 429 once.
+ *
+ * `insecure` SKIPS CERTIFICATE VERIFICATION, for a host whose chain is broken — an internal server with a
+ * self-signed certificate, an expired intermediate — where the alternative is not fetching it at all.
+ *
+ * `fetch` has no per-request switch for this: the option lives on the dispatcher, and Node does not expose
+ * one without the `undici` package this project does not depend on. So that path goes through
+ * `node:https` instead. It is the SAME request — same headers, same redirects, same body cap — just built
+ * by hand so `rejectUnauthorized: false` can be passed.
+ */
+async function fetchWithRetry(url, signal, insecure = false) {
+  if (insecure) return httpsRequest(url, signal, true);
+  const first = await fetch(url, { signal, redirect: 'follow', headers: HEADERS });
+  if (first.status !== 429) return first;
+  await new Promise((r) => setTimeout(r, RETRY_AFTER_MS));
+  // The first response body was never read; release it so the connection can be reused.
+  try { await first.body?.cancel(); } catch { /* already gone */ }
+  return fetch(url, { signal, redirect: 'follow', headers: HEADERS });
+}
+
+/**
+ * One GET over `node:https`, returning the shape the caller already handles.
+ *
+ * Only used for the `insecure` path, where `fetch` cannot express what is needed. The response is
+ * buffered up to MAX_BYTES and handed back as an object with `.ok`, `.status`, `.headers.get()` and
+ * `.arrayBuffer()`, so the rest of `execute` does not know which transport ran.
+ */
+function httpsRequest(url, signal, insecure) {
+  return new Promise((resolve, reject) => {
+    let u;
+    try { u = new URL(url); } catch (e) { reject(e); return; }
+    const mod = u.protocol === 'http:' ? http : https;
+    const req = mod.request({
+      protocol: u.protocol,
+      hostname: u.hostname,
+      port: u.port || undefined,
+      path: u.pathname + u.search,
+      method: 'GET',
+      headers: HEADERS,
+      // The whole point of this path. Every other request in the tool keeps verification on.
+      rejectUnauthorized: !insecure,
+    }, (res) => {
+      // A redirect is followed rather than reported: `fetch` defaults to `follow`, and a fetch that
+      // stopped at a 301 would silently return an empty body for most of the web.
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        res.resume();
+        const next = new URL(res.headers.location, u).href;
+        resolve(httpsRequest(next, signal, insecure));
+        return;
+      }
+      const chunks = [];
+      let got = 0;
+      res.on('data', (c) => { if (got < MAX_BYTES) { chunks.push(c); got += c.length; } });
+      res.on('end', () => {
+        const body = Buffer.concat(chunks);
+        resolve({
+          ok: res.statusCode >= 200 && res.statusCode < 300,
+          status: res.statusCode,
+          statusText: res.statusMessage || '',
+          headers: { get: (n) => res.headers[String(n).toLowerCase()] || null },
+          arrayBuffer: async () => body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength),
+          body: null,
+        });
+      });
+      res.on('error', reject);
+    });
+    req.on('error', reject);
+    if (signal) signal.addEventListener('abort', () => req.destroy(new Error('interrupted')), { once: true });
+    req.end();
+  });
+}
+
 export const spec = {
   name: 'FetchURL',
   description: 'Fetch a URL and return its text (main page text, or the full body; a leading note says which). Any http/https URL, including localhost.',
@@ -49,6 +145,7 @@ export const spec = {
     type: 'object',
     properties: {
       url: { type: 'string', description: 'URL to fetch.' },
+      insecure: { type: 'boolean', default: false, description: 'Skip TLS certificate verification. For a host with a self-signed or expired certificate whose content is still wanted — the connection is no longer authenticated, so only use it for a source you already trust.' },
     },
     required: ['url'],
   },
@@ -57,10 +154,21 @@ export const spec = {
     if (rejected) return rejected;
     const signal = (ctx && ctx.signal) || undefined;
     try {
-      const res = await fetch(args.url.trim(), { signal, redirect: 'follow' });
-      if (!res.ok) {
-        return `Error: ${res.status} ${res.statusText} from ${args.url}`;
-      }
+      // A BROWSER USER-AGENT, and it is not cosmetic.
+      //
+      // Without one Node sends `user-agent: node`, and a great many sites answer that with 403 or 429
+      // before serving anything. Measured on a wukongsch.com article: 429 with the default headers,
+      // served normally with a browser UA.
+      const res = await fetchWithRetry(args.url.trim(), signal, args.insecure === true);
+      if (!res.ok) {
+        // SAY WHAT THE STATUS MEANS. A bare 429 left the caller re-fetching the same page to see the
+        // same number.
+        const hint = res.status === 429 ? ' — the site is rate-limiting requests; wait and retry, or find another source.'
+          : res.status === 403 ? ' — the site refused the request; it may require a login or block automated fetches.'
+            : res.status === 404 ? ' — no such page.'
+              : '';
+        return `Error: ${res.status} ${res.statusText} from ${args.url}${hint}`;
+      }
       const contentType = (res.headers.get('content-type') || '').toLowerCase();
       const isHtml = contentType.includes('text/html') || contentType.includes('application/xhtml');
       let isTruncated = false;
@@ -101,7 +209,12 @@ export const spec = {
       if (isTruncated) out += `\n\n[... truncated; page larger than ${Math.round(MAX_BYTES / 1024)} KB]`;
       return out;
     } catch (e) {
-      const msg = e && e.name === 'AbortError' ? 'interrupted' : (e.message || String(e));
+      // 'fetch failed' IS NOT A REASON. Node puts the real cause — ENOTFOUND, ECONNREFUSED,
+      // CERT_HAS_EXPIRED, a TLS handshake failure — on `e.cause`, and only `e.message` was read, so
+      // every distinct failure looked identical and told the caller nothing they could act on.
+      const cause = e && e.cause ? (e.cause.code || e.cause.message) : '';
+      const base = e && e.name === 'AbortError' ? 'interrupted' : (e.message || String(e));
+      const msg = cause && !String(base).includes(cause) ? `${base} (${cause})` : base;
       return `Error fetching ${args.url}: ${msg}`;
     }
   },

package/src/tools/glob.js

@@ -4,7 +4,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { normalizeInput } from './utils.js';
+import { resolvePath } from './utils.js';
 import { walkFiles } from './ignore.js';
 import { globToRegexSource, expandBraces } from './matchers.js';
 
@@ -29,9 +29,11 @@ export const spec = {
       return 'Error: `pattern` is required (e.g. "src/**/*.ts").';
     }
     const fromDir = typeof args.path === 'string' && args.path ? args.path : '.';
-    const p = normalizeInput(fromDir);
     let base;
-    try { base = path.resolve(ctx.cwd || ctx.workspace, p); } catch (e) { return `Error: ${e.message}`; }
+    // Same workspace boundary as Read/Write/Edit. Glob resolved `path` directly,
+    // so `Glob { pattern: '**', path: 'C:\\Users\\...' }` walked any directory on
+    // disk with no permission gate at all.
+    try { base = resolvePath(fromDir, ctx); } catch (e) { return `Error: ${e.message}`; }
     if (!fs.existsSync(base)) return `Error: path does not exist: ${fromDir}`;
     if (!fs.statSync(base).isDirectory()) return `Error: --path is not a directory: ${fromDir}`;
 

package/src/tools/grep.js

@@ -5,7 +5,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import cp from 'node:child_process';
-import { normalizeInput, isProbablyTextFile, truncateBuf } from './utils.js';
+import { isProbablyTextFile, truncateBuf, resolvePath } from './utils.js';
 import { walkFiles } from './ignore.js';
 import { matchGlob } from './matchers.js';
 
@@ -33,8 +33,11 @@ export const spec = {
     required: ['pattern'],
   },
   async execute(args, ctx) {
-    const p = normalizeInput(args.path || '.');
-    const base = path.resolve(ctx.cwd || ctx.workspace, p);
+    // Same workspace boundary as Read/Write/Edit. Grep resolved `path` directly,
+    // so `Grep { pattern: 'KEY', path: 'C:/Users/...' }` searched any directory
+    // on disk — the search tools had no gate at all.
+    let base;
+    try { base = resolvePath(args.path || '.', ctx); } catch (e) { return `Error: ${e.message}`; }
     if (!fs.existsSync(base)) return `Error: path does not exist: ${args.path}`;
     if (!args.multiline && hasRg()) return await grepRg(args, base, ctx);
     return grepJs(args, base, ctx);
@@ -58,7 +61,11 @@ function hasRg() {
 }
 
 function buildRgArgs(args, base) {
-  const a = ['--no-heading', '--line-number', '--no-config', '-e', args.pattern];
+  // --crlf: an end anchor (`;$`) must match a line that ends `\r\n`, exactly as
+  // it does in an LF file — and as the JS fallback already does. Without it the
+  // rg path reported "No matches found" for patterns the user could SEE ending
+  // the line, on this repo's own CRLF files.
+  const a = ['--no-heading', '--line-number', '--no-config', '--crlf', '-e', args.pattern];
   if (args['-i']) a.push('-i');
   const before = args['-B'] || (args['-C'] || 0);
   const after = args['-A'] || (args['-C'] || 0);
@@ -99,6 +106,13 @@ function grepRg(args, base, ctx) {
     child.on('error', () => done(() => resolve(grepJs(args, base, ctx))));
     child.on('close', (code) => done(() => {
       if (code > 1 && stderr) resolve(`rg error: ${stderr.trim()}`);
+      else if (!stdout.trim() && args.pattern.includes('$')) {
+        // A zero-match END-ANCHORED query may be a LONE-CR file (old-Mac endings),
+        // which rg cannot treat as line breaks at all. The JS walker handles every
+        // ending, so it gets the final word — only for `$` patterns that found
+        // nothing, so ordinary searches never pay for the extra pass.
+        resolve(grepJs(args, base, ctx));
+      }
       else resolve(paginate(stdout, args));
     }));
     // Honour an aborted turn (Esc): kill rg instead of leaving it running.
@@ -113,7 +127,7 @@ function grepRg(args, base, ctx) {
 function grepJs(args, base, ctx) {
   const flags = 'g' + (args['-i'] ? 'i' : '') + (args.multiline ? 's' : '');
   const re = new RegExp(args.pattern, flags);
-  const files = walkFiles(base, { includeIgnored: !!args.include_ignored, includeDirs: false });
+  const files = walkFiles(base, { includeIgnored: !!args.include_ignored, includeDirs: false, limit: 0 });
   const filtered = files.filter((abs) => {
     if (args.glob) {
       const rel = path.relative(base, abs).split(path.sep).join('/');

package/src/tools/ignore.js

@@ -77,17 +77,29 @@ export function matchPattern(pat, relPath, isDir) {
 // duplication, since the information was already available as each entry was
 // visited. One stat per file now, reused for both.
 export function walkFiles(base, opts = {}) {
-  const { includeIgnored = false, includeDirs = false } = opts;
+  // `limit` caps the RESULT. Glob keeps the default (newest 100); Grep passes 0 —
+  // truncating the WALK by mtime made the search silently skip older files and
+  // report "No matches found" for text that was right there.
+  const { includeIgnored = false, includeDirs = false, limit = 1000 } = opts;
   const baseAbs = path.resolve(base);
   /** @type {{path:string, mtime:number, isFile:boolean}[]} */
   const found = [];
   _walk(baseAbs, '', [], found, { includeIgnored, includeDirs });
-  // Newest first. Sort before truncating so the newest 1000 survive the cap.
+  // Newest first. Sort before truncating so the newest entries survive the cap.
   found.sort((a, b) => b.mtime - a.mtime);
-  if (found.length > 1000) found.length = 1000;
+  if (limit > 0 && found.length > limit) found.length = limit;
   return found.filter((e) => includeDirs || e.isFile).map((e) => e.path);
 }
 
+// Directories that are never worth walking. `.git` holds the object database —
+// hundreds of thousands of files on an old repo, none of them source, and no
+// .gitignore ever lists it. `node_modules` is pruned for the JS walker unless the
+// caller explicitly asked for ignored files: walking it was a multi-second stall
+// of the event loop (everything here is readdirSync/statSync) for results nobody
+// wanted.
+const PRUNED_DIRS = new Set(['.git']);
+const PRUNED_UNLESS_IGNORED = new Set(['node_modules']);
+
 function _walk(dir, relPrefix, parentPatterns, found, opts) {
   const { includeIgnored, includeDirs } = opts;
   let entries;
@@ -98,6 +110,8 @@ function _walk(dir, relPrefix, parentPatterns, found, opts) {
     const abs = path.join(dir, ent.name);
     let isDir;
     try { isDir = ent.isDirectory(); } catch { try { isDir = fs.statSync(abs).isDirectory(); } catch { isDir = false; } }
+    if (isDir && (PRUNED_DIRS.has(ent.name)
+      || (!includeIgnored && PRUNED_UNLESS_IGNORED.has(ent.name)))) continue;
     // ignore decision
     let ignored = false;
     for (const pat of acc) {

package/src/tools/index.js

@@ -16,13 +16,13 @@ import * as gitMod from './git.js';
 import * as askUserQuestionMod from './ask-user-question.js';
 import { spec as agentSpec } from './agent.js';
 import { spec as agentSwarmSpec } from './agent-swarm.js';
-import { TaskListSpec, TaskOutputSpec, TaskStopSpec, TaskWaitSpec } from './tasks.js';
+import { TaskListSpec, TaskOutputSpec, TaskStopSpec, TaskWaitSpec, TaskInputSpec } from './tasks.js';
 import { AgentListSpec, AgentMessageSpec, AgentInterruptSpec, AgentCloseSpec } from './agent-control.js';
 import { TEAM_TOOL_SPECS } from './team.js';
 import { spec as notebookSpec } from './notebook.js';
 import { spec as diagnosticsSpec } from './diagnostics.js';
 import * as memoryMod from './memory.js';
-import { pluginTools } from '../plugin.js';
+import { pluginTools, pluginToolGeneration } from '../plugin.js';
 
 
 
@@ -47,6 +47,7 @@ const builtinTools = [
   TaskOutputSpec,
   TaskStopSpec,
   TaskWaitSpec,
+  TaskInputSpec,
   AgentListSpec,
   AgentMessageSpec,
   AgentInterruptSpec,
@@ -72,11 +73,24 @@ export { builtinTools };
 // tools are resolvable. The previous Map was built from builtinTools only,
 // so `llmTools()` advertised a plugin tool to the model but `getTool(name)`
 // returned undefined and the call failed with `unknown tool`.
+//
+// The map is keyed to a REGISTRATION GENERATION: plugin.js bumps the counter
+// whenever a tool registers or the plugin set is reloaded. Without that, a
+// server connected in the background (MCP connects after first paint) stayed
+// "unknown tool" forever, and /reload served the OLD plugin instances while
+// fresh modules were imported under new spec objects.
 let _byName = null;
+let _byNameGeneration = -1;
+function toolGeneration() {
+  // Read live from plugin.js so any registration source bumps the same counter.
+  return pluginToolGeneration();
+}
 function byNameMap() {
-  if (!_byName) {
+  const gen = toolGeneration();
+  if (!_byName || _byNameGeneration !== gen) {
     _byName = new Map();
     for (const t of combinedTools()) if (!_byName.has(t.name)) _byName.set(t.name, t);
+    _byNameGeneration = gen;
   }
   return _byName;
 }

package/src/tools/read.js

@@ -64,14 +64,25 @@ export const spec = {
     if (!isProbablyTextFile(buf)) {
       return `Cannot read: ${args.path} appears to be a binary file (use a tool suited for binary).`;
     }
-    let st;
+    let st = null;
+    try { st = fs.statSync(p); } catch { /* stat is advisory only */ }
     // NO truncation: the caller asked for the file, so the whole file is returned
     // (line ranges still work via line_offset / n_lines). The old 1000-line and
     // 128 KB caps silently cut the content, which also corrupted the
     // staleness hashes recorded below because they were computed from the
     // TRUNCATED text rather than the file on disk.
     const text = buf.toString('utf8');
-    const lines = normalizeText(text).split('\n');
+    // A FILE ENDING IN A NEWLINE HAS ONE FEWER LINE THAN `split` REPORTS.
+    //
+    // `"a\nb\n".split("\n")` is `["a", "b", ""]` — the trailing newline leaves an empty element, and
+    // counting it made a ten-line file report `lines 1-11 of 11`. The numbers on each line were right;
+    // the TOTAL was one too high, so a caller planning an edit at the end of the file aimed at a row that
+    // does not exist.
+    //
+    // Only the element the trailing newline produced is dropped: a file that genuinely ends with a blank
+    // line (`"a\n\n"`) keeps it, because that is real content.
+    const lines = normalizeText(text).split("\n");
+    if (lines.length > 1 && lines[lines.length - 1] === "") lines.pop();
     const total = lines.length;
     // Default: every line. An explicit n_lines still narrows the window.
     const nLines = args.n_lines ? args.n_lines : total;

package/src/tools/shell.js

@@ -1,134 +1,145 @@
-// Shell discovery for the Bash tool.
-//
-// The tool used to hardcode `spawn('pwsh', …)`, which relies on `pwsh` being on
-// PATH. On a Windows box with only the built-in Windows PowerShell that name does
-// not resolve at all, so the spawn failed with ENOENT and the whole tool was dead —
-// no fallback, and nothing in the message said why. It only ever worked where the
-// user had installed PowerShell 7 and added it to PATH by hand.
-//
-// Mirrors Claude Code's findPowerShell (src/utils/shell/powershellDetection.ts):
-// prefer pwsh (Core 7+), fall back to powershell (Desktop 5.1), and cache the
-// answer — the probe shells out, so it must not run per command.
-//
-// The EDITION matters beyond picking a binary: 7+ supports the pipeline chain
-// operators (`&&`, `||`) and 5.1 does not, so the prompt's syntax guidance depends
-// on which one was found.
-
-import cp from 'node:child_process';
-import fs from 'node:fs';
-
-// The two PowerShell families, by the name they are invoked as.
-export const SHELL_CANDIDATES = ['pwsh', 'powershell'];
-
-// Last-resort Windows fallback. A Windows box always has cmd.exe (%COMSPEC%),
-// so when neither PowerShell exists the Bash tool must still run SOMETHING
-// rather than failing outright. `cmd` is not a PowerShell, so the syntax
-// guidance and the spawn args differ (see cmdSpawnArgs).
-export function findCmdExe() {
-  const fromEnv = process.env.COMSPEC || process.env.ComSpec;
-  if (fromEnv) {
-    try { if (fs.existsSync(fromEnv)) return fromEnv; } catch { /* fall through to the PATH probe */ }
-  }
-  if (process.platform === 'win32') {
-    return whichSync('cmd') || whichSync('cmd.exe') || 'cmd.exe';
-  }
-  return null;
-}
-
-/**
- * Resolve an executable name through PATH without spawning it.
- *
- * `where` on Windows / `which` on POSIX are the platform's own resolvers, so the
- * answer matches what a shell would do. Returns the first absolute path or null.
- */
-function whichSync(name) {
-  const probe = process.platform === 'win32' ? 'where' : 'which';
-  try {
-    const out = cp.execFileSync(probe, [name], {
-      stdio: ['ignore', 'pipe', 'ignore'],
-      encoding: 'utf8',
-      windowsHide: true,
-    });
-    // `where` can print several matches; take the first non-empty line.
-    const first = String(out).split(/\r?\n/).map((l) => l.trim()).filter(Boolean)[0];
-    return first || null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Find a usable shell: pwsh, then the built-in powershell, then (on Windows)
- * cmd.exe as a last resort. Returns { path, name, edition } or null.
- *
- * `edition` drives syntax guidance — see the header. It is inferred from the NAME
- * rather than by running the binary (a spawn per probe is not worth it, and
- * PowerShell 6, also named `pwsh`, is EOL and not a realistic target, so `pwsh`
- * safely implies 7+). `edition: 'cmd'` means neither PowerShell exists and the
- * Bash tool is running through cmd.exe: it still works, but the command syntax is
- * cmd's, not PowerShell's.
- */
-export function detectShell() {
-  for (const name of SHELL_CANDIDATES) {
-    const path = whichSync(name);
-    if (path) {
-      return { path, name, edition: name === 'pwsh' ? 'core' : 'desktop' };
-    }
-  }
-  // No PowerShell at all: on Windows, guarantee cmd.exe so the tool is not dead.
-  const cmd = findCmdExe();
-  if (cmd) return { path: cmd, name: 'cmd', edition: 'cmd' };
-  return null;
-}
-
-let cached;          // undefined = not probed yet; null = probed, none found
-let cachedEnvKey;    // re-probe if PATH changes (a /env PATH=… must take effect)
-
-/**
- * Cached detectShell(). The probe spawns a process, so it runs once per PATH.
- * Re-probing when PATH changes means an in-session PATH fix (`/env PATH=…`, which
- * is exactly what a user with a stripped PATH would do) can rescue the tool.
- */
-export function getShell() {
-  const key = String(process.env.PATH || '');
-  if (cached === undefined || cachedEnvKey !== key) {
-    cached = detectShell();
-    cachedEnvKey = key;
-  }
-  return cached;
-}
-
-/** Test seam: forget the cached probe. */
-export function resetShellCache() {
-  cached = undefined;
-  cachedEnvKey = undefined;
-}
-
-/**
- * The command + args to run `command` through the detected shell.
- *
- * `-NoProfile` and `-NonInteractive` are not cosmetic: a user profile can print a
- * banner into stdout (polluting the captured result) and can take seconds to load
- * on every single tool call, and `-NonInteractive` stops a command that prompts
- * from hanging the tool forever with no way to answer.
- *
- * When neither PowerShell exists, `edition === 'cmd'` selects cmd.exe args instead
- * (see detectShell). Throws a message naming the fix only when no shell at all
- * was found, instead of letting the caller hit a bare ENOENT.
- */
-export function shellSpawnArgs(command) {
-  const shell = getShell();
-  if (!shell) {
-    throw new Error(
-      'No shell found (tried pwsh, powershell, and cmd.exe). '
-      + 'Install PowerShell 7+ or add it to PATH, then retry.',
-    );
-  }
-  if (shell.edition === 'cmd') {
-    // cmd.exe: `/d` skips AutoRun commands, `/s` makes `/c` quoting behave
-    // predictably. The command is passed as ONE argv element, so Node does the
-    // quoting and we do not wrap it ourselves.
-    return { bin: shell.path, args: ['/d', '/s', '/c', command], shell };
-  }
-  return { bin: shell.path, args: ['-NoProfile', '-NonInteractive', '-Command', command], shell };
-}
+// Shell discovery for the Bash tool.
+//
+// The tool used to hardcode `spawn('pwsh', …)`, which relies on `pwsh` being on
+// PATH. On a Windows box with only the built-in Windows PowerShell that name does
+// not resolve at all, so the spawn failed with ENOENT and the whole tool was dead —
+// no fallback, and nothing in the message said why. It only ever worked where the
+// user had installed PowerShell 7 and added it to PATH by hand.
+//
+// Mirrors Claude Code's findPowerShell (src/utils/shell/powershellDetection.ts):
+// prefer pwsh (Core 7+), fall back to powershell (Desktop 5.1), and cache the
+// answer — the probe shells out, so it must not run per command.
+//
+// The EDITION matters beyond picking a binary: 7+ supports the pipeline chain
+// operators (`&&`, `||`) and 5.1 does not, so the prompt's syntax guidance depends
+// on which one was found.
+
+import cp from 'node:child_process';
+import fs from 'node:fs';
+
+// The two PowerShell families, by the name they are invoked as.
+export const SHELL_CANDIDATES = ['pwsh', 'powershell'];
+
+// Last-resort Windows fallback. A Windows box always has cmd.exe (%COMSPEC%),
+// so when neither PowerShell exists the Bash tool must still run SOMETHING
+// rather than failing outright. `cmd` is not a PowerShell, so the syntax
+// guidance and the spawn args differ (see cmdSpawnArgs).
+export function findCmdExe() {
+  const fromEnv = process.env.COMSPEC || process.env.ComSpec;
+  if (fromEnv) {
+    try { if (fs.existsSync(fromEnv)) return fromEnv; } catch { /* fall through to the PATH probe */ }
+  }
+  if (process.platform === 'win32') {
+    return whichSync('cmd') || whichSync('cmd.exe') || 'cmd.exe';
+  }
+  return null;
+}
+
+/**
+ * Resolve an executable name through PATH without spawning it.
+ *
+ * `where` on Windows / `which` on POSIX are the platform's own resolvers, so the
+ * answer matches what a shell would do. Returns the first absolute path or null.
+ */
+function whichSync(name) {
+  const probe = process.platform === 'win32' ? 'where' : 'which';
+  try {
+    const out = cp.execFileSync(probe, [name], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf8',
+      windowsHide: true,
+    });
+    // `where` can print several matches; take the first non-empty line.
+    const first = String(out).split(/\r?\n/).map((l) => l.trim()).filter(Boolean)[0];
+    return first || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find a usable shell: pwsh, then the built-in powershell, then (on Windows)
+ * cmd.exe as a last resort. Returns { path, name, edition } or null.
+ *
+ * `edition` drives syntax guidance — see the header. It is inferred from the NAME
+ * rather than by running the binary (a spawn per probe is not worth it, and
+ * PowerShell 6, also named `pwsh`, is EOL and not a realistic target, so `pwsh`
+ * safely implies 7+). `edition: 'cmd'` means neither PowerShell exists and the
+ * Bash tool is running through cmd.exe: it still works, but the command syntax is
+ * cmd's, not PowerShell's.
+ */
+export function detectShell() {
+  for (const name of SHELL_CANDIDATES) {
+    const path = whichSync(name);
+    if (path) {
+      return { path, name, edition: name === 'pwsh' ? 'core' : 'desktop' };
+    }
+  }
+  // No PowerShell at all: on Windows, guarantee cmd.exe so the tool is not dead.
+  const cmd = findCmdExe();
+  if (cmd) return { path: cmd, name: 'cmd', edition: 'cmd' };
+  return null;
+}
+
+let cached;          // undefined = not probed yet; null = probed, none found
+let cachedEnvKey;    // re-probe if PATH changes (a /env PATH=… must take effect)
+
+/**
+ * Cached detectShell(). The probe spawns a process, so it runs once per PATH.
+ * Re-probing when PATH changes means an in-session PATH fix (`/env PATH=…`, which
+ * is exactly what a user with a stripped PATH would do) can rescue the tool.
+ */
+export function getShell() {
+  const key = String(process.env.PATH || '');
+  if (cached === undefined || cachedEnvKey !== key) {
+    cached = detectShell();
+    cachedEnvKey = key;
+  }
+  return cached;
+}
+
+/** Test seam: forget the cached probe. */
+export function resetShellCache() {
+  cached = undefined;
+  cachedEnvKey = undefined;
+}
+
+/**
+ * The command + args to run `command` through the detected shell.
+ *
+ * `-NoProfile` and `-NonInteractive` are not cosmetic: a user profile can print a
+ * banner into stdout (polluting the captured result) and can take seconds to load
+ * on every single tool call, and `-NonInteractive` stops a command that prompts
+ * from hanging the tool forever with no way to answer.
+ *
+ * When neither PowerShell exists, `edition === 'cmd'` selects cmd.exe args instead
+ * (see detectShell). Throws a message naming the fix only when no shell at all
+ * was found, instead of letting the caller hit a bare ENOENT.
+ */
+/**
+ * The spawn argv for a command.
+ *
+ * `interactive` drops `-NonInteractive`, and that is not cosmetic: PowerShell in non-interactive mode
+ * treats stdin as an already-finished stream and closes it, so a child started that way reads EOF
+ * immediately and exits — before anything can be written to it. The flag has to come off for
+ * `Bash {interactive: true}` to mean anything.
+ */
+export function shellSpawnArgs(command, opts = {}) {
+  const shell = getShell();
+  if (!shell) {
+    throw new Error(
+      'No shell found (tried pwsh, powershell, and cmd.exe). '
+      + 'Install PowerShell 7+ or add it to PATH, then retry.',
+    );
+  }
+  if (shell.edition === 'cmd') {
+    // cmd.exe: `/d` skips AutoRun commands, `/s` makes `/c` quoting behave
+    // predictably. The command is passed as ONE argv element, so Node does the
+    // quoting and we do not wrap it ourselves.
+    return { bin: shell.path, args: ['/d', '/s', '/c', command], shell };
+  }
+  const args = ['-NoProfile'];
+  if (!opts.interactive) args.push('-NonInteractive');
+  args.push('-Command', command);
+  return { bin: shell.path, args, shell };
+}