fauxnix-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 20000419
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# 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
+bash it already knows (`ls -la | grep foo`, `find . -name '*.ts' | wc -l`, `kill -9 1234`), and
+fauxnix deterministically translates each command into PowerShell, executes it natively, and hands
+back output that looks like GNU/Linux: `ls -l` columns, bash-style error messages, coreutils exit
+codes, UTF-8/GBK handled automatically.
+
+```
+$ 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
+
+$ fauxnix "cat nope.txt"
+cat: nope.txt: No such file or directory        # not a PowerShell stack trace
+```
+
+## Why
+
+LLM agents are dramatically better at bash than at PowerShell — bash dominates training data, so
+models on Windows often produce "looks right, doesn't run" commands (wrong quoting, `curl` that
+isn't curl, mojibake from codepage mismatches, inscrutable `CategoryInfo` error dumps). Existing
+solutions are either a full VM (WSL — heavy, wrong filesystem, separate environment) or plain
+shell wrappers (still PowerShell underneath).
+
+fauxnix takes the third road: **translate, don't emulate**. A large, high-value subset of the
+Linux command line — file ops, text processing, process management, archives, networking basics —
+maps cleanly onto PowerShell + .NET. fauxnix implements that subset faithfully and *fails loudly
+and helpfully* on what it can't translate, so the agent never gets silently-wrong results.
+
+## Install
+
+```bash
+npm install -g fauxnix-cli
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/20000419/fauxnix && cd fauxnix && npm install -g .
+```
+
+> npm package name is `fauxnix-cli` (the `fauxnix` name on npm belongs to an
+> unrelated 2015 websocket library); the installed command is still `fauxnix`.
+
+Requires: Windows with PowerShell 5.1+ (built-in) and Node.js ≥ 18.
+
+## Quick start
+
+```bash
+# one-off commands
+fauxnix "ls -la"
+fauxnix "grep -rn TODO src | wc -l"
+fauxnix "cat log.txt | grep -i error | sort | uniq -c"
+
+# see what a command becomes (great for debugging / learning PS)
+fauxnix translate "find . -name '*.log' -mtime +7 -delete"
+
+# check your environment
+fauxnix check
+
+# run the MCP stdio server (what agent harnesses connect to)
+fauxnix mcp
+```
+
+Unknown commands (git, node, npm, python, cargo, gh, docker, ...) are **passed through natively**
+with argv-style quoting — no string re-parsing, no quoting bugs.
+
+## Use with your agent harness
+
+fauxnix ships an MCP stdio server exposing a `bash` tool (plus `fauxnix_translate` and
+`fauxnix_session`). Point any MCP-capable harness at it:
+
+**Claude Code**
+```bash
+claude mcp add fauxnix -- fauxnix mcp
+```
+
+**Codex** (`~/.codex/config.toml`)
+```toml
+[mcp_servers.fauxnix]
+command = "fauxnix"
+args = ["mcp"]
+```
+
+**OpenCode** (`opencode.json`)
+```json
+{
+  "mcp": {
+    "fauxnix": { "type": "local", "command": ["fauxnix", "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.
+
+The MCP session persists `cwd`, environment variables, `export`/`unset` and `cd -`/OLDPWD across
+tool calls — it behaves like a logged-in shell, not a stateless `exec`.
+
+## What's translated
+
+~105 commands, all output-matched against real GNU coreutils on Windows (Git Bash) during
+development:
+
+- **files**: `ls cp mv rm mkdir rmdir touch mktemp ln readlink realpath basename dirname stat file du df find chmod chown diff`
+- **text filters**: `grep egrep sed awk sort uniq cut tr` — sed/awk scripts are parsed at
+  translate time (unsupported constructs throw named errors, never silently misbehave)
+- **text I/O**: `echo printf cat head tail wc tee nl tac md5sum sha1sum sha256sum base64 seq yes xargs`
+- **shell/system**: `cd pwd export unset env printenv ps kill pkill pgrep sleep which type whoami
+  id groups date uname hostname uptime free nproc clear true false test [ : pushd popd dirs sudo
+  timeout man history less more source . eval exit alias set`
+- **network**: `curl wget ping netstat ss ip ifconfig nslookup dig host`
+- **archives**: `tar gzip gunzip zcat zip unzip`
+
+Plus shell syntax: pipes, `&&` / `||` / `;`, redirections (`> >> 2> 2>&1 < &>`, `/dev/null`),
+quoting, `$VAR` `$(...)` command substitution, `VAR=x cmd` prefixes, `~` expansion, and
+POSIX-style path normalization (`/tmp`, `/d/foo` → `D:\foo`).
+
+Exit codes follow bash conventions: 0 ok, 1 fail, 2 usage/serious, 127 command not found,
+124 timeout.
+
+## How it works
+
+```
+bash command ──parser──▶ AST ──translator──▶ PowerShell script ──executor──▶ powershell.exe
+                                                                              │
+agent ◀── GNU-style output, bash-style errors ◀── decoder (UTF-8 → GBK fallback) ◀┘
+```
+
+- **Deterministic translation, zero LLM calls** at runtime.
+- Each command maps to a generator that emits a self-contained PowerShell block honoring the
+  "Fauxnix contract": string-per-line stdout, `[Console]::Error.WriteLine` for bash-style
+  stderr, `$script:fx_exit` for exit codes, `$input` for stdin.
+- The executor wraps every script with UTF-8 enforcement (`[Console]::OutputEncoding`,
+  `$OutputEncoding`, `chcp 65001`), decodes output as strict-UTF-8 with a GBK(936) fallback for
+  legacy native tools, strips CLIXML serialization and PowerShell noise from stderr, and rewrites
+  common PowerShell errors (including zh-CN locale messages) into bash phrasing.
+- Scripts run via `-EncodedCommand` (UTF-16LE) and transparently fall back to a temp `.ps1` file
+  when the 32 KB command-line limit would be exceeded.
+
+## Known deviations (honest list)
+
+fauxnix optimizes for the commands agents actually run. Documented deviations:
+
+- `yes` is capped at 65,536 lines — PS 5.1 pipelines cannot signal upstream producers to stop, so
+  an unbounded `yes | head` would hang.
+- `tail -f`, `source`, `eval`, `alias`, heredocs, backticks, shell control flow (`if`/`for`/`while`)
+  and background `&` are rejected with actionable error messages instead of misbehaving.
+- `chmod` maps only the read-only bit; exec bits are no-ops on Windows. `chown` is a silent no-op
+  (as in Git Bash).
+- `ps aux` columns are approximations (no per-process CPU% accounting, USER shows `?`).
+- `gzip -c`/pipeline stdin is text-faithful, not byte-faithful; file-mode `gzip f` is byte-exact.
+- A pipeline producing exactly one line, piped into `wc -l`, counts that line (bash would count 0
+  if the producer omitted the trailing newline). `printf 'x' | md5sum` stays byte-exact.
+- `sed`/`awk` support the common subset; hold-space, labels, arrays, loops throw named
+  "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.
+
+## Development
+
+```bash
+npm install
+npm test          # unit + real-PowerShell integration suite (Windows only, auto-skipped elsewhere)
+npm run build
+npx tsx scratch/run.mjs "any bash command"   # quick live check
+```
+
+Architecture map: `src/parser.ts` (bash subset → AST) · `src/translator.ts` (AST → PowerShell +
+executor wrapper) · `src/executor.ts` (spawn, redirects, session persistence) ·
+`src/commands/*.ts` (per-command generators) · `src/mcp.ts` (MCP server) · `src/cli.ts`.
+
+## License
+
+MIT © 20000419

package/dist/ast.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Fauxnix AST — a pragmatic subset of POSIX/bash command syntax.
+ *
+ * Supported:
+ *   - pipelines:            cmd1 | cmd2 | cmd3
+ *   - lists:                cmd1 ; cmd2 && cmd3 || cmd4   (newlines act as ';')
+ *   - redirections:         > >> 2> 2>> &> 2>&1 1>&2 <
+ *   - quoting:              'literal'  "interp $VAR $(cmd)"
+ *   - variables:            $VAR ${VAR} plus special cases ($HOME $USER $PATH ...)
+ *   - command substitution: $(...) (recursively translated)
+ *   - env assignment prefix: VAR=value cmd
+ *
+ * Explicitly unsupported (parser throws a helpful FauxnixError):
+ *   heredocs, backticks, subshells (...), background &, control flow
+ *   (if/for/while), globs inside quotes, process substitution <(...).
+ */
+export interface CommandList {
+    kind: 'CommandList';
+    segments: ListSegment[];
+}
+/** One pipeline plus the operator that connects it to the *previous* segment. */
+export interface ListSegment {
+    pipeline: Pipeline;
+    /** ';' for the first segment, otherwise the operator seen before this one. */
+    op: ';' | '&&' | '||';
+}
+export interface Pipeline {
+    kind: 'Pipeline';
+    commands: SimpleCommand[];
+}
+export interface SimpleCommand {
+    kind: 'SimpleCommand';
+    /** `VAR=value` prefixes before the command name. */
+    assignments: Assignment[];
+    name: Word;
+    args: Word[];
+    redirects: Redirect[];
+}
+export interface Assignment {
+    name: string;
+    value: Word;
+}
+export type RedirectOp = '>' | '>>' | '2>' | '2>>' | '&>' | '&>>' | '2>&1' | '1>&2' | '<';
+export interface Redirect {
+    op: RedirectOp;
+    /** Target path (words are already flattened; no vars in v1 targets except $VAR which is kept raw). */
+    target: string;
+}
+/** A word is a sequence of parts that concatenate into one argument. */
+export type Word = WordPart[];
+export type WordPart = {
+    kind: 'Text';
+    text: string;
+} | {
+    kind: 'SingleQuoted';
+    text: string;
+} | {
+    kind: 'DoubleQuoted';
+    parts: WordPart[];
+} | {
+    kind: 'Var';
+    name: string;
+} | {
+    kind: 'CmdSub';
+    cmd: string;
+};
+export declare function wordToString(w: Word): string;
+/** Best-effort "raw literal" view: is this word free of interpolation? */
+export declare function isLiteralWord(w: Word): boolean;
+export declare class FauxnixParseError extends Error {
+    constructor(message: string);
+}

package/dist/ast.js

@@ -0,0 +1,43 @@
+/**
+ * Fauxnix AST — a pragmatic subset of POSIX/bash command syntax.
+ *
+ * Supported:
+ *   - pipelines:            cmd1 | cmd2 | cmd3
+ *   - lists:                cmd1 ; cmd2 && cmd3 || cmd4   (newlines act as ';')
+ *   - redirections:         > >> 2> 2>> &> 2>&1 1>&2 <
+ *   - quoting:              'literal'  "interp $VAR $(cmd)"
+ *   - variables:            $VAR ${VAR} plus special cases ($HOME $USER $PATH ...)
+ *   - command substitution: $(...) (recursively translated)
+ *   - env assignment prefix: VAR=value cmd
+ *
+ * Explicitly unsupported (parser throws a helpful FauxnixError):
+ *   heredocs, backticks, subshells (...), background &, control flow
+ *   (if/for/while), globs inside quotes, process substitution <(...).
+ */
+export function wordToString(w) {
+    return w.map(partToString).join('');
+}
+function partToString(p) {
+    switch (p.kind) {
+        case 'Text':
+            return p.text;
+        case 'SingleQuoted':
+            return p.text;
+        case 'DoubleQuoted':
+            return p.parts.map(partToString).join('');
+        case 'Var':
+            return `$${p.name}`;
+        case 'CmdSub':
+            return '$(' + p.cmd + ')';
+    }
+}
+/** Best-effort "raw literal" view: is this word free of interpolation? */
+export function isLiteralWord(w) {
+    return w.every((p) => p.kind === 'Text' || p.kind === 'SingleQuoted');
+}
+export class FauxnixParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FauxnixParseError';
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+import './commands/install-all.js';
+export declare function runCli(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,91 @@
+import { spawn } from 'node:child_process';
+import { FauxnixSession } from './executor.js';
+import { parseCommand } from './parser.js';
+import { translateCommandList } from './translator.js';
+import { registeredNames } from './registry.js';
+import { encodeCommand } from './encoding.js';
+import { startMcpServer } from './mcp.js';
+import './commands/install-all.js';
+const USAGE = `fauxnix — run Linux-style commands on Windows via PowerShell translation
+
+Usage:
+  fauxnix "ls -la | head -5"        translate + execute a bash-style command
+  fauxnix -c "cmd"                   same as above
+  fauxnix translate "cmd"            show the PowerShell translation only
+  fauxnix mcp                        start the MCP stdio server (for agent harnesses)
+  fauxnix list                       list translated commands
+  fauxnix check                      verify the local PowerShell environment
+  fauxnix --version
+
+Notes:
+  Unknown commands (git, node, npm, python, cargo, ...) pass through and run natively.`;
+export async function runCli(argv) {
+    if (argv.length === 0) {
+        console.log(USAGE);
+        return;
+    }
+    const [verb, ...rest] = argv;
+    if (verb === '--version' || verb === '-v') {
+        console.log('fauxnix 0.1.0');
+        return;
+    }
+    if (verb === 'list') {
+        const names = registeredNames();
+        console.log(names.length + ' translated commands:');
+        for (const n of names)
+            console.log('  ' + n);
+        console.log('\nAnything else (git, node, npm, python, cargo, ...) is passed through natively.');
+        return;
+    }
+    if (verb === 'check') {
+        await runCheck();
+        return;
+    }
+    if (verb === 'mcp') {
+        await startMcpServer();
+        return;
+    }
+    if (verb === 'translate') {
+        const cmd = rest.join(' ');
+        const list = parseCommand(cmd);
+        const plans = translateCommandList(list);
+        console.log(plans.map((p) => p.script).join('\n# ---- next segment ----\n'));
+        return;
+    }
+    const cmd = verb === '-c' || verb === '-e' ? rest.join(' ') : argv.join(' ');
+    if (!cmd.trim()) {
+        console.log(USAGE);
+        return;
+    }
+    const list = parseCommand(cmd);
+    const plans = translateCommandList(list);
+    const session = new FauxnixSession();
+    const result = await session.run(plans);
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    await session.dispose();
+    process.exit(result.exitCode);
+}
+const PS_ARGS = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass'];
+async function runCheck() {
+    console.log('powershell : powershell.exe (Windows built-in)');
+    const probeCmd = '$PSVersionTable.PSVersion.ToString()';
+    const probe = spawn('powershell.exe', [...PS_ARGS, '-EncodedCommand', encodeCommand(probeCmd)], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+    });
+    let out = '';
+    probe.stdout.on('data', (d) => (out += d.toString('utf8')));
+    const code = await new Promise((resolve) => probe.on('close', (c) => resolve(c ?? 1)));
+    if (code === 0) {
+        console.log('version    : ' + out.trim());
+        console.log('commands   : ' + registeredNames().length + ' translated, others pass through');
+        console.log('status     : OK');
+    }
+    else {
+        console.error('status     : FAILED to run powershell.exe');
+        process.exitCode = 1;
+    }
+}

package/dist/commands/archive.d.ts

@@ -0,0 +1,2 @@
+import { Handler } from '../registry.js';
+export declare const handlers: Record<string, Handler>;