fauxnix-cli 0.4.2 → 0.5.1

package/README.md

@@ -193,8 +193,13 @@ 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`, word-level
+  `$((...))` arithmetic expansion
   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,13 @@
  *   - 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,
+ *   word-level $((...)) arithmetic expansion, globs inside quotes,
+ *   process substitution <(...).
  */
 export interface CommandList {
     kind: 'CommandList';
@@ -24,9 +25,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 +79,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,13 @@
  *   - 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,
+ *   word-level $((...)) arithmetic expansion, 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/mcp.js

@@ -37,7 +37,7 @@ 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, backticks, control flow (if/for/while), background jobs.
+Not supported: heredocs, while/until/case, word-level \$((...)) arithmetic expansion, 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).

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,12 +235,33 @@ 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 };
     }
+    // $((...)) 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.
+    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 ]]');
+    }
     // $(cmd substitution) — captured with balanced parens; the translator
     // recursively translates this text before embedding it.
     if (input[j] === '(') {
@@ -509,7 +561,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 +586,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: ';' | '&&' | '||';
@@ -85,5 +85,7 @@ export declare function translateCommandList(list: CommandList): SegmentPlan[];
 /**
  * Wrap a pipeline body with the Fauxnix executor contract:
  * UTF-8 everywhere, bash-style exit codes, cwd/env persistence channels.
+ * Only the fx- helpers the body actually calls are emitted — the full
+ * catalog is ~170 lines and was paid on every `echo hi`.
  */
 export declare function wrapScript(body: string): string;

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})' };
@@ -639,11 +775,72 @@ export function translateCommandList(list) {
     }
     return plans;
 }
+const WRAP_HELPER_ORDER = [
+    'fx-readlines',
+    'fx-csub',
+    'fx-svenc',
+    'fx-svdec',
+    'fx-arrload',
+    'fx-scalar0',
+    'fx-ifs1',
+    'fx-arrdrop',
+    'fx-arrhas',
+    'fx-arrpackget',
+    'fx-arrpackset',
+    'fx-arrput',
+    'fx-arrclr',
+    'fx-subget',
+];
+const WRAP_HELPER_DEPS = {
+    'fx-readlines': [],
+    'fx-csub': [],
+    'fx-svenc': [],
+    'fx-svdec': [],
+    'fx-arrload': ['fx-scalar0', 'fx-svdec'],
+    'fx-scalar0': ['fx-svdec'],
+    'fx-ifs1': ['fx-scalar0'],
+    'fx-arrdrop': [],
+    'fx-arrhas': [],
+    'fx-arrpackget': [],
+    'fx-arrpackset': ['fx-arrdrop'],
+    'fx-arrput': ['fx-arrdrop', 'fx-svenc'],
+    'fx-arrclr': ['fx-arrdrop'],
+    'fx-subget': ['fx-arrload', 'fx-ifs1'],
+};
+/** Helpers the body calls that wrapScript still has to emit (not already defined there). */
+function wrapHelpersNeeded(body) {
+    const defined = new Set();
+    const defRe = /function\s+(fx-[A-Za-z0-9]+)/g;
+    let m;
+    while ((m = defRe.exec(body)))
+        defined.add(m[1]);
+    const seeds = [];
+    const callRe = /\b(fx-[A-Za-z0-9]+)\b/g;
+    while ((m = callRe.exec(body))) {
+        const n = m[1];
+        if (!defined.has(n) && n in WRAP_HELPER_DEPS)
+            seeds.push(n);
+    }
+    const needed = new Set();
+    const stack = seeds.slice();
+    while (stack.length) {
+        const n = stack.pop();
+        if (needed.has(n) || defined.has(n))
+            continue;
+        needed.add(n);
+        for (const d of WRAP_HELPER_DEPS[n])
+            stack.push(d);
+    }
+    return needed;
+}
 /**
  * Wrap a pipeline body with the Fauxnix executor contract:
  * UTF-8 everywhere, bash-style exit codes, cwd/env persistence channels.
+ * Only the fx- helpers the body actually calls are emitted — the full
+ * catalog is ~170 lines and was paid on every `echo hi`.
  */
 export function wrapScript(body) {
+    const needed = wrapHelpersNeeded(body);
     const lines = [
         '$ErrorActionPreference = "Continue"',
         "$ProgressPreference = 'SilentlyContinue'",
@@ -667,175 +864,191 @@ export function wrapScript(body) {
         // .NET APIs (ReadAllBytes & friends) resolve relative paths against the
         // process working directory, NOT the PS location — keep them in sync.
         'try { [Environment]::CurrentDirectory = (Get-Location).ProviderPath } catch {}',
-        // byte-sniffing line reader for `< file` stdin redirects (UTF-8 → GBK)
-        'function fx-readlines($p) {',
-        '  $b = [IO.File]::ReadAllBytes($p)',
-        '  $t = $null',
-        '  try { $t = (New-Object System.Text.UTF8Encoding($false, $true)).GetString($b) } catch {}',
-        "  if ($null -eq $t) { try { $t = [System.Text.Encoding]::GetEncoding(936).GetString($b) } catch { $t = [System.Text.Encoding]::ASCII.GetString($b) } }",
-        '  $t = $t -replace "`r`n", "`n"',
-        '  $t = $t -replace "`r", "`n"',
-        '  $parts = @($t.Split("`n"))',
-        "  if ($parts.Count -eq 1 -and $parts[0] -eq '') { return @() }",
-        "  if ($parts[$parts.Count - 1] -eq '') { $parts = $parts[0..($parts.Count - 2)] }",
-        '  return $parts',
-        '}',
-        'function fx-csub([scriptblock]$b) {',
-        '  $fx_prevcs = $script:fx_csub',
-        '  $script:fx_csub = $true',
-        '  try { $fx_o = @(& $b | ForEach-Object { [string]$_ }) }',
-        '  finally { $script:fx_csub = $fx_prevcs }',
-        '  $fx_s = ($fx_o -join [string][char]10)',
-        '  while ($fx_s.Length -gt 0 -and $fx_s[$fx_s.Length - 1] -eq [char]10) {',
-        '    $fx_s = $fx_s.Substring(0, $fx_s.Length - 1)',
-        '  }',
-        '  return $fx_s',
-        '}',
-        'function fx-svenc($s) {',
-        '  return ([string]$s).Replace([string][char]92, ([string][char]92 + [string][char]92)).Replace([string][char]13, ([string][char]92 + [char]114)).Replace([string][char]10, ([string][char]92 + [char]110))',
-        '}',
-        'function fx-svdec($s) {',
-        '  $s = [string]$s',
-        '  $sb = New-Object System.Text.StringBuilder',
-        '  $i = 0',
-        '  while ($i -lt $s.Length) {',
-        '    $c = $s[$i]',
-        '    if ($c -eq [char]92 -and ($i + 1) -lt $s.Length) {',
-        '      $n2 = $s[$i + 1]',
-        '      if ($n2 -eq [char]110) { [void]$sb.Append([char]10); $i += 2; continue }',
-        '      if ($n2 -eq [char]114) { [void]$sb.Append([char]13); $i += 2; continue }',
-        '      if ($n2 -eq [char]92) { [void]$sb.Append([char]92); $i += 2; continue }',
-        '    }',
-        '    [void]$sb.Append($c)',
-        '    $i++',
-        '  }',
-        '  return [string]$sb',
-        '}',
-        'function fx-arrload($n) {',
-        '  $n = [string]$n',
-        '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -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) { continue }',
-        '    $out = @()',
-        '    foreach ($el in @($fx_pair.Substring($fx_eq + 1) -split [string][char]30)) { $out += ,(fx-svdec $el) }',
-        '    return $out',
-        '  }',
-        '  $s0 = fx-scalar0 $n',
-        '  if ($null -eq $s0) { return @() }',
-        '  return @([string]$s0)',
-        '}',
-        'function fx-scalar0($n) {',
-        '  $n = [string]$n',
-        "  if (@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ceq $n }).Count -gt 0) { return $null }",
-        '  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) -ceq $n) { return (fx-svdec $fx_pair.Substring($fx_eq + 1)) }',
-        '  }',
-        "  if ($n -ceq 'HOME') { return [string]$HOME }",
-        "  if ($n -ceq 'PWD') { return [string]$PWD.Path }",
-        "  if ($n -ceq 'USER' -or $n -ceq 'LOGNAME') { return [string]$env:USERNAME }",
-        "  if ($n -ceq 'PATH') { return [string]$env:PATH }",
-        "  if ($n -ceq 'SHELL') { return 'powershell' }",
-        "  if ($n -ceq 'TERM') { return 'xterm-256color' }",
-        "  if ($n -ceq 'OLDPWD') { return $(if ($env:FAUXNIX_OLDPWD) { [string]$env:FAUXNIX_OLDPWD } else { $null }) }",
-        "  if ($n -ceq 'HOSTNAME') { return [string]$env:COMPUTERNAME }",
-        '  $ev = Get-ChildItem Env: | Where-Object { $_.Name -ceq $n } | Select-Object -First 1',
-        '  if ($ev) { return [string]$ev.Value }',
-        '  return $null',
-        '}',
-        'function fx-ifs1 {',
-        "  $s = fx-scalar0 'IFS'",
-        "  if ($null -eq $s) { return ' ' }",
-        "  if ([string]$s -eq '') { return '' }",
-        '  return [string]$s[0]',
-        '}',
-        'function fx-arrdrop($n) {',
-        '  $n = [string]$n',
-        '  $fx_sm = @()',
-        '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -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_sm += $fx_pair }',
-        '  }',
-        '  $env:FAUXNIX_ARRS = ($fx_sm -join [string][char]10)',
-        '}',
-        'function fx-arrhas($n) {',
-        '  $n = [string]$n',
-        '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -split [string][char]10)) {',
-        '    $fx_eq = $fx_pair.IndexOf([char]61)',
-        '    if ($fx_eq -lt 1) { continue }',
-        '    if ($fx_pair.Substring(0, $fx_eq) -ceq $n) { return $true }',
-        '  }',
-        '  return $false',
-        '}',
-        'function fx-arrpackget($n) {',
-        '  $n = [string]$n',
-        '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -split [string][char]10)) {',
-        '    $fx_eq = $fx_pair.IndexOf([char]61)',
-        '    if ($fx_eq -lt 1) { continue }',
-        '    if ($fx_pair.Substring(0, $fx_eq) -ceq $n) { return $fx_pair.Substring($fx_eq + 1) }',
-        '  }',
-        '  return $null',
-        '}',
-        'function fx-arrpackset($n, $pay) {',
-        '  fx-arrdrop $n',
-        '  if ($null -eq $pay) { return }',
-        "  $env:FAUXNIX_ARRS = ((@($env:FAUXNIX_ARRS -split [string][char]10 | Where-Object { $_ -ne '' }) + ([string]$n + [string][char]61 + [string]$pay)) -join [string][char]10)",
-        '}',
-        'function fx-arrput($n, $vals) {',
-        '  $n = [string]$n',
-        '  $vals = @($vals)',
-        '  fx-arrdrop $n',
-        '  if ($vals.Count -eq 0) { } else {',
-        '    $encs = @(); foreach ($v in $vals) { $encs += (fx-svenc $v) }',
-        "    $env:FAUXNIX_ARRS = ((@($env:FAUXNIX_ARRS -split [string][char]10 | Where-Object { $_ -ne '' }) + ($n + [string][char]61 + ($encs -join [string][char]30))) -join [string][char]10)",
-        '  }',
-        "  $fx_0 = $(if ($vals.Count -gt 0) { [string]$vals[0] } else { '' })",
-        '  Set-Item -LiteralPath (\'Env:\\\' + $n) -Value $fx_0',
-        "  $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_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_0)); $env:FAUXNIX_SETVALS = ($fx_sv -join [string][char]10)",
-        '}',
-        'function fx-arrclr($n) {',
-        '  $n = [string]$n',
-        '  fx-arrdrop $n',
-        "  Remove-Item -LiteralPath ('Env:\\' + $n) -ErrorAction SilentlyContinue",
-        "  $env:FAUXNIX_SETVARS = (@($env:FAUXNIX_SETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) -join ';')",
-        "  $env:FAUXNIX_UNSETVARS = ((@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) + $n) -join ';')",
-        '  $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 } }; $env:FAUXNIX_SETVALS = ($fx_sv -join [string][char]10)',
-        '}',
-        'function fx-subget($n, $ix) {',
-        '  $arr = @(fx-arrload $n)',
-        '  $ix = [string]$ix',
-        // argv-level `@` is expanded by argListExpr; this is the scalar/quoted-* join.
-        "  if ($ix -eq '*') { return ($arr -join (fx-ifs1)) }",
-        "  if ($ix -eq '@') { return ($arr -join (fx-ifs1)) }",
-        '  $i = 0',
-        '  if (-not [int]::TryParse($ix, [ref]$i)) { return \'\' }',
-        "  if ($i -lt 0 -or $i -ge $arr.Count) { return '' }",
-        '  return [string]$arr[$i]',
-        '}',
-        'try {',
-        ...body.split('\n').map((l) => '  ' + l),
-        '} catch [System.Management.Automation.CommandNotFoundException] {',
-        "  [Console]::Error.WriteLine('bash: ' + $_.Exception.TargetName + ': command not found')",
-        '  $script:fx_exit = 127',
-        '} catch {',
-        '  [Console]::Error.WriteLine(($_.Exception.Message).Split("`n")[0])',
-        '  $script:fx_exit = 1',
-        '}',
-        '# persist session cwd and environment for the next segment',
-        'try { [IO.File]::WriteAllText($env:FAUXNIX_CWD_FILE, (Get-Location).Path) } catch {}',
-        'if ((Get-Location).Path -ne $fx_oldcwd) { $env:FAUXNIX_OLDPWD = $fx_oldcwd }',
-        'try {',
-        '  $envObj = @{}',
-        '  Get-ChildItem Env: | ForEach-Object { $envObj[$_.Name] = $_.Value }',
-        '  [IO.File]::WriteAllText($env:FAUXNIX_ENV_FILE, (ConvertTo-Json $envObj -Compress))',
-        '} catch {}',
-        'exit $script:fx_exit',
     ];
