fauxnix-cli 0.4.0 → 0.5.0

package/README.md

@@ -1,5 +1,11 @@
 # fauxnix
 
+[![CI](https://github.com/20000419/fauxnix/actions/workflows/ci.yml/badge.svg)](https://github.com/20000419/fauxnix/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/fauxnix-cli.svg)](https://www.npmjs.com/package/fauxnix-cli)
+[![npm downloads](https://img.shields.io/npm/dt/fauxnix-cli.svg)](https://www.npmjs.com/package/fauxnix-cli)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![20000419/fauxnix MCP server](https://glama.ai/mcp/servers/20000419/fauxnix/badges/score.svg)](https://glama.ai/mcp/servers/20000419/fauxnix)
+
 **Run Linux-style commands on Windows — natively, deterministically, with no VM and no WSL.**
 
 fauxnix is a bash→PowerShell translation layer built for AI agents. Your agent keeps writing the
@@ -8,15 +14,37 @@ fauxnix deterministically translates each command into PowerShell, executes it n
 back output that looks like GNU/Linux: `ls -l` columns, bash-style error messages, coreutils exit
 codes, UTF-8/GBK handled automatically.
 
+```bash
+npm install -g fauxnix-cli    # then point any MCP harness at `fauxnix mcp`
+```
+
+![fauxnix demo](docs/assets/demo.svg)
+
 ```
 $ fauxnix "ls -la src | head -2"
 -rw-r--r-- 1 me me 1204 Aug 16 09:12 ast.ts
--rw-r--r-- 1 me me  8192 Aug 16 09:12 cli.ts
+-rw-r--r-- 1 me me 8192 Aug 16 09:12 cli.ts
 
 $ fauxnix "cat nope.txt"
 cat: nope.txt: No such file or directory        # not a PowerShell stack trace
 ```
 
+## Measured: your model is probably worse at PowerShell than you think
+
+Same model (DeepSeek-V4-Pro), same 5 tasks, three execution modes on one Windows machine —
+full data in [`docs/benchmark-deepseek-v4-pro.md`](docs/benchmark-deepseek-v4-pro.md) and
+[`docs/benchmark-ark-models.md](docs/benchmark-ark-models.md):
+
+| | PowerShell | **fauxnix** | Git Bash |
+|---|---|---|---|
+| tool calls / unexpected errors | 14 / 9 | **7 / 0** | 4 / 0 |
+| time (T1–T4) | 163s | **66s** | 57s |
+
+Across 7 models on the Volcano Ark Coding Plan, the PowerShell-vs-fauxnix gap held for every
+model tested — worst case (kimi-k2-thinking): **3.1× slower with 24 error events** writing
+PowerShell vs zero errors through fauxnix. fauxnix lands within ~15% of the real-bash ceiling
+with no bash toolchain installed.
+
 ## Why
 
 LLM agents are dramatically better at bash than at PowerShell — bash dominates training data, so
@@ -165,8 +193,12 @@ 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`, `source`, `eval`, `alias`, heredocs, backticks, shell control flow (`if`/`for`/`while`)
+- `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.)
+- `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
   (as in Git Bash).
 - `ps aux` columns are approximations (no per-process CPU% accounting, USER shows `?`).

package/dist/ast.d.ts

@@ -7,12 +7,12 @@
  *   - redirections:         > >> 2> 2>> &> 2>&1 1>&2 <
  *   - quoting:              'literal'  "interp $VAR $(cmd)"
  *   - variables:            $VAR ${VAR} ${VAR[n]} plus special cases ($HOME $USER $PATH ...)
- *   - command substitution: $(...) (recursively translated)
+ *   - command substitution: $(...) and `...` (recursively translated)
  *   - env assignment prefix: VAR=value cmd
  *
  * Explicitly unsupported (parser throws a helpful FauxnixError):
- *   heredocs, backticks, subshells (...), background &, control flow
- *   (if/for/while), globs inside quotes, process substitution <(...).
+ *   heredocs, subshells (...), background &, while/until/case,
+ *   globs inside quotes, process substitution <(...).
  */
 export interface CommandList {
     kind: 'CommandList';
@@ -24,9 +24,24 @@ export interface ListSegment {
     /** ';' for the first segment, otherwise the operator seen before this one. */
     op: ';' | '&&' | '||';
 }
+export type ShellCommand = SimpleCommand | IfCommand | ForCommand;
 export interface Pipeline {
     kind: 'Pipeline';
-    commands: SimpleCommand[];
+    commands: ShellCommand[];
+}
+export interface IfCommand {
+    kind: 'If';
+    test: CommandList;
+    then: CommandList;
+    else?: CommandList;
+    redirects: Redirect[];
+}
+export interface ForCommand {
+    kind: 'For';
+    name: string;
+    words: Word[];
+    body: CommandList;
+    redirects: Redirect[];
 }
 export interface SimpleCommand {
     kind: 'SimpleCommand';
@@ -63,6 +78,13 @@ export type WordPart = {
     kind: 'Var';
     name: string;
     index?: string;
+    /** `${name:-word}` / `${name:+word}` / `${name:?word}` (and non-colon). */
+    param?: {
+        op: ':-' | ':=' | ':+' | ':?' | '-' | '+' | '?';
+        word: string;
+    };
+    /** `${#name}` / `${#name[@]}` — string/array length expansion. */
+    length?: boolean;
 } | {
     kind: 'CmdSub';
     cmd: string;

package/dist/ast.js

@@ -7,12 +7,12 @@
  *   - redirections:         > >> 2> 2>> &> 2>&1 1>&2 <
  *   - quoting:              'literal'  "interp $VAR $(cmd)"
  *   - variables:            $VAR ${VAR} ${VAR[n]} plus special cases ($HOME $USER $PATH ...)
- *   - command substitution: $(...) (recursively translated)
+ *   - command substitution: $(...) and `...` (recursively translated)
  *   - env assignment prefix: VAR=value cmd
  *
  * Explicitly unsupported (parser throws a helpful FauxnixError):
- *   heredocs, backticks, subshells (...), background &, control flow
- *   (if/for/while), globs inside quotes, process substitution <(...).
+ *   heredocs, subshells (...), background &, while/until/case,
+ *   globs inside quotes, process substitution <(...).
  */
 export function wordToString(w) {
     return w.map(partToString).join('');

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, } from '../translator.js';
+import { argListExpr, exprOfWord, operandExpr, translateSimple, wrapTempEnv, encodeSetValExpr, escapeDq, translateCmdSub, normalizeLiteralPath, pathExpr, paramExpr, varExpr, } from '../translator.js';
 import { handlers as textIoHandlers } from './text-io.js';
 /* ------------------------------------------------------------------ */
 /* Shared TS helpers                                                   */
@@ -545,6 +545,55 @@ const type = (args) => {
         '}',
     ].join('\n');
 };
+/** `command -v name` (and bare `command name args` as a no-alias run). */
+const commandCmd = (args, ctx) => {
+    let i = 0;
+    let identify = false;
+    while (i < args.length) {
+        const t = wordToString(args[i]);
+        if (t === '-v' || t === '-V') {
+            identify = true;
+            i++;
+            continue;
+        }
+        if (t === '--') {
+            i++;
+            break;
+        }
+        if (t.startsWith('-')) {
+            i++;
+            continue;
+        }
+        break;
+    }
+    const rest = args.slice(i);
+    if (identify) {
+        if (rest.length === 0)
+            return '';
+        return [
+            PS_WHICH_FN,
+            '$fx_b = @(' + builtinNames().map(psStr).join(', ') + ')',
+            '$fx_ns = ' + textArgs(rest),
+            'foreach ($fx_n in $fx_ns) {',
+            "  if ($fx_b -contains $fx_n) { '/usr/bin/' + $fx_n }",
+            '  else {',
+            '    $fx_w = fx-which $fx_n',
+            "    if ($fx_w -eq '') { $script:fx_exit = 1 }",
+            "    else { $fx_w.Replace('\\', '/') }",
+            '  }',
+            '}',
+        ].join('\n');
+    }
+    if (rest.length === 0)
+        return '';
+    return translateSimple({
+        kind: 'SimpleCommand',
+        assignments: [],
+        name: rest[0],
+        args: rest.slice(1),
+        redirects: [],
+    }, ctx.position, ctx.hasStdin);
+};
 /* ------------------------------------------------------------------ */
 /* whoami / id / groups                                                */
 /* ------------------------------------------------------------------ */
@@ -1344,6 +1393,12 @@ function kshExprOfWord(w) {
     if (tilde && expanded.length === 0)
         return '(fx-home)';
     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);
+        }
+        if (expanded[0].length) {
+            return varExpr(expanded[0].name, expanded[0].index, undefined, true);
+        }
         if (expanded[0].index !== undefined) {
             return '(fx-subget ' + psStr(expanded[0].name) + ' ' + psStr(expanded[0].index) + ')';
         }
@@ -1369,9 +1424,11 @@ function kshExprOfWord(w) {
                 break;
             case 'Var':
                 out +=
-                    p.index !== undefined
-                        ? '$(fx-subget ' + psStr(p.name) + ' ' + psStr(p.index) + ')'
-                        : '$(fx-envget ' + psStr(p.name) + ')';
+                    p.param
+                        ? '$(' + paramExpr(p.name, p.param.op, p.param.word) + ')'
+                        : p.index !== undefined
+                            ? '$(fx-subget ' + psStr(p.name) + ' ' + psStr(p.index) + ')'
+                            : '$(fx-envget ' + psStr(p.name) + ')';
                 break;
             case 'CmdSub':
                 // [[ ]] does not IFS-split, so keep the newline contract.
@@ -2310,12 +2367,107 @@ const less = (args, ctx) => {
     return cat(files, ctx);
 };
 /* ------------------------------------------------------------------ */
+/* read                                                                */
+/* ------------------------------------------------------------------ */
+const readCmd = (args, ctx) => {
+    const names = [];
+    for (const w of args) {
+        const t = wordToString(w);
+        if (t === '-r' || t === '-a' || t.startsWith('-'))
+            continue;
+        if (!NAME_RE.test(t)) {
+            return ('[Console]::Error.WriteLine(' +
+                psStr('bash: read: `' + t + "': not a valid identifier") +
+                '); $script:fx_exit = 2');
+        }
+        names.push(t);
+    }
+    if (names.length === 0)
+        names.push('REPLY');
+    const first = names[0];
+    return [
+        ctx.hasStdin
+            ? "$fx_line = [string]((@($input) | Select-Object -First 1))"
+            : "$fx_line = ''",
+        ctx.hasStdin ? '' : '$script:fx_exit = 1',
+        names.length === 1
+            ? [
+                "Set-Item -LiteralPath ('Env:\\' + " + psStr(first) + ') -Value $fx_line',
+                " $n = " + psStr(first),
+                " $env:FAUXNIX_SETVARS = ((@($env:FAUXNIX_SETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) + $n) -join ';')",
+                " $env:FAUXNIX_UNSETVARS = (@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) -join ';')",
+                ' fx-arrdrop $n',
+                ' $fx_sv = @(); foreach ($fx_pair in @($env:FAUXNIX_SETVALS -split [string][char]10)) { $fx_eq = $fx_pair.IndexOf([char]61); if ($fx_eq -lt 1) { continue }; if ($fx_pair.Substring(0, $fx_eq) -cne $n) { $fx_sv += $fx_pair } }',
+                ' $fx_sv += ($n + [string][char]61 + (fx-svenc $fx_line)); $env:FAUXNIX_SETVALS = ($fx_sv -join [string][char]10)',
+            ].join('\n')
+            : [
+                "$fx_fs = @($fx_line -split '\\s+', " + names.length + ')',
+                'foreach ($fx_i in 0..' + (names.length - 1) + ') {',
+                '  $n = @(' + names.map(psStr).join(',') + ')[$fx_i]',
+                "  $fx_v = $(if ($fx_i -lt $fx_fs.Count) { [string]$fx_fs[$fx_i] } else { '' })",
+                "  Set-Item -LiteralPath ('Env:\\' + $n) -Value $fx_v",
+                "  $env:FAUXNIX_SETVARS = ((@($env:FAUXNIX_SETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) + $n) -join ';')",
+                "  $env:FAUXNIX_UNSETVARS = (@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) -join ';')",
+                '  fx-arrdrop $n',
+                '  $fx_sv = @(); foreach ($fx_pair in @($env:FAUXNIX_SETVALS -split [string][char]10)) { $fx_eq = $fx_pair.IndexOf([char]61); if ($fx_eq -lt 1) { continue }; if ($fx_pair.Substring(0, $fx_eq) -cne $n) { $fx_sv += $fx_pair } }',
+                '  $fx_sv += ($n + [string][char]61 + (fx-svenc $fx_v)); $env:FAUXNIX_SETVALS = ($fx_sv -join [string][char]10)',
+                '}',
+            ].join('\n'),
+    ]
+        .filter((l) => l !== '')
+        .join('\n');
+};
+/* ------------------------------------------------------------------ */
 /* source / . / eval / exit / alias / set                              */
 /* ------------------------------------------------------------------ */
-const source = () => {
-    return ('[Console]::Error.WriteLine(' +
-        psStr('fauxnix: source/. requires a persistent shell; fauxnix persists cwd and env across calls but not shell functions') +
-        '); $script:fx_exit = 1');
+const source = (args) => {
+    const files = stripFlags(args);
+    if (files.length === 0) {
+        return ('[Console]::Error.WriteLine(' +
+            psStr('bash: source: filename argument required') +
+            '); $script:fx_exit = 2');
+    }
+    const q = (c) => '[char]' + c.charCodeAt(0);
+    return [
+        '$fx_files = ' + argListExpr(files, operandExpr),
+        'foreach ($fx_f in $fx_files) {',
+        '  if (-not (Test-Path -LiteralPath $fx_f -PathType Leaf)) {',
+        "    [Console]::Error.WriteLine('bash: source: ' + $fx_f + ': No such file or directory'); $script:fx_exit = 1; continue",
+        '  }',
+        '  $fx_raw = [IO.File]::ReadAllText($fx_f) -replace ([string][char]13 + [string][char]10), [string][char]10',
+        '  foreach ($fx_line in @($fx_raw -split [string][char]10)) {',
+        '    $fx_t = $fx_line.Trim()',
+        "    if ($fx_t -eq '' -or $fx_t.StartsWith([string][char]35)) { continue }",
+        '    if ($fx_t.StartsWith(' +
+            psStr('export ') +
+            ') -or $fx_t.StartsWith(' +
+            psStr('export\t') +
+            ')) { $fx_t = $fx_t.Substring(7).Trim() }',
+        '    $fx_eq = $fx_t.IndexOf([char]61)',
+        '    if ($fx_eq -lt 1) { [Console]::Error.WriteLine(' +
+            psStr('fauxnix: source: only NAME=VALUE lines are supported') +
+            '); $script:fx_exit = 1; continue }',
+        '    $fx_n = $fx_t.Substring(0, $fx_eq)',
+        "    if ($fx_n -notmatch '^[A-Za-z_][A-Za-z0-9_]*$') { [Console]::Error.WriteLine('bash: source: ' + $fx_n + ': not a valid identifier'); $script:fx_exit = 1; continue }",
+        '    $fx_v = $fx_t.Substring($fx_eq + 1)',
+        '    if ($fx_v.Length -ge 2 -and (($fx_v[0] -eq ' +
+            q('"') +
+            ' -and $fx_v[$fx_v.Length-1] -eq ' +
+            q('"') +
+            ') -or ($fx_v[0] -eq ' +
+            q("'") +
+            ' -and $fx_v[$fx_v.Length-1] -eq ' +
+            q("'") +
+            '))) { $fx_v = $fx_v.Substring(1, $fx_v.Length - 2) }',
+        "    Set-Item -LiteralPath ('Env:\\' + $fx_n) -Value $fx_v",
+        "    $env:FAUXNIX_SETVARS = ((@($env:FAUXNIX_SETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $fx_n }) + $fx_n) -join ';')",
+        "    $env:FAUXNIX_UNSETVARS = (@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $fx_n }) -join ';')",
+        '    fx-arrdrop $fx_n',
+        '    $fx_sv = @(); foreach ($fx_pair in @($env:FAUXNIX_SETVALS -split [string][char]10)) { $fx_eq2 = $fx_pair.IndexOf([char]61); if ($fx_eq2 -lt 1) { continue }; if ($fx_pair.Substring(0, $fx_eq2) -cne $fx_n) { $fx_sv += $fx_pair } }',
+        '    $fx_sv += ($fx_n + [string][char]61 + (fx-svenc $fx_v)); $env:FAUXNIX_SETVALS = ($fx_sv -join [string][char]10)',
+        '  }',
+        '}',
+    ].join('\n');
 };
 const evalCmd = () => {
     return ("[Console]::Error.WriteLine('fauxnix: eval is not supported; pass the command itself'); $script:fx_exit = 1");
@@ -2352,7 +2504,28 @@ const alias = (args) => {
         return '';
     return "[Console]::Error.WriteLine('fauxnix: alias is not supported'); $script:fx_exit = 1";
 };
-const set = () => ''; // silently ignore (`set -e`, `set --` ... no-op)
+const set = (args) => {
+    const raw = args.map(wordToString);
+    const unsupported = raw.filter((t) => t === '-e' ||
+        t === '-u' ||
+        t === '-x' ||
+        t === '-o' ||
+        t === '+e' ||
+        t === '+u' ||
+        t === '+x' ||
+        t.startsWith('-o') ||
+        t.startsWith('+o') ||
+        t === '-eu' ||
+        t === '-ue' ||
+        t === '-eux' ||
+        /^-.*[eux]/.test(t));
+    if (unsupported.length > 0) {
+        return ('[Console]::Error.WriteLine(' +
+            psStr('fauxnix: set -e/-u/-x is not supported (would silently lie); use explicit || exit') +
+            '); $script:fx_exit = 2');
+    }
+    return '';
+};
 /* ------------------------------------------------------------------ */
 export const handlers = {
     cd,
@@ -2368,6 +2541,7 @@ export const handlers = {
     sleep,
     which,
     type,
+    command: commandCmd,
     whoami,
     id,
     groups,
@@ -2393,6 +2567,7 @@ export const handlers = {
     history,
     less,
     more: less,
+    read: readCmd,
     source,
     '.': source,
     eval: evalCmd,

package/dist/executor.js

@@ -350,7 +350,15 @@ async function runPlans(plans, session, opts, afterSegment, scriptFile) {
             }, timeoutMs);
             const code = await new Promise((resolve) => {
                 child.on('error', (e) => {
-                    stderr += 'fauxnix: failed to start powershell.exe: ' + e.message + '\n';
+                    if (e.code === 'ENOENT') {
+                        stderr +=
+                            'fauxnix: powershell.exe not found — fauxnix executes bash via native Windows PowerShell 5.1+.\n' +
+                                'This host has no PowerShell on PATH (typical for Linux containers/sandboxes).\n' +
+                                'Run fauxnix on Windows, or install PowerShell and make powershell.exe reachable on PATH.\n';
+                    }
+                    else {
+                        stderr += 'fauxnix: failed to start powershell.exe: ' + e.message + '\n';
+                    }
                     resolve(127);
                 });
                 child.on('close', (c) => resolve(running.killed ? 124 : (c ?? 0)));

package/dist/mcp.js

@@ -1,25 +1,50 @@
 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 './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 TOOL_DESCRIPTION = `Execute a Linux/bash-style command on this Windows machine.
-
-Commands are deterministically translated to PowerShell and executed natively — no WSL or VM.
-Output is formatted to look like GNU/Linux tooling (ls -l, ps aux, df -h ...), errors look like bash errors, and text encoding (UTF-8/GBK) is handled automatically.
-
-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, backticks, control flow (if/for/while), background jobs.
-
-CWD, environment variables, export/unset and cd persist across calls within this session — but prefer COMBINING related commands in one call with ; or && (e.g. 'cd src && ls | wc -l'); each call is a fresh translation+process, so batching is faster than many tiny calls.
-Exit codes follow bash conventions (0 ok, 1 fail, 2 usage/serious, 127 command not found, 124 timeout).`;
+const EXEC_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+const TRANSLATE_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+const SESSION_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+const TOOL_DESCRIPTION = `Execute a Linux/bash-style command on this Windows machine.
+
+Commands are deterministically translated to PowerShell and executed natively — no WSL or VM.
+Output is formatted to look like GNU/Linux tooling (ls -l, ps aux, df -h ...), errors look like bash errors, and text encoding (UTF-8/GBK) is handled automatically.
+
+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, background jobs. if/then/else/fi and for-in loops are supported.
+
+CWD, environment variables, export/unset and cd persist across calls within this session — but prefer COMBINING related commands in one call with ; or && (e.g. 'cd src && ls | wc -l'); each call is a fresh translation+process, so batching is faster than many tiny calls.
+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: '0.4.0' }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: 'fauxnix', version: pkgVersion }, { capabilities: { tools: {} } });
     const session = new FauxnixSession();
     server.tool(TOOL_NAME, TOOL_DESCRIPTION, {
         command: z.string().describe('The bash-style command line to run'),
@@ -30,7 +55,7 @@ export async function startMcpServer() {
             .max(600_000)
             .optional()
             .describe('Timeout in milliseconds (default 120000)'),
-    }, async ({ command, timeout_ms }) => {
+    }, EXEC_ANNOTATIONS, async ({ command, timeout_ms }) => {
         try {
             const plans = translateCommandList(parseCommand(command));
             const result = await session.run(plans, { timeoutMs: timeout_ms });
@@ -49,7 +74,7 @@ export async function startMcpServer() {
             return { content: [{ type: 'text', text: msg }], isError: true };
         }
     });
-    server.tool('fauxnix_translate', 'Translate a bash-style command into the equivalent PowerShell script WITHOUT executing it. Useful for learning/debugging what fauxnix does under the hood.', { command: z.string() }, async ({ command }) => {
+    server.tool('fauxnix_translate', 'Translate a bash-style command into the equivalent PowerShell script WITHOUT executing it. Useful for learning/debugging what fauxnix does under the hood.', { command: z.string().describe('The bash-style command line to translate (never executed)') }, TRANSLATE_ANNOTATIONS, async ({ command }) => {
         try {
             const list = parseCommand(command);
             const plans = translateCommandList(list);
@@ -61,7 +86,12 @@ export async function startMcpServer() {
             return { content: [{ type: 'text', text: msg }], isError: true };
         }
     });
-    server.tool('fauxnix_session', 'Inspect or reset the persistent fauxnix shell session (current directory, environment, session id). Actions: "status" (default) or "reset".', { action: z.enum(['status', 'reset']).default('status') }, async ({ action }) => {
+    server.tool('fauxnix_session', 'Inspect or reset the persistent fauxnix shell session (current directory, environment, session id). Actions: "status" (default) or "reset".', {
+        action: z
+            .enum(['status', 'reset'])
+            .default('status')
+            .describe('"status" shows the session state (cwd, tracked env keys); "reset" clears it back to a fresh shell'),
+    }, SESSION_ANNOTATIONS, async ({ action }) => {
         if (action === 'reset') {
             await session.dispose();
             return { content: [{ type: 'text', text: 'fauxnix: session reset' }] };

package/dist/parser.js

@@ -127,6 +127,16 @@ export function tokenize(input) {
                         continue;
                     }
                 }
+                if (c === '`') {
+                    const v = readBacktick(input, i);
+                    if (buf) {
+                        parts.push({ kind: 'Text', text: buf });
+                        buf = '';
+                    }
+                    parts.push(v.part);
+                    i = v.next;
+                    continue;
+                }
                 buf += c;
                 i++;
             }
@@ -153,7 +163,11 @@ export function tokenize(input) {
             continue;
         }
         if (ch === '`') {
-            throw new FauxnixParseError('fauxnix: backticks are not supported. Use $(...) command substitution instead.');
+            const v = readBacktick(input, i);
+            beginWordPart();
+            cur.push(v.part);
+            i = v.next;
+            continue;
         }
         // escape outside quotes — keep the escape so [[ =~ ]] / == can
         // treat `\*` as a literal rather than a metacharacter
@@ -186,6 +200,23 @@ function isNameStart(c) {
 function isNameChar(c) {
     return /[A-Za-z0-9_]/.test(c);
 }
+/** Parse `cmd` as command substitution (same AST as $(cmd)). */
+function readBacktick(input, i) {
+    if (input[i] !== '`')
+        throw new FauxnixParseError('fauxnix: expected backtick');
+    let k = i + 1;
+    while (k < input.length) {
+        if (input[k] === '\\' && k + 1 < input.length) {
+            k += 2;
+            continue;
+        }
+        if (input[k] === '`') {
+            return { part: { kind: 'CmdSub', cmd: input.slice(i + 1, k) }, next: k + 1 };
+        }
+        k++;
+    }
+    throw new FauxnixParseError('fauxnix: unclosed backtick');
+}
 /** Parse $VAR, ${VAR}, $(cmd substitution). Returns null when not a valid dollar construct. */
 function readDollar(input, i) {
     const n = input.length;
@@ -204,8 +235,23 @@ function readDollar(input, i) {
         if (sub) {
             return { part: { kind: 'Var', name: sub[1], index: sub[2] }, next: end + 1 };
         }
+        const pm = name.match(/^([A-Za-z_][A-Za-z0-9_]*)(:?[-+?])(.*)$/);
+        if (pm) {
+            const op = pm[2];
+            return {
+                part: { kind: 'Var', name: pm[1], param: { op, word: pm[3] } },
+                next: end + 1,
+            };
+        }
+        const hash = name.match(/^#([A-Za-z_][A-Za-z0-9_]*)(\[([0-9]+|@|\*)\])?$/);
+        if (hash) {
+            return {
+                part: { kind: 'Var', name: hash[1], index: hash[3], length: true },
+                next: end + 1,
+            };
+        }
         if (!name || !isNameStart(name[0]) || !name.split('').every(isNameChar)) {
-            // ${VAR:-default} etc. — unsupported, kept as raw text
+            // ${VAR:=default} etc. still raw text
             return { part: { kind: 'Text', text: input.slice(i, end + 1) }, next: end + 1 };
         }
         return { part: { kind: 'Var', name }, next: end + 1 };
@@ -509,7 +555,22 @@ export function parseCommand(input) {
     const parsePipeline = () => {
         const commands = [];
         for (;;) {
-            commands.push(parseSimple());
+            const kw = peekKw();
+            if (kw === 'if') {
+                if (commands.length > 0) {
+                    throw new FauxnixParseError('fauxnix: if in a pipeline is not supported');
+                }
+                commands.push(parseIf());
+            }
+            else if (kw === 'for') {
+                if (commands.length > 0) {
+                    throw new FauxnixParseError('fauxnix: for in a pipeline is not supported');
+                }
+                commands.push(parseFor());
+            }
+            else {
+                commands.push(parseSimple());
+            }
             const t = peek();
             if (t.type === 'OP' && t.op === '|') {
                 next();
@@ -519,6 +580,108 @@ export function parseCommand(input) {
         }
         return { kind: 'Pipeline', commands };
     };
+    const peekKw = () => {
+        const t = peek();
+        if (t.type !== 'WORD' || !t.parts)
+            return null;
+        const s = wordToString(t.parts);
+        if (!isUnquotedLiteral(t.parts, s))
+            return null;
+        if (s === 'if' ||
+            s === 'then' ||
+            s === 'else' ||
+            s === 'elif' ||
+            s === 'fi' ||
+            s === 'for' ||
+            s === 'in' ||
+            s === 'do' ||
+            s === 'done' ||
+            s === 'while') {
+            return s;
+        }
+        return null;
+    };
+    const expectKw = (k) => {
+        if (peekKw() !== k) {
+            throw new FauxnixParseError('fauxnix: expected `' + k + "'");
+        }
+        next();
+    };
+    const parseListUntil = (stops) => {
+        const stop = new Set(stops);
+        const segments = [];
+        let op = ';';
+        const isListSep = (o) => o === ';' || o === '\n';
+        while (peek().type === 'OP' && isListSep(peek().op))
+            next();
+        while (peek().type !== 'EOF') {
+            const kw = peekKw();
+            if (kw && stop.has(kw))
+                break;
+            const pipeline = parsePipeline();
+            segments.push({ pipeline, op });
+            const t = peek();
+            if (t.type === 'OP' && (t.op === '&&' || t.op === '||' || isListSep(t.op))) {
+                op = t.op === '\n' ? ';' : t.op;
+                next();
+                while (peek().type === 'OP' && isListSep(peek().op))
+                    next();
+            }
+            else {
+                break;
+            }
+        }
+        if (segments.length === 0) {
+            throw new FauxnixParseError('fauxnix: empty command');
+        }
+        return { kind: 'CommandList', segments };
+    };
+    const parseIf = () => {
+        expectKw('if');
+        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');
+        }
+        if (peekKw() === 'else') {
+            next();
+            elseL = parseListUntil(['fi']);
+        }
+        expectKw('fi');
+        return { kind: 'If', test, then: thenL, else: elseL, redirects: [] };
+    };
+    const parseFor = () => {
+        expectKw('for');
+        const nt = peek();
+        if (nt.type !== 'WORD' || !nt.parts) {
+            throw new FauxnixParseError('fauxnix: `for` expected a name');
+        }
+        const name = wordToString(nt.parts);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || !isUnquotedLiteral(nt.parts, name)) {
+            throw new FauxnixParseError('fauxnix: `for` name must be an identifier');
+        }
+        next();
+        expectKw('in');
+        const words = [];
+        for (;;) {
+            while (peek().type === 'OP' && (peek().op === ';' || peek().op === '\n'))
+                next();
+            if (peekKw() === 'do')
+                break;
+            const t = peek();
+            if (t.type !== 'WORD' || !t.parts) {
+                throw new FauxnixParseError("fauxnix: `for` expected `do`");
+            }
+            words.push(t.parts);
+            next();
+        }
+        expectKw('do');
+        const body = parseListUntil(['done']);
+        expectKw('done');
+        return { kind: 'For', name, words, body, redirects: [] };
+    };
     const parseSimple = () => {
         const assignments = [];
         let redirects = [];

package/dist/translator.d.ts

@@ -1,7 +1,12 @@
-import { Assignment, CommandList, Redirect, SimpleCommand, Word } from './ast.js';
+import { Assignment, CommandList, Redirect, SimpleCommand, IfCommand, ForCommand, Word } 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;
 /** Map a bash $VAR name to a PowerShell expression (usable inside $(...)). */
-export declare function varExpr(name: string, index?: string): string;
+export declare function varExpr(name: string, index?: string, param?: {
+    op: ':-' | ':=' | ':+' | ':?' | '-' | '+' | '?';
+    word: string;
+}, length?: boolean): string;
 /** Escape text destined for the inside of a PS double-quoted string. */
 export declare function escapeDq(s: string): string;
 /** Normalize a literal POSIX-ish path to its Windows equivalent. */
@@ -66,13 +71,8 @@ export interface PipelineParts {
     /** The pipeline invocation itself. */
     call: string;
 }
-/**
- * Pipeline body. A lone command runs as a plain script-block expression;
- * multi-command pipelines become generated functions chained with `|`
- * (PS 5.1 forbids parenthesized expressions as non-first pipeline elements).
- */
 export declare function translatePipelineBody(p: {
-    commands: SimpleCommand[];
+    commands: Array<SimpleCommand | IfCommand | ForCommand>;
 }): PipelineParts;
 export interface SegmentPlan {
     op: ';' | '&&' | '||';

package/dist/translator.js

@@ -4,8 +4,55 @@ import { lookup, psStr } from './registry.js';
 /* ------------------------------------------------------------------ */
 /* Variable mapping                                                    */
 /* ------------------------------------------------------------------ */
+function paramWordExpr(word) {
+    if (word.startsWith('$') && /^\$[A-Za-z_][A-Za-z0-9_]*$/.test(word)) {
+        return varExpr(word.slice(1));
+    }
+    return psStr(word);
+}
+/** `${name:-word}` and friends using case-exact fx-scalar0. */
+export function paramExpr(name, op, word) {
+    const alt = paramWordExpr(word);
+    const get = '(fx-scalar0 ' + psStr(name) + ')';
+    const empty = '($null -eq $fx_pv -or [string]$fx_pv -eq \'\')';
+    const unset = '($null -eq $fx_pv)';
+    if (op === ':-') {
+        return '$( $fx_pv = ' + get + '; if (' + empty + ') { ' + alt + ' } else { $fx_pv } )';
+    }
+    if (op === '-') {
+        return '$( $fx_pv = ' + get + '; if (' + unset + ') { ' + alt + ' } else { $fx_pv } )';
+    }
+    if (op === ':+') {
+        return '$( $fx_pv = ' + get + '; if (' + empty + ') { \'\' } else { ' + alt + ' } )';
+    }
+    if (op === '+') {
+        return '$( $fx_pv = ' + get + '; if (' + unset + ') { \'\' } else { ' + alt + ' } )';
+    }
+    const msg = word === '' ? name + ': parameter null or not set' : name + ': ' + word;
+    const cond = op === ':?' ? empty : unset;
+    return ('$( $fx_pv = ' +
+        get +
+        '; if (' +
+        cond +
+        ') { [Console]::Error.WriteLine(' +
+        psStr('bash: ' + msg) +
+        '); $script:fx_exit = 1; \'\' } else { $fx_pv } )');
+}
 /** Map a bash $VAR name to a PowerShell expression (usable inside $(...)). */
-export function varExpr(name, index) {
+export function varExpr(name, index, param, length = false) {
+    if (param)
+        return paramExpr(name, param.op, param.word);
+    if (length) {
+        if (index === '@' || index === '*') {
+            return '@(fx-arrload ' + psStr(name) + ').Count';
+        }
+        if (index !== undefined) {
+            return '([string](fx-subget ' + psStr(name) + ' ' + psStr(index) + ')).Length';
+        }
+        return ('([string]$(if ($null -eq ($fx_pv = fx-scalar0 ' +
+            psStr(name) +
+            ')) { \'\' } else { $fx_pv })).Length');
+    }
     // Indexed reads always go through fx-subget → fx-arrload → fx-scalar0 so
     // ${PWD[0]} keeps the special mapping and ${bash_rematch[0]} stays
     // case-exact (a `$env:name` fallback would alias BASH_REMATCH on Windows).
@@ -106,7 +153,8 @@ export function exprOfWord(w, opts) {
     }
     // single bare variable → bare expression
     if (expanded.length === 1 && expanded[0].kind === 'Var') {
-        return varExpr(expanded[0].name, expanded[0].index);
+        const v = expanded[0];
+        return varExpr(v.name, v.index, v.param, v.length === true);
     }
     // Bare `$(...)` must not sit inside a PS expandable string: the
     // substitution body contains `"` / `$_` that would break interpolation.
@@ -133,7 +181,7 @@ export function exprOfWord(w, opts) {
                     emitPart(q, true);
                 break;
             case 'Var':
-                out += '$(' + varExpr(p.name, p.index) + ')';
+                out += '$(' + varExpr(p.name, p.index, p.param, p.length === true) + ')';
                 break;
             case 'CmdSub':
                 out += '$(' + translateCmdSub(p.cmd, quoted || opts?.preserveCmdSub === true) + ')';
@@ -189,7 +237,9 @@ export function splatSpec(w) {
     let suffix = '';
     let seen = false;
     for (const { part: p, quoted } of parts) {
-        const splat = p.kind === 'Var' && (p.index === '@' || (p.index === '*' && !quoted));
+        const splat = p.kind === 'Var' &&
+            !p.length &&
+            (p.index === '@' || (p.index === '*' && !quoted));
         if (splat) {
             if (seen)
                 return null;
@@ -258,6 +308,12 @@ export function translateCmdSub(cmdText, keepNl = false) {
 /* ------------------------------------------------------------------ */
 /* Simple command translation                                          */
 /* ------------------------------------------------------------------ */
+function indentBlock(s) {
+    return s
+        .split('\n')
+        .map((l) => (l ? '  ' + l : l))
+        .join('\n');
+}
 export function translateSimple(cmd, position, hasStdin) {
     // assignment-only segment (`X=1; cmd`): bash semantics are "set for the
     // rest of the shell". Reuse the export code path — persist + env shadow —
@@ -276,20 +332,35 @@ export function translateSimple(cmd, position, hasStdin) {
     let body;
     if (nameSplat) {
         const invoke = '& $fx_cmd @fx_na';
-        body = [
+        const hasAffix = !!(nameSplat.prefix || nameSplat.suffix);
+        const promoted = cmd.args.length === 0
+            ? ''
+            : translateSimple({
+                kind: 'SimpleCommand',
+                assignments: [],
+                name: cmd.args[0],
+                args: cmd.args.slice(1),
+                redirects: cmd.redirects,
+            }, position, hasStdin);
+        const emptyCmdLines = [
             '$fx_cw = @(fx-arrload ' + psStr(nameSplat.name) + ')',
-            'if ($fx_cw.Count -eq 0) { $fx_cw = @(' + psStr(nameSplat.prefix + nameSplat.suffix) + ') }',
-            'else { $fx_cw[0] = ' +
+        ];
+        if (hasAffix) {
+            emptyCmdLines.push('if ($fx_cw.Count -eq 0) { $fx_cw = @(' +
+                psStr(nameSplat.prefix + nameSplat.suffix) +
+                ') } else { $fx_cw[0] = ' +
                 psStr(nameSplat.prefix) +
                 ' + $fx_cw[0]; $fx_cw[$fx_cw.Count-1] = $fx_cw[$fx_cw.Count-1] + ' +
                 psStr(nameSplat.suffix) +
-                ' }',
-            '$fx_cmd = [string]$fx_cw[0]',
-            '$fx_na = ' + argListExpr(cmd.args),
-            'if ($fx_cw.Count -gt 1) { $fx_na = @($fx_cw[1..($fx_cw.Count - 1)]) + $fx_na }',
-            (hasStdin ? '($input | ' + invoke + ')' : invoke) + ' | ForEach-Object { [string]$_ }',
-            'if ($LASTEXITCODE -gt 0) { $script:fx_exit = $LASTEXITCODE } elseif ($LASTEXITCODE -lt 0) { $script:fx_exit = 1 }',
-        ].join('\n');
+                ' }');
+        }
+        emptyCmdLines.push('if ($fx_cw.Count -eq 0) {', 
+        // No words left → bash null command (exit 0). Remaining words are
+        // known at compile time, so reuse translateSimple (handlers, not `&`).
+        promoted ? indentBlock(promoted) : '  ', '} else {', '  $fx_na = [object[]]@(' + argListExpr(cmd.args) + ')', '  $fx_cmd = [string]$fx_cw[0]', '  if ($fx_cw.Count -gt 1) { $fx_na = @($fx_cw[1..($fx_cw.Count - 1)]) + $fx_na }', '  ' +
+            (hasStdin ? '($input | ' + invoke + ')' : invoke) +
+            ' | ForEach-Object { [string]$_ }', '  if ($LASTEXITCODE -gt 0) { $script:fx_exit = $LASTEXITCODE } elseif ($LASTEXITCODE -lt 0) { $script:fx_exit = 1 }', '}');
+        body = emptyCmdLines.join('\n');
     }
     else if (nameLit !== null) {
         const handler = lookup(nameLit);
@@ -591,12 +662,77 @@ let stageSeq = 0;
  * multi-command pipelines become generated functions chained with `|`
  * (PS 5.1 forbids parenthesized expressions as non-first pipeline elements).
  */
+function translateListInline(list) {
+    const chunks = [];
+    for (const seg of list.segments) {
+        const { defs, call } = translatePipelineBody(seg.pipeline);
+        const body = (defs ? defs + '\n' : '') + call;
+        if (seg.op === '&&') {
+            chunks.push('if ($script:fx_exit -eq 0) {\n' + body + '\n}');
+        }
+        else if (seg.op === '||') {
+            chunks.push('if ($script:fx_exit -ne 0) {\n' + body + '\n}');
+        }
+        else {
+            chunks.push(body);
+        }
+    }
+    return chunks.join('\n');
+}
+function translateIf(cmd) {
+    // Branch bodies reset fx_exit first: the compound's exit status must come
+    // from the taken branch's last command (bash semantics), not leak the test's
+    // failure — `if false; then A; else B; fi` exits 0 in bash.
+    const lines = [translateListInline(cmd.test), 'if ($script:fx_exit -eq 0) {', '  $script:fx_exit = 0'];
+    for (const l of translateListInline(cmd.then).split('\n'))
+        lines.push(l ? '  ' + l : l);
+    lines.push('} else {', '  $script:fx_exit = 0');
+    if (cmd.else) {
+        for (const l of translateListInline(cmd.else).split('\n'))
+            lines.push(l ? '  ' + l : l);
+    }
+    lines.push('}');
+    return lines.join('\n');
+}
+function translateFor(cmd) {
+    const n = cmd.name.replace(/'/g, "''");
+    const lines = [
+        '$fx_for = ' + argListExpr(cmd.words),
+        'foreach ($fx_it in @($fx_for)) {',
+        "  Set-Item -LiteralPath ('Env:\\' + '" + n + "') -Value ([string]$fx_it)",
+        "  $env:FAUXNIX_SETVARS = ((@($env:FAUXNIX_SETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne '" +
+            n +
+            "' }) + '" +
+            n +
+            "') -join ';')",
+        "  $env:FAUXNIX_UNSETVARS = (@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne '" +
+            n +
+            "' }) -join ';')",
+        '  fx-arrdrop ' + psStr(cmd.name),
+        "  $fx_sv = @(); foreach ($fx_pair in @($env:FAUXNIX_SETVALS -split [string][char]10)) { $fx_eq = $fx_pair.IndexOf([char]61); if ($fx_eq -lt 1) { continue }; if ($fx_pair.Substring(0, $fx_eq) -cne '" +
+            n +
+            "') { $fx_sv += $fx_pair } }",
+        "  $fx_sv += ('" +
+            n +
+            "' + [string][char]61 + (fx-svenc ([string]$fx_it))); $env:FAUXNIX_SETVALS = ($fx_sv -join [string][char]10)",
+    ];
+    for (const l of translateListInline(cmd.body).split('\n'))
+        lines.push(l ? '  ' + l : l);
+    lines.push('}');
+    return lines.join('\n');
+}
 export function translatePipelineBody(p) {
     const bodies = [];
     for (let i = 0; i < p.commands.length; i++) {
-        const hasStdin = i > 0 || p.commands[i].redirects.some((r) => r.op === '<');
+        const c = p.commands[i];
+        const hasStdin = i > 0 || c.redirects.some((r) => r.op === '<');
         const position = i === 0 ? 'first' : i === p.commands.length - 1 ? 'last' : 'middle';
-        bodies.push(translateSimple(p.commands[i], position, hasStdin));
+        if (c.kind === 'If')
+            bodies.push(translateIf(c));
+        else if (c.kind === 'For')
+            bodies.push(translateFor(c));
+        else
+            bodies.push(translateSimple(c, position, hasStdin));
     }
     if (bodies.length === 1) {
         return { defs: '', call: '(& {\n' + bodies[0] + '\n})' };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fauxnix-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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": {
@@ -53,6 +53,6 @@
     "@types/node": "^20.14.0",
     "tsx": "^4.19.0",
     "typescript": "^5.5.0",
-    "vitest": "^2.1.0"
+    "vitest": "3.2.6"
   }
 }