fauxnix-cli 0.9.1 → 0.9.3

package/dist/commands/text-io.js

@@ -511,7 +511,9 @@ const head = (args, ctx) => {
         lines.push(STDIN_INLINES);
     lines.push(...psCollectFiles(operandWords, (g) => qErr('head', g, 'No such file or directory'), (g) => qErr('head', g, 'Is a directory', 'error reading ')), '$fx_count = [int](' + countLit + ')', '$fx_hdr = ((($fx_srcs.Count -gt 1) -and ' + pb(!quiet) + ') -or ' + pb(verbose) + ')', '$fx_first = $true');
     if (bytesMode) {
-        lines.push('$fx_out = New-Object System.Text.StringBuilder', 'for ($fx_k = 0; $fx_k -lt $fx_srcs.Count; $fx_k++) {', '  $fx_g = $fx_srcs[$fx_k]', "  if ($fx_g -eq '-') { $fx_txt = (fx-stdinraw $fx_items); $fx_disp = 'standard input' }", '  else { $fx_txt = fx-read $fx_g; $fx_disp = $fx_names[$fx_k] }', '  if ($fx_hdr) {', '    if (-not $fx_first) { [void]$fx_out.Append([string][char]10) }', "    [void]$fx_out.Append('==> ' + $fx_disp + ' <==' + [string][char]10)", '  }', '  $fx_first = $false', '  $fx_len = [math]::Min($fx_count, $fx_txt.Length)', '  if ($fx_len -lt 0) { $fx_len = 0 }', '  if ($fx_len -gt 0) { [void]$fx_out.Append($fx_txt.Substring(0, $fx_len)) }', '}', 'fx-write $fx_out.ToString() $fx_term');
+        lines.push('$fx_out = New-Object System.Text.StringBuilder', 'for ($fx_k = 0; $fx_k -lt $fx_srcs.Count; $fx_k++) {', '  $fx_g = $fx_srcs[$fx_k]', "  if ($fx_g -eq '-') { $fx_txt = (fx-stdinraw $fx_items); $fx_disp = 'standard input' }", '  else { $fx_txt = fx-read $fx_g; $fx_disp = $fx_names[$fx_k] }', '  if ($fx_hdr) {', '    if (-not $fx_first) { [void]$fx_out.Append([string][char]10) }', "    [void]$fx_out.Append('==> ' + $fx_disp + ' <==' + [string][char]10)", '  }', '  $fx_first = $false', 
+        // GNU: --bytes=-N prints all but last N; -0 / N≥size → empty
+        '  if ($fx_count -lt 0) { $fx_len = [math]::Max(0, $fx_txt.Length + $fx_count) }', '  else { $fx_len = [math]::Min($fx_count, $fx_txt.Length) }', '  if ($fx_len -gt 0) { [void]$fx_out.Append($fx_txt.Substring(0, $fx_len)) }', '}', 'fx-write $fx_out.ToString() $fx_term');
     }
     else {
         lines.push('for ($fx_k = 0; $fx_k -lt $fx_srcs.Count; $fx_k++) {', '  $fx_g = $fx_srcs[$fx_k]', "  if ($fx_g -eq '-') { $fx_ls = @($fx_in); $fx_disp = 'standard input' }", '  else { $fx_ls = @(fx-splitlines (fx-read $fx_g)); $fx_disp = $fx_names[$fx_k] }', '  if ($fx_hdr) {', "    if (-not $fx_first) { '' }", "    '==> ' + $fx_disp + ' <=='", '  }', '  $fx_first = $false', '  $fx_lim = $fx_ls.Count', '  if ($fx_count -lt 0) { $fx_lim = $fx_ls.Count + $fx_count }', '  elseif ($fx_lim -gt $fx_count) { $fx_lim = $fx_count }', '  if ($fx_lim -lt 0) { $fx_lim = 0 }', '  for ($fx_i = 0; $fx_i -lt $fx_lim; $fx_i++) { $fx_ls[$fx_i] }', '}');
@@ -1091,6 +1093,9 @@ const xargs = (args) => {
                     noRunIfEmpty = true;
                 else if (ch === 't')
                     trace = true;
+                else if (ch === '0') {
+                    return psErrExpr(psStr('xargs: -0 is not supported by fauxnix'));
+                }
                 else if (ch === 'n' || ch === 'I' || ch === 'L') {
                     const restv = body.slice(c + 1);
                     let val;
@@ -1138,12 +1143,12 @@ const xargs = (args) => {
     }
     const n = chunkN !== null && Number.isFinite(chunkN) && chunkN > 0 ? chunkN : 0;
     const replExpr = repl !== null ? psStr(repl) : null;
+    // fx-native already records $script:fx_exit from ExitCode.
     const invoke = [
         '    if (' +
             pb(trace) +
             ") { [Console]::Error.WriteLine(((@($fx_cmd) + @($fx_argv)) -join ' ')) }",
-        '    & $fx_cmd @fx_argv',
-        '    if ($LASTEXITCODE -ne 0 -and $script:fx_exit -eq 0) { $script:fx_exit = $LASTEXITCODE }',
+        '    fx-native $fx_cmd $fx_argv',
     ];
     let dispatch;
     const guard = '  if (' + pb(noRunIfEmpty) + ' -and $fx_args.Count -eq 0) { }' + '\n' + '  else {';
@@ -1152,7 +1157,7 @@ const xargs = (args) => {
         dispatch = [
             guard,
             '  foreach ($fx_l in $fx_args) {',
-            '    $fx_argv = @()',
+            '    $fx_argv = [object[]]@()',
             '    $fx_hit = $false',
             '    foreach ($fx_a in $fx_base) {',
             '      if ($fx_a.Contains(' + replExpr + ')) {',
@@ -1173,7 +1178,7 @@ const xargs = (args) => {
             '  $fx_i = 0',
             '  $fx_ran = $false',
             '  while ($fx_i -lt $fx_args.Count) {',
-            '    $fx_argv = @($fx_base)',
+            '    $fx_argv = [object[]]@($fx_base)',
             '    $fx_j = 0',
             '    while ($fx_j -lt ' + n + ' -and $fx_i -lt $fx_args.Count) {',
             '      $fx_argv += $fx_args[$fx_i]',
@@ -1183,10 +1188,8 @@ const xargs = (args) => {
             ...invoke,
             '  }',
             '  if (-not $fx_ran) {',
-            '    $fx_argv = @($fx_base)',
-            '    ' + invoke[0],
-            '    ' + invoke[1],
-            '    ' + invoke[2],
+            '    $fx_argv = [object[]]@($fx_base)',
+            ...invoke.map((line) => '  ' + line),
             '  }',
             '  }',
         ];
@@ -1194,17 +1197,27 @@ const xargs = (args) => {
     else {
         dispatch = [
             guard,
-            '  $fx_argv = @($fx_base) + @($fx_args)',
+            '  $fx_argv = [object[]](@($fx_base) + @($fx_args))',
             ...invoke,
             '  }',
         ];
     }
+    // Default GNU xargs splits on blanks; -I keeps whole lines as one item.
+    const collectArgs = replExpr !== null
+        ? "$fx_args = @($fx_in | Where-Object { $_ -ne '' })"
+        : [
+            '$fx_args = @()',
+            'foreach ($fx_l in $fx_in) {',
+            "  if ($fx_l -eq '') { continue }",
+            "  $fx_args += @($fx_l -split '[ \\t]+' | Where-Object { $_ -ne '' })",
+            '}',
+        ].join('\n');
     return [
         PS_SPLITLINES_FN,
         STDIN_INLINES,
         '$fx_tg = ' + argListExpr(target, exprOfWord),
         "if ($fx_tg.Count -eq 0) { $fx_cmd = ''; $fx_base = @() } else { $fx_cmd = [string]$fx_tg[0]; $fx_base = $(if ($fx_tg.Count -gt 1) { @($fx_tg[1..($fx_tg.Count - 1)]) } else { @() }) }",
-        "$fx_args = @($fx_in | Where-Object { $_ -ne '' })",
+        collectArgs,
         ...dispatch,
     ].join('\n');
 };
@@ -1234,6 +1247,74 @@ export const specs = [
         dispatch: 'translated',
         handler: head,
     },
+    {
+        names: ['echo'],
+        options: [
+            { short: 'n', support: 'implemented' },
+            { short: 'e', support: 'implemented' },
+            { short: 'E', support: 'implemented' },
+        ],
+        effects: [],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        usageExit: 2,
+        leadingOptions: true,
+        handler: echo,
+    },
+    {
+        names: ['printf'],
+        options: [],
+        effects: [],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        usageExit: 2,
+        leadingOptions: true,
+        handler: printf,
+    },
+    {
+        names: ['cat'],
+        options: [
+            { short: 'n', support: 'implemented' },
+            { short: 'b', support: 'implemented' },
+            { short: 's', support: 'implemented' },
+            { short: 'E', support: 'implemented' },
+            { short: 'T', support: 'implemented' },
+            { short: 'A', support: 'implemented' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: cat,
+    },
+    {
+        names: ['tail'],
+        options: [
+            { short: 'n', long: '--lines', takesValue: true, support: 'implemented' },
+            { short: 'c', long: '--bytes', takesValue: true, support: 'implemented' },
+            { short: 'q', long: '--quiet', support: 'implemented' },
+            { long: '--silent', support: 'implemented' },
+            { short: 'v', long: '--verbose', support: 'implemented' },
+            { short: 'f', support: 'unsupported', reason: 'no persistent tty' },
+            { short: 'F', support: 'unsupported', reason: 'no persistent tty' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: tail,
+    },
+    {
+        names: ['wc'],
+        options: [
+            { short: 'l', support: 'implemented' },
+            { short: 'w', support: 'implemented' },
+            { short: 'c', support: 'implemented' },
+            { short: 'm', support: 'implemented' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: wc,
+    },
 ];
 export const handlers = {
     echo,

package/dist/errors.d.ts

@@ -2,4 +2,8 @@
  * Error normalization — make PowerShell failures look like bash failures
  * so agents can pattern-match on familiar Linux error styles.
  */
+/** Missing `python3` on Windows (Mac/Linux agents emit this; do not alias). */
+export declare const PYTHON3_WINDOWS_HINT = " (fauxnix: try `python` or `py` on Windows)";
+/** `.sh` cannot be CreateProcess'd; fx-native never emits the PS not-recognized line. */
+export declare const SH_SCRIPT_WINDOWS_HINT = " (fauxnix: .sh scripts cannot run natively on Windows)";
 export declare function normalizeStderr(stderr: string): string;

package/dist/errors.js

@@ -2,6 +2,19 @@
  * Error normalization — make PowerShell failures look like bash failures
  * so agents can pattern-match on familiar Linux error styles.
  */
+/** Missing `python3` on Windows (Mac/Linux agents emit this; do not alias). */
+export const PYTHON3_WINDOWS_HINT = ' (fauxnix: try `python` or `py` on Windows)';
+/** `.sh` cannot be CreateProcess'd; fx-native never emits the PS not-recognized line. */
+export const SH_SCRIPT_WINDOWS_HINT = ' (fauxnix: .sh scripts cannot run natively on Windows)';
+function commandNotFound(name) {
+    const msg = 'bash: ' + name + ': command not found';
+    const base = name.replace(/^.*[/\\]/, '');
+    if (/^python3(\.exe)?$/i.test(base))
+        return msg + PYTHON3_WINDOWS_HINT;
+    if (/\.sh$/i.test(name))
+        return msg + SH_SCRIPT_WINDOWS_HINT;
+    return msg;
+}
 /** Lines produced by PowerShell error formatting that bash would never show. */
 const PS_NOISE = [
     /^\s*\+ CategoryInfo\s*:/,
@@ -62,15 +75,15 @@ export function normalizeStderr(stderr) {
         // "The term 'x' is not recognized as a name of a cmdlet, function, ..."
         let m = line.match(/^The term '(.+?)' is not recognized/);
         if (m)
-            return 'bash: ' + m[1] + ': command not found';
+            return commandNotFound(m[1]);
         // zh-CN: 无法将"x"项识别为 cmdlet、函数、脚本文件或可运行程序的名称
         m = line.match(/^无法将["'”]?([^"'”]+)["'”]?项识别为/);
         if (m)
-            return 'bash: ' + m[1] + ': command not found';
+            return commandNotFound(m[1]);
         // "x : The term 'y' is not recognized ..." (with source prefix)
         m = line.match(/^(\S+)\s*:\s*The term '(.+?)' is not recognized/);
         if (m)
-            return 'bash: ' + m[2] + ': command not found';
+            return commandNotFound(m[2]);
         // "cat : Cannot find path 'D:\x' because it does not exist."
         m = line.match(/^(\S+)\s*:\s*Cannot find path '(.+?)' because it does not exist\.?$/);
         if (m) {
@@ -93,9 +106,9 @@ export function normalizeStderr(stderr) {
         m = line.match(/^(\S+)\s*:\s*(.*)Access to the path '(.+?)' is denied\.?$/);
         if (m)
             return m[1].toLowerCase() + ': cannot remove \'' + m[3] + '\': Permission denied';
-        // helpful hint for bash scripts
+        // leftover PS not-recognized lines that the rewrites above did not catch
         if (/\.sh'?/.test(line) && /is not recognized/.test(line)) {
-            return line + ' (fauxnix: .sh scripts cannot run natively on Windows)';
+            return line + SH_SCRIPT_WINDOWS_HINT;
         }
         return line;
     });

package/dist/executor.js

@@ -21,7 +21,40 @@ function winTarget(target) {
         return path.join(os.tmpdir(), p.slice('$env:TEMP\\'.length));
     return p;
 }
-function emitToPrepDest(dest, msg, fds, fallback) {
+/** Windows NUL device — `NUL`, `\\.\NUL`, and `cwd\NUL` after path.resolve. */
+function isNulPath(p) {
+    const base = p.split(/[/\\]/).pop() ?? p;
+    return /^NUL$/i.test(base);
+}
+function applyRedirectDest(op, target, stdout, stderr) {
+    if (op === '2>&1')
+        return { stdout, stderr: stdout };
+    if (op === '1>&2')
+        return { stdout: stderr, stderr };
+    if (op === '<' || target === undefined)
+        return { stdout, stderr };
+    const dest = isNulPath(target) ? { kind: 'nul' } : { kind: 'file', path: target };
+    if (op === '>' || op === '>>')
+        return { stdout: dest, stderr };
+    if (op === '2>' || op === '2>>')
+        return { stdout, stderr: dest };
+    if (op === '&>' || op === '&>>')
+        return { stdout: dest, stderr: dest };
+    return { stdout, stderr };
+}
+/** Last-stage output fds only — captured stdout/stderr apply. */
+function lastStageOutputDests(redirects, resolveTarget) {
+    let stdout = { kind: 'caller', fd: 1 };
+    let stderr = { kind: 'caller', fd: 2 };
+    for (const r of redirects) {
+        const target = r.op === '2>&1' || r.op === '1>&2' || r.op === '<'
+            ? undefined
+            : resolveTarget(winTarget(r.target));
+        ({ stdout, stderr } = applyRedirectDest(r.op, target, stdout, stderr));
+    }
+    return { stdout, stderr };
+}
+function emitToPrepDest(dest, msg, fds, caller) {
     if (dest.kind === 'nul')
         return;
     if (dest.kind === 'file') {
@@ -30,10 +63,14 @@ function emitToPrepDest(dest, msg, fds, fallback) {
             return;
         }
         catch {
-            /* fall through to caller */
+            caller.stderr(msg);
+            return;
         }
     }
-    fallback(msg);
+    if (dest.fd === 1)
+        caller.stdout(msg);
+    else
+        caller.stderr(msg);
 }
 function writeAllSync(fd, data) {
     let off = 0;
@@ -89,19 +126,20 @@ function planRedirects(redirects) {
         appendStdout: false,
         stderrFile: null,
         appendStderr: false,
-        mergeStderr: false,
-        devNull: false,
     };
     for (const red of redirects) {
         const target = winTarget(red.target);
         switch (red.op) {
             case '<':
-                r.stdinFile = target;
+                r.stdinFile = isNulPath(target) ? null : target;
                 break;
             case '>':
             case '&>':
-                if (target === 'NUL')
-                    r.devNull = true;
+                if (isNulPath(target)) {
+                    r.stdoutFile = null;
+                    if (red.op === '&>')
+                        r.stderrFile = null;
+                }
                 else {
                     r.stdoutFile = target;
                     r.appendStdout = false;
@@ -111,8 +149,11 @@ function planRedirects(redirects) {
                 break;
             case '>>':
             case '&>>':
-                if (target === 'NUL')
-                    r.devNull = true;
+                if (isNulPath(target)) {
+                    r.stdoutFile = null;
+                    if (red.op === '&>>')
+                        r.stderrFile = null;
+                }
                 else {
                     r.stdoutFile = target;
                     r.appendStdout = true;
@@ -123,11 +164,9 @@ function planRedirects(redirects) {
                 }
                 break;
             case '2>':
-                if (target === 'NUL') {
-                    // 2>/dev/null swallows stderr only
+                if (isNulPath(target)) {
+                    // stderr only — must not undo a prior >/dev/null
                     r.stderrFile = null;
-                    r.devNull = false;
-                    r.swallowStderr = true;
                 }
                 else {
                     r.stderrFile = target;
@@ -135,17 +174,15 @@ function planRedirects(redirects) {
                 }
                 break;
             case '2>>':
-                if (target !== 'NUL') {
+                if (isNulPath(target)) {
+                    r.stderrFile = null;
+                }
+                else {
                     r.stderrFile = target;
                     r.appendStderr = true;
                 }
                 break;
-            case '2>&1':
-                r.mergeStderr = true;
-                break;
-            case '1>&2':
-                r.mergeStderr = false;
-                r.stdoutToStderr = true;
+            default:
                 break;
         }
     }
@@ -319,7 +356,9 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
             session.prevExit = exitCode;
             break;
         }
-        const red = planRedirects(plan.redirects);
+        const red = planRedirects(plan.outputRedirects);
+        const inRed = planRedirects(plan.stdinRedirects);
+        red.stdinFile = inRed.stdinFile;
         red.stdinFile = red.stdinFile ? resolveTarget(red.stdinFile) : null;
         red.stdoutFile = red.stdoutFile ? resolveTarget(red.stdoutFile) : null;
         red.stderrFile = red.stderrFile ? resolveTarget(red.stderrFile) : null;
@@ -334,22 +373,25 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
             let redirectPrepFailed = false;
             // Snapshot fd destinations as we walk. `2>&1` copies stdout *at that
             // moment*; a later `>file` must not drag stderr along (bash fd dup).
-            let prepStdout = { kind: 'caller' };
-            let prepStderr = { kind: 'caller' };
-            const emitPrepError = (msg) => emitToPrepDest(prepStderr, msg, prepFds, (s) => {
-                stderr += s;
+            let prepStdout = { kind: 'caller', fd: 1 };
+            let prepStderr = { kind: 'caller', fd: 2 };
+            const emitPrepError = (msg) => emitToPrepDest(prepStderr, msg, prepFds, {
+                stdout: (s) => {
+                    stdout += s;
+                },
+                stderr: (s) => {
+                    stderr += s;
+                },
             });
             for (const r of plan.redirects) {
-                if (r.op === '2>&1') {
-                    prepStderr = prepStdout;
-                    continue;
-                }
-                if (r.op === '1>&2') {
-                    prepStdout = prepStderr;
+                if (r.op === '2>&1' || r.op === '1>&2') {
+                    ({ stdout: prepStdout, stderr: prepStderr } = applyRedirectDest(r.op, undefined, prepStdout, prepStderr));
                     continue;
                 }
                 const target = resolveTarget(winTarget(r.target));
                 if (r.op === '<') {
+                    if (isNulPath(target))
+                        continue;
                     if (!existsSync(target)) {
                         emitPrepError('bash: ' + target + ': No such file or directory\n');
                         redirectPrepFailed = true;
@@ -357,33 +399,16 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
                     }
                     continue;
                 }
-                if (target === 'NUL') {
-                    if (r.op === '>' || r.op === '>>')
-                        prepStdout = { kind: 'nul' };
-                    else if (r.op === '2>' || r.op === '2>>')
-                        prepStderr = { kind: 'nul' };
-                    else if (r.op === '&>' || r.op === '&>>') {
-                        prepStdout = { kind: 'nul' };
-                        prepStderr = { kind: 'nul' };
+                if (!isNulPath(target)) {
+                    const append = r.op === '>>' || r.op === '2>>' || r.op === '&>>';
+                    const fail = prepareRedirectFile(target, append, prepFds);
+                    if (fail) {
+                        emitPrepError('bash: ' + fail + '\n');
+                        redirectPrepFailed = true;
+                        break;
                     }
-                    continue;
-                }
-                const append = r.op === '>>' || r.op === '2>>' || r.op === '&>>';
-                const fail = prepareRedirectFile(target, append, prepFds);
-                if (fail) {
-                    emitPrepError('bash: ' + fail + '\n');
-                    redirectPrepFailed = true;
-                    break;
-                }
-                const fileDest = { kind: 'file', path: target };
-                if (r.op === '>' || r.op === '>>')
-                    prepStdout = fileDest;
-                else if (r.op === '2>' || r.op === '2>>')
-                    prepStderr = fileDest;
-                else if (r.op === '&>' || r.op === '&>>') {
-                    prepStdout = fileDest;
-                    prepStderr = fileDest;
                 }
+                ({ stdout: prepStdout, stderr: prepStderr } = applyRedirectDest(r.op, target, prepStdout, prepStderr));
             }
             if (redirectPrepFailed) {
                 exitCode = 1;
@@ -406,11 +431,15 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
                 break;
             }
             const encoded = wrapScript(plan.body, { mode: 'host' });
+            // Last-stage fds last-win independently. `2>&1 >/dev/null` snapshots
+            // stderr onto the caller's stdout before stdout is pointed at NUL, so
+            // captured stderr is still returned; `>/dev/null 2>&1` points both at NUL.
+            const applyDests = lastStageOutputDests(plan.outputRedirects, resolveTarget);
             // Response budgets cap what the CALLER receives — streams redirected to
             // files must never be truncated by them (Codex-review P1: `printf … > f`
             // with a small stdoutLimit was writing a clipped file). The final
             // clipUtf8 below still enforces the returned-data budget.
-            const fileRedirected = !!(red.stdoutFile || red.stderrFile);
+            const fileRedirected = applyDests.stdout.kind === 'file' || applyDests.stderr.kind === 'file';
             const inv = await ensureHost().invoke(encoded, {
                 FAUXNIX_CWD: currentDir,
                 FAUXNIX_PREV_EXIT: session.prevExit === null ? '' : String(session.prevExit),
@@ -438,51 +467,45 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
             // GNU line discipline: the PS host terminates Write-Output lines with
             // CRLF. Exact writers (fx-write / printf / echo -n) must keep embedded
             // CR so `printf 'a\r\nb' > out` stays 4 bytes.
-            let segOut = normalizeHostNewlines(decodeOutput(inv.stdout, decodePref));
+            const segOut = normalizeHostNewlines(decodeOutput(inv.stdout, decodePref));
             let segErr = normalizeHostNewlines(normalizeStderr(decodeOutput(inv.stderr, decodePref)));
             if (inv.timedOut) {
                 segErr += timeoutMessage;
             }
-            if (red.mergeStderr) {
-                segOut += (segOut && !segOut.endsWith('\n') && segErr ? '\n' : '') + segErr;
-                segErr = '';
-            }
-            const stdoutToStderr = red.stdoutToStderr;
-            if (stdoutToStderr) {
-                segErr += segOut;
-                segOut = '';
-            }
-            const swallowStderr = red.swallowStderr;
-            if (swallowStderr)
-                segErr = '';
             // Write captured streams through the fds opened during preflight
             // (bash: the redirect refers to the open file, not the path). Reopening
             // the path would recreate a file the command just unlinked
             // (`rm out.txt > out.txt`).
             let redirectOk = true;
-            if (red.stdoutFile) {
-                try {
-                    writeToPrepFd(prepFds, red.stdoutFile, segOut);
-                    segOut = '';
-                }
-                catch (e) {
-                    segErr += 'bash: ' + red.stdoutFile + ': cannot create: ' + e.message + '\n';
-                    exitCode = 1;
-                    redirectOk = false;
-                }
-            }
-            if (red.stderrFile) {
-                try {
-                    const body = red.stderrFile === red.stdoutFile ? segOut + segErr : segErr;
-                    writeToPrepFd(prepFds, red.stderrFile, body);
-                    segErr = '';
-                }
-                catch {
-                    /* best effort */
+            const deliverCaptured = (dest, data, fromStdout) => {
+                if (!data)
+                    return;
+                if (dest.kind === 'nul')
+                    return;
+                if (dest.kind === 'file') {
+                    try {
+                        writeToPrepFd(prepFds, dest.path, data);
+                    }
+                    catch (e) {
+                        if (fromStdout) {
+                            stderr += 'bash: ' + dest.path + ': cannot create: ' + e.message + '\n';
+                            exitCode = 1;
+                            redirectOk = false;
+                            stdout += data;
+                        }
+                        else {
+                            stderr += data;
+                        }
+                    }
+                    return;
                 }
-            }
-            stdout += segOut;
-            stderr += segErr;
+                if (dest.fd === 1)
+                    stdout += data;
+                else
+                    stderr += data;
+            };
+            deliverCaptured(applyDests.stdout, segOut, true);
+            deliverCaptured(applyDests.stderr, segErr, false);
             if (inv.truncated)
                 truncated = true;
             exitCode = inv.timedOut ? 124 : inv.cancelled ? 130 : inv.exitCode;

package/dist/registry.d.ts

@@ -99,6 +99,8 @@ export interface CommandSpec {
     dispatch?: 'translated' | 'native' | 'dynamic';
     /** GNU usage/syntax exit (grep uses 2; cp/mv/rm use 1). */
     usageExit?: number;
+    /** First non-option operand ends option scanning (echo/printf). */
+    leadingOptions?: boolean;
     handler: Handler;
 }
 /** Register a spec'd command. Unknown/unsupported options become GNU-style usage errors. */

package/dist/registry.js

@@ -197,7 +197,8 @@ export function specsMarkdown() {
     for (const spec of registeredSpecs()) {
         lines.push('## `' + spec.names.join('` / `') + '`');
         lines.push('');
-        lines.push('Effects: ' + spec.effects.map((e) => '`' + e + '`').join(', '));
+        lines.push('Effects: ' +
+            (spec.effects.length ? spec.effects.map((e) => '`' + e + '`').join(', ') : 'none'));
         lines.push('');
         if (!spec.options.length) {
             lines.push('No options declared.');
@@ -319,6 +320,8 @@ export function specOptionError(spec, args, cmdName) {
             i++;
             continue;
         }
+        if (spec.leadingOptions)
+            onlyOperands = true;
         i++;
     }
     return null;

package/dist/translator.d.ts

@@ -84,8 +84,12 @@ export interface SegmentPlan {
     script: string;
     /** Pipeline body before wrapScript — executor host mode re-wraps this. */
     body: string;
-    /** All redirects collected from this segment (executor handles them). */
+    /** Every stage's redirects, in source order — executor prep (open/fail). */
     redirects: Redirect[];
+    /** Last-stage redirects — captured stdout/stderr apply / >/dev/null. */
+    outputRedirects: Redirect[];
+    /** First-stage `<` only — FAUXNIX_STDIN_FILE feed. */
+    stdinRedirects: Redirect[];
 }
 export declare function translateCommandList(list: CommandList): SegmentPlan[];
 export type WrapMode = 'spawn' | 'host';