+    const helpers = {
+        'fx-readlines': [
+            'function fx-readlines($p) {',
+            '  $b = [IO.File]::ReadAllBytes($p)',
+            '  $t = $null',
+            '  try { $t = (New-Object System.Text.UTF8Encoding($false, $true)).GetString($b) } catch {}',
+            "  if ($null -eq $t) { try { $t = [System.Text.Encoding]::GetEncoding(936).GetString($b) } catch { $t = [System.Text.Encoding]::ASCII.GetString($b) } }",
+            '  $t = $t -replace "`r`n", "`n"',
+            '  $t = $t -replace "`r", "`n"',
+            '  $parts = @($t.Split("`n"))',
+            "  if ($parts.Count -eq 1 -and $parts[0] -eq '') { return @() }",
+            "  if ($parts[$parts.Count - 1] -eq '') { $parts = $parts[0..($parts.Count - 2)] }",
+            '  return $parts',
+            '}',
+        ],
+        'fx-csub': [
+            'function fx-csub([scriptblock]$b) {',
+            '  $fx_prevcs = $script:fx_csub',
+            '  $script:fx_csub = $true',
+            '  try { $fx_o = @(& $b | ForEach-Object { [string]$_ }) }',
+            '  finally { $script:fx_csub = $fx_prevcs }',
+            '  $fx_s = ($fx_o -join [string][char]10)',
+            '  while ($fx_s.Length -gt 0 -and $fx_s[$fx_s.Length - 1] -eq [char]10) {',
+            '    $fx_s = $fx_s.Substring(0, $fx_s.Length - 1)',
+            '  }',
+            '  return $fx_s',
+            '}',
+        ],
+        'fx-svenc': [
+            'function fx-svenc($s) {',
+            '  return ([string]$s).Replace([string][char]92, ([string][char]92 + [string][char]92)).Replace([string][char]13, ([string][char]92 + [char]114)).Replace([string][char]10, ([string][char]92 + [char]110))',
+            '}',
+        ],
+        'fx-svdec': [
+            'function fx-svdec($s) {',
+            '  $s = [string]$s',
+            '  $sb = New-Object System.Text.StringBuilder',
+            '  $i = 0',
+            '  while ($i -lt $s.Length) {',
+            '    $c = $s[$i]',
+            '    if ($c -eq [char]92 -and ($i + 1) -lt $s.Length) {',
+            '      $n2 = $s[$i + 1]',
+            '      if ($n2 -eq [char]110) { [void]$sb.Append([char]10); $i += 2; continue }',
+            '      if ($n2 -eq [char]114) { [void]$sb.Append([char]13); $i += 2; continue }',
+            '      if ($n2 -eq [char]92) { [void]$sb.Append([char]92); $i += 2; continue }',
+            '    }',
+            '    [void]$sb.Append($c)',
+            '    $i++',
+            '  }',
+            '  return [string]$sb',
+            '}',
+        ],
+        'fx-arrload': [
+            'function fx-arrload($n) {',
+            '  $n = [string]$n',
+            '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -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) { continue }',
+            '    $out = @()',
+            '    foreach ($el in @($fx_pair.Substring($fx_eq + 1) -split [string][char]30)) { $out += ,(fx-svdec $el) }',
+            '    return $out',
+            '  }',
+            '  $s0 = fx-scalar0 $n',
+            '  if ($null -eq $s0) { return @() }',
+            '  return @([string]$s0)',
+            '}',
+        ],
+        'fx-scalar0': [
+            'function fx-scalar0($n) {',
+            '  $n = [string]$n',
+            "  if (@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ceq $n }).Count -gt 0) { return $null }",
+            '  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) -ceq $n) { return (fx-svdec $fx_pair.Substring($fx_eq + 1)) }',
+            '  }',
+            "  if ($n -ceq 'HOME') { return [string]$HOME }",
+            "  if ($n -ceq 'PWD') { return [string]$PWD.Path }",
+            "  if ($n -ceq 'USER' -or $n -ceq 'LOGNAME') { return [string]$env:USERNAME }",
+            "  if ($n -ceq 'PATH') { return [string]$env:PATH }",
+            "  if ($n -ceq 'SHELL') { return 'powershell' }",
+            "  if ($n -ceq 'TERM') { return 'xterm-256color' }",
+            "  if ($n -ceq 'OLDPWD') { return $(if ($env:FAUXNIX_OLDPWD) { [string]$env:FAUXNIX_OLDPWD } else { $null }) }",
+            "  if ($n -ceq 'HOSTNAME') { return [string]$env:COMPUTERNAME }",
+            '  $ev = Get-ChildItem Env: | Where-Object { $_.Name -ceq $n } | Select-Object -First 1',
+            '  if ($ev) { return [string]$ev.Value }',
+            '  return $null',
+            '}',
+        ],
+        'fx-ifs1': [
+            'function fx-ifs1 {',
+            "  $s = fx-scalar0 'IFS'",
+            "  if ($null -eq $s) { return ' ' }",
+            "  if ([string]$s -eq '') { return '' }",
+            '  return [string]$s[0]',
+            '}',
+        ],
+        'fx-arrdrop': [
+            'function fx-arrdrop($n) {',
+            '  $n = [string]$n',
+            '  $fx_sm = @()',
+            '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -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_sm += $fx_pair }',
+            '  }',
+            '  $env:FAUXNIX_ARRS = ($fx_sm -join [string][char]10)',
+            '}',
+        ],
+        'fx-arrhas': [
+            'function fx-arrhas($n) {',
+            '  $n = [string]$n',
+            '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -split [string][char]10)) {',
+            '    $fx_eq = $fx_pair.IndexOf([char]61)',
+            '    if ($fx_eq -lt 1) { continue }',
+            '    if ($fx_pair.Substring(0, $fx_eq) -ceq $n) { return $true }',
+            '  }',
+            '  return $false',
+            '}',
+        ],
+        'fx-arrpackget': [
+            'function fx-arrpackget($n) {',
+            '  $n = [string]$n',
+            '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -split [string][char]10)) {',
+            '    $fx_eq = $fx_pair.IndexOf([char]61)',
+            '    if ($fx_eq -lt 1) { continue }',
+            '    if ($fx_pair.Substring(0, $fx_eq) -ceq $n) { return $fx_pair.Substring($fx_eq + 1) }',
+            '  }',
+            '  return $null',
+            '}',
+        ],
+        'fx-arrpackset': [
+            'function fx-arrpackset($n, $pay) {',
+            '  fx-arrdrop $n',
+            '  if ($null -eq $pay) { return }',
+            "  $env:FAUXNIX_ARRS = ((@($env:FAUXNIX_ARRS -split [string][char]10 | Where-Object { $_ -ne '' }) + ([string]$n + [string][char]61 + [string]$pay)) -join [string][char]10)",
+            '}',
+        ],
+        'fx-arrput': [
+            'function fx-arrput($n, $vals) {',
+            '  $n = [string]$n',
+            '  $vals = @($vals)',
+            '  fx-arrdrop $n',
+            '  if ($vals.Count -eq 0) { } else {',
+            '    $encs = @(); foreach ($v in $vals) { $encs += (fx-svenc $v) }',
+            "    $env:FAUXNIX_ARRS = ((@($env:FAUXNIX_ARRS -split [string][char]10 | Where-Object { $_ -ne '' }) + ($n + [string][char]61 + ($encs -join [string][char]30))) -join [string][char]10)",
+            '  }',
+            "  $fx_0 = $(if ($vals.Count -gt 0) { [string]$vals[0] } else { '' })",
+            '  Set-Item -LiteralPath (\'Env:\\\' + $n) -Value $fx_0',
+            "  $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_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_0)); $env:FAUXNIX_SETVALS = ($fx_sv -join [string][char]10)",
+            '}',
+        ],
+        'fx-arrclr': [
+            'function fx-arrclr($n) {',
+            '  $n = [string]$n',
+            '  fx-arrdrop $n',
+            "  Remove-Item -LiteralPath ('Env:\\' + $n) -ErrorAction SilentlyContinue",
+            "  $env:FAUXNIX_SETVARS = (@($env:FAUXNIX_SETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) -join ';')",
+            "  $env:FAUXNIX_UNSETVARS = ((@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) + $n) -join ';')",
+            '  $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 } }; $env:FAUXNIX_SETVALS = ($fx_sv -join [string][char]10)',
+            '}',
+        ],
+        'fx-subget': [
+            'function fx-subget($n, $ix) {',
+            '  $arr = @(fx-arrload $n)',
+            '  $ix = [string]$ix',
+            // argv-level `@` is expanded by argListExpr; this is the scalar/quoted-* join.
+            "  if ($ix -eq '*') { return ($arr -join (fx-ifs1)) }",
+            "  if ($ix -eq '@') { return ($arr -join (fx-ifs1)) }",
+            '  $i = 0',
+            '  if (-not [int]::TryParse($ix, [ref]$i)) { return \'\' }',
+            "  if ($i -lt 0 -or $i -ge $arr.Count) { return '' }",
+            '  return [string]$arr[$i]',
+            '}',
+        ],
+    };
+    for (const name of WRAP_HELPER_ORDER) {
+        if (needed.has(name))
+            lines.push(...helpers[name]);
+    }
+    lines.push('try {', ...body.split('\n').map((l) => '  ' + l), '} catch [System.Management.Automation.CommandNotFoundException] {', "  [Console]::Error.WriteLine('bash: ' + $_.Exception.TargetName + ': command not found')", '  $script:fx_exit = 127', '} catch {', '  [Console]::Error.WriteLine(($_.Exception.Message).Split("`n")[0])', '  $script:fx_exit = 1', '}', '# persist session cwd and environment for the next segment', 'try { [IO.File]::WriteAllText($env:FAUXNIX_CWD_FILE, (Get-Location).Path) } catch {}', 'if ((Get-Location).Path -ne $fx_oldcwd) { $env:FAUXNIX_OLDPWD = $fx_oldcwd }', 'try {', '  $envObj = @{}', '  Get-ChildItem Env: | ForEach-Object { $envObj[$_.Name] = $_.Value }', '  [IO.File]::WriteAllText($env:FAUXNIX_ENV_FILE, (ConvertTo-Json $envObj -Compress))', '} catch {}', 'exit $script:fx_exit');
     return lines.join('\n');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fauxnix-cli",
-  "version": "0.4.2",
+  "version": "0.5.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": {