@wrongstack/tools 0.273.0 → 0.274.0

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { replaceTool } from './replace.js';
 export { globTool } from './glob.js';
 export { grepTool } from './grep.js';
 export { bashTool } from './bash.js';
-export { execTool } from './exec.js';
+export { configureExecPolicy, execTool, getExecAllowlist, isExecCommandAllowed, resetExecPolicy } from './exec.js';
 export { fetchTool } from './fetch.js';
 export { searchTool } from './search.js';
 export { todoTool } from './todo.js';
@@ -39,6 +39,115 @@ export { OPTIONAL_TOOLS, TIER1_TOOLS, TIER2_TOOLS, TIER3_TOOLS, builtinTools } f
 export { builtinToolsPack } from './pack.js';
 import 'node:child_process';
 
+/**
+ * Shell picker for the `bash` tool on Windows.
+ *
+ * Historically the bash tool always fell back to `cmd.exe` on Windows — a
+ * reasonable default for the small set of POSIX-style commands the tool was
+ * built around (`echo`, `dir`, `cd`, `set`, etc.). That breaks when the
+ * caller emits PowerShell-style commands (e.g. Codex on Windows routinely
+ * emits `Get-Content`, `Get-ChildItem`, `Set-Location`, …), which `cmd.exe`
+ * rejects with "'Get-Content' is not recognized as an internal or external
+ * command, operable program or batch file." This module decides — purely from
+ * the command string and a few well-known env vars — which shell should run
+ * the command. It returns a tagged value; bash.ts does the actual spawn.
+ *
+ * The picker never spawns anything itself, so it is safe to unit-test in
+ * isolation. Shell *resolution* (finding the actual binary on PATH) lives in
+ * `_win32-resolve.ts` and runs at spawn time.
+ * @see {@link ../../docs/configuration.md#windows-shell-selection-wrongstackshell} for user-facing documentation of the WRONGSTACK_SHELL env var and auto-detection behavior.
+ *
+ * Selection precedence (Windows only):
+ *   1. `WRONGSTACK_SHELL` env var, if it names a known shell (cmd | powershell
+ *      | pwsh). This is the override for users who want a fixed shell.
+ *   2. Auto-detect: if the command "looks like" PowerShell — i.e. uses cmdlet
+ *      verb-noun syntax, $-variables, subexpressions, here-strings, etc. —
+ *      route to PowerShell. Prefers `pwsh` (PowerShell 7+) and falls back to
+ *      `powershell` (Windows PowerShell 5.1) at spawn time.
+ *   3. Default: `cmd.exe` (preserves legacy behavior).
+ *
+ * On non-Windows the picker is a no-op — bash.ts already routes through
+ * `/bin/bash -c`. We return `'cmd'` as a sentinel value that means "the
+ * platform default"; bash.ts maps it to the right binary.
+ *
+ * See docs/configuration.md § "Windows shell selection (WRONGSTACK_SHELL)" for
+ * user-facing documentation of the env var and auto-detection behaviour.
+ */
+type BashShell = 'cmd' | 'powershell' | 'pwsh';
+
+/**
+ * Session-shell resolution for Windows.
+ *
+ * `pickShell` (`_shell-pick.ts`) decides the shell *per command* — it inspects
+ * each command string and routes PowerShell-looking work to PowerShell, else
+ * `cmd.exe`. That keeps individual commands working, but it means the shell the
+ * model is *told* about (the system-prompt Environment block) and the shell that
+ * actually runs a given command can disagree, and a plain command like
+ * `git status` silently lands in `cmd.exe` while `Get-ChildItem` lands in
+ * PowerShell. The model has no stable target to write syntax for.
+ *
+ * This module resolves ONE shell for the whole session and pins it via the
+ * `WRONGSTACK_SHELL` env var. Because `WRONGSTACK_SHELL` is already the top
+ * precedence in `pickShell`, pinning it makes every command route to the same
+ * shell with zero changes to `bash.ts` — and the system-prompt builder can read
+ * the same env var to tell the model exactly which shell + syntax to use.
+ *
+ * Resolution (Windows only — POSIX has no fixed session shell here; `bash.ts`
+ * routes through `/bin/bash -c` and honours an explicit `WRONGSTACK_SHELL` as a
+ * binary path):
+ *   1. A valid user-set `WRONGSTACK_SHELL` (cmd | powershell | pwsh) wins and is
+ *      left untouched.
+ *   2. Otherwise prefer `pwsh` (PowerShell 7+) when `pwsh.exe` is on PATH.
+ *   3. Otherwise `powershell` (Windows PowerShell 5.1).
+ *   4. Otherwise `cmd` (only when no PowerShell is installed — effectively never
+ *      on a real Windows box).
+ *
+ * @see {@link ../../docs/configuration.md#windows-shell-selection-wrongstackshell}
+ */
+
+/**
+ * Map a raw `WRONGSTACK_SHELL` value (which may carry a `.exe` suffix or odd
+ * casing) to a canonical {@link BashShell}, or `undefined` when it is unset /
+ * not a known shell. Mirrors the override parsing in `pickShell`.
+ */
+declare function normalizeShell(value: string | undefined): BashShell | undefined;
+interface ResolveSessionShellDeps {
+    /**
+     * Returns true when `bin` (e.g. `'pwsh.exe'`) resolves on PATH. Injectable so
+     * the resolver is unit-testable off-Windows; defaults to `resolveWin32Command`
+     * (which itself short-circuits to "not found" when `process.platform` is not
+     * win32).
+     */
+    hasBinary?: ((bin: string) => boolean) | undefined;
+}
+/**
+ * Pure decision: which single shell should the session use on `platform`?
+ * Returns `undefined` on non-win32 (no fixed session shell). Does not mutate
+ * anything.
+ */
+declare function resolveSessionShell(platform: NodeJS.Platform, env: {
+    get(key: string): string | undefined;
+}, deps?: ResolveSessionShellDeps): BashShell | undefined;
+interface EnsureSessionShellOptions {
+    /** Env to read/mutate. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv | undefined;
+    /** Platform override (tests). Defaults to `process.platform`. */
+    platform?: NodeJS.Platform | undefined;
+    /** Binary-presence probe (tests). Forwarded to {@link resolveSessionShell}. */
+    hasBinary?: ((bin: string) => boolean) | undefined;
+}
+/**
+ * Resolve the session shell and pin it into `WRONGSTACK_SHELL` so the bash tool
+ * and the system-prompt builder agree on one stable value. Idempotent:
+ *
+ *   - non-win32 → no-op, returns `undefined`.
+ *   - a valid user-set `WRONGSTACK_SHELL` → returned as-is, env left untouched.
+ *   - otherwise → resolves, writes the canonical value into the env, returns it.
+ *
+ * Call this once at process boot, before the system-prompt builder is built.
+ */
+declare function ensureSessionShell(opts?: EnsureSessionShellOptions): BashShell | undefined;
+
 /**
  * `planTool` — the LLM-callable counterpart to the `/plan` slash command.
  *
@@ -450,4 +559,4 @@ declare const TOOL_ICON_CONFIG: Record<ToolIconId, ToolIconConfig>;
  */
 declare const FALLBACK_ICON: ToolIconId;
 
