fauxnix-cli 0.9.3 → 0.12.0

package/dist/translator.js

@@ -1,7 +1,181 @@
-import { FauxnixParseError, isUnquotedLiteral, } from './ast.js';
+import { FauxnixParseError, isUnquotedLiteral, wordToString, } from './ast.js';
 import { parseCommand } from './parser.js';
 import { lookup, psStr } from './registry.js';
 import { PYTHON3_WINDOWS_HINT, SH_SCRIPT_WINDOWS_HINT } from './errors.js';
+export const EXECUTE_TRANSLATION = Object.freeze({ mode: 'execute' });
+export const PURE_TRANSLATION = Object.freeze({ mode: 'pure' });
+export const PURE_SED_FILE_MESSAGE = 'fauxnix: translate does not read sed script files; use -e with the script text, or run the command to use -f';
+/** Match the sed option rules without opening the referenced script file. */
+function sedUsesScriptFile(args) {
+    const raw = args.map((word) => wordToString(word));
+    let onlyOperands = false;
+    for (let i = 0; i < raw.length; i++) {
+        const arg = raw[i];
+        if (!onlyOperands && arg === '--') {
+            onlyOperands = true;
+            continue;
+        }
+        if (onlyOperands || !arg.startsWith('-') || arg.length === 1 || arg.startsWith('--')) {
+            continue;
+        }
+        const body = arg.slice(1);
+        for (let c = 0; c < body.length; c++) {
+            const flag = body[c];
+            if (flag === 'f')
+                return c < body.length - 1 || i + 1 < raw.length;
+            if (flag === 'e') {
+                if (c === body.length - 1)
+                    i++;
+                break;
+            }
+            if (flag === 'i')
+                break;
+            if (!['n', 'E', 'r', 's', 'u', 'z'].includes(flag))
+                return false;
+        }
+    }
+    return false;
+}
+function assertPureWord(word) {
+    const visitPart = (part) => {
+        if (part.kind === 'CmdSub') {
+            assertPureCommandList(parseCommand(part.cmd));
+        }
+        else if (part.kind === 'DoubleQuoted' || part.kind === 'Arith') {
+            for (const nested of part.parts)
+                visitPart(nested);
+        }
+    };
+    for (const part of word)
+        visitPart(part);
+}
+function wrappedSimpleCommand(command, name) {
+    const raw = command.args.map((word) => wordToString(word));
+    let commandIndex = -1;
+    if (name === 'env') {
+        for (let i = 0; i < raw.length;) {
+            const arg = raw[i];
+            if (arg === '--') {
+                commandIndex = i + 1;
+                break;
+            }
+            if (arg === '-i' || arg === '--ignore-environment')
+                return null;
+            if (arg === '-u' || arg === '--unset') {
+                i += 2;
+                continue;
+            }
+            if (arg.startsWith('-u=') || arg.startsWith('--unset=')) {
+                i++;
+                continue;
+            }
+            if (arg.startsWith('-')) {
+                i++;
+                continue;
+            }
+            if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(arg)) {
+                i++;
+                continue;
+            }
+            commandIndex = i;
+            break;
+        }
+    }
+    else if (name === 'command') {
+        let identify = false;
+        let i = 0;
+        while (i < raw.length) {
+            const arg = raw[i];
+            if (arg === '-v' || arg === '-V') {
+                identify = true;
+                i++;
+                continue;
+            }
+            if (arg === '--') {
+                i++;
+                break;
+            }
+            if (arg.startsWith('-')) {
+                i++;
+                continue;
+            }
+            break;
+        }
+        if (identify)
+            return null;
+        commandIndex = i;
+    }
+    else if (name === 'timeout') {
+        let i = 0;
+        while (i < raw.length && raw[i].startsWith('-') && raw[i] !== '-' && raw[i] !== '--')
+            i++;
+        if (i < raw.length && raw[i] === '--')
+            i++;
+        commandIndex = i + 1;
+    }
+    if (commandIndex < 0 || commandIndex >= command.args.length)
+        return null;
+    return {
+        kind: 'SimpleCommand',
+        assignments: [],
+        name: command.args[commandIndex],
+        args: command.args.slice(commandIndex + 1),
+        redirects: [],
+    };
+}
+function assertPureShellCommand(command) {
+    if (command.kind === 'SimpleCommand') {
+        const name = command.name === null ? null : literalOfWord(command.name);
+        if (name === 'sed' && sedUsesScriptFile(command.args)) {
+            throw new FauxnixParseError(PURE_SED_FILE_MESSAGE);
+        }
+        if (command.name)
+            assertPureWord(command.name);
+        for (const arg of command.args)
+            assertPureWord(arg);
+        for (const assignment of command.assignments) {
+            assertPureWord(assignment.value);
+            for (const value of assignment.values ?? [])
+                assertPureWord(value);
+        }
+        if (name === 'env' || name === 'command' || name === 'timeout') {
+            const nested = wrappedSimpleCommand(command, name);
+            if (nested)
+                assertPureShellCommand(nested);
+        }
+        return;
+    }
+    if (command.kind === 'If') {
+        assertPureCommandList(command.test);
+        assertPureCommandList(command.then);
+        if (command.else)
+            assertPureCommandList(command.else);
+        return;
+    }
+    if (command.kind === 'For') {
+        for (const word of command.words)
+            assertPureWord(word);
+        assertPureCommandList(command.body);
+        return;
+    }
+    if (command.kind === 'While') {
+        assertPureCommandList(command.test);
+        assertPureCommandList(command.body);
+        return;
+    }
+    assertPureWord(command.word);
+    for (const arm of command.arms) {
+        for (const pattern of arm.patterns)
+            assertPureWord(pattern);
+        assertPureCommandList(arm.body);
+    }
+}
+function assertPureCommandList(list) {
+    for (const segment of list.segments) {
+        for (const command of segment.pipeline.commands)
+            assertPureShellCommand(command);
+    }
+}
 /* ------------------------------------------------------------------ */
 /* Variable mapping                                                    */
 /* ------------------------------------------------------------------ */
@@ -39,8 +213,43 @@ export function paramExpr(name, op, word) {
         psStr('bash: ' + msg) +
         '); $script:fx_exit = 1; \'\' } else { $fx_pv } )');
 }
+function sliceArgExpr(s) {
+    if (s.length > 0 && s[0] === '$') {
+        return '(fx-scalar0 ' + psStr(s.slice(1)) + ')';
+    }
+    return psStr(s);
+}
+export function varExtraOf(p) {
+    if (p.kind !== 'Var')
+        return undefined;
+    if (!p.replace && !p.slice)
+        return undefined;
+    const extra = {};
+    if (p.replace)
+        extra.replace = p.replace;
+    if (p.slice)
+        extra.slice = p.slice;
+    return extra;
+}
 /** Map a bash $VAR name to a PowerShell expression (usable inside $(...)). */
