fauxnix-cli 0.6.0 → 0.7.1

package/README.md

@@ -67,7 +67,9 @@ npm install -g fauxnix-cli
 Or from source:
 
 ```bash
-git clone https://github.com/20000419/fauxnix && cd fauxnix && npm install -g .
+git clone https://github.com/20000419/fauxnix && cd fauxnix
+npm ci
+npm install -g .
 ```
 
 > npm package name is `fauxnix-cli` (the `fauxnix` name on npm belongs to an
@@ -193,11 +195,10 @@ fauxnix optimizes for the commands agents actually run. Documented deviations:
   word expansion precedes the temporary environment).
 - `yes` is capped at 65,536 lines — PS 5.1 pipelines cannot signal upstream producers to stop, so
   an unbounded `yes | head` would hang.
-- `tail -f`, `eval`, `alias`, heredocs, `while`/`until`/`case`, word-level
-  `$((...))` arithmetic expansion
+- `tail -f`, `eval`, `alias`, heredocs, `while`/`until`/`case`,
   and background `&` are rejected with actionable error messages instead of misbehaving.
-  (`if/then/else/fi`, `for x in ...`, backtick substitution, `command -v`, pipeline `read`,
-  and dotenv-style `source` are supported.)
+  (`if/then/elif/else/fi`, `for x in ...`, backtick substitution, `command -v`, pipeline `read`,
+  dotenv-style `source`, and word-level `$((...))` arithmetic expansion are supported.)
 - `command -v <builtin>` prints `/usr/bin/<name>` where bash prints the bare builtin name;
   exit codes and empty-result semantics match.
 - `chmod` maps only the read-only bit; exec bits are no-ops on Windows. `chown` is a silent no-op
@@ -231,6 +232,9 @@ Architecture map: `src/parser.ts` (bash subset → AST) · `src/translator.ts` (
 executor wrapper) · `src/executor.ts` (spawn, redirects, session persistence) ·
 `src/commands/*.ts` (per-command generators) · `src/mcp.ts` (MCP server) · `src/cli.ts`.
 
+Roadmap: [docs/rfc-roadmap-to-1.0.md](docs/rfc-roadmap-to-1.0.md) — tracks, milestones,
+and the RFC process for proposing waves.
+
 ## License
 
 MIT © 20000419

package/dist/ast.d.ts

@@ -8,12 +8,12 @@
  *   - quoting:              'literal'  "interp $VAR $(cmd)"
  *   - variables:            $VAR ${VAR} ${VAR[n]} plus special cases ($HOME $USER $PATH ...)
  *   - command substitution: $(...) and `...` (recursively translated)
+ *   - arithmetic expansion: $((...)) (existing fx-arith engine)
  *   - env assignment prefix: VAR=value cmd
  *
  * Explicitly unsupported (parser throws a helpful FauxnixError):
  *   heredocs, subshells (...), background &, while/until/case,