-export { FALLBACK_ICON, type GlobalProcessStatus, type InstanceInfo, type InstanceListOptions, type PersistentProcessEntry, type PersistentRegistryData, type ProcessGuardianConfig, ProcessRegistryImpl, TOOL_ICON_CONFIG, TOOL_ICON_MAP, type ToolIconConfig, type ToolIconId, createGlobalPsSlashCommand, formatGlobalStatus, formatInstanceList, formatInstanceSummary, getInstanceCount, getPersistentProcessRegistry, getProcessGuardian, getToolIcon, listInstances, planTool, resetPersistentProcessRegistry, startProcessGuardian, stopProcessGuardian };
+export { type BashShell, type EnsureSessionShellOptions, FALLBACK_ICON, type GlobalProcessStatus, type InstanceInfo, type InstanceListOptions, type PersistentProcessEntry, type PersistentRegistryData, type ProcessGuardianConfig, ProcessRegistryImpl, type ResolveSessionShellDeps, TOOL_ICON_CONFIG, TOOL_ICON_MAP, type ToolIconConfig, type ToolIconId, createGlobalPsSlashCommand, ensureSessionShell, formatGlobalStatus, formatInstanceList, formatInstanceSummary, getInstanceCount, getPersistentProcessRegistry, getProcessGuardian, getToolIcon, listInstances, normalizeShell, planTool, resetPersistentProcessRegistry, resolveSessionShell, startProcessGuardian, stopProcessGuardian };