fauxnix-cli 0.4.0 → 0.4.2

package/README.md

@@ -1,5 +1,11 @@
 # fauxnix
 
+[![CI](https://github.com/20000419/fauxnix/actions/workflows/ci.yml/badge.svg)](https://github.com/20000419/fauxnix/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/fauxnix-cli.svg)](https://www.npmjs.com/package/fauxnix-cli)
+[![npm downloads](https://img.shields.io/npm/dt/fauxnix-cli.svg)](https://www.npmjs.com/package/fauxnix-cli)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![20000419/fauxnix MCP server](https://glama.ai/mcp/servers/20000419/fauxnix/badges/score.svg)](https://glama.ai/mcp/servers/20000419/fauxnix)
+
 **Run Linux-style commands on Windows — natively, deterministically, with no VM and no WSL.**
 
 fauxnix is a bash→PowerShell translation layer built for AI agents. Your agent keeps writing the
@@ -8,15 +14,37 @@ fauxnix deterministically translates each command into PowerShell, executes it n
 back output that looks like GNU/Linux: `ls -l` columns, bash-style error messages, coreutils exit
 codes, UTF-8/GBK handled automatically.
 
+```bash
+npm install -g fauxnix-cli    # then point any MCP harness at `fauxnix mcp`
+```
+
+![fauxnix demo](docs/assets/demo.svg)
+
 ```
 $ fauxnix "ls -la src | head -2"
 -rw-r--r-- 1 me me 1204 Aug 16 09:12 ast.ts
--rw-r--r-- 1 me me  8192 Aug 16 09:12 cli.ts
+-rw-r--r-- 1 me me 8192 Aug 16 09:12 cli.ts
 
 $ fauxnix "cat nope.txt"
 cat: nope.txt: No such file or directory        # not a PowerShell stack trace
 ```
 
+## Measured: your model is probably worse at PowerShell than you think
+
+Same model (DeepSeek-V4-Pro), same 5 tasks, three execution modes on one Windows machine —
+full data in [`docs/benchmark-deepseek-v4-pro.md`](docs/benchmark-deepseek-v4-pro.md) and
+[`docs/benchmark-ark-models.md](docs/benchmark-ark-models.md):
+
+| | PowerShell | **fauxnix** | Git Bash |
+|---|---|---|---|
+| tool calls / unexpected errors | 14 / 9 | **7 / 0** | 4 / 0 |
+| time (T1–T4) | 163s | **66s** | 57s |
+
+Across 7 models on the Volcano Ark Coding Plan, the PowerShell-vs-fauxnix gap held for every
+model tested — worst case (kimi-k2-thinking): **3.1× slower with 24 error events** writing
+PowerShell vs zero errors through fauxnix. fauxnix lands within ~15% of the real-bash ceiling
+with no bash toolchain installed.
+
 ## Why
 
 LLM agents are dramatically better at bash than at PowerShell — bash dominates training data, so

package/dist/executor.js

@@ -350,7 +350,15 @@ async function runPlans(plans, session, opts, afterSegment, scriptFile) {
             }, timeoutMs);
             const code = await new Promise((resolve) => {
                 child.on('error', (e) => {
-                    stderr += 'fauxnix: failed to start powershell.exe: ' + e.message + '\n';
+                    if (e.code === 'ENOENT') {
+                        stderr +=
+                            'fauxnix: powershell.exe not found — fauxnix executes bash via native Windows PowerShell 5.1+.\n' +
+                                'This host has no PowerShell on PATH (typical for Linux containers/sandboxes).\n' +
+                                'Run fauxnix on Windows, or install PowerShell and make powershell.exe reachable on PATH.\n';
+                    }
+                    else {
+                        stderr += 'fauxnix: failed to start powershell.exe: ' + e.message + '\n';
+                    }
                     resolve(127);
                 });
                 child.on('close', (c) => resolve(running.killed ? 124 : (c ?? 0)));

package/dist/mcp.js

@@ -1,12 +1,35 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import { FauxnixSession } from './executor.js';
 import { parseCommand } from './parser.js';
 import { translateCommandList, wrapScript, translatePipelineBody } from './translator.js';
 import { registeredNames } from './registry.js';
 import './commands/install-all.js';
+// single source of truth: the npm package version in package.json
+// (src/ and dist/ sit one level below the root, so the relative path holds in both)
+const pkgVersion = JSON.parse(readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8')).version;
 const TOOL_NAME = process.env.FAUXNIX_TOOL_NAME || 'bash';
+const EXEC_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+const TRANSLATE_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+const SESSION_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
 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.
@@ -17,9 +40,11 @@ Unknown commands (git, node, npm, python, cargo...) are passed through and execu
 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).`;
+Exit codes follow bash conventions (0 ok, 1 fail, 2 usage/serious, 127 command not found, 124 timeout).
+
+Platform requirement: the execution backend is native Windows PowerShell 5.1+. On hosts without PowerShell on PATH (e.g. Linux containers/sandboxes), the bash tool returns exit code 127 with an actionable error instead of running the command.`;
 export async function startMcpServer() {
-    const server = new McpServer({ name: 'fauxnix', version: '0.4.0' }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: 'fauxnix', version: pkgVersion }, { capabilities: { tools: {} } });
     const session = new FauxnixSession();
     server.tool(TOOL_NAME, TOOL_DESCRIPTION, {
         command: z.string().describe('The bash-style command line to run'),
@@ -30,7 +55,7 @@ export async function startMcpServer() {
             .max(600_000)
             .optional()
             .describe('Timeout in milliseconds (default 120000)'),
-    }, async ({ command, timeout_ms }) => {
+    }, EXEC_ANNOTATIONS, async ({ command, timeout_ms }) => {
         try {
             const plans = translateCommandList(parseCommand(command));
             const result = await session.run(plans, { timeoutMs: timeout_ms });
@@ -49,7 +74,7 @@ export async function startMcpServer() {
             return { content: [{ type: 'text', text: msg }], isError: true };
         }
     });
-    server.tool('fauxnix_translate', 'Translate a bash-style command into the equivalent PowerShell script WITHOUT executing it. Useful for learning/debugging what fauxnix does under the hood.', { command: z.string() }, async ({ command }) => {
+    server.tool('fauxnix_translate', 'Translate a bash-style command into the equivalent PowerShell script WITHOUT executing it. Useful for learning/debugging what fauxnix does under the hood.', { command: z.string().describe('The bash-style command line to translate (never executed)') }, TRANSLATE_ANNOTATIONS, async ({ command }) => {
         try {
             const list = parseCommand(command);
             const plans = translateCommandList(list);
@@ -61,7 +86,12 @@ export async function startMcpServer() {
             return { content: [{ type: 'text', text: msg }], isError: true };
         }
     });
-    server.tool('fauxnix_session', 'Inspect or reset the persistent fauxnix shell session (current directory, environment, session id). Actions: "status" (default) or "reset".', { action: z.enum(['status', 'reset']).default('status') }, async ({ action }) => {
+    server.tool('fauxnix_session', 'Inspect or reset the persistent fauxnix shell session (current directory, environment, session id). Actions: "status" (default) or "reset".', {
+        action: z
+            .enum(['status', 'reset'])
+            .default('status')
+            .describe('"status" shows the session state (cwd, tracked env keys); "reset" clears it back to a fresh shell'),
+    }, SESSION_ANNOTATIONS, async ({ action }) => {
         if (action === 'reset') {
             await session.dispose();
             return { content: [{ type: 'text', text: 'fauxnix: session reset' }] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fauxnix-cli",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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": {
@@ -53,6 +53,6 @@
     "@types/node": "^20.14.0",
     "tsx": "^4.19.0",
     "typescript": "^5.5.0",
-    "vitest": "^2.1.0"
+    "vitest": "3.2.6"
   }
 }