@hncode/hncode 0.4.0 → 0.4.2

package/src/remote.js

@@ -0,0 +1,271 @@
+// Remote skills and plugins — pull them from the hncode GitHub repo.
+//
+// Both live in the repo under a folder per item:
+//
+//   skills/<name>/SKILL.md      ->  ~/.hncode/skills/<name>.md
+//   plugins/<name>/…            ->  ~/.hncode/plugins/…
+//
+// The layout differs on purpose. A SKILL is a single Markdown prompt fragment, so it
+// is FLATTENED to `<name>.md`: that is what `skills.js` already reads (and what makes
+// `/skill:<name>` work without teaching the loader about directories). A PLUGIN is an
+// ESM module that may sit beside helper files, so it is copied as a directory or, when
+// it is a single file, as that file — see installPlugin.
+//
+// Discovery uses the GitHub Contents API and downloads use raw.githubusercontent.com.
+// No git, no dependencies: a user who has never installed git can still pull a skill,
+// and fetching one item does not drag down the whole repository.
+//
+// Everything network-facing is best-effort and reports failure as a value rather than
+// throwing, so a command can print what went wrong instead of killing the TUI.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { skillsDir, normalizeSkillName } from './skills.js';
+
+// The canonical source. Overridable so a fork (or a test) can point elsewhere.
+export const DEFAULT_REPO = process.env.HNCODE_REPO || 'NiceHello666/hncode';
+export const DEFAULT_REF = process.env.HNCODE_REPO_REF || 'main';
+
+// Where remote plugins land. `plugin.js` loads *.js/*.mjs from this directory.
+export function pluginsDir() {
+  return process.env.HNCODE_PLUGINS || path.join(os.homedir(), '.hncode', 'plugins');
+}
+
+// Plugin files that are never worth downloading or dangerous to copy blindly.
+const PLUGIN_EXT = new Set(['.js', '.mjs', '.cjs', '.json', '.md']);
+
+const USER_AGENT = 'hncode-remote';
+
+async function ghJson(url, { timeoutMs = 15000 } = {}) {
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      signal: ctl.signal,
+      headers: { accept: 'application/vnd.github+json', 'user-agent': USER_AGENT },
+    });
+    if (!res.ok) {
+      // 404 is the normal "the folder does not exist yet" case, so it gets its own
+      // wording: the repo simply has not had anything contributed to that folder.
+      if (res.status === 404) return { ok: false, error: 'not-found' };
+      if (res.status === 403) return { ok: false, error: 'rate-limited' };
+      return { ok: false, error: `HTTP ${res.status}` };
+    }
+    return { ok: true, data: await res.json() };
+  } catch (e) {
+    return { ok: false, error: e && e.name === 'AbortError' ? 'timed out' : String((e && e.message) || e) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function fetchText(url, { timeoutMs = 20000 } = {}) {
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: ctl.signal, headers: { 'user-agent': USER_AGENT } });
+    if (!res.ok) return { ok: false, error: `HTTP ${res.status}` };
+    return { ok: true, text: await res.text() };
+  } catch (e) {
+    return { ok: false, error: e && e.name === 'AbortError' ? 'timed out' : String((e && e.message) || e) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function apiContents(repo, ref, dir) {
+  return `http://127.0.0.1:62578/api/repos/${repo}/contents/${dir}${ref ? `?ref=${encodeURIComponent(ref)}` : ''}`;
+}
+
+function rawUrl(repo, ref, file) {
+  return `http://127.0.0.1:62578/raw/${repo}/${ref}/${file}`;
+}
+
+// Each item is a DIRECTORY in the repo (skills/<name>/, plugins/<name>/). A loose file
+// at the top level is ignored: the convention is the contract, and accepting both
+// would make the listing ambiguous about what a name refers to.
+function dirsOnly(entries) {
+  return (Array.isArray(entries) ? entries : [])
+    .filter((e) => e && e.type === 'dir' && e.name && !e.name.startsWith('.'))
+    .map((e) => ({ name: e.name, path: e.path }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** List the skills available in the repo: [{ name, path }]. */
+export async function listRemoteSkills({ repo = DEFAULT_REPO, ref = DEFAULT_REF } = {}) {
+  const r = await ghJson(apiContents(repo, ref, 'skills'));
+  if (!r.ok) return r;
+  return { ok: true, items: dirsOnly(r.data) };
+}
+
+/** List the plugins available in the repo: [{ name, path }]. */
+export async function listRemotePlugins({ repo = DEFAULT_REPO, ref = DEFAULT_REF } = {}) {
+  const r = await ghJson(apiContents(repo, ref, 'plugins'));
+  if (!r.ok) return r;
+  return { ok: true, items: dirsOnly(r.data) };
+}
+
+// A skill's description comes from its front-matter (the same field `skills.js` reads
+// for a local skill), so the local and remote listings describe a skill identically.
+function describeSkill(text) {
+  const m = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---/.exec(String(text || ''));
+  if (!m) return '';
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^\s*(?:description|title)\s*:\s*(.*?)\s*$/.exec(line);
+    if (kv) {
+      let v = kv[1];
+      if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+      return v;
+    }
+  }
+  return '';
+}
+
+/**
+ * Fetch the SKILL.md inside each remote skill directory, so the list can show what a
+ * skill is before the user installs it. One request per skill; failures leave the
+ * description empty rather than dropping the entry.
+ */
+export async function listRemoteSkillsDetailed({ repo = DEFAULT_REPO, ref = DEFAULT_REF } = {}) {
+  const listed = await listRemoteSkills({ repo, ref });
+  if (!listed.ok) return listed;
+  const items = await Promise.all(listed.items.map(async (it) => {
+    const file = `${it.path}/SKILL.md`;
+    const r = await fetchText(rawUrl(repo, ref, file));
+    return { ...it, file, description: r.ok ? describeSkill(r.text) : '', readable: r.ok };
+  }));
+  return { ok: true, items };
+}
+
+/**
+ * Install one remote skill as `~/.hncode/skills/<name>.md`.
+ *
+ * The repo requires the file to be named SKILL.md; a directory without one is skipped
+ * (returns ok:false) instead of creating a nameless entry. Returns
+ * { ok, name, path, replaced } or { ok: false, error }.
+ */
+export async function installRemoteSkill(name, { repo = DEFAULT_REPO, ref = DEFAULT_REF, overwrite = true } = {}) {
+  const clean = normalizeSkillName(name);
+  // A name is a path SEGMENT in the repo URL. Reject anything that could escape it or
+  // name a hidden directory, before the request is even made — `.hidden` used to slip
+  // through and only fail later as a confusing "no SKILL.md" 404.
+  if (!clean || /[\\/]/.test(clean) || clean.startsWith('.') || /[\u0000-\u001f]/.test(clean)) {
+    return { ok: false, error: `Invalid skill name: ${name}` };
+  }
+
+  const file = `skills/${clean}/SKILL.md`;
+  const r = await fetchText(rawUrl(repo, ref, file));
+  if (!r.ok) {
+    return { ok: false, error: r.error === 'HTTP 404'
+      ? `No SKILL.md at ${file} (each skill directory must contain SKILL.md).`
+      : `Could not download ${file}: ${r.error}` };
+  }
+  if (!r.text.trim()) return { ok: false, error: `${file} is empty.` };
+
+  const dir = skillsDir();
+  const dest = path.join(dir, `${clean}.md`);
+  const replaced = fs.existsSync(dest);
+  if (replaced && !overwrite) return { ok: false, error: 'exists', replaced: true, path: dest };
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(dest, r.text, 'utf8');
+  } catch (e) {
+    return { ok: false, error: `Cannot write ${dest}: ${e.message}` };
+  }
+  return { ok: true, name: clean, path: dest, replaced, description: describeSkill(r.text) };
+}
+
+/** Remove an installed skill by name (thin alias so the command reads uniformly). */
+export function removeLocalSkill(name) {
+  const clean = normalizeSkillName(name);
+  if (!clean) return false;
+  try { fs.unlinkSync(path.join(skillsDir(), `${clean}.md`)); return true; } catch { return false; }
+}
+
+// ---- plugins ---------------------------------------------------------------
+
+// Flatten a Contents API tree into { path, type, size } for one plugin directory.
+async function listDir(repo, ref, dir) {
+  const r = await ghJson(apiContents(repo, ref, dir));
+  if (!r.ok) return r;
+  return { ok: true, entries: Array.isArray(r.data) ? r.data : [] };
+}
+
+/**
+ * Install one remote plugin into `~/.hncode/plugins/`.
+ *
+ * Two shapes are accepted, because a plugin is either one file or a small package:
+ *   plugins/<name>/index.js (+ helpers)
+ *   plugins/<name>/<name>.js
+ * Sub-directories are copied recursively; only the extensions plugins can actually be
+ * loaded from are fetched, so a stray asset cannot land in the plugin directory.
+ */
+export async function installRemotePlugin(name, { repo = DEFAULT_REPO, ref = DEFAULT_REF, overwrite = true } = {}) {
+  const clean = String(name == null ? '' : name).trim();
+  if (!clean || /[\\/]/.test(clean) || clean.startsWith('.')) {
+    return { ok: false, error: `Invalid plugin name: ${name}` };
+  }
+  const srcDir = `plugins/${clean}`;
+  const listed = await listDir(repo, ref, srcDir);
+  if (!listed.ok) {
+    return { ok: false, error: listed.error === 'not-found'
+      ? `No plugins/${clean} directory in the repo.`
+      : `Could not list ${srcDir}: ${listed.error}` };
+  }
+
+  const files = listed.entries.filter((e) => e.type === 'file'
+    && PLUGIN_EXT.has(path.extname(e.name).toLowerCase()));
+  if (!files.length) return { ok: false, error: `plugins/${clean} has no .js/.mjs/.json files.` };
+
+  const destDir = path.join(pluginsDir(), clean);
+  const dest = path.join(destDir, files[0].name);
+  const existed = fs.existsSync(destDir);
+  if (existed && !overwrite) return { ok: false, error: 'exists', replaced: true, path: destDir };
+
+  const written = [];
+  for (const f of files) {
+    const r = await fetchText(rawUrl(repo, ref, f.path));
+    if (!r.ok) return { ok: false, error: `Could not download ${f.path}: ${r.error}` };
+    const out = path.join(destDir, path.basename(f.path));
+    try {
+      fs.mkdirSync(path.dirname(out), { recursive: true });
+      fs.writeFileSync(out, r.text, 'utf8');
+    } catch (e) {
+      return { ok: false, error: `Cannot write ${out}: ${e.message}` };
+    }
+    written.push(path.basename(f.path));
+  }
+  return { ok: true, name: clean, path: destDir, files: written, replaced: existed };
+}
+
+/** Remove an installed plugin directory (or a single-file plugin) by name. */
+export function removeLocalPlugin(name) {
+  const clean = String(name == null ? '' : name).trim();
+  if (!clean || /[\\/]/.test(clean)) return false;
+  const dir = path.join(pluginsDir(), clean);
+  if (fs.existsSync(dir)) { try { fs.rmSync(dir, { recursive: true, force: true }); return true; } catch { return false; } }
+  // A single-file plugin installs as <name>.js.
+  for (const ext of ['.js', '.mjs', '.cjs']) {
+    const f = path.join(pluginsDir(), clean + ext);
+    if (fs.existsSync(f)) { try { fs.unlinkSync(f); return true; } catch { return false; } }
+  }
+  return false;
+}
+
+/** Installed plugin names, read from the plugin directory. */
+export function listLocalPlugins() {
+  let entries;
+  try { entries = fs.readdirSync(pluginsDir()); } catch { return []; }
+  const out = [];
+  for (const e of entries) {
+    if (e.startsWith('.')) continue;
+    const full = path.join(pluginsDir(), e);
+    let st;
+    try { st = fs.statSync(full); } catch { continue; }
+    if (st.isDirectory()) out.push({ name: e, kind: 'dir', path: full });
+    else if (/\.(mjs?|cjs)$/i.test(e)) out.push({ name: e.replace(/\.[^.]+$/, ''), kind: 'file', path: full });
+  }
+  out.sort((a, b) => a.name.localeCompare(b.name));
+  return out;
+}

package/src/tasks-browser.js

@@ -136,20 +136,47 @@ export function renderTasksBrowser(state, cols, rows) {
 
   const key = (s) => C.cyan + C.bold + s + C.reset;
   const dim = (s) => C.gray + s + C.reset;
+  // The footer doubles as a TOOLBAR: each `KEY label` pair is clickable, so the
+  // whole pair is recorded as one span. `cursor` tracks the column so the spans stay
+  // correct as the parts are concatenated by `join('  ')`.
+  const footerHits = [];
   let footer;
   if (state.pendingStop) {
-    footer = fitExactly(' ' + C.orange + C.bold + 'Stop' + C.reset + ' ' + C.white + state.pendingStop + C.reset + '? '
-      + key('Y') + ' ' + dim('confirm') + '  ' + key('N') + dim('/') + key('esc') + ' ' + dim('cancel') + ' ', cols);
+    // The confirm prompt is a toolbar too: Y / N / Esc each do something, so each
+    // gets a clickable span. `c` tracks the column so the spans land exactly on the
+    // rendered words — the original drew `N/esc cancel` as one run, so the two keys
+    // share the single "cancel" label and are measured as one span.
+    const prefix = ' ' + C.orange + C.bold + 'Stop' + C.reset + ' ' + C.white + state.pendingStop + C.reset + '? ';
+    let c = visWidth(prefix);
+    const yPart = key('Y') + ' ' + dim('confirm');
+    footerHits.push({ keyWord: 'Y', label: 'confirm', action: 'confirmStop', col0: c, col1: c + visWidth(yPart) - 1 });
+    c += visWidth(yPart) + 2;
+    const nPart = key('N') + dim('/') + key('esc') + ' ' + dim('cancel');
+    footerHits.push({ keyWord: 'N/esc', label: 'cancel', action: 'cancelStop', col0: c, col1: c + visWidth(nPart) - 1 });
+    footer = fitExactly(prefix + yPart + '  ' + nPart + ' ', cols);
   } else {
-    const parts = [
-      ' ' + key('\u2191\u2193') + ' ' + dim('select'),
-      key('Enter/O') + ' ' + dim('output'),
-      key('S') + ' ' + dim('stop'),
-      key('R') + ' ' + dim('refresh'),
-      key('Tab') + ' ' + dim('filter'),
-      key('Q/Esc') + ' ' + dim('close') + ' ',
+    const specs = [
+      ['\u2191\u2193', 'select', 'select'],
+      ['Enter/O', 'output', 'openOutput'],
+      ['S', 'stop', 'requestStop'],
+      ['R', 'refresh', 'refresh'],
+      ['Tab', 'filter', 'toggleFilter'],
+      ['Q/Esc', 'close', 'close'],
     ];
-    const left = parts.join('  ');
+    const parts = [];
+    let cursor = 1;
+    for (const [kw, label, action] of specs) {
+      const piece = key(kw) + ' ' + dim(label);
+      const w = visWidth(piece);
+      // `col1` is the LAST included column (hitboxes use an inclusive range, see
+      // hitAt), so a piece starting at `cursor` spanning `w` cells ends at
+      // `cursor + w - 1`. Using `cursor + w` made the span one column too wide, so a
+      // hover tinted the following space as well.
+      footerHits.push({ keyWord: kw, label, action, col0: cursor, col1: cursor + w - 1 });
+      cursor += w + 2;             // the `parts.join('  ')` separator
+      parts.push(piece);
+    }
+    const left = ' ' + parts.join('  ');
     const flash = state.flash ? C.orange + ' ' + state.flash + ' ' + C.reset : '';
     const total = visWidth(left) + visWidth(flash);
     footer = total <= cols ? left + ' '.repeat(cols - total) + flash : fitExactly(left, cols);
@@ -168,7 +195,11 @@ export function renderTasksBrowser(state, cols, rows) {
   } else {
     listLines = visible.map((t, i) => {
       const selected = i === state.selectedIndex;
-      const ptr = selected ? C.cyan + '\u276f ' + C.reset : '  ';
+      // Hover highlight, mirroring the rest of the TUI: the row under the pointer is
+      // tinted by the generic hover pass in tui.js (composeFrame), which needs a
+      // hitbox to aim at — those are recorded in state._taskHits below.
+      const hot = state.hoverIndex === i;
+      const ptr = selected ? C.cyan + '\u276f ' + C.reset : (hot ? C.hover + '\u276f ' + C.reset : '  ');
       const idCol = t.kind === 'agent' ? C.green : t.kind === 'question' ? C.orange : C.blue;
       const idText = selected ? idCol + C.bold + t.taskId + C.reset : idCol + t.taskId + C.reset;
       const pad = ' '.repeat(Math.max(0, 20 - visWidth(t.taskId)));
@@ -180,6 +211,18 @@ export function renderTasksBrowser(state, cols, rows) {
       return fitExactly(prefix + ' ' + C.white + truncateToWidth(desc, budget) + C.reset, listInnerW);
     });
   }
+  // Click targets. Coordinates are FRAME cells: line 0 is the header, line 1 is the
+  // list box's TOP RULE, so the first content row is line 2 — using `1 + i` put the
+  // hitboxes one row high, which highlighted the border instead of the task and made
+  // a click select the wrong row. Columns match the box interior (`│` + 1 cell of
+  // padding), and `col1` is the LAST included column.
+  state._taskHits = [];
+  for (let i = 0; i < Math.min(visible.length, listInnerH); i++) {
+    state._taskHits.push({ row: 2 + i, col0: 1, col1: listInnerW, kind: 'taskRow', index: i });
+  }
+  for (const h of footerHits) {
+    state._taskHits.push({ row: rows - 1, col0: h.col0, col1: h.col1, kind: 'taskFooter', action: h.action });
+  }
   while (listLines.length < listInnerH) listLines.push('');
   const listFrame = renderFrame('Tasks [' + state.filter + ']', listLines.slice(0, listInnerH), listW, bodyH);
 

package/src/tools/bash.js

@@ -7,6 +7,7 @@ import fs from 'node:fs';
 import cp from 'node:child_process';
 import { resolvePath, truncateBuf } from './utils.js';
 import { createTask, appendTaskOutput, settleTask } from '../agent-task.js';
+import { shellSpawnArgs } from './shell.js';
 
 // kimi-code's timeout policy (agent-core-v2/agent/tools/os/bash/bash.ts).
 export const DEFAULT_TIMEOUT_S = 60;
@@ -137,10 +138,19 @@ export const spec = {
     const cap = bg ? MAX_BACKGROUND_TIMEOUT_S : MAX_TIMEOUT_S;
     const def = bg ? DEFAULT_BACKGROUND_TIMEOUT_S : DEFAULT_TIMEOUT_S;
     const timeoutMs = args.disable_timeout ? undefined : Math.min(args.timeout ?? def, cap) * 1000;
-    const command = args.command;
+const command = args.command;
     // stdin is 'ignore' (NUL / /dev/null): leaving it as an open pipe made any
     // command that reads stdin (`cat`, `npm init`, …) block until the timeout.
-    const child = cp.spawn('pwsh', ['-Command', command], { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    //
+    // The shell is RESOLVED, not hardcoded: `spawn('pwsh', …)` failed outright on a
+    // box with only the built-in Windows PowerShell (see tools/shell.js). `env` is
+    // passed explicitly rather than relying on Node's implicit inheritance, which is
+    // what made the tool depend on pwsh having been added to PATH by hand.
+    let shell;
+    try { shell = shellSpawnArgs(command); } catch (e) { return `Error: ${e.message}`; }
+    const child = cp.spawn(shell.bin, shell.args, {
+      cwd, stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env },
+    });
 
     const chunks = [];
     let settled = false;
@@ -288,7 +298,11 @@ function spawnBackground(args, cwd, ctx) {
   // task's output file instead, so the process survives and TaskOutput can
   // still read it. (In the TUI the parent rarely exits, but headless -p mode
   // does, and a background job should outlive the prompt.)
-  const child = cp.spawn('pwsh', ['-Command', command], { cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+let shell;
+  try { shell = shellSpawnArgs(command); } catch (e) { return `Error: ${e.message}`; }
+  const child = cp.spawn(shell.bin, shell.args, {
+    cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env },
+  });
   const task = createTask(ctx, 'process', {
     description: args.description || args.command,
     command: args.command,

package/src/tools/edit.js

@@ -28,13 +28,13 @@ import { hashRegion as hashLines } from './read.js';
 
 export const spec = {
   name: 'Edit',
-  description: 'Edit a file. THE TWO MODES ARE MUTUALLY EXCLUSIVE — NEVER combine them:\n  - LINE-RANGE mode: path + start_line + end_line + new_string. Replaces lines [start_line, end_line] with new_string. PRESERVE the exact indentation (spaces/tabs) of the lines you are replacing — copy it straight from the Read output, after its line-number prefix. PREFERRED — use it whenever you have Read the file and know the line numbers.\n  - EXACT-SUBSTRING mode: path + old_string + new_string. Replaces text exactly matching old_string. Use ONLY when the exact text is known and a line range is not convenient.\nDo NOT pass start_line/end_line together with old_string/new_string in one call, and do NOT pass any of these four keys when you are not using that mode. Omitting new_string is an error, not an empty replacement (in line-range mode pass new_string; in substring mode pass old_string + new_string).',
+  description: 'Edit a file. THE TWO MODES ARE MUTUALLY EXCLUSIVE — NEVER combine them:\n  - LINE-RANGE mode: path + start_line + end_line + new_string. Replaces lines [start_line, end_line] with new_string. new_string is written VERBATIM: nothing is re-indented or auto-indented, so EVERY line you send — including the FIRST one — must already carry the exact leading spaces/tabs it should have. Copy that whitespace straight from the Read output, after its `N\\t` line-number prefix (Read prints `12\\t    return x`, so you send `    return x`). PREFERRED — use it whenever you have Read the file and know the line numbers.\n  - EXACT-SUBSTRING mode: path + old_string + new_string. Replaces text exactly matching old_string. Use ONLY when the exact text is known and a line range is not convenient.\nDo NOT pass start_line/end_line together with old_string/new_string in one call, and do NOT pass any of these four keys when you are not using that mode. Omitting new_string is an error, not an empty replacement (in line-range mode pass new_string; in substring mode pass old_string + new_string).',
   parameters: {
     type: 'object',
     properties: {
       path: { type: 'string', description: 'Path to the file to edit.' },
       old_string: { type: 'string', description: 'Exact text to replace, including whitespace and newlines. Omit when using start_line/end_line.' },
-      new_string: { type: 'string', description: 'Replacement text. In SUBSTRING mode it replaces old_string. In LINE-RANGE mode it replaces lines [start_line, end_line]. In line-range mode PRESERVE the exact leading whitespace (indentation) from Read output; copy it exactly as it appears after the line-number prefix.' },
+      new_string: { type: 'string', description: 'Replacement text, written VERBATIM. In SUBSTRING mode it replaces old_string. In LINE-RANGE mode it replaces lines [start_line, end_line], and its leading whitespace is used exactly as sent — no indentation is added, and the FIRST line needs its own. Copy it from the Read output after the `N\\t` line-number prefix (Read prints `12\\t    return x`, so you send `    return x`).' },
       replace_all: { type: 'boolean', default: false, description: 'Replace all occurrences of old_string.' },
       start_line: { type: 'integer', minimum: 1, description: 'PREFERRED MODE. 1-based first line to replace (requires end_line and new_string). Use this line-range mode first.' },
       end_line: { type: 'integer', minimum: 1, description: 'PREFERRED MODE. 1-based last line to replace (inclusive; requires start_line).' },

package/src/tools/shell.js

@@ -0,0 +1,106 @@
+// 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';
+
+// The two PowerShell families, by the name they are invoked as.
+export const SHELL_CANDIDATES = ['pwsh', 'powershell'];
+
+/**
+ * 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 PowerShell: pwsh first, then the built-in powershell.
+ * Returns { path, name, edition } or null when neither exists.
+ *
+ * `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+).
+ */
+export function detectShell() {
+  for (const name of SHELL_CANDIDATES) {
+    const path = whichSync(name);
+    if (path) {
+      return { path, name, edition: name === 'pwsh' ? 'core' : 'desktop' };
+    }
+  }
+  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.
+ *
+ * Throws a message naming the fix when no PowerShell is installed, instead of
+ * letting the caller hit a bare ENOENT.
+ */
+export function shellSpawnArgs(command) {
+  const shell = getShell();
+  if (!shell) {
+    throw new Error(
+      'No PowerShell found on PATH (tried pwsh, powershell). '
+      + 'Install PowerShell 7+ or add it to PATH, then retry.',
+    );
+  }
+  return { bin: shell.path, args: ['-NoProfile', '-NonInteractive', '-Command', command], shell };
+}