- *   word-level $((...)) arithmetic expansion, globs inside quotes,
- *   process substitution <(...).
+ *   globs inside quotes, process substitution <(...).
  */
 export interface CommandList {
     kind: 'CommandList';
@@ -89,6 +89,9 @@ export type WordPart = {
 } | {
     kind: 'CmdSub';
     cmd: string;
+} | {
+    kind: 'Arith';
+    parts: WordPart[];
 };
 export declare function wordToString(w: Word): string;
 /** True when every part is unquoted Text and the concatenation equals `tok`. */

package/dist/ast.js

@@ -8,12 +8,12 @@
  *   - quoting:              'literal'  "interp $VAR $(cmd)"
  *   - variables:            $VAR ${VAR} ${VAR[n]} plus special cases ($HOME $USER $PATH ...)
  *   - command substitution: $(...) and `...` (recursively translated)
+ *   - arithmetic expansion: $((...)) (existing fx-arith engine)
  *   - env assignment prefix: VAR=value cmd
  *
  * Explicitly unsupported (parser throws a helpful FauxnixError):
  *   heredocs, subshells (...), background &, while/until/case,
- *   word-level $((...)) arithmetic expansion, globs inside quotes,
- *   process substitution <(...).
+ *   globs inside quotes, process substitution <(...).
  */
 export function wordToString(w) {
     return w.map(partToString).join('');
@@ -40,6 +40,8 @@ function partToString(p) {
             return p.index !== undefined ? `\${${p.name}[${p.index}]}` : `$${p.name}`;
         case 'CmdSub':
             return '$(' + p.cmd + ')';
+        case 'Arith':
+            return '$((' + p.parts.map(partToString).join('') + '))';
     }
 }
 /** Best-effort "raw literal" view: is this word free of interpolation? */

package/dist/cli.js

@@ -5,6 +5,7 @@ import { translateCommandList } from './translator.js';
 import { registeredNames } from './registry.js';
 import { encodeCommand } from './encoding.js';
 import { startMcpServer } from './mcp.js';
+import { packageVersion } from './version.js';
 import './commands/install-all.js';
 const USAGE = `fauxnix — run Linux-style commands on Windows via PowerShell translation
 
@@ -26,7 +27,7 @@ export async function runCli(argv) {
     }
     const [verb, ...rest] = argv;
     if (verb === '--version' || verb === '-v') {
-        console.log('fauxnix 0.4.0');
+        console.log(`fauxnix ${packageVersion}`);
         return;
     }
     if (verb === 'list') {

package/dist/commands/files.js

@@ -492,6 +492,22 @@ const find = (args) => {
     const mtimeExpr = extractValue(preds, ['-mtime']);
     const wantDelete = preds.includes('-delete');
     const paths = pathWords.length ? argListExpr(pathWords) : "@('.')";
+    for (const option of ['-maxdepth', '-mindepth']) {
+        const optionIndex = preds.indexOf(option);
+        if (optionIndex < 0)
+            continue;
+        if (optionIndex + 1 >= preds.length) {
+            return ('[Console]::Error.WriteLine(' +
+                psStr(`find: missing argument to '${option}'`) +
+                '); $script:fx_exit = 1');
+        }
+        const value = preds[optionIndex + 1];
+        if (!/^\d+$/.test(value)) {
+            return ('[Console]::Error.WriteLine(' +
+                psStr(`find: expected a non-negative decimal integer argument to ${option}, but got '${value}'`) +
+                '); $script:fx_exit = 1');
+        }
+    }
     const conditions = [];
     if (namePat !== null)
         conditions.push("($fx_i.Name -like '" + likeOf(namePat) + "')");
@@ -516,9 +532,9 @@ const find = (args) => {
         '  foreach ($fx_i in $fx_all) {',
         "    $fx_rel = $fx_i.FullName.Substring($fx_root.Length).TrimStart('\\').Replace('\\', '/')",
         "    if ($fx_rel -eq '') { $fx_disp = $fx_p } else { $fx_disp = ($fx_p.TrimEnd('/') + '/' + $fx_rel) }",
-        '    $fx_depth = 0; foreach ($fx_c in $fx_rel.ToCharArray()) { if ($fx_c -eq \'/\') { $fx_depth++ } }',
-        '    if ($fx_depth -lt ' + (minDepthS && /^\d+$/.test(minDepthS) ? minDepthS : '0') + ') { continue }',
-        maxDepthS && /^\d+$/.test(maxDepthS) ? '    if ($fx_depth -gt ' + maxDepthS + ') { continue }' : '',
+        '    $fx_depth = 0; if ($fx_rel -ne \'\') { $fx_depth = 1; foreach ($fx_c in $fx_rel.ToCharArray()) { if ($fx_c -eq \'/\') { $fx_depth++ } } }',
+        '    if ($fx_depth -lt ' + (minDepthS ?? '0') + ') { continue }',
+        maxDepthS !== null ? '    if ($fx_depth -gt ' + maxDepthS + ') { continue }' : '',
         '    if (-not (' + cond + ')) { continue }',
         sizeCond ? '    $fx_sz = 0; if (-not $fx_i.PSIsContainer) { try { $fx_sz = $fx_i.Length } catch {} }' : '',
         sizeCond ? '    if (-not (' + sizeCond + ')) { continue }' : '',

package/dist/commands/sysinfo.js

@@ -1,6 +1,6 @@
 import { FauxnixParseError, isUnquotedLiteral, wordToString } from '../ast.js';
 import { lookup, parseWords, psStr, registeredNames } from '../registry.js';
-import { argListExpr, exprOfWord, operandExpr, translateSimple, wrapTempEnv, encodeSetValExpr, escapeDq, translateCmdSub, normalizeLiteralPath, pathExpr, paramExpr, varExpr, } from '../translator.js';
+import { argListExpr, exprOfWord, operandExpr, translateSimple, wrapTempEnv, encodeSetValExpr, escapeDq, translateCmdSub, normalizeLiteralPath, pathExpr, paramExpr, varExpr, arithExpr, setArithHelperPreamble, } from '../translator.js';
 import { handlers as textIoHandlers } from './text-io.js';
 /* ------------------------------------------------------------------ */
 /* Shared TS helpers                                                   */
@@ -1373,6 +1373,7 @@ const FX_ENVGET_FN = [
     '  return [string]$fx_ev.Value',
     '}',
 ].join('\n');
+setArithHelperPreamble(FX_TNK_FN + '\n' + FX_ENVGET_FN);
 /** Like exprOfWord, but $var is an exact-case env lookup (bash, not $env:). */
 function kshExprOfWord(w) {
     const expanded = [];
@@ -1392,6 +1393,9 @@ function kshExprOfWord(w) {
     }
     if (tilde && expanded.length === 0)
         return '(fx-home)';
+    if (!tilde && expanded.length === 1 && expanded[0].kind === 'Arith') {
+        return arithExpr(expanded[0].parts);
+    }
     if (!tilde && expanded.length === 1 && expanded[0].kind === 'Var') {
         if (expanded[0].param) {
             return paramExpr(expanded[0].name, expanded[0].param.op, expanded[0].param.word);
@@ -1434,6 +1438,9 @@ function kshExprOfWord(w) {
                 // [[ ]] does not IFS-split, so keep the newline contract.
                 out += '$(' + translateCmdSub(p.cmd, true) + ')';
                 break;
+            case 'Arith':
+                out += arithExpr(p.parts);
+                break;
         }
     };
     for (const p of expanded)

package/dist/commands/text-filters.js

@@ -77,7 +77,7 @@ function textExpr(w) {
     return exprOfWord(w);
 }
 /** Collect EVERY value of a short option (-kN, -k N) — parseWords keeps only the last. */
-function collectShortValues(args, letter, longName) {
+function collectShortValues(args, letter) {
     const out = [];
     let onlyOps = false;
     for (let i = 0; i < args.length; i++) {
@@ -88,9 +88,7 @@ function collectShortValues(args, letter, longName) {
         }
         if (onlyOps)
             continue;
-        if (longName && t.startsWith(longName + '='))
-            out.push(t.slice(longName.length + 1));
-        else if (t === '-' + letter) {
+        if (t === '-' + letter) {
             if (i + 1 < args.length) {
                 out.push(wordToString(args[i + 1]));
                 i++;
@@ -102,6 +100,32 @@ function collectShortValues(args, letter, longName) {
     }
     return out;
 }
+/** Collect repeated value-taking long options without mistaking short bundles for values. */
+function collectLongValues(args, names) {
+    const out = [];
+    let onlyOps = false;
+    for (let i = 0; i < args.length; i++) {
+        const t = wordToString(args[i]);
+        if (t === '--') {
+            onlyOps = true;
+            continue;
+        }
+        if (onlyOps || !t.startsWith('--'))
+            continue;
+        const eq = t.indexOf('=');
+        const name = eq >= 0 ? t.slice(0, eq) : t;
+        if (!names.includes(name))
+            continue;
+        if (eq >= 0) {
+            out.push({ name, value: t.slice(eq + 1) });
+        }
+        else if (i + 1 < args.length) {
+            out.push({ name, value: wordToString(args[i + 1]) });
+            i++;
+        }
+    }
+    return out;
+}
 /** Build the "collect file operands through fx-glob" PS prologue. */
 function psCollectSources(filesExpr, cmdErr, leafOnly) {
     const test = leafOnly
@@ -238,8 +262,19 @@ function ereToDotNet(re) {
 /* grep                                                                */
 /* ------------------------------------------------------------------ */
 const grep = (args) => {
-    const includeGlobs = collectShortValues(args, '', '--include');
-    const { flags, operandWords, values } = parseWords(args, ['A', 'B', 'C']);
+    const filterOptionNames = ['--include', '--exclude', '--exclude-dir'];
+    const filterOptions = collectLongValues(args, filterOptionNames);
+    const fileFilterOptions = filterOptions.filter((o) => o.name !== '--exclude-dir');
+    const excludeDirGlobs = filterOptions
+        .filter((o) => o.name === '--exclude-dir')
+        .map((o) => o.value.replace(/[\\/]+$/, ''));
+    const { flags, operandWords, values, missingValue } = parseWords(args, ['A', 'B', 'C'], filterOptionNames);
+    const missingFilterOption = missingValue.find((o) => filterOptionNames.includes(o));
+    if (missingFilterOption) {
+        return ('[Console]::Error.WriteLine(' +
+            psStr("grep: option '" + missingFilterOption + "' requires an argument") +
+            '); $script:fx_exit = 2');
+    }
     const ci = flags.has('i');
     const inv = flags.has('v');
     const num = flags.has('n');
@@ -320,23 +355,68 @@ const grep = (args) => {
     // --- source collection -------------------------------------------------
     if (fileWords.length > 0) {
         lines.push(PS_GLOB_FN);
-        lines.push('$fx_inc = @(' + includeGlobs.map((g) => psStr(g)).join(', ') + ')', '$fx_srcs = @()', '$fx_err = $false', '$fx_recd = $false');
+        lines.push('$fx_fsel = @(' +
+            fileFilterOptions
+                .map((o) => '[pscustomobject]@{ Keep = ' +
+                pb(o.name === '--include') +
+                '; Glob = ' +
+                psStr(o.value) +
+                ' }')
+                .join(', ') +
+            ')', '$fx_excd = @(' + excludeDirGlobs.map((g) => psStr(g)).join(', ') + ')', '$fx_srcs = @()', '$fx_err = $false', '$fx_recd = $false');
+        lines.push('function fx-globmatch($fx_name, $fx_glob, $fx_suffix) {');
+        lines.push("  $fx_n = ([string]$fx_name).Replace('\\', '/')");
+        lines.push("  $fx_p = ([string]$fx_glob).Replace('\\', '/')");
+        lines.push('  if ($fx_n -like $fx_p) { return $true }');
+        lines.push('  if ($fx_suffix) {');
+        lines.push("    $fx_slash = $fx_n.IndexOf('/')");
+        lines.push('    while ($fx_slash -ge 0 -and $fx_slash + 1 -lt $fx_n.Length) {');
+        lines.push('      $fx_n = $fx_n.Substring($fx_slash + 1)');
+        lines.push('      if ($fx_n -like $fx_p) { return $true }');
+        lines.push("      $fx_slash = $fx_n.IndexOf('/')");
+        lines.push('    }');
+        lines.push('  }');
+        lines.push('  return $false');
+        lines.push('}');
+        lines.push('function fx-anyglob($fx_name, $fx_globs, $fx_suffix) {');
+        lines.push('  foreach ($fx_glob in $fx_globs) { if (fx-globmatch $fx_name $fx_glob $fx_suffix) { return $true } }');
+        lines.push('  return $false');
+        lines.push('}');
+        lines.push('function fx-filewanted($fx_path, $fx_suffix) {');
+        lines.push('  if ($fx_fsel.Count -eq 0) { return $true }');
+        lines.push('  $fx_name = if ($fx_suffix) { [string]$fx_path } else { [IO.Path]::GetFileName([string]$fx_path) }');
+        lines.push('  $fx_keep = -not [bool]$fx_fsel[0].Keep');
+        lines.push('  foreach ($fx_rule in $fx_fsel) { if (fx-globmatch $fx_name $fx_rule.Glob $fx_suffix) { $fx_keep = [bool]$fx_rule.Keep } }');
+        lines.push('  return $fx_keep');
+        lines.push('}');
+        if (rec) {
+            lines.push('function fx-walkfiles($fx_root) {');
+            lines.push('  $fx_dirs = New-Object System.Collections.Stack');
+            lines.push('  $fx_dirs.Push([string]$fx_root)');
+            lines.push('  while ($fx_dirs.Count -gt 0) {');
+            lines.push('    $fx_cur = [string]$fx_dirs.Pop()');
+            lines.push('    foreach ($fx_item in @(Get-ChildItem -LiteralPath $fx_cur -Force -ErrorAction SilentlyContinue)) {');
+            lines.push('      if ($fx_item.PSIsContainer) {');
+            lines.push('        if (($fx_item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0 -and -not (fx-anyglob $fx_item.Name $fx_excd $false)) { $fx_dirs.Push($fx_item.FullName) }');
+            lines.push('      } elseif (fx-filewanted $fx_item.FullName $false) { $fx_item.FullName }');
+            lines.push('    }');
+            lines.push('  }');
+            lines.push('}');
+        }
         lines.push('foreach ($fx_o in ' + psArray(fileWords) + ') {');
         lines.push('  foreach ($fx_g in (fx-glob $fx_o)) {');
         lines.push("    if (-not (Test-Path -LiteralPath $fx_g)) { [Console]::Error.WriteLine('grep: ' + $fx_g + ': No such file or directory'); $fx_err = $true; continue }");
         lines.push('    if (Test-Path -LiteralPath $fx_g -PathType Container) {');
         if (rec) {
+            lines.push('      $fx_dir = Get-Item -LiteralPath $fx_g');
+            lines.push('      if (fx-anyglob $fx_g $fx_excd $true) { continue }');
             lines.push('      $fx_recd = $true');
-            lines.push('      $fx_subs = @(Get-ChildItem -LiteralPath $fx_g -Recurse -Force -File -ErrorAction SilentlyContinue)');
-            lines.push('      if ($fx_inc.Count -gt 0) {');
-            lines.push("        $fx_subs = @($fx_subs | Where-Object { $fx_ok = $false; foreach ($fx_gi in $fx_inc) { if ($_.Name -like $fx_gi) { $fx_ok = $true; break } }; $fx_ok })");
-            lines.push('      }');
-            lines.push('      foreach ($fx_s in $fx_subs) { $fx_srcs += $fx_s.FullName }');
+            lines.push('      $fx_srcs += @(fx-walkfiles $fx_dir.FullName)');
         }
         else {
             lines.push("      [Console]::Error.WriteLine('grep: ' + $fx_g + ': Is a directory'); $fx_err = $true");
         }
-        lines.push('    } else { $fx_srcs += $fx_g }');
+        lines.push('    } elseif (fx-filewanted $fx_g $true) { $fx_srcs += $fx_g }');
         lines.push('  }');
         lines.push('}');
         lines.push('$fx_pre = $false');

package/dist/executor.d.ts

@@ -25,6 +25,8 @@ export declare class FauxnixSession {
     private bindFiles;
     private syncFromDisk;
     private ensureHost;
+    /** Boot powershell.exe now so the first run() is not the 1.1s cold start. */
+    prewarm(): Promise<void>;
     dispose(): Promise<void>;
     /** env for the child powershell process. */
     childEnv(cwdOverride?: string, stdinFile?: string | null): NodeJS.ProcessEnv;

package/dist/executor.js

@@ -7,6 +7,11 @@ import { decodeOutput, normalizeHostNewlines, resolveNativePref } from './encodi
 import { normalizeStderr } from './errors.js';
 import { PowerShellHost, PS_MISSING_MESSAGE } from './ps-host.js';
 const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_WINDOWS_PATHEXT = '.COM;.EXE;.BAT;.CMD';
+function hasEnvKey(env, name) {
+    const normalized = name.toUpperCase();
+    return Object.keys(env).some((key) => key.toUpperCase() === normalized);
+}
 /** Resolve /dev/null and POSIX-ish literal targets to real Windows paths. */
 function winTarget(target) {
     const p = normalizeLiteralPath(target);
@@ -195,6 +200,10 @@ export class FauxnixSession {
         }
         return this.host;
     }
+    /** Boot powershell.exe now so the first run() is not the 1.1s cold start. */
+    async prewarm() {
+        await this.ensureHost().ready();
+    }
     async dispose() {
         if (this.host) {
             await this.host.stop();
@@ -220,6 +229,14 @@ export class FauxnixSession {
             else
                 env[k] = v;
         }
+        // The MCP SDK's safe Windows stdio environment omits PATHEXT. Without it,
+        // PowerShell cannot resolve extensionless native commands such as `node`.
+        // Windows environment names are case-insensitive, so preserve any explicit
+        // spelling/value supplied by the caller and only restore the OS default
+        // when no variant is present at all.
+        if (process.platform === 'win32' && !hasEnvKey(env, 'PATHEXT')) {
+            env.PATHEXT = DEFAULT_WINDOWS_PATHEXT;
+        }
         env.FAUXNIX_CWD_FILE = this.cwdFile;
         env.FAUXNIX_ENV_FILE = this.envFile;
         if (stdinFile)
@@ -245,6 +262,8 @@ export class FauxnixSession {
 }
 async function runPlans(plans, session, opts, afterSegment, ensureHost) {
     const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    const timeoutMessage = '\nbash: command timed out after ' + Math.round(timeoutMs / 1000) + 's';
     let stdout = '';
     let stderr = '';
     let exitCode = 0;
@@ -263,6 +282,12 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
             continue;
         if (plan.op === '||' && chainOk)
             continue;
+        if (Date.now() >= deadline) {
+            stderr += timeoutMessage;
+            exitCode = 124;
+            session.prevExit = exitCode;
+            break;
+        }
         const red = planRedirects(plan.redirects);
         red.stdinFile = red.stdinFile ? resolveTarget(red.stdinFile) : null;
         red.stdoutFile = red.stdoutFile ? resolveTarget(red.stdoutFile) : null;
@@ -335,12 +360,19 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
                 chainOk = false;
                 continue;
             }
+            const remainingMs = deadline - Date.now();
+            if (remainingMs <= 0) {
+                stderr += timeoutMessage;
+                exitCode = 124;
+                session.prevExit = exitCode;
+                break;
+            }
             const encoded = wrapScript(plan.body, { mode: 'host' });
             const inv = await ensureHost().invoke(encoded, {
                 FAUXNIX_CWD: currentDir,
                 FAUXNIX_PREV_EXIT: session.prevExit === null ? '' : String(session.prevExit),
                 FAUXNIX_STDIN_FILE: red.stdinFile || '',
-            }, timeoutMs);
+            }, remainingMs);
             if (inv.spawnError === 'ENOENT') {
                 stderr += inv.stderr.toString('utf8') || PS_MISSING_MESSAGE;
                 exitCode = 127;
@@ -356,7 +388,7 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
             let segOut = normalizeHostNewlines(decodeOutput(inv.stdout, decodePref));
             let segErr = normalizeHostNewlines(normalizeStderr(decodeOutput(inv.stderr, decodePref)));
             if (inv.timedOut) {
-                segErr += '\nbash: command timed out after ' + Math.round(timeoutMs / 1000) + 's';
+                segErr += timeoutMessage;
             }
             if (red.mergeStderr) {
                 segOut += (segOut && !segOut.endsWith('\n') && segErr ? '\n' : '') + segErr;
@@ -406,6 +438,8 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
             // not move later relative redirects.
             if (redirectOk && session.cwd)
                 currentDir = session.cwd;
+            if (inv.timedOut)
+                break;
         }
         finally {
             closePrepFds(prepFds);

package/dist/mcp.js

@@ -1,16 +1,12 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import { FauxnixSession } from './executor.js';
 import { parseCommand } from './parser.js';
 import { translateCommandList, wrapScript, translatePipelineBody } from './translator.js';
 import { registeredNames } from './registry.js';
+import { packageVersion } from './version.js';
 import './commands/install-all.js';
-// single source of truth: the npm package version in package.json
-// (src/ and dist/ sit one level below the root, so the relative path holds in both)
-const pkgVersion = JSON.parse(readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8')).version;
 const TOOL_NAME = process.env.FAUXNIX_TOOL_NAME || 'bash';
 const EXEC_ANNOTATIONS = {
     readOnlyHint: false,
@@ -37,15 +33,16 @@ Output is formatted to look like GNU/Linux tooling (ls -l, ps aux, df -h ...), e
 
 Supported: pipes (|), && / || / ;, redirections (> >> 2> 2>&1 < /dev/null), variables ($VAR $HOME ~), command substitution $(...), and ${registeredNames().length}+ coreutils-style commands (${registeredNames().slice(0, 18).join(', ')}...).
 Unknown commands (git, node, npm, python, cargo...) are passed through and executed natively with argv-style quoting.
-Not supported: heredocs, while/until/case, word-level \$((...)) arithmetic expansion, background jobs. if/then/else/fi and for-in loops are supported.
+Not supported: heredocs, while/until/case, background jobs. if/then/elif/else/fi, for-in loops, and word-level \$((...)) arithmetic expansion are supported.
 
-CWD, environment variables, export/unset and cd persist across calls within this session — a resident PowerShell 5.1 host is reused, so batching with ; or && is still nicer but many tiny calls no longer each pay a powershell.exe spawn.
+CWD, environment variables, export/unset and cd persist across calls within this session — a resident PowerShell 5.1 host is started when the MCP session begins (and after reset), so the first bash tool call is already warm.
 Exit codes follow bash conventions (0 ok, 1 fail, 2 usage/serious, 127 command not found, 124 timeout).
 
 Platform requirement: the execution backend is native Windows PowerShell 5.1+. On hosts without PowerShell on PATH (e.g. Linux containers/sandboxes), the bash tool returns exit code 127 with an actionable error instead of running the command.`;
 export async function startMcpServer() {
-    const server = new McpServer({ name: 'fauxnix', version: pkgVersion }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: 'fauxnix', version: packageVersion }, { capabilities: { tools: {} } });
     let session = new FauxnixSession();
+    await session.prewarm();
     server.tool(TOOL_NAME, TOOL_DESCRIPTION, {
         command: z.string().describe('The bash-style command line to run'),
         timeout_ms: z
@@ -95,6 +92,7 @@ export async function startMcpServer() {
         if (action === 'reset') {
             await session.dispose();
             session = new FauxnixSession();
+            await session.prewarm();
             return { content: [{ type: 'text', text: 'fauxnix: session reset' }] };
         }
         const envKeys = Object.keys(session.env).sort();

package/dist/parser.js

@@ -217,7 +217,32 @@ function readBacktick(input, i) {
     }
     throw new FauxnixParseError('fauxnix: unclosed backtick');
 }
-/** Parse $VAR, ${VAR}, $(cmd substitution). Returns null when not a valid dollar construct. */
+/** Expand `$…` constructs that appear inside `$((…))`. */
+function readArithParts(input) {
+    const parts = [];
+    let buf = '';
+    let i = 0;
+    while (i < input.length) {
+        if (input[i] === '$') {
+            const v = readDollar(input, i);
+            if (v) {
+                if (buf) {
+                    parts.push({ kind: 'Text', text: buf });
+                    buf = '';
+                }
+                parts.push(v.part);
+                i = v.next;
+                continue;
+            }
+        }
+        buf += input[i];
+        i++;
+    }
+    if (buf)
+        parts.push({ kind: 'Text', text: buf });
+    return parts;
+}
+/** Parse $VAR, ${VAR}, $(cmd substitution), $((arith)). Returns null when not a valid dollar construct. */
 function readDollar(input, i) {
     const n = input.length;
     if (input[i] !== '$')
@@ -256,11 +281,41 @@ function readDollar(input, i) {
         }
         return { part: { kind: 'Var', name }, next: end + 1 };
     }
-    // $((...)) is arithmetic expansion, not command substitution of a
-    // parenthesized body. Today it was parsed as $( (expr) ) and became an
-    // empty/confusing command. Reject loudly until word-level arith lands.
+    // $((...)) arithmetic expansion — distinct from `$( (cmd) )` (space after
+    // the first paren is command substitution of a grouped body).
     if (input[j] === '(' && j + 1 < n && input[j + 1] === '(') {
-        throw new FauxnixParseError('fauxnix: $((...)) arithmetic expansion is not supported; compute the value in the agent or compare with [[ $n -eq m ]]');
+        let depth = 0;
+        let k = j;
+        while (k < n) {
+            const c = input[k];
+            if (c === "'" || c === '"') {
+                const q = c;
+                k++;
+                while (k < n && input[k] !== q) {
+                    if (input[k] === '\\')
+                        k++;
+                    k++;
+                }
+                k++;
+                continue;
+            }
+            if (c === '(')
+                depth++;
+            else if (c === ')') {
+                depth--;
+                if (depth === 0) {
+                    k++;
+                    break;
+                }
+            }
+            k++;
+        }
+        if (depth !== 0)
+            throw new FauxnixParseError('fauxnix: unclosed $(( ))');
+        return {
+            part: { kind: 'Arith', parts: readArithParts(input.slice(j + 2, k - 2)) },
+            next: k,
+        };
     }
     // $(cmd substitution) — captured with balanced parens; the translator
     // recursively translates this text before embedding it.
@@ -642,14 +697,24 @@ export function parseCommand(input) {
         }
         return { kind: 'CommandList', segments };
     };
-    const parseIf = () => {
-        expectKw('if');
+    const parseIf = (start = 'if') => {
+        expectKw(start);
         const test = parseListUntil(['then']);
         expectKw('then');
         const thenL = parseListUntil(['else', 'elif', 'fi']);
         let elseL;
         if (peekKw() === 'elif') {
-            throw new FauxnixParseError('fauxnix: elif is not supported yet; use else + if');
+            // bash `elif` is `else` + nested `if`; the innermost clause eats `fi`.
+            elseL = {
+                kind: 'CommandList',
+                segments: [
+                    {
+                        op: ';',
+                        pipeline: { kind: 'Pipeline', commands: [parseIf('elif')] },
+                    },
+                ],
+            };
+            return { kind: 'If', test, then: thenL, else: elseL, redirects: [] };
         }
         if (peekKw() === 'else') {
             next();

package/dist/ps-host.d.ts

@@ -37,6 +37,8 @@ export declare class PowerShellHost {
     private startLock;
     private invokeLock;
     constructor(hostFile: string, envFn: () => NodeJS.ProcessEnv);
+    /** Start the resident process and wait for the ready handshake (B1 prewarm). */
+    ready(): Promise<HostInvokeResult | null>;
     invoke(script: string, env: HostRequestEnv, timeoutMs: number): Promise<HostInvokeResult>;
     stop(): Promise<void>;
     private invokeSerial;

package/dist/ps-host.js

@@ -46,6 +46,10 @@ export class PowerShellHost {
         this.hostFile = hostFile;
         this.envFn = envFn;
     }
+    /** Start the resident process and wait for the ready handshake (B1 prewarm). */
+    async ready() {
+        return this.ensureStarted();
+    }
     async invoke(script, env, timeoutMs) {
         const run = this.invokeLock.then(() => this.invokeSerial(script, env, timeoutMs));
         this.invokeLock = run.then(() => undefined, () => undefined);

package/dist/translator.d.ts

@@ -1,4 +1,4 @@
-import { Assignment, CommandList, Redirect, SimpleCommand, IfCommand, ForCommand, Word } from './ast.js';
+import { Assignment, CommandList, Redirect, SimpleCommand, IfCommand, ForCommand, Word, WordPart } from './ast.js';
 import { PipelineCtx } from './registry.js';
 /** `${name:-word}` and friends using case-exact fx-scalar0. */
 export declare function paramExpr(name: string, op: ':-' | ':=' | ':+' | ':?' | '-' | '+' | '?', word: string): string;
@@ -25,6 +25,10 @@ export declare function pathExpr(s: string): string;
 export declare function exprOfWord(w: Word, opts?: {
     preserveCmdSub?: boolean;
 }): string;
+/** Registered by sysinfo so wrapScript can emit fx-arith without a circular import. */
+export declare function setArithHelperPreamble(s: string): void;
+/** PowerShell expression: evaluate `$((…))` via fx-arith; errors are loud, expansion empty. */
+export declare function arithExpr(parts: WordPart[]): string;
 /** Literal text of a word when it contains no interpolation, else null. */
 export declare function literalOfWord(w: Word): string | null;
 /**

package/dist/translator.js

@@ -161,6 +161,9 @@ export function exprOfWord(w, opts) {
     if (expanded.length === 1 && expanded[0].kind === 'CmdSub') {
         return '$(' + translateCmdSub(expanded[0].cmd, opts?.preserveCmdSub === true) + ')';
     }
+    if (expanded.length === 1 && expanded[0].kind === 'Arith') {
+        return arithExpr(expanded[0].parts);
+    }
     const literal = expanded.every((p) => p.kind === 'Text' || p.kind === 'SingleQuoted');
     if (literal) {
         const text = expanded.map((p) => p.text).join('');
@@ -186,6 +189,9 @@ export function exprOfWord(w, opts) {
             case 'CmdSub':
                 out += '$(' + translateCmdSub(p.cmd, quoted || opts?.preserveCmdSub === true) + ')';
                 break;
+            case 'Arith':
+                out += arithExpr(p.parts);
+                break;
         }
     };
     for (const p of expanded)
@@ -193,6 +199,62 @@ export function exprOfWord(w, opts) {
     out += '"';
     return out;
 }
+let arithHelperPreamble = '';
+/** Registered by sysinfo so wrapScript can emit fx-arith without a circular import. */
+export function setArithHelperPreamble(s) {
+    arithHelperPreamble = s;
+}
+function injectArithHelpers(body) {
+    if (!arithHelperPreamble)
+        return body;
+    if (!/\bfx-arith\b/.test(body))
+        return body;
+    if (/function\s+fx-arith\b/.test(body))
+        return body;
+    return arithHelperPreamble + '\n' + body;
+}
+/** PowerShell expression: evaluate `$((…))` via fx-arith; errors are loud, expansion empty. */
+export function arithExpr(parts) {
+    const src = arithSourceExpr(parts);
+    return ('$(try { [string](fx-arith (' +
+        src +
+        ')) } catch { [Console]::Error.WriteLine((\'bash: \' + [string](' +
+        src +
+        ') + \': integer expression expected\')); $script:fx_exit = 1; \'\' })');
+}
+function arithSourceExpr(parts) {
+    if (parts.length === 0)
+        return "''";
+    if (parts.every((p) => p.kind === 'Text')) {
+        return psStr(parts.map((p) => p.text).join(''));
+    }
+    let out = '"';
+    const emit = (p) => {
+        switch (p.kind) {
+            case 'Text':
+            case 'SingleQuoted':
+                out += escapeDq(p.text);
+                break;
+            case 'DoubleQuoted':
+                for (const q of p.parts)
+                    emit(q);
+                break;
+            case 'Var':
+                out += '$(' + varExpr(p.name, p.index, p.param, p.length === true) + ')';
+                break;
+            case 'CmdSub':
+                out += '$(' + translateCmdSub(p.cmd, true) + ')';
+                break;
+            case 'Arith':
+                out += arithExpr(p.parts);
+                break;
+        }
+    };
+    for (const p of parts)
+        emit(p);
+    out += '"';
+    return out;
+}
 /** Literal text of a word when it contains no interpolation, else null. */
 export function literalOfWord(w) {
     if (!w.every((p) => p.kind === 'Text' || p.kind === 'SingleQuoted'))
@@ -657,6 +719,8 @@ export function wrapTempEnv(sets, body, extra) {
 }
 /** Unique suffix for generated stage functions (nested pipelines included). */
 let stageSeq = 0;
+/** Unique suffix for generated pipeline wrappers and their local status arrays. */
+let pipelineSeq = 0;
 /**
  * Pipeline body. A lone command runs as a plain script-block expression;
  * multi-command pipelines become generated functions chained with `|`
@@ -722,6 +786,12 @@ function translateFor(cmd) {
     return lines.join('\n');
 }
 export function translatePipelineBody(p) {
+    // Every pipeline stage needs its own status slot. Handlers deliberately use
+    // `$script:fx_exit` because their helper functions run in child scopes; in a
+    // pipeline that shared flag lets an earlier failure leak into a successful
+    // last stage. Reserve the wrapper id before translating bodies so nested
+    // command substitutions cannot reuse it.
+    const pipelineId = p.commands.length > 1 ? pipelineSeq++ : -1;
     const bodies = [];
     for (let i = 0; i < p.commands.length; i++) {
         const c = p.commands[i];
@@ -739,16 +809,36 @@ export function translatePipelineBody(p) {
     }
     const names = [];
     const defs = [];
+    const statusVar = '$fx_pipe_status' + pipelineId;
     for (let i = 0; i < bodies.length; i++) {
         const name = '__fx_s' + stageSeq++;
         names.push(name);
-        const indented = bodies[i]
+        const isolatedBody = bodies[i].split('$script:fx_exit').join(statusVar + '[' + i + ']');
+        const indented = isolatedBody
             .split('\n')
             .map((l) => (l ? '  ' + l : l))
             .join('\n');
         defs.push('function ' + name + ' {\n' + indented + '\n}');
     }
-    return { defs: defs.join('\n'), call: names.join(' | ') };
+    const pipelineName = '__fx_p' + pipelineId;
+    const statuses = bodies.map(() => '0').join(', ');
+    const pipelineCall = names.join(' | ');
+    defs.push([
+        'function ' + pipelineName + ' {',
+        '  ' + statusVar + ' = @(' + statuses + ')',
+        '  try {',
+        // The wrapper forwards redirect input to stage zero. With no input,
+        // PowerShell still invokes a regular function once, which preserves the
+        // existing no-stdin pipeline behavior on Windows PowerShell 5.1.
+        '    $input | ' + pipelineCall,
+        '  } finally {',
+        // Bash defaults to pipefail off: only the last stage controls the list
+        // status used by a following && / || segment.
+        '    $script:fx_exit = [int]' + statusVar + '[' + (bodies.length - 1) + ']',
+        '  }',
+        '}',
+    ].join('\n'));
+    return { defs: defs.join('\n'), call: pipelineName };
 }
 export function translateCommandList(list) {
     const plans = [];
@@ -895,6 +985,7 @@ function wrapBodyAndPersist(body, exitProcess) {
  */
 export function wrapScript(body, opts = {}) {
     const mode = opts.mode ?? 'spawn';
+    body = injectArithHelpers(body);
     const needed = mode === 'host' ? new Set() : wrapHelpersNeeded(body);
     const lines = mode === 'host'
         ? wrapCwdPreamble()

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const packageVersion: string;

package/dist/version.js

@@ -0,0 +1,8 @@
+import { readFileSync } from 'node:fs';
+// src/ and dist/ are both one level below the package root, so package.json is
+// the runtime source of truth in development and in the published tarball.
+const metadata = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+if (typeof metadata.version !== 'string' || metadata.version.length === 0) {
+    throw new Error('fauxnix: package.json does not contain a valid version');
+}
+export const packageVersion = metadata.version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fauxnix-cli",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Fauxnix — run Linux-style commands on Windows via deterministic PowerShell translation. No VM, no WSL. MCP server + CLI for AI agents.",
   "type": "module",
   "bin": {
@@ -13,7 +13,9 @@
   ],
   "scripts": {
     "build": "tsc",
+    "prepare": "npm run build",
     "test": "vitest run",
+    "test:package": "node scripts/package-smoke.mjs",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "dev": "tsx src/index.ts"