fauxnix-cli 0.11.0 → 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                                                    */
 /* ------------------------------------------------------------------ */
@@ -421,8 +595,8 @@ export function argListExpr(words, fn = exprOfWord) {
  * Lists (`;` `&&` `||`) reuse translateListInline inside the fx-csub
  * scriptblock so the newline contract is unchanged.
  */
-export function translateCmdSub(cmdText, keepNl = false) {
-    const inner = translateListInline(parseCommand(cmdText));
+export function translateCmdSub(cmdText, keepNl = false, translation = EXECUTE_TRANSLATION) {
+    const inner = translateListInline(parseCommand(cmdText), translation);
     const collected = '(fx-csub { ' + inner + ' })';
     if (keepNl)
         return collected;
@@ -439,7 +613,10 @@ 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
@@ -456,8 +633,9 @@ export function translateSimple(cmd, position, hasStdin) {
             }
             else {
                 const words = [[{ kind: 'Text', text: a.name + '=' }, ...a.value]];
-                if (exportHandler)
-                    chunks.push(exportHandler(words, { position, hasStdin }));
+                if (exportHandler) {
+                    chunks.push(exportHandler(words, { position, hasStdin, translationMode: translation.mode }));
+                }
             }
         }
         return chunks.join('\n');
@@ -475,7 +653,7 @@ 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 = @(' + splatLoadCall(nameSplat.name) + ')',
         ];
@@ -491,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),
@@ -514,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),
@@ -807,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}');
@@ -824,29 +1005,29 @@ 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 translateCase(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);
+        const body = translateListInline(arm.body, translation);
         if (body) {
             for (const l of body.split('\n'))
                 lines.push(l ? '  ' + l : l);
@@ -855,7 +1036,7 @@ function translateCase(cmd) {
     }
     return lines.join('\n');
 }
-function translateFor(cmd) {
+function translateFor(cmd, translation) {
     const n = cmd.name.replace(/'/g, "''");
     const lines = [
         '$fx_for = ' + argListExpr(cmd.words),
@@ -877,22 +1058,22 @@ 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) {
+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).split('\n'))
+    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).split('\n'))
+    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)');
@@ -917,19 +1098,41 @@ 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)';
-function rejectNonLastStdoutRedirects(commands) {
+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++) {
-        if (commands[i].redirects.some((r) => isStdoutFileRedirect(r.op))) {
-            throw new FauxnixParseError(NONLAST_STDOUT_REDIRECT_MSG);
+        for (const redirect of commands[i].redirects) {
+            const message = nonLastFdRedirectMessage(redirect.op);
+            if (message)
+                throw new FauxnixParseError(message);
         }
     }
 }
-export function translatePipelineBody(p) {
-    // Last-stage `>` is Node apply; a non-last `>` would truncate the file and
-    // still feed the pipe. Fail loud until in-stage writes (#157).
-    rejectNonLastStdoutRedirects(p.commands);
+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
@@ -942,15 +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));
+            bodies.push(translateWhile(c, translation));
         else if (c.kind === 'Case')
-            bodies.push(translateCase(c));
+            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})' };
@@ -1009,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;
@@ -1020,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.
@@ -1070,6 +1273,7 @@ const WRAP_HELPER_ORDER = [
     'fx-subst',
     'fx-slice',
     'fx-winargv',
+    'fx-cmdargv',
     'fx-native',
 ];
 const WRAP_HELPER_DEPS = {
@@ -1095,7 +1299,8 @@ const WRAP_HELPER_DEPS = {
     '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) {
@@ -1529,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) {',
@@ -1559,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) {',
@@ -1569,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',
@@ -1583,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 {}',
             '}',
         ],
     };
@@ -1631,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();
@@ -1647,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()
@@ -1666,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
@@ -1693,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 }
@@ -1720,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)
@@ -1753,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 = ''