fauxnix-cli 0.9.3 → 0.12.0

package/dist/errors.js

@@ -43,7 +43,7 @@ function unescapeClixml(t) {
         .trim();
 }
 /**
- * When stderr is redirected, powershell.exe serializes error records as
+ * When stderr is redirected, PowerShell can serialize error records as
  * CLIXML (`#< CLIXML` + XML). Unwrap the real message lines and drop
  * progress records, so agents see plain bash-style text.
  */
@@ -76,8 +76,10 @@ export function normalizeStderr(stderr) {
         let m = line.match(/^The term '(.+?)' is not recognized/);
         if (m)
             return commandNotFound(m[1]);
-        // zh-CN: 无法将"x"项识别为 cmdlet、函数、脚本文件或可运行程序的名称
-        m = line.match(/^无法将["'”]?([^"'”]+)["'”]?项识别为/);
+        // zh-CN: & : 无法将“x”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。
+        // Require the PowerShell-specific suffix so ordinary Chinese prose that
+        // happens to contain “无法将…项识别为” is not rewritten.
+        m = line.match(/^(?:\S+\s*:\s*)?无法将[“"'‘]?(.+?)[”"'’]?项识别为\s*cmdlet、函数、脚本文件或可运行程序的名称(?:。|$)/);
         if (m)
             return commandNotFound(m[1]);
         // "x : The term 'y' is not recognized ..." (with source prefix)
@@ -94,18 +96,26 @@ export function normalizeStderr(stderr) {
                 ': No such file or directory');
         }
         // zh-CN: "Get-Content : 找不到路径“X”，因为该路径不存在。"
-        m = line.match(/^(\S+)\s*:\s*找不到路径[“'"](.+?)[”'"]，因为该路径不存在\.?$/);
+        m = line.match(/^(\S+)\s*:\s*找不到路径[“"'‘](.+?)[”"'’]，因为该路径不存在[。.]?$/);
         if (m) {
             return m[1].toLowerCase() + ': ' + m[2].replace(/\\/g, '/') + ': No such file or directory';
         }
         // "cat : Cannot find drive. A drive with the name 'z' does not exist."
         m = line.match(/^(\S+)\s*:\s*Cannot find drive\..*name '(.+?)'.*$/);
+        if (m)
+            return m[1].toLowerCase() + ': ' + m[2] + ': No such file or directory';
+        // zh-CN: "Get-Content : 找不到驱动器。名为“Z”的驱动器不存在。"
+        m = line.match(/^(\S+)\s*:\s*找不到驱动器[。.]\s*名为[“"'‘](.+?)[”"'’]的驱动器不存在[。.]?$/);
         if (m)
             return m[1].toLowerCase() + ': ' + m[2] + ': No such file or directory';
         // "rm : Cannot remove item ... Access is denied"
         m = line.match(/^(\S+)\s*:\s*(.*)Access to the path '(.+?)' is denied\.?$/);
         if (m)
             return m[1].toLowerCase() + ': cannot remove \'' + m[3] + '\': Permission denied';
+        // zh-CN: "rm : 对路径“C:\\protected”的访问被拒绝。"
+        m = line.match(/^(\S+)\s*:\s*对路径[“"'‘](.+?)[”"'’]的访问被拒绝[。.]?$/);
+        if (m)
+            return m[1].toLowerCase() + ': cannot remove \'' + m[2] + '\': Permission denied';
         // leftover PS not-recognized lines that the rewrites above did not catch
         if (/\.sh'?/.test(line) && /is not recognized/.test(line)) {
             return line + SH_SCRIPT_WINDOWS_HINT;

package/dist/executor.d.ts

@@ -29,12 +29,15 @@ export declare class FauxnixSession {
     private hostFile;
     private host;
     private lifecycleLock;
+    /** True once `env` was loaded from the host's complete environment snapshot. */
+    private hasEnvSnapshot;
+    private readonly powerShell;
     constructor();
     private bindFiles;
     private withLock;
     private syncFromDisk;
     private ensureHost;
-    /** Boot powershell.exe now so the first run() is not the 1.1s cold start. */
+    /** Boot the selected PowerShell now so the first run() is not a cold start. */
     prewarm(): Promise<void>;
     dispose(): Promise<void>;
     /** Kill the host and re-prewarm the same session object (no second FauxnixSession). */

package/dist/executor.js

@@ -1,13 +1,35 @@
 import { randomUUID } from 'node:crypto';
-import { promises as fs, readFileSync, existsSync, openSync, closeSync, writeSync } from 'node:fs';
+import { promises as fs, readFileSync, existsSync, openSync, closeSync, readSync, rmSync, writeSync, } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { normalizeLiteralPath, wrapScript } from './translator.js';
-import { decodeOutput, normalizeHostNewlines, resolveNativePref } from './encoding.js';
+import { decodeOutput, resolveNativePref } from './encoding.js';
 import { normalizeStderr } from './errors.js';
-import { DEFAULT_STDERR_LIMIT, DEFAULT_STDOUT_LIMIT, PowerShellHost, PS_MISSING_MESSAGE, } from './ps-host.js';
+import { DEFAULT_STDERR_LIMIT, DEFAULT_STDOUT_LIMIT, PowerShellHost, } from './ps-host.js';
+import { resolvePowerShell } from './powershell.js';
 const DEFAULT_TIMEOUT_MS = 120_000;
 const DEFAULT_WINDOWS_PATHEXT = '.COM;.EXE;.BAT;.CMD';
+const MAX_HOST_CAPTURE_LIMIT = 0x7fffffff;
+const UTF8_BOUNDARY_SUFFIX = 4;
+const MAX_CALLER_OUTPUT_LIMIT = MAX_HOST_CAPTURE_LIMIT - UTF8_BOUNDARY_SUFFIX;
+function validateOutputLimit(name, value) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > MAX_CALLER_OUTPUT_LIMIT) {
+        throw new RangeError('fauxnix: ' + name + ' must be an integer from 0 to ' + MAX_CALLER_OUTPUT_LIMIT);
+    }
+    return value;
+}
+/**
+ * Retain one complete codepoint beyond the logical caller budget so Node can
+ * detect truncation and clip at a UTF-8 boundary. The host itself stays
+ * bounded even when the caller has no remaining budget.
+ */
+function rawHostCaptureLimit(logicalBytes) {
+    if (!Number.isFinite(logicalBytes)) {
+        return logicalBytes === Number.POSITIVE_INFINITY ? MAX_HOST_CAPTURE_LIMIT : 0;
+    }
+    const bytes = Math.max(0, Math.floor(logicalBytes));
+    return Math.min(MAX_HOST_CAPTURE_LIMIT, bytes + UTF8_BOUNDARY_SUFFIX);
+}
 function hasEnvKey(env, name) {
     const normalized = name.toUpperCase();
     return Object.keys(env).some((key) => key.toUpperCase() === normalized);
@@ -201,8 +223,12 @@ export class FauxnixSession {
     hostFile;
     host = null;
     lifecycleLock = Promise.resolve();
+    /** True once `env` was loaded from the host's complete environment snapshot. */
+    hasEnvSnapshot = false;
+    powerShell;
     constructor() {
         this.id = randomUUID().slice(0, 8);
+        this.powerShell = resolvePowerShell();
         this.bindFiles(this.id);
     }
     bindFiles(id) {
@@ -231,8 +257,10 @@ export class FauxnixSession {
         try {
             if (existsSync(this.envFile)) {
                 const raw = readFileSync(this.envFile, 'utf8');
-                if (raw.trim())
+                if (raw.trim()) {
                     this.env = JSON.parse(raw);
+                    this.hasEnvSnapshot = true;
+                }
             }
         }
         catch {
@@ -241,11 +269,11 @@ export class FauxnixSession {
     }
     ensureHost() {
         if (!this.host) {
-            this.host = new PowerShellHost(this.hostFile, () => this.childEnv());
+            this.host = new PowerShellHost(this.hostFile, () => this.childEnv(), this.powerShell);
         }
         return this.host;
     }
-    /** Boot powershell.exe now so the first run() is not the 1.1s cold start. */
+    /** Boot the selected PowerShell now so the first run() is not a cold start. */
     prewarm() {
         return this.withLock(async () => {
             await this.ensureHost().ready();
@@ -268,6 +296,7 @@ export class FauxnixSession {
         }
         this.cwd = null;
         this.env = {};
+        this.hasEnvSnapshot = false;
         this.prevExit = null;
         await Promise.allSettled([
             fs.rm(this.cwdFile, { force: true }),
@@ -279,12 +308,19 @@ export class FauxnixSession {
     }
     /** env for the child powershell process. */
     childEnv(cwdOverride, stdinFile) {
-        const env = { ...process.env };
-        for (const [k, v] of Object.entries(this.env)) {
-            if (v === undefined)
-                delete env[k];
-            else
-                env[k] = v;
+        // Before the first completed request, `env` contains optional caller
+        // overrides and is layered over the process baseline. Afterwards it is a
+        // complete snapshot written by the resident host. Restore that snapshot
+        // verbatim on transparent host restarts: merging it with process.env would
+        // resurrect inherited variables that the shell successfully unset.
+        const env = this.hasEnvSnapshot ? { ...this.env } : { ...process.env };
+        if (!this.hasEnvSnapshot) {
+            for (const [k, v] of Object.entries(this.env)) {
+                if (v === undefined)
+                    delete env[k];
+                else
+                    env[k] = v;
+            }
         }
         // The MCP SDK's safe Windows stdio environment omits PATHEXT. Without it,
         // PowerShell cannot resolve extensionless native commands such as `node`.
@@ -318,16 +354,70 @@ export class FauxnixSession {
 async function runPlans(plans, session, opts, afterSegment, ensureHost) {
     const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const deadline = Date.now() + timeoutMs;
-    const stdoutLimit = opts.stdoutLimit ?? DEFAULT_STDOUT_LIMIT;
-    const stderrLimit = opts.stderrLimit ?? DEFAULT_STDERR_LIMIT;
+    const stdoutLimit = validateOutputLimit('stdoutLimit', opts.stdoutLimit ?? DEFAULT_STDOUT_LIMIT);
+    const stderrLimit = validateOutputLimit('stderrLimit', opts.stderrLimit ?? DEFAULT_STDERR_LIMIT);
     const timeoutMessage = '\nbash: command timed out after ' + Math.round(timeoutMs / 1000) + 's';
     let stdout = '';
     let stderr = '';
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let stdoutClosed = false;
+    let stderrClosed = false;
     let exitCode = 0;
     let timedOut = false;
     let cancelled = false;
     let truncated = false;
     let spawnError;
+    const appendCaller = (fd, data) => {
+        if (!data)
+            return;
+        if (fd === 1 ? stdoutClosed : stderrClosed)
+            return;
+        const used = fd === 1 ? stdoutBytes : stderrBytes;
+        const limit = fd === 1 ? stdoutLimit : stderrLimit;
+        const clipped = clipUtf8(data, Math.max(0, limit - used));
+        if (fd === 1) {
+            stdout += clipped.text;
+            stdoutBytes += Buffer.byteLength(clipped.text, 'utf8');
+        }
+        else {
+            stderr += clipped.text;
+            stderrBytes += Buffer.byteLength(clipped.text, 'utf8');
+        }
+        if (clipped.truncated) {
+            if (fd === 1)
+                stdoutClosed = true;
+            else
+                stderrClosed = true;
+            truncated = true;
+        }
+    };
+    const remainingFor = (dest) => {
+        if (dest.kind !== 'caller')
+            return 0;
+        if (dest.fd === 1 ? stdoutClosed : stderrClosed)
+            return 0;
+        const limit = dest.fd === 1 ? stdoutLimit : stderrLimit;
+        const used = dest.fd === 1 ? stdoutBytes : stderrBytes;
+        return Math.max(0, limit - used);
+    };
+    const closeCallerDest = (dest) => {
+        if (dest.kind !== 'caller')
+            return;
+        if (dest.fd === 1)
+            stdoutClosed = true;
+        else
+            stderrClosed = true;
+    };
+    const hostStream = (dest) => {
+        if (dest.kind === 'file')
+            return { mode: 'spool', limit: 0 };
+        if (dest.kind === 'nul')
+            return { mode: 'discard', limit: 0 };
+        if (dest.fd === 1 ? stdoutClosed : stderrClosed)
+            return { mode: 'discard', limit: 0 };
+        return { mode: 'capture', limit: rawHostCaptureLimit(remainingFor(dest)) };
+    };
     // bash list semantics: `a && b ; c` runs c regardless of a; `a && b && c`
     // skips b AND c when a fails. chainOk models the value of the current
     // &&/|| chain; `;` segments always run and restart the chain.
@@ -350,7 +440,7 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
             break;
         }
         if (Date.now() >= deadline) {
-            stderr += timeoutMessage;
+            appendCaller(2, timeoutMessage);
             exitCode = 124;
             timedOut = true;
             session.prevExit = exitCode;
@@ -377,10 +467,10 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
             let prepStderr = { kind: 'caller', fd: 2 };
             const emitPrepError = (msg) => emitToPrepDest(prepStderr, msg, prepFds, {
                 stdout: (s) => {
-                    stdout += s;
+                    appendCaller(1, s);
                 },
                 stderr: (s) => {
-                    stderr += s;
+                    appendCaller(2, s);
                 },
             });
             for (const r of plan.redirects) {
@@ -424,7 +514,7 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
                 break;
             }
             if (remainingMs <= 0) {
-                stderr += timeoutMessage;
+                appendCaller(2, timeoutMessage);
                 exitCode = 124;
                 timedOut = true;
                 session.prevExit = exitCode;
@@ -435,20 +525,23 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
             // 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 = applyDests.stdout.kind === 'file' || applyDests.stderr.kind === 'file';
+            // Each source stream is bounded according to its final destination.
+            // A file keeps the complete stream, /dev/null retains nothing, and a
+            // caller stream receives only the budget left by earlier list segments.
+            const hostStdout = hostStream(applyDests.stdout);
+            const hostStderr = hostStream(applyDests.stderr);
             const inv = await ensureHost().invoke(encoded, {
                 FAUXNIX_CWD: currentDir,
                 FAUXNIX_PREV_EXIT: session.prevExit === null ? '' : String(session.prevExit),
                 FAUXNIX_STDIN_FILE: red.stdinFile || '',
-            }, remainingMs, opts.signal, fileRedirected
-                ? { stdoutLimit: 0, stderrLimit: 0 }
-                : { stdoutLimit, stderrLimit });
+            }, remainingMs, opts.signal, {
+                stdoutLimit: hostStdout.limit,
+                stderrLimit: hostStderr.limit,
+                stdoutMode: hostStdout.mode,
+                stderrMode: hostStderr.mode,
+            });
             if (inv.spawnError === 'ENOENT' || inv.spawnError === 'START') {
-                stderr += inv.stderr.toString('utf8') || PS_MISSING_MESSAGE;
+                appendCaller(2, inv.stderr.toString('utf8') || 'fauxnix: failed to start the selected PowerShell host\n');
                 exitCode = 127;
                 spawnError = inv.spawnError;
                 session.prevExit = exitCode;
@@ -464,11 +557,14 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
             }
             afterSegment();
             const decodePref = resolveNativePref();
-            // 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.
-            const segOut = normalizeHostNewlines(decodeOutput(inv.stdout, decodePref));
-            let segErr = normalizeHostNewlines(normalizeStderr(decodeOutput(inv.stderr, decodePref)));
+            // Captured protocol frames are always UTF-8. FAUXNIX_NATIVE_ENCODING is
+            // consumed at the native-process boundary inside fx-native; applying it
+            // again here double-decodes every translated/non-ASCII frame. Only bytes
+            // written directly to the host's OS stderr pipe retain a native encoding.
+            const segOut = decodeOutput(inv.stdout, 'utf8');
+            const framedErr = decodeOutput(inv.stderr, 'utf8');
+            const nativeErr = decodeOutput(inv.nativeStderr ?? Buffer.alloc(0), decodePref);
+            let segErr = normalizeStderr(framedErr + nativeErr);
             if (inv.timedOut) {
                 segErr += timeoutMessage;
             }
@@ -488,27 +584,53 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
                     }
                     catch (e) {
                         if (fromStdout) {
-                            stderr += 'bash: ' + dest.path + ': cannot create: ' + e.message + '\n';
+                            appendCaller(2, 'bash: ' + dest.path + ': cannot create: ' + e.message + '\n');
                             exitCode = 1;
                             redirectOk = false;
-                            stdout += data;
+                            appendCaller(1, data);
                         }
                         else {
-                            stderr += data;
+                            appendCaller(2, data);
                         }
                     }
                     return;
                 }
-                if (dest.fd === 1)
-                    stdout += data;
-                else
-                    stderr += data;
+                appendCaller(dest.fd, data);
             };
-            deliverCaptured(applyDests.stdout, segOut, true);
-            deliverCaptured(applyDests.stderr, segErr, false);
+            const deliverSpool = (dest, spool, fromStdout) => {
+                if (!spool)
+                    return;
+                if (dest.kind !== 'file') {
+                    throw new Error('fauxnix: host returned a spool for a non-file destination');
+                }
+                try {
+                    writeSpoolToPrepFd(prepFds, spool, dest.path);
+                }
+                catch (e) {
+                    appendCaller(2, 'bash: ' + dest.path + ': cannot write: ' + e.message + '\n');
+                    exitCode = 1;
+                    redirectOk = false;
+                }
+            };
+            const spools = [inv.stdoutSpool, inv.stderrSpool, inv.nativeStderrSpool].filter((file) => !!file);
+            try {
+                deliverCaptured(applyDests.stdout, segOut, true);
+                if (inv.stdoutTruncated)
+                    closeCallerDest(applyDests.stdout);
+                deliverCaptured(applyDests.stderr, segErr, false);
+                if (inv.stderrTruncated)
+                    closeCallerDest(applyDests.stderr);
+                deliverSpool(applyDests.stdout, inv.stdoutSpool, true);
+                deliverSpool(applyDests.stderr, inv.stderrSpool, false);
+                deliverSpool(applyDests.stderr, inv.nativeStderrSpool, false);
+            }
+            finally {
+                for (const spool of spools)
+                    rmSync(spool, { force: true });
+            }
             if (inv.truncated)
                 truncated = true;
-            exitCode = inv.timedOut ? 124 : inv.cancelled ? 130 : inv.exitCode;
+            exitCode = !redirectOk ? 1 : inv.timedOut ? 124 : inv.cancelled ? 130 : inv.exitCode;
             if (inv.timedOut)
                 timedOut = true;
             session.prevExit = exitCode;
@@ -525,13 +647,9 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
             closePrepFds(prepFds);
         }
     }
-    const clippedOut = clipUtf8(stdout, stdoutLimit);
-    const clippedErr = clipUtf8(stderr, stderrLimit);
-    if (clippedOut.truncated || clippedErr.truncated)
-        truncated = true;
     return {
-        stdout: clippedOut.text,
-        stderr: clippedErr.text,
+        stdout,
+        stderr,
         exitCode,
         timedOut,
         cancelled,
@@ -542,8 +660,33 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
 function clipUtf8(text, limit) {
     if (Buffer.byteLength(text, 'utf8') <= limit)
         return { text, truncated: false };
-    let end = text.length;
-    while (end > 0 && Buffer.byteLength(text.slice(0, end), 'utf8') > limit)
-        end--;
+    let used = 0;
+    let end = 0;
+    for (const codepoint of text) {
+        const size = Buffer.byteLength(codepoint, 'utf8');
+        if (used + size > limit)
+            break;
+        used += size;
+        end += codepoint.length;
+    }
     return { text: text.slice(0, end), truncated: true };
 }
+/** Copy a host spool into an already-open redirect fd with bounded memory. */
+function writeSpoolToPrepFd(fds, file, target) {
+    const outFd = fds.get(target);
+    if (outFd === undefined)
+        throw new Error('fauxnix: redirect fd missing for ' + target);
+    const inFd = openSync(file, 'r');
+    const input = Buffer.allocUnsafe(65_536);
+    try {
+        while (true) {
+            const n = readSync(inFd, input, 0, input.length, null);
+            if (n <= 0)
+                break;
+            writeAllSync(outFd, input.subarray(0, n));
+        }
+    }
+    finally {
+        closeSync(inFd);
+    }
+}

package/dist/install.d.ts

@@ -0,0 +1,15 @@
+export type InstallOptions = {
+    home?: string;
+    /** Accepted for parity with collectDoctorReport; install writes user-level configs only. */
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+};
+export type InstallReport = {
+    lines: string[];
+    ok: boolean;
+};
+export declare const INSTALL_FLAGS: readonly ["claude", "codex", "opencode", "kimi", "qwen"];
+export type HarnessName = (typeof INSTALL_FLAGS)[number];
+export declare function kimiConfigPath(home: string, env: NodeJS.ProcessEnv): string;
+export declare function qwenConfigPath(home: string, env: NodeJS.ProcessEnv): string;
+export declare function runInstall(argv: string[], opts?: InstallOptions): InstallReport;