-export function varExpr(name, index, param, length = false) {
+export function varExpr(name, index, param, length = false, extra) {
+    if (extra && extra.replace) {
+        const r = extra.replace;
+        return ('(fx-subst (fx-scalar0 ' +
+            psStr(name) +
+            ') ' +
+            psStr(r.pat) +
+            ' ' +
+            psStr(r.repl) +
+            ' ' +
+            (r.global ? '$true' : '$false') +
+            ')');
+    }
+    if (extra && extra.slice) {
+        const off = sliceArgExpr(extra.slice.offset);
+        const len = extra.slice.length !== undefined ? sliceArgExpr(extra.slice.length) : '$null';
+        return '(fx-slice (fx-scalar0 ' + psStr(name) + ') ' + off + ' ' + len + ')';
+    }
     if (param)
         return paramExpr(name, param.op, param.word);
     if (length) {
@@ -60,6 +269,12 @@ export function varExpr(name, index, param, length = false) {
     if (index !== undefined) {
         return '(fx-subget ' + psStr(name) + ' ' + psStr(index) + ')';
     }
+    if (/^[0-9]+$/.test(name)) {
+        if (name === '0') {
+            return "$(if ($env:FAUXNIX_ARG0) { [string]$env:FAUXNIX_ARG0 } else { 'fauxnix' })";
+        }
+        return '(fx-posget ' + name + ')';
+    }
     switch (name) {
         case 'HOME':
             return '$HOME';
@@ -82,10 +297,24 @@ export function varExpr(name, index, param, length = false) {
             return '[string]$PID';
         case 'HOSTNAME':
             return '$env:COMPUTERNAME';
+        case '#':
+            return '@(fx-posload).Count';
+        case '@':
+        case '*':
+            return '((@(fx-posload) -join (fx-ifs1)))';
         default:
             return '$env:' + name;
     }
 }
+/** `$?` `$$` `$0`–`$n` `$#` `$@` `$*` — not ordinary `$env:` names. */
+export function isSpecialShellVar(name) {
+    return (name === '?' ||
+        name === '$' ||
+        name === '#' ||
+        name === '@' ||
+        name === '*' ||
+        /^[0-9]+$/.test(name));
+}
 /* ------------------------------------------------------------------ */
 /* Word → PowerShell expression                                        */
 /* ------------------------------------------------------------------ */
@@ -155,7 +384,7 @@ export function exprOfWord(w, opts) {
     // single bare variable → bare expression
     if (expanded.length === 1 && expanded[0].kind === 'Var') {
         const v = expanded[0];
-        return varExpr(v.name, v.index, v.param, v.length === true);
+        return varExpr(v.name, v.index, v.param, v.length === true, varExtraOf(v));
     }
     // Bare `$(...)` must not sit inside a PS expandable string: the
     // substitution body contains `"` / `$_` that would break interpolation.
@@ -185,7 +414,7 @@ export function exprOfWord(w, opts) {
                     emitPart(q, true);
                 break;
             case 'Var':
-                out += '$(' + varExpr(p.name, p.index, p.param, p.length === true) + ')';
+                out += '$(' + varExpr(p.name, p.index, p.param, p.length === true, varExtraOf(p)) + ')';
                 break;
             case 'CmdSub':
                 out += '$(' + translateCmdSub(p.cmd, quoted || opts?.preserveCmdSub === true) + ')';
@@ -241,7 +470,7 @@ function arithSourceExpr(parts) {
                     emit(q);
                 break;
             case 'Var':
-                out += '$(' + varExpr(p.name, p.index, p.param, p.length === true) + ')';
+                out += '$(' + varExpr(p.name, p.index, p.param, p.length === true, varExtraOf(p)) + ')';
                 break;
             case 'CmdSub':
                 out += '$(' + translateCmdSub(p.cmd, true) + ')';
@@ -292,6 +521,7 @@ function wordPartsForSplat(w) {
 /**
  * `${name[@]}` / `"pre${name[@]}post"` — one argv per element.
  * Unquoted `${name[*]}` also splats (bash); quoted `"${name[*]}"` stays one join.
+ * `$@` / unquoted `$*` splat like `${arr[@]}`; quoted `"$@"` still splats.
  */
 export function splatSpec(w) {
     const parts = wordPartsForSplat(w);
@@ -302,7 +532,10 @@ export function splatSpec(w) {
     for (const { part: p, quoted } of parts) {
         const splat = p.kind === 'Var' &&
             !p.length &&
-            (p.index === '@' || (p.index === '*' && !quoted));
+            (p.name === '@' ||
+                (p.name === '*' && !quoted) ||
+                p.index === '@' ||
+                (p.index === '*' && !quoted));
         if (splat) {
             if (seen)
                 return null;
@@ -319,6 +552,12 @@ export function splatSpec(w) {
     }
     return name ? { name, prefix, suffix } : null;
 }
+/** Load the splat source: positionals (`@`/`*`) vs named arrays. */
+function splatLoadCall(name) {
+    if (name === '@' || name === '*')
+        return 'fx-posload';
+    return 'fx-arrload ' + psStr(name);
+}
 /** PS expression of a string[]: `@` words splat, others stay one element. */
 export function argListExpr(words, fn = exprOfWord) {
     if (words.length === 0)
@@ -330,9 +569,9 @@ export function argListExpr(words, fn = exprOfWord) {
             if (!s)
                 return '@(' + fn(w) + ')';
             if (!s.prefix && !s.suffix)
-                return '@(fx-arrload ' + psStr(s.name) + ')';
-            return ('@($( $fx_sp = @(fx-arrload ' +
-                psStr(s.name) +
+                return '@(' + splatLoadCall(s.name) + ')';
+            return ('@($( $fx_sp = @(' +
+                splatLoadCall(s.name) +
                 '); if ($fx_sp.Count -eq 0) { $fx_sp = @(' +
                 psStr(s.prefix + s.suffix) +
                 ') } else { $fx_sp[0] = ' +
@@ -353,14 +592,11 @@ export function argListExpr(words, fn = exprOfWord) {
  * Unquoted command words join non-empty lines with a space (IFS
  * word-split approximation). Handlers often emit one string object, so
  * a bare `$(…)` interpolation would keep those newlines.
+ * Lists (`;` `&&` `||`) reuse translateListInline inside the fx-csub
+ * scriptblock so the newline contract is unchanged.
  */
-export function translateCmdSub(cmdText, keepNl = false) {
-    const list = parseCommand(cmdText);
-    if (list.segments.length !== 1) {
-        throw new FauxnixParseError('fauxnix: command substitution with ; && || is not supported yet');
-    }
-    const { defs, call } = translatePipelineBody(list.segments[0].pipeline);
-    const inner = defs ? defs + '\n' + call : call;
+export function translateCmdSub(cmdText, keepNl = false, translation = EXECUTE_TRANSLATION) {
+    const inner = translateListInline(parseCommand(cmdText), translation);
     const collected = '(fx-csub { ' + inner + ' })';
     if (keepNl)
         return collected;
@@ -377,18 +613,32 @@ function indentBlock(s) {
         .map((l) => (l ? '  ' + l : l))
         .join('\n');
 }
-export function translateSimple(cmd, position, hasStdin) {
+export function translateSimple(cmd, position, hasStdin, translation = EXECUTE_TRANSLATION) {
+    const nativeTerm = "(-not $script:fx_csub -and (($MyInvocation.MyCommand.Name -eq '') -or " +
+        (position === 'last' ? '$true' : '$false') +
+        '))';
     // assignment-only segment (`X=1; cmd`): bash semantics are "set for the
     // rest of the shell". Reuse the export code path — persist + env shadow —
     // so empty values (`X=`) and `[[ -v X ]]` behave like bash (documented
     // deviation: shell var vs exported var are indistinguishable here).
     if (cmd.name === null) {
         const exportHandler = lookup('export');
-        const words = cmd.assignments.map((a) => [
-            { kind: 'Text', text: a.name + '=' },
-            ...a.value,
-        ]);
-        return exportHandler ? exportHandler(words, { position, hasStdin }) : '';
+        const chunks = [];
+        for (const a of cmd.assignments) {
+            if (a.values) {
+                chunks.push('fx-arrput ' +
+                    psStr(a.name) +
+                    ' ' +
+                    argListExpr(a.values, (w) => exprOfWord(w, { preserveCmdSub: true })));
+            }
+            else {
+                const words = [[{ kind: 'Text', text: a.name + '=' }, ...a.value]];
+                if (exportHandler) {
+                    chunks.push(exportHandler(words, { position, hasStdin, translationMode: translation.mode }));
+                }
+            }
+        }
+        return chunks.join('\n');
     }
     const nameLit = literalOfWord(cmd.name);
     const nameSplat = splatSpec(cmd.name);
@@ -403,9 +653,9 @@ export function translateSimple(cmd, position, hasStdin) {
                 name: cmd.args[0],
                 args: cmd.args.slice(1),
                 redirects: cmd.redirects,
-            }, position, hasStdin);
+            }, position, hasStdin, translation);
         const emptyCmdLines = [
-            '$fx_cw = @(fx-arrload ' + psStr(nameSplat.name) + ')',
+            '$fx_cw = @(' + splatLoadCall(nameSplat.name) + ')',
         ];
         if (hasAffix) {
             emptyCmdLines.push('if ($fx_cw.Count -eq 0) { $fx_cw = @(' +
@@ -419,20 +669,23 @@ export function translateSimple(cmd, position, hasStdin) {
         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 = [object[]](@($fx_cw[1..($fx_cw.Count - 1)]) + $fx_na) }', '  ' + (hasStdin ? '($input | fx-native $fx_cmd $fx_na)' : 'fx-native $fx_cmd $fx_na'), '}');
+        promoted ? indentBlock(promoted) : '  ', '} else {', '  $fx_na = [object[]](' + argListExpr(cmd.args) + ')', '  $fx_cmd = [string]$fx_cw[0]', '  if ($fx_cw.Count -gt 1) { $fx_na = [object[]](@($fx_cw[1..($fx_cw.Count - 1)]) + $fx_na) }', '  ' +
+            (hasStdin
+                ? '($input | fx-native $fx_cmd $fx_na ' + nativeTerm + ')'
+                : 'fx-native $fx_cmd $fx_na ' + nativeTerm), '}');
         body = emptyCmdLines.join('\n');
     }
     else if (nameLit !== null) {
         const handler = lookup(nameLit);
         if (handler && !(nameLit === '[[' && !isUnquotedLiteral(cmd.name, '[['))) {
-            body = handler(cmd.args, { position, hasStdin });
+            body = handler(cmd.args, { position, hasStdin, translationMode: translation.mode });
         }
         else {
             // passthrough: native command (git, node, npm, python, cargo, ...)
             // via fx-native (Win32 command line + Process). `& name @array` on
             // PS 5.1 drops empty argv entries and eats embedded quotes.
             const nameExpr = psStr(nameLit);
-            const invoke = 'fx-native ' + nameExpr + ' $fx_na';
+            const invoke = 'fx-native ' + nameExpr + ' $fx_na ' + nativeTerm;
             body = [
                 '$fx_na = [object[]](' + argListExpr(cmd.args) + ')',
                 (hasStdin ? '($input | ' + invoke + ')' : invoke),
@@ -442,7 +695,7 @@ export function translateSimple(cmd, position, hasStdin) {
     else {
         // dynamic command name — evaluate it
         const nameExpr = exprOfWord(cmd.name);
-        const invoke = 'fx-native (' + nameExpr + ') $fx_na';
+        const invoke = 'fx-native (' + nameExpr + ') $fx_na ' + nativeTerm;
         body = [
             '$fx_na = [object[]](' + argListExpr(cmd.args) + ')',
             (hasStdin ? '($input | ' + invoke + ')' : invoke),
@@ -547,10 +800,20 @@ export function wrapTempEnv(sets, body, extra) {
         lines.push(arrSave + '[' + psStr(n) + '] = (fx-arrpackget ' + psStr(n) + ')');
     }
     const valVars = [];
+    const valIsArr = [];
     for (let i = 0; i < sets.length; i++) {
         const vn = '$fx_ev' + id + '_' + i;
         valVars.push(vn);
-        lines.push(vn + ' = ' + exprOfWord(sets[i].value, { preserveCmdSub: true }));
+        if (sets[i].values) {
+            valIsArr.push(true);
+            lines.push(vn +
+                ' = ' +
+                argListExpr(sets[i].values, (w) => exprOfWord(w, { preserveCmdSub: true })));
+        }
+        else {
+            valIsArr.push(false);
+            lines.push(vn + ' = ' + exprOfWord(sets[i].value, { preserveCmdSub: true }));
+        }
     }
     lines.push('try {');
     for (const u of unsets) {
@@ -576,6 +839,10 @@ export function wrapTempEnv(sets, body, extra) {
     for (let i = 0; i < sets.length; i++) {
         const n = sets[i].name;
         const nq = n.replace(/'/g, "''");
+        if (valIsArr[i]) {
+            lines.push('  fx-arrput ' + psStr(n) + ' ' + valVars[i]);
+            continue;
+        }
         lines.push('  $env:' + n + ' = ' + valVars[i]);
         lines.push('  fx-arrdrop ' + psStr(n));
         lines.push("  $env:FAUXNIX_SETVARS = ((@($env:FAUXNIX_SETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne '" +
@@ -721,10 +988,10 @@ let pipelineSeq = 0;
  * multi-command pipelines become generated functions chained with `|`
  * (PS 5.1 forbids parenthesized expressions as non-first pipeline elements).
  */
-function translateListInline(list) {
+function translateListInline(list, translation = EXECUTE_TRANSLATION) {
     const chunks = [];
     for (const seg of list.segments) {
-        const { defs, call } = translatePipelineBody(seg.pipeline);
+        const { defs, call } = translatePipelineBody(seg.pipeline, translation);
         const body = (defs ? defs + '\n' : '') + call;
         if (seg.op === '&&') {
             chunks.push('if ($script:fx_exit -eq 0) {\n' + body + '\n}');
@@ -738,22 +1005,38 @@ function translateListInline(list) {
     }
     return chunks.join('\n');
 }
-function translateIf(cmd) {
+function translateIf(cmd, translation) {
     // 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'))
+    const lines = [translateListInline(cmd.test, translation), 'if ($script:fx_exit -eq 0) {', '  $script:fx_exit = 0'];
+    for (const l of translateListInline(cmd.then, translation).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'))
+        for (const l of translateListInline(cmd.else, translation).split('\n'))
             lines.push(l ? '  ' + l : l);
     }
     lines.push('}');
     return lines.join('\n');
 }
-function translateFor(cmd) {
+function translateCase(cmd, translation) {
+    const lines = ['$script:fx_exit = 0', '$fx_cw = ' + exprOfWord(cmd.word)];
+    for (let i = 0; i < cmd.arms.length; i++) {
+        const arm = cmd.arms[i];
+        const pats = arm.patterns.map((w) => exprOfWord(w)).join(',');
+        const head = i === 0 ? 'if' : 'elseif';
+        lines.push(head + ' (fx-casematch $fx_cw @(' + pats + ')) {');
+        const body = translateListInline(arm.body, translation);
+        if (body) {
+            for (const l of body.split('\n'))
+                lines.push(l ? '  ' + l : l);
+        }
+        lines.push('}');
+    }
+    return lines.join('\n');
+}
+function translateFor(cmd, translation) {
     const n = cmd.name.replace(/'/g, "''");
     const lines = [
         '$fx_for = ' + argListExpr(cmd.words),
@@ -775,11 +1058,27 @@ function translateFor(cmd) {
             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'))
+    for (const l of translateListInline(cmd.body, translation).split('\n'))
         lines.push(l ? '  ' + l : l);
     lines.push('}');
     return lines.join('\n');
 }
+function translateWhile(cmd, translation) {
+    // Bash: last executed body owns status; a test that ends the loop does not.
+    // Never-entered loops (`while false; do …; done`, `until true; do …; done`)
+    // exit 0. Save the body status and restore it on the failing test.
+    const fail = cmd.until ? '$script:fx_exit -eq 0' : '$script:fx_exit -ne 0';
+    const lines = ['$fx_wst = 0', 'do {'];
+    for (const l of translateListInline(cmd.test, translation).split('\n'))
+        lines.push(l ? '  ' + l : l);
+    lines.push('  if (' + fail + ') { $script:fx_exit = $fx_wst; break }');
+    lines.push('  $script:fx_exit = 0');
+    for (const l of translateListInline(cmd.body, translation).split('\n'))
+        lines.push(l ? '  ' + l : l);
+    lines.push('  $fx_wst = $script:fx_exit');
+    lines.push('} while ($true)');
+    return lines.join('\n');
+}
 function stdinTarget(c) {
     let t = null;
     for (const r of c.redirects) {
@@ -794,7 +1093,46 @@ function stdinReadExpr(target) {
         return '@()';
     return '@(fx-readlines ' + pathExpr(n) + ')';
 }
-export function translatePipelineBody(p) {
+/** `>` `>>` `&>` `&>>` — Node last-stage apply cannot honor these on earlier stages. */
+function isStdoutFileRedirect(op) {
+    return op === '>' || op === '>>' || op === '&>' || op === '&>>';
+}
+const NONLAST_STDOUT_REDIRECT_MSG = 'fauxnix: stdout redirect on a non-last pipeline stage is not supported yet; write the file in a previous list segment (cmd >f; cat f) or wait for per-stage fds (#157)';
+const NONLAST_STDERR_FILE_REDIRECT_MSG = 'fauxnix: stderr redirect ({op}) on a non-last pipeline stage is not supported yet; spool the stage first (cmd >out {op}err; cat out | next) or wait for per-stage fds (#157)';
+function nonLastFdRedirectMessage(op) {
+    if (isStdoutFileRedirect(op))
+        return NONLAST_STDOUT_REDIRECT_MSG;
+    if (op === '2>' || op === '2>>') {
+        return NONLAST_STDERR_FILE_REDIRECT_MSG.replaceAll('{op}', op);
+    }
+    if (op === '2>&1') {
+        return 'fauxnix: 2>&1 on a non-last pipeline stage is not supported yet; spool the merged output first (cmd >out 2>&1; cat out | next) or wait for per-stage fds (#157)';
+    }
+    if (op === '1>&2') {
+        return 'fauxnix: 1>&2 on a non-last pipeline stage is not supported yet; run the stage separately (cmd 1>&2; next </dev/null) or wait for per-stage fds (#157)';
+    }
+    return null;
+}
+function rejectNonLastFdRedirects(commands) {
+    if (commands.length < 2)
+        return;
+    for (let i = 0; i < commands.length - 1; i++) {
+        for (const redirect of commands[i].redirects) {
+            const message = nonLastFdRedirectMessage(redirect.op);
+            if (message)
+                throw new FauxnixParseError(message);
+        }
+    }
+}
+export function translatePipelineBody(p, translation = EXECUTE_TRANSLATION) {
+    if (translation.mode === 'pure') {
+        for (const command of p.commands)
+            assertPureShellCommand(command);
+    }
+    // Last-stage output fds are applied by Node. On an earlier stage they would
+    // be prepared but not owned by that stage, so output would still reach the
+    // wrong destination. Fail loud until routed in-stage fds land (#157).
+    rejectNonLastFdRedirects(p.commands);
     // Every pipeline stage needs its own status slot. Handlers deliberately use
     // `$script:fx_exit` because their helper functions run in child scopes; in a
     // pipeline that shared flag lets an earlier failure leak into a successful
@@ -807,11 +1145,15 @@ export function translatePipelineBody(p) {
         const hasStdin = i > 0 || c.redirects.some((r) => r.op === '<');
         const position = i === 0 ? 'first' : i === p.commands.length - 1 ? 'last' : 'middle';
         if (c.kind === 'If')
-            bodies.push(translateIf(c));
+            bodies.push(translateIf(c, translation));
         else if (c.kind === 'For')
-            bodies.push(translateFor(c));
+            bodies.push(translateFor(c, translation));
+        else if (c.kind === 'While')
+            bodies.push(translateWhile(c, translation));
+        else if (c.kind === 'Case')
+            bodies.push(translateCase(c, translation));
         else
-            bodies.push(translateSimple(c, position, hasStdin));
+            bodies.push(translateSimple(c, position, hasStdin, translation));
     }
     if (bodies.length === 1) {
         return { defs: '', call: '(& {\n' + bodies[0] + '\n})' };
@@ -870,7 +1212,7 @@ export function translatePipelineBody(p) {
     ].join('\n'));
     return { defs: defs.join('\n'), call: pipelineName };
 }
-export function translateCommandList(list) {
+export function translateCommandList(list, translation = EXECUTE_TRANSLATION) {
     const plans = [];
     for (const seg of list.segments) {
         const cmds = seg.pipeline.commands;
@@ -881,7 +1223,7 @@ export function translateCommandList(list) {
         const stdinRedirects = cmds.length
             ? cmds[0].redirects.filter((r) => r.op === '<')
             : [];
-        const { defs, call } = translatePipelineBody(seg.pipeline);
+        const { defs, call } = translatePipelineBody(seg.pipeline, translation);
         let body = defs ? defs + '\n' + call : call;
         // First-stage `< file` feeds stage zero via FAUXNIX_STDIN_FILE.
         // Later-stage `<` is owned inside the pipeline body, not this wrapper.
@@ -913,6 +1255,10 @@ const WRAP_HELPER_ORDER = [
     'fx-csub',
     'fx-svenc',
     'fx-svdec',
+    'fx-posload',
+    'fx-posset',
+    'fx-posget',
+    'fx-posshift',
     'fx-arrload',
     'fx-scalar0',
     'fx-ifs1',
@@ -923,7 +1269,11 @@ const WRAP_HELPER_ORDER = [
     'fx-arrput',
     'fx-arrclr',
     'fx-subget',
+    'fx-casematch',
+    'fx-subst',
+    'fx-slice',
     'fx-winargv',
+    'fx-cmdargv',
     'fx-native',
 ];
 const WRAP_HELPER_DEPS = {
@@ -931,6 +1281,10 @@ const WRAP_HELPER_DEPS = {
     'fx-csub': [],
     'fx-svenc': [],
     'fx-svdec': [],
+    'fx-posload': ['fx-svdec'],
+    'fx-posset': ['fx-svenc'],
+    'fx-posget': ['fx-posload'],
+    'fx-posshift': ['fx-posload', 'fx-posset'],
     'fx-arrload': ['fx-scalar0', 'fx-svdec'],
     'fx-scalar0': ['fx-svdec'],
     'fx-ifs1': ['fx-scalar0'],
@@ -941,8 +1295,12 @@ const WRAP_HELPER_DEPS = {
     'fx-arrput': ['fx-arrdrop', 'fx-svenc'],
     'fx-arrclr': ['fx-arrdrop'],
     'fx-subget': ['fx-arrload', 'fx-ifs1'],
+    'fx-casematch': [],
+    'fx-subst': [],
+    'fx-slice': [],
     'fx-winargv': [],
-    'fx-native': ['fx-winargv'],
+    'fx-cmdargv': ['fx-winargv'],
+    'fx-native': ['fx-cmdargv'],
 };
 /** Helpers the body calls that wrapScript still has to emit (not already defined there). */
 function wrapHelpersNeeded(body) {
@@ -1058,7 +1416,16 @@ export function wrapScript(body, opts = {}) {
             '  $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)',
+            // Line items (no trailing NL) get a NL between them. Chunks that
+            // already end in NL concatenate, so $(echo a; echo b) is a\nb.
+            "  $fx_s = ''",
+            '  foreach ($fx_x in $fx_o) {',
+            '    $fx_t = [string]$fx_x',
+            '    if ($fx_s.Length -gt 0 -and $fx_s[$fx_s.Length - 1] -ne [char]10) {',
+            '      $fx_s += [string][char]10',
+            '    }',
+            '    $fx_s += $fx_t',
+            '  }',
             '  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)',
             '  }',
@@ -1089,6 +1456,52 @@ export function wrapScript(body, opts = {}) {
             '  return [string]$sb',
             '}',
         ],
+        'fx-posload': [
+            'function fx-posload {',
+            '  if ($null -eq $env:FAUXNIX_POS -or [string]$env:FAUXNIX_POS -eq \'\') { return @() }',
+            '  $out = @()',
+            '  foreach ($el in @($env:FAUXNIX_POS -split [string][char]30)) { $out += ,(fx-svdec $el) }',
+            '  return $out',
+            '}',
+        ],
+        'fx-posset': [
+            'function fx-posset($vals) {',
+            '  if ($null -eq $vals) { $vals = @() }',
+            '  $vals = @($vals)',
+            '  if ($vals.Count -eq 0) { $env:FAUXNIX_POS = \'\'; return }',
+            '  $encs = @(); foreach ($v in $vals) { $encs += (fx-svenc $v) }',
+            '  $env:FAUXNIX_POS = ($encs -join [string][char]30)',
+            '}',
+        ],
+        'fx-posget': [
+            'function fx-posget($i) {',
+            '  $arr = @(fx-posload)',
+            '  $n = 0',
+            '  if (-not [int]::TryParse([string]$i, [ref]$n)) { return \'\' }',
+            '  if ($n -lt 1 -or $n -gt $arr.Count) { return \'\' }',
+            '  return [string]$arr[$n - 1]',
+            '}',
+        ],
+        'fx-posshift': [
+            'function fx-posshift($n) {',
+            '  $arr = @(fx-posload)',
+            '  $i = 1',
+            '  if ($null -ne $n -and [string]$n -ne \'\') {',
+            '    $parsed = 0',
+            '    if (-not [int]::TryParse([string]$n, [ref]$parsed)) {',
+            '      [Console]::Error.WriteLine(\'bash: shift: \' + [string]$n + \': numeric argument required\')',
+            '      $script:fx_exit = 1',
+            '      return',
+            '    }',
+            '    $i = $parsed',
+            '  }',
+            '  if ($i -lt 0 -or $i -gt $arr.Count) { $script:fx_exit = 1; return }',
+            '  if ($i -eq 0) { return }',
+            '  if ($i -eq $arr.Count) { fx-posset @(); return }',
+            '  $new = @($arr[$i..($arr.Count - 1)])',
+            '  fx-posset $new',
+            '}',
+        ],
         'fx-arrload': [
             'function fx-arrload($n) {',
             '  $n = [string]$n',
@@ -1096,8 +1509,10 @@ export function wrapScript(body, opts = {}) {
             '    $fx_eq = $fx_pair.IndexOf([char]61)',
             '    if ($fx_eq -lt 1) { continue }',
             '    if ($fx_pair.Substring(0, $fx_eq) -cne $n) { continue }',
+            '    $pay = $fx_pair.Substring($fx_eq + 1)',
+            '    if ($pay -eq [string][char]1) { return @() }',
             '    $out = @()',
-            '    foreach ($el in @($fx_pair.Substring($fx_eq + 1) -split [string][char]30)) { $out += ,(fx-svdec $el) }',
+            '    foreach ($el in @($pay -split [string][char]30)) { $out += ,(fx-svdec $el) }',
             '    return $out',
             '  }',
             '  $s0 = fx-scalar0 $n',
@@ -1179,9 +1594,12 @@ export function wrapScript(body, opts = {}) {
         'fx-arrput': [
             'function fx-arrput($n, $vals) {',
             '  $n = [string]$n',
-            '  $vals = @($vals)',
+            '  if ($null -eq $vals) { $vals = @() } else { $vals = @($vals) }',
             '  fx-arrdrop $n',
-            '  if ($vals.Count -eq 0) { } else {',
+            '  if ($vals.Count -eq 0) {',
+            // SOH payload: empty array, distinct from scalar '' and from A=('')
+            "    $env:FAUXNIX_ARRS = ((@($env:FAUXNIX_ARRS -split [string][char]10 | Where-Object { $_ -ne '' }) + ($n + [string][char]61 + [string][char]1)) -join [string][char]10)",
+            '  } 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)",
             '  }',
@@ -1216,6 +1634,70 @@ export function wrapScript(body, opts = {}) {
             '  return [string]$arr[$i]',
             '}',
         ],
+        'fx-casematch': [
+            'function fx-casematch($w, $pats) {',
+            '  $w = [string]$w',
+            '  foreach ($p in @($pats)) {',
+            '    $pat = [string]$p',
+            '    try {',
+            '      $wp = [WildcardPattern]::new($pat, [System.Management.Automation.WildcardOptions]::None)',
+            '      if ($wp.IsMatch($w)) { return $true }',
+            '    } catch {}',
+            '  }',
+            '  return $false',
+            '}',
+        ],
+        'fx-subst': [
+            'function fx-subst($s, $pat, $repl, $all) {',
+            '  if ($null -eq $s) { return \'\' }',
+            '  $s = [string]$s',
+            '  $pat = [string]$pat',
+            '  $repl = [string]$repl',
+            '  if ($pat -eq \'\') { return $s }',
+            '  $glob = $false',
+            '  foreach ($fx_c in $pat.ToCharArray()) {',
+            '    if ($fx_c -eq [char]42 -or $fx_c -eq [char]63) { $glob = $true; break }',
+            '  }',
+            '  if (-not $glob) {',
+            '    if ($all) { return $s.Replace($pat, $repl) }',
+            '    $i = $s.IndexOf($pat)',
+            '    if ($i -lt 0) { return $s }',
+            '    return $s.Substring(0, $i) + $repl + $s.Substring($i + $pat.Length)',
+            '  }',
+            '  $sb = New-Object System.Text.StringBuilder',
+            '  foreach ($fx_c in $pat.ToCharArray()) {',
+            '    if ($fx_c -eq [char]42) { [void]$sb.Append(\'.*\'); continue }',
+            '    if ($fx_c -eq [char]63) { [void]$sb.Append(\'.\'); continue }',
+            '    [void]$sb.Append([regex]::Escape([string]$fx_c))',
+            '  }',
+            '  $rx = New-Object System.Text.RegularExpressions.Regex($sb.ToString(), [System.Text.RegularExpressions.RegexOptions]::Singleline)',
+            '  $fx_rep = $repl.Replace([string][char]36, ([string][char]36 + [string][char]36))',
+            '  if ($all) { return $rx.Replace($s, $fx_rep) }',
+            '  return $rx.Replace($s, $fx_rep, 1)',
+            '}',
+        ],
+        'fx-slice': [
+            'function fx-slice($s, $off, $len) {',
+            '  if ($null -eq $s) { return \'\' }',
+            '  $s = [string]$s',
+            '  $n = $s.Length',
+            '  $o = 0',
+            '  if (-not [int]::TryParse([string]$off, [ref]$o)) { return \'\' }',
+            '  if ($o -lt 0) { $o = $n + $o }',
+            '  if ($o -lt 0 -or $o -ge $n) { return \'\' }',
+            '  if ($null -eq $len -or [string]$len -eq \'\') { return $s.Substring($o) }',
+            '  $l = 0',
+            '  if (-not [int]::TryParse([string]$len, [ref]$l)) { return \'\' }',
+            '  if ($l -lt 0) {',
+            '    $fx_end = $n + $l',
+            '    if ($fx_end -lt $o) { return \'\' }',
+            '    $l = $fx_end - $o',
+            '  }',
+            '  if ($l -le 0) { return \'\' }',
+            '  if (($o + $l) -gt $n) { $l = $n - $o }',
+            '  return $s.Substring($o, $l)',
+            '}',
+        ],
         'fx-winargv': [
             'function fx-winargv($argv, $cmdmeta) {',
             // Empty [object[]] unwraps to $null on PS 5.1; @($null) is one empty arg.
@@ -1252,8 +1734,48 @@ export function wrapScript(body, opts = {}) {
             "  return (($parts.ToArray()) -join ' ')",
             '}',
         ],
+        'fx-cmdargv': [
+            'function fx-cmdargv($argv) {',
+            // cmd.exe performs percent expansion even inside quotes, and embedded
+            // quotes can reopen its metacharacter grammar. CR/LF/NUL cannot be
+            // represented as one batch argument. Reject those values instead of
+            // silently handing a different argv to the shim.
+            '  if ($null -eq $argv) { $argv = @() }',
+            '  foreach ($a in @($argv)) {',
+            '    $s = [string]$a',
+            "    if ($s.IndexOf('%') -ge 0) { throw \"fauxnix: cannot pass '%' to a .cmd/.bat file without changing the argument; invoke the underlying executable directly\" }",
+            '    if ($s.IndexOf([char]34) -ge 0) { throw \'fauxnix: cannot pass a double quote to a .cmd/.bat file without changing the argument; invoke the underlying executable directly\' }',
+            '    if ($s.IndexOf([char]13) -ge 0 -or $s.IndexOf([char]10) -ge 0) { throw \'fauxnix: cannot pass a line break to a .cmd/.bat file as one argument; invoke the underlying executable directly\' }',
+            '    if ($s.IndexOf([char]0) -ge 0) { throw \'fauxnix: cannot pass NUL to a .cmd/.bat file as one argument; invoke the underlying executable directly\' }',
+            '  }',
+            '  return (fx-winargv $argv $true)',
+            '}',
+        ],
         'fx-native': [
-            'function fx-native($name, $argv) {',
+            "if (-not ('FauxnixTextPump' -as [type])) {",
+            "  Add-Type -TypeDefinition @'",
+            'using System;',
+            'using System.IO;',
+            'using System.Text;',
+            'using System.Threading.Tasks;',
+            'public static class FauxnixTextPump {',
+            '  public static async Task CopyAsync(TextReader reader, TextWriter writer) {',
+            '    var buffer = new char[4096];',
+            '    int read;',
+            '    while ((read = await reader.ReadAsync(buffer, 0, buffer.Length).ConfigureAwait(false)) > 0) {',
+            '      await writer.WriteAsync(buffer, 0, read).ConfigureAwait(false);',
+            '    }',
+            '    await writer.FlushAsync().ConfigureAwait(false);',
+            '  }',
+            '  public static async Task CopyFileAsync(TextReader reader, string path) {',
+            '    using (var writer = new StreamWriter(path, false, new UTF8Encoding(false))) {',
+            '      await CopyAsync(reader, writer).ConfigureAwait(false);',
+            '    }',
+            '  }',
+            '}',
+            "'@",
+            '}',
+            'function fx-native($name, $argv, $term) {',
             '  if ($null -eq $argv) { $argv = @() } else { $argv = [object[]]@($argv) }',
             '  $app = Get-Command -Name $name -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1',
             '  if ($null -eq $app) {',
@@ -1282,8 +1804,8 @@ export function wrapScript(body, opts = {}) {
             '  $psi = New-Object System.Diagnostics.ProcessStartInfo',
             '  $ext = [IO.Path]::GetExtension([string]$app.Source)',
             // CreateProcess cannot launch .cmd/.bat with UseShellExecute=false (npm.cmd).
-            // /s strips one outer quote pair from the /c tail; CRT-quote cmd
-            // metacharacters so `&`/`|`/`()` do not start a second command.
+            // /s strips one outer quote pair from the /c tail. Build only the
+            // subset of batch argv that cmd.exe can pass through unchanged.
             "  if ($ext -eq '.cmd' -or $ext -eq '.bat') {",
             '    $comspec = Get-Command -Name cmd -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1',
             '    if ($null -eq $comspec) {',
@@ -1292,10 +1814,16 @@ export function wrapScript(body, opts = {}) {
             '      return',
             '    }',
             '    $psi.FileName = $comspec.Source',
-            '    $fx_app = fx-winargv $app.Source $true',
-            '    $fx_rest = fx-winargv $argv $true',
+            '    try {',
+            '      $fx_app = fx-cmdargv $app.Source',
+            '      $fx_rest = fx-cmdargv $argv',
+            '    } catch {',
+            // Let the common wrapper report the validation error and stop the
+            // current pipeline. Returning here would let xargs mask the failure.
+            '      throw $_.Exception',
+            '    }',
             "    if ($fx_rest.Length -gt 0) { $fx_tail = $fx_app + ' ' + $fx_rest } else { $fx_tail = $fx_app }",
-            '    $psi.Arguments = \'/d /s /c "\' + $fx_tail + \'"\'',
+            '    $psi.Arguments = \'/d /s /v:off /c "\' + $fx_tail + \'"\'',
             '  } else {',
             '    $psi.FileName = $app.Source',
             '    $psi.Arguments = fx-winargv $argv',
@@ -1306,35 +1834,40 @@ export function wrapScript(body, opts = {}) {
             '  $psi.RedirectStandardError = $true',
             '  $psi.CreateNoWindow = $true',
             '  $psi.WorkingDirectory = [Environment]::CurrentDirectory',
-            // StreamReader.ReadToEndAsync is .NET 4.5 (PS 5.1). Start readers
-            // before writing stdin so a chatty child cannot fill the 64KB pipe.
+            // Drain both child pipes concurrently into disk-backed spools before
+            // replaying them. This prevents either 64KB OS pipe from blocking the
+            // child and avoids retaining the complete output in a .NET string.
             "  if ($env:FAUXNIX_NATIVE_ENCODING -eq 'ansi') { $enc = [System.Text.Encoding]::GetEncoding(936) } else { $enc = New-Object System.Text.UTF8Encoding $false }",
             '  $psi.StandardOutputEncoding = $enc',
             '  $psi.StandardErrorEncoding = $enc',
             '  $p = New-Object System.Diagnostics.Process',
             '  $p.StartInfo = $psi',
-            '  [void]$p.Start()',
-            '  $outTask = $p.StandardOutput.ReadToEndAsync()',
-            '  $errTask = $p.StandardError.ReadToEndAsync()',
-            '  $ins = @($input)',
-            '  if ($ins.Count -gt 0) {',
-            '    foreach ($fx_ln in $ins) { $p.StandardInput.WriteLine([string]$fx_ln) }',
-            '  }',
-            '  $p.StandardInput.Close()',
-            '  [void][System.Threading.Tasks.Task]::WaitAll(@($outTask, $errTask))',
-            '  [void]$p.WaitForExit()',
-            '  $errt = [string]$errTask.Result',
-            '  if ($errt.Length -gt 0) { [Console]::Error.Write($errt) }',
-            '  $t = [string]$outTask.Result',
-            "  $t = $t.Replace(([string][char]13 + [string][char]10), [string][char]10).Replace([string][char]13, [string][char]10)",
-            "  if ($t -ne '') {",
-            '    $parts = @($t.Split([char]10))',
-            "    if ($parts.Count -gt 0 -and $parts[$parts.Count - 1] -eq '') { $parts = $parts[0..($parts.Count - 2)] }",
-            '    foreach ($fx_ol in $parts) { $fx_ol }',
+            '  $fx_no = $null',
+            '  $fx_spoolUtf8 = New-Object System.Text.UTF8Encoding $false',
+            '  try {',
+            '    if (-not $term) {',
+            "      if ($env:FAUXNIX_NATIVE_SPOOL_DIR) { $fx_no = Join-Path $env:FAUXNIX_NATIVE_SPOOL_DIR (([guid]::NewGuid().ToString('N')) + '.out') }",
+            '      else { $fx_no = [IO.Path]::GetTempFileName() }',
+            '    }',
+            '    [void]$p.Start()',
+            '    if ($term) { $outTask = [FauxnixTextPump]::CopyAsync($p.StandardOutput, [Console]::Out) }',
+            '    else { $outTask = [FauxnixTextPump]::CopyFileAsync($p.StandardOutput, $fx_no) }',
+            '    $errTask = [FauxnixTextPump]::CopyAsync($p.StandardError, [Console]::Error)',
+            '    foreach ($fx_ln in $input) { $p.StandardInput.WriteLine([string]$fx_ln) }',
+            '    $p.StandardInput.Close()',
+            '    [void][System.Threading.Tasks.Task]::WaitAll(@($outTask, $errTask))',
+            '    [void]$p.WaitForExit()',
+            '    if (-not $term) {',
+            '      $fx_or = New-Object System.IO.StreamReader($fx_no, $fx_spoolUtf8)',
+            '      try { while (($fx_line = $fx_or.ReadLine()) -ne $null) { $fx_line } }',
+            '      finally { $fx_or.Dispose() }',
+            '    }',
+            '    $code = [int]$p.ExitCode',
+            '    if ($code -gt 0) { $script:fx_exit = $code } elseif ($code -lt 0) { $script:fx_exit = 1 }',
+            '  } finally {',
+            '    try { $p.Close() } catch {}',
+            '    if ($null -ne $fx_no) { Remove-Item -LiteralPath $fx_no -Force -ErrorAction SilentlyContinue }',
             '  }',
-            '  $code = [int]$p.ExitCode',
-            '  if ($code -gt 0) { $script:fx_exit = $code } elseif ($code -lt 0) { $script:fx_exit = 1 }',
-            '  try { $p.Close() } catch {}',
             '}',
         ],
     };
@@ -1354,7 +1887,7 @@ function wrapHelperCatalog() {
 }
 /**
  * Resident-host bootstrap: encoding + full fx-* catalog + JSON-line RPC loop.
- * Loaded once via `powershell.exe -File`. Must never `exit` a successful frame.
+ * Loaded once via the selected PowerShell's `-File`. Must never `exit` a successful frame.
  */
 export function hostBootstrapScript() {
     const helpers = wrapHelperCatalog();
@@ -1370,6 +1903,46 @@ export function hostBootstrapScript() {
 }
 /** Raw UTF-8 JSON lines on stdin/stdout; command streams captured per frame. */
 const HOST_RPC_LOOP = `
+if (-not ('FauxnixBoundedStream' -as [type])) {
+  Add-Type -TypeDefinition @'
+using System;
+using System.IO;
+public sealed class FauxnixBoundedStream : Stream {
+  private readonly MemoryStream inner;
+  private readonly long limit;
+  private readonly long storageLimit;
+  private long totalWritten;
+  public bool Truncated { get; private set; }
+  public FauxnixBoundedStream(long limit) {
+    this.limit = Math.Max(0, limit);
+    this.storageLimit = this.limit + 3;
+    this.inner = new MemoryStream((int)Math.Min(this.storageLimit, 65536));
+  }
+  public byte[] ToArray() { return inner.ToArray(); }
+  public override bool CanRead { get { return false; } }
+  public override bool CanSeek { get { return false; } }
+  public override bool CanWrite { get { return true; } }
+  public override long Length { get { return inner.Length; } }
+  public override long Position { get { return inner.Position; } set { throw new NotSupportedException(); } }
+  public override void Flush() { }
+  public override int Read(byte[] buffer, int offset, int count) { throw new NotSupportedException(); }
+  public override long Seek(long offset, SeekOrigin origin) { throw new NotSupportedException(); }
+  public override void SetLength(long value) { throw new NotSupportedException(); }
+  public override void Write(byte[] buffer, int offset, int count) {
+    long remaining = Math.Max(0, storageLimit - inner.Length);
+    int keep = (int)Math.Min((long)count, remaining);
+    if (keep > 0) inner.Write(buffer, offset, keep);
+    totalWritten += count;
+    if (totalWritten > limit) Truncated = true;
+  }
+  public override void WriteByte(byte value) {
+    if (inner.Length < storageLimit) inner.WriteByte(value);
+    totalWritten++;
+    if (totalWritten > limit) Truncated = true;
+  }
+}
+'@
+}
 $fx_utf8 = New-Object System.Text.UTF8Encoding $false
 $fx_in = [Console]::OpenStandardInput()
 $fx_out = [Console]::OpenStandardOutput()
@@ -1389,8 +1962,8 @@ function fx-emit-chunks($type, $id, [byte[]]$bytes, $limit, [ref]$seq) {
   if ($null -ne $bytes) { $n = $bytes.Length }
   $use = $n
   $trunc = $false
-  # limit 0 = uncapped (file-redirected streams must never be budget-clipped)
-  if ($limit -gt 0 -and $use -gt $limit) {
+  # limit -1 = uncapped; zero is a real empty caller budget
+  if ($limit -ge 0 -and $use -gt $limit) {
     $use = $limit
     $trunc = $true
     # back the cut off to a valid UTF-8 boundary — a split codepoint makes
@@ -1416,6 +1989,18 @@ function fx-emit-chunks($type, $id, [byte[]]$bytes, $limit, [ref]$seq) {
   }
   return $trunc
 }
+function fx-new-capture($mode, $limit, $spoolPath) {
+  if ([string]$mode -eq 'discard') { return [System.IO.Stream]::Null }
+  if ([string]$mode -eq 'spool') {
+    return (New-Object System.IO.FileStream([string]$spoolPath, [System.IO.FileMode]::Create, [System.IO.FileAccess]::Write, [System.IO.FileShare]::Read))
+  }
+  return (New-Object FauxnixBoundedStream ([Math]::Max(0, [long]$limit)))
+}
+function fx-capture-bytes($stream) {
+  if ($stream -is [FauxnixBoundedStream]) { return $stream.ToArray() }
+  if ($stream -is [System.IO.MemoryStream]) { return $stream.ToArray() }
+  return (New-Object byte[] 0)
+}
 while ($true) {
   $fx_line = $fx_reader.ReadLine()
   if ($null -eq $fx_line) { break }
@@ -1443,12 +2028,24 @@ while ($true) {
       }
     }
     $fx_script = [System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String([string]$fx_req.scriptB64))
-    $fx_msOut = New-Object System.IO.MemoryStream
-    $fx_msErr = New-Object System.IO.MemoryStream
+    $fx_outLimit = 8388608
+    $fx_errLimit = 1048576
+    if ($null -ne $fx_req.PSObject.Properties['stdoutLimit']) { $fx_outLimit = [int]$fx_req.stdoutLimit }
+    if ($null -ne $fx_req.PSObject.Properties['stderrLimit']) { $fx_errLimit = [int]$fx_req.stderrLimit }
+    $fx_outMode = 'capture'
+    $fx_errMode = 'capture'
+    $fx_outSpool = ''
+    $fx_errSpool = ''
+    if ($null -ne $fx_req.PSObject.Properties['stdoutMode']) { $fx_outMode = [string]$fx_req.stdoutMode }
+    if ($null -ne $fx_req.PSObject.Properties['stderrMode']) { $fx_errMode = [string]$fx_req.stderrMode }
+    if ($null -ne $fx_req.PSObject.Properties['stdoutSpoolPath']) { $fx_outSpool = [string]$fx_req.stdoutSpoolPath }
+    if ($null -ne $fx_req.PSObject.Properties['stderrSpoolPath']) { $fx_errSpool = [string]$fx_req.stderrSpoolPath }
+    $fx_msOut = fx-new-capture $fx_outMode $fx_outLimit $fx_outSpool
+    $fx_msErr = fx-new-capture $fx_errMode $fx_errLimit $fx_errSpool
     $fx_outW = New-Object System.IO.StreamWriter($fx_msOut, $fx_utf8, 1024, $true)
     $fx_errW = New-Object System.IO.StreamWriter($fx_msErr, $fx_utf8, 1024, $true)
-    $fx_outW.NewLine = [string][char]13 + [string][char]10
-    $fx_errW.NewLine = [string][char]13 + [string][char]10
+    $fx_outW.NewLine = [string][char]10
+    $fx_errW.NewLine = [string][char]10
     $fx_outW.AutoFlush = $true
     $fx_errW.AutoFlush = $true
     [Console]::SetOut($fx_outW)
@@ -1476,24 +2073,29 @@ while ($true) {
   }
   $fx_outBytes = New-Object byte[] 0
   $fx_errBytes = New-Object byte[] 0
-  if ($null -ne $fx_msOut) { $fx_outBytes = $fx_msOut.ToArray() }
-  if ($null -ne $fx_msErr) { $fx_errBytes = $fx_msErr.ToArray() }
+  if ($null -ne $fx_msOut) { $fx_outBytes = fx-capture-bytes $fx_msOut }
+  if ($null -ne $fx_msErr) { $fx_errBytes = fx-capture-bytes $fx_msErr }
+  try { if ($null -ne $fx_outW) { $fx_outW.Dispose() } } catch {}
+  try { if ($null -ne $fx_errW) { $fx_errW.Dispose() } } catch {}
+  try { if ($null -ne $fx_msOut -and $fx_msOut -ne [System.IO.Stream]::Null) { $fx_msOut.Dispose() } } catch {}
+  try { if ($null -ne $fx_msErr -and $fx_msErr -ne [System.IO.Stream]::Null) { $fx_msErr.Dispose() } } catch {}
   if ($fx_v2) {
-    $fx_outLimit = 8388608
-    $fx_errLimit = 1048576
-    if ($null -ne $fx_req.PSObject.Properties['stdoutLimit']) { $fx_outLimit = [int]$fx_req.stdoutLimit }
-    if ($null -ne $fx_req.PSObject.Properties['stderrLimit']) { $fx_errLimit = [int]$fx_req.stderrLimit }
     $fx_outSeq = 0
     $fx_errSeq = 0
-    $fx_trunc = $false
-    if (fx-emit-chunks 'stdout' $fx_id $fx_outBytes $fx_outLimit ([ref]$fx_outSeq)) { $fx_trunc = $true }
-    if (fx-emit-chunks 'stderr' $fx_id $fx_errBytes $fx_errLimit ([ref]$fx_errSeq)) { $fx_trunc = $true }
+    $fx_outTrunc = $false
+    $fx_errTrunc = $false
+    if ($fx_msOut -is [FauxnixBoundedStream] -and $fx_msOut.Truncated) { $fx_outTrunc = $true }
+    if ($fx_msErr -is [FauxnixBoundedStream] -and $fx_msErr.Truncated) { $fx_errTrunc = $true }
+    $fx_outEmitLimit = $(if ($fx_outMode -eq 'capture') { $fx_outLimit } else { -1 })
+    $fx_errEmitLimit = $(if ($fx_errMode -eq 'capture') { $fx_errLimit } else { -1 })
+    if (fx-emit-chunks 'stdout' $fx_id $fx_outBytes $fx_outEmitLimit ([ref]$fx_outSeq)) { $fx_outTrunc = $true }
+    if (fx-emit-chunks 'stderr' $fx_id $fx_errBytes $fx_errEmitLimit ([ref]$fx_errSeq)) { $fx_errTrunc = $true }
     $fx_nativeErr = [Console]::OpenStandardError()
     $fx_mark = $fx_utf8.GetBytes(('FAUXNIX_ERR_END:' + $fx_id + [char]10))
     $fx_nativeErr.Write($fx_mark, 0, $fx_mark.Length)
     $fx_nativeErr.Flush()
-    $fx_end = '{"v":2,"type":"end","id":"' + $fx_id + '","exitCode":' + $fx_code + ',"timedOut":false,"cancelled":false,"truncated":'
-    if ($fx_trunc) { $fx_end = $fx_end + 'true}' } else { $fx_end = $fx_end + 'false}' }
+    $fx_trunc = $fx_outTrunc -or $fx_errTrunc
+    $fx_end = '{"v":2,"type":"end","id":"' + $fx_id + '","exitCode":' + $fx_code + ',"timedOut":false,"cancelled":false,"truncated":' + ([string]$fx_trunc).ToLowerInvariant() + ',"stdoutTruncated":' + ([string]$fx_outTrunc).ToLowerInvariant() + ',"stderrTruncated":' + ([string]$fx_errTrunc).ToLowerInvariant() + '}'
     $fx_proto.WriteLine($fx_end)
   } else {
     $fx_outB64 = ''