fauxnix-cli 0.1.0 → 0.2.1

package/README.md

@@ -78,12 +78,15 @@ fauxnix ships an MCP stdio server exposing a `bash` tool (plus `fauxnix_translat
 claude mcp add fauxnix -- fauxnix mcp
 ```
 
-**Codex** (`~/.codex/config.toml`)
+**Codex** (`~/.codex/config.toml` or `codex mcp add fauxnix -- fauxnix mcp`)
 ```toml
 [mcp_servers.fauxnix]
 command = "fauxnix"
 args = ["mcp"]
 ```
+Note: in non-interactive `codex exec` mode, MCP tool calls are auto-denied by
+the approval layer; pass `--dangerously-bypass-approvals-and-sandbox` (or run
+interactively and approve once).
 
 **OpenCode** (`opencode.json`)
 ```json
@@ -94,6 +97,16 @@ args = ["mcp"]
 }
 ```
 
+**Kimi Code** — unlike the others, MCP servers live in a JSON file, not the
+TOML config: `~/.kimi-code/mcp.json`
+```json
+{
+  "mcpServers": {
+    "fauxnix": { "command": "fauxnix", "args": ["mcp"] }
+  }
+}
+```
+
 **Any MCP client** — stdio server: `fauxnix mcp`. The tool name is `bash` (override with
 `FAUXNIX_TOOL_NAME`). Tool description already teaches the model the supported subset, so no
 system-prompt changes are required.
@@ -160,6 +173,13 @@ fauxnix optimizes for the commands agents actually run. Documented deviations:
   "not supported" errors at translate time.
 - `curl`/`wget` refuse loopback/private/reserved addresses (localhost, 127.x, ::1, 10.x,
   172.16–31.x, 192.168.x, 169.254.x) as a safety default for agent-driven HTTP.
+- **Native-tool pipelines vs encoding**: PS 5.1 has a single console-encoding knob, so
+  piping localized admin tools (ipconfig, tasklist — GBK on zh-CN) and UTF-8-native dev
+  tools (node, curl) cannot both decode cleanly mid-pipeline. Default favors UTF-8 dev
+  tools; set `FAUXNIX_NATIVE_ENCODING=ansi` when your agents grep Chinese output of
+  native Windows admin tools. **File reads are always sniffed per file** (UTF-8 strict →
+  GBK fallback), so grep/sed/awk over GBK *files* works in either mode — unlike Git Bash,
+  which only matches the encoding its locale assumes.
 
 ## Development
 

package/dist/cli.js

@@ -26,7 +26,7 @@ export async function runCli(argv) {
     }
     const [verb, ...rest] = argv;
     if (verb === '--version' || verb === '-v') {
-        console.log('fauxnix 0.1.0');
+        console.log('fauxnix 0.2.1');
         return;
     }
     if (verb === 'list') {

package/dist/encoding.d.ts

@@ -1,7 +1,18 @@
 /**
- * Decode process output: UTF-8 first (we force UTF-8 in the wrapper),
- * with a GBK fallback for legacy native tools that ignore the codepage.
+ * How PowerShell decodes native tool output mid-pipeline. PS 5.1 has a single
+ * console-encoding knob, so GBK-native admin tools (ipconfig, tasklist, ...)
+ * and UTF-8-native dev tools (node, curl) cannot both decode cleanly:
+ *   utf8 (default) — dev tools exact; localized admin tools mojibake
+ *   ansi            — admin tools exact; dev tools' non-ASCII mojibake
+ * File reads are unaffected (fx-read byte-sniffs per file).
  */
-export declare function decodeOutput(buf: Buffer): string;
+export type NativeEncodingPref = 'utf8' | 'gbk';
+export declare function resolveNativePref(): NativeEncodingPref;
+/**
+ * Decode process output per the resolved preference. UTF-8 mode sniffs
+ * strictly first (so genuine UTF-8 never falls back); GBK mode trusts the
+ * setting (GBK decoding is lenient and cannot be validity-tested).
+ */
+export declare function decodeOutput(buf: Buffer, prefer?: NativeEncodingPref): string;
 /** Encode a PowerShell script for -EncodedCommand (UTF-16LE base64). */
 export declare function encodeCommand(script: string): string;

package/dist/encoding.js

@@ -1,12 +1,22 @@
 import iconv from 'iconv-lite';
 const strictUtf8 = new TextDecoder('utf-8', { fatal: true });
+export function resolveNativePref() {
+    return process.env.FAUXNIX_NATIVE_ENCODING === 'ansi' ? 'gbk' : 'utf8';
+}
 /**
- * Decode process output: UTF-8 first (we force UTF-8 in the wrapper),
- * with a GBK fallback for legacy native tools that ignore the codepage.
+ * Decode process output per the resolved preference. UTF-8 mode sniffs
+ * strictly first (so genuine UTF-8 never falls back); GBK mode trusts the
+ * setting (GBK decoding is lenient and cannot be validity-tested).
  */
-export function decodeOutput(buf) {
+export function decodeOutput(buf, prefer = 'utf8') {
     if (buf.length === 0)
         return '';
+    if (prefer === 'gbk') {
+        let s = iconv.decode(buf, 'gbk');
+        if (s.charCodeAt(0) === 0xfeff)
+            s = s.slice(1);
+        return s;
+    }
     try {
         let s = strictUtf8.decode(buf);
         if (s.charCodeAt(0) === 0xfeff)

package/dist/executor.js

@@ -4,7 +4,7 @@ import { promises as fs, readFileSync, writeFileSync, existsSync } from 'node:fs
 import os from 'node:os';
 import path from 'node:path';
 import { normalizeLiteralPath } from './translator.js';
-import { decodeOutput, encodeCommand } from './encoding.js';
+import { decodeOutput, encodeCommand, resolveNativePref } from './encoding.js';
 import { normalizeStderr } from './errors.js';
 const DEFAULT_TIMEOUT_MS = 120_000;
 const PS_ARGS = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass'];
@@ -160,16 +160,6 @@ export class FauxnixSession {
         return runPlans(plans, this, opts, () => this.syncFromDisk(), this.scriptFile);
     }
 }
-function killTree(pid) {
-    if (!pid)
-        return;
-    try {
-        spawn('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' });
-    }
-    catch {
-        /* best effort */
-    }
-}
 async function runPlans(plans, session, opts, afterSegment, scriptFile) {
     const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     let stdout = '';
@@ -224,7 +214,15 @@ async function runPlans(plans, session, opts, afterSegment, scriptFile) {
         child.stdin.end();
         const timer = setTimeout(() => {
             running.killed = true;
-            killTree(child.pid);
+            // Node-native termination — no external kill process, nothing injectable.
+            // Grandchildren of a timed-out script may survive; the `kill -9`/`pkill`
+            // builtins remain available for explicit Windows tree kills.
+            try {
+                child.kill();
+            }
+            catch {
+                /* best effort */
+            }
         }, timeoutMs);
         const code = await new Promise((resolve) => {
             child.on('error', (e) => {
@@ -235,8 +233,12 @@ async function runPlans(plans, session, opts, afterSegment, scriptFile) {
         });
         clearTimeout(timer);
         afterSegment();
-        let segOut = decodeOutput(Buffer.concat(outBufs));
-        let segErr = normalizeStderr(decodeOutput(Buffer.concat(errBufs)));
+        const decodePref = resolveNativePref();
+        // GNU line discipline: PowerShell's console layer terminates every line
+        // with CRLF; bash tools expect LF (redirect-written files and byte counts
+        // must match coreutils, e.g. `head -2 f > out.txt; wc -c out.txt`)
+        let segOut = decodeOutput(Buffer.concat(outBufs), decodePref).replace(/\r\n/g, '\n');
+        let segErr = normalizeStderr(decodeOutput(Buffer.concat(errBufs), decodePref)).replace(/\r\n/g, '\n');
         if (running.killed) {
             segErr += '\nbash: command timed out after ' + Math.round(timeoutMs / 1000) + 's';
         }

package/dist/mcp.js

@@ -7,19 +7,19 @@ import { translateCommandList, wrapScript, translatePipelineBody } from './trans
 import { registeredNames } from './registry.js';
 import './commands/install-all.js';
 const TOOL_NAME = process.env.FAUXNIX_TOOL_NAME || 'bash';
-const TOOL_DESCRIPTION = `Execute a Linux/bash-style command on this Windows machine.
-
-Commands are deterministically translated to PowerShell and executed natively — no WSL or VM.
-Output is formatted to look like GNU/Linux tooling (ls -l, ps aux, df -h ...), errors look like bash errors, and text encoding (UTF-8/GBK) is handled automatically.
-
-Supported: pipes (|), && / || / ;, redirections (> >> 2> 2>&1 < /dev/null), variables ($VAR $HOME ~), command substitution $(...), and ${registeredNames().length}+ coreutils-style commands (${registeredNames().slice(0, 18).join(', ')}...).
-Unknown commands (git, node, npm, python, cargo...) are passed through and executed natively with argv-style quoting.
-Not supported: heredocs, backticks, control flow (if/for/while), background jobs.
-
-CWD, environment variables, export/unset and cd persist across calls within this session.
+const TOOL_DESCRIPTION = `Execute a Linux/bash-style command on this Windows machine.
+
+Commands are deterministically translated to PowerShell and executed natively — no WSL or VM.
+Output is formatted to look like GNU/Linux tooling (ls -l, ps aux, df -h ...), errors look like bash errors, and text encoding (UTF-8/GBK) is handled automatically.
+
+Supported: pipes (|), && / || / ;, redirections (> >> 2> 2>&1 < /dev/null), variables ($VAR $HOME ~), command substitution $(...), and ${registeredNames().length}+ coreutils-style commands (${registeredNames().slice(0, 18).join(', ')}...).
+Unknown commands (git, node, npm, python, cargo...) are passed through and executed natively with argv-style quoting.
+Not supported: heredocs, backticks, control flow (if/for/while), background jobs.
+
+CWD, environment variables, export/unset and cd persist across calls within this session — but prefer COMBINING related commands in one call with ; or && (e.g. 'cd src && ls | wc -l'); each call is a fresh translation+process, so batching is faster than many tiny calls.
 Exit codes follow bash conventions (0 ok, 1 fail, 2 usage/serious, 127 command not found, 124 timeout).`;
 export async function startMcpServer() {
-    const server = new McpServer({ name: 'fauxnix', version: '0.1.0' }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: 'fauxnix', version: '0.2.1' }, { capabilities: { tools: {} } });
     const session = new FauxnixSession();
     server.tool(TOOL_NAME, TOOL_DESCRIPTION, {
         command: z.string().describe('The bash-style command line to run'),

package/dist/translator.js

@@ -272,9 +272,16 @@ export function wrapScript(body) {
         '$fx_exit = 0',
         '$fx_prev = 0',
         'if ($env:FAUXNIX_PREV_EXIT) { try { $fx_prev = [int]$env:FAUXNIX_PREV_EXIT } catch { $fx_prev = 0 } }',
-        'try { [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 } catch {}',
+        // single console-encoding knob in PS 5.1: ansi mode decodes GBK-native
+        // admin tools correctly, utf8 mode decodes UTF-8-native dev tools
+        // (see encoding.ts — file reads sniff per file and are always right)
+        "if ($env:FAUXNIX_NATIVE_ENCODING -eq 'ansi') {",
+        "  try { [Console]::OutputEncoding = [System.Text.Encoding]::GetEncoding(936) } catch {}",
+        '} else {',
+        '  try { [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 } catch {}',
+        '  try { chcp 65001 > $null } catch {}',
+        '}',
         '$OutputEncoding = [System.Text.Encoding]::UTF8',
-        'try { chcp 65001 > $null } catch {}',
         'if ($env:FAUXNIX_CWD) { try { Set-Location -LiteralPath $env:FAUXNIX_CWD } catch {} }',
         // capture AFTER the session cwd is applied — OLDPWD must refer to the
         // shell's previous directory, not the host process' startup directory

package/package.json

@@ -1,57 +1,58 @@
-{
-  "name": "fauxnix-cli",
-  "version": "0.1.0",
-  "description": "Fauxnix — run Linux-style commands on Windows via deterministic PowerShell translation. No VM, no WSL. MCP server + CLI for AI agents.",
-  "type": "module",
-  "bin": {
-    "fauxnix": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "dev": "tsx src/index.ts"
-  },
-  "keywords": [
-    "bash",
-    "powershell",
-    "translate",
-    "translator",
-    "linux",
-    "windows",
-    "mcp",
-    "mcp-server",
-    "ai-agent",
-    "claude-code",
-    "codex",
-    "opencode",
-    "shell",
-    "gbk",
-    "utf8"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/20000419/fauxnix.git"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "iconv-lite": "^0.6.3",
-    "zod": "^3.24.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.14.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.5.0",
-    "vitest": "^2.1.0"
-  }
-}
+{
+  "name": "fauxnix-cli",
+  "version": "0.2.1",
+  "description": "Fauxnix — run Linux-style commands on Windows via deterministic PowerShell translation. No VM, no WSL. MCP server + CLI for AI agents.",
+  "type": "module",
+  "bin": {
+    "fauxnix": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx src/index.ts"
+  },
+  "keywords": [
+    "bash",
+    "powershell",
+    "translate",
+    "translator",
+    "linux",
+    "windows",
+    "mcp",
+    "mcp-server",
+    "ai-agent",
+    "claude-code",
+    "codex",
+    "opencode",
+    "kimi-code",
+    "shell",
+    "gbk",
+    "utf8"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/20000419/fauxnix.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "iconv-lite": "^0.6.3",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.0"
+  }
+}