fauxnix-cli 0.1.0

package/dist/encoding.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+export declare function decodeOutput(buf: Buffer): string;
+/** Encode a PowerShell script for -EncodedCommand (UTF-16LE base64). */
+export declare function encodeCommand(script: string): string;

package/dist/encoding.js

@@ -0,0 +1,29 @@
+import iconv from 'iconv-lite';
+const strictUtf8 = new TextDecoder('utf-8', { fatal: true });
+/**
+ * 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.
+ */
+export function decodeOutput(buf) {
+    if (buf.length === 0)
+        return '';
+    try {
+        let s = strictUtf8.decode(buf);
+        if (s.charCodeAt(0) === 0xfeff)
+            s = s.slice(1);
+        return s;
+    }
+    catch {
+        // not valid UTF-8 — assume the console ANSI codepage (GBK on zh-CN)
+        try {
+            return iconv.decode(buf, 'gbk');
+        }
+        catch {
+            return buf.toString('utf8');
+        }
+    }
+}
+/** Encode a PowerShell script for -EncodedCommand (UTF-16LE base64). */
+export function encodeCommand(script) {
+    return Buffer.from(script, 'utf16le').toString('base64');
+}

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Error normalization — make PowerShell failures look like bash failures
+ * so agents can pattern-match on familiar Linux error styles.
+ */
+export declare function normalizeStderr(stderr: string): string;

package/dist/errors.js

@@ -0,0 +1,103 @@
+/**
+ * Error normalization — make PowerShell failures look like bash failures
+ * so agents can pattern-match on familiar Linux error styles.
+ */
+/** Lines produced by PowerShell error formatting that bash would never show. */
+const PS_NOISE = [
+    /^\s*\+ CategoryInfo\s*:/,
+    /^\s*\+ FullyQualifiedErrorId\s*:/,
+    /^\s*\+ .*\.ps1:? line \d+/,
+    /^At line:\d+ char:\d+/,
+    /^所在位置 行:\d+ 字符: \d+/,
+    /^\s*\+ ~+/,
+    /^\s+at [\w.]+, .+ line \d+/,
+    /^#< CLIXML/,
+    /^<Objs /,
+];
+const CLIXML_MARKER = '#< CLIXML';
+/** Undo .NET's CLIXML string escaping inside serialized records. */
+function unescapeClixml(t) {
+    return t
+        .replace(/_x000D__x000A_/g, '\n')
+        .replace(/_x000A_/g, '\n')
+        .replace(/_x000D_/g, '')
+        .replace(/_x0009_/g, '\t')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, '&')
+        .trim();
+}
+/**
+ * When stderr is redirected, powershell.exe serializes error records as
+ * CLIXML (`#< CLIXML` + XML). Unwrap the real message lines and drop
+ * progress records, so agents see plain bash-style text.
+ */
+function extractClixml(s) {
+    const idx = s.indexOf(CLIXML_MARKER);
+    if (idx < 0)
+        return s;
+    const plain = s.slice(0, idx).trim();
+    const xml = s.slice(idx);
+    const messages = [];
+    // each serialized record looks like: <S S="Error">message text</S>
+    for (const chunk of xml.split('<S ')) {
+        const close = chunk.indexOf('</S>');
+        if (close < 0)
+            continue;
+        const open = chunk.indexOf('>');
+        if (open < 0 || open >= close)
+            continue;
+        const text = unescapeClixml(chunk.slice(open + 1, close));
+        if (text)
+            messages.push(text);
+    }
+    return plain ? plain + '\n' + messages.join('\n') : messages.join('\n');
+}
+export function normalizeStderr(stderr) {
+    const unwrapped = extractClixml(stderr);
+    const lines = unwrapped.split(/\r?\n/).filter((l) => !PS_NOISE.some((re) => re.test(l)));
+    const out = lines.map((line) => {
+        // "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';
+        // zh-CN: 无法将"x"项识别为 cmdlet、函数、脚本文件或可运行程序的名称
+        m = line.match(/^无法将["'”]?([^"'”]+)["'”]?项识别为/);
+        if (m)
+            return 'bash: ' + m[1] + ': command not found';
+        // "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';
+        // "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) {
+            const cmd = m[1].toLowerCase();
+            return (cmd +
+                ': ' +
+                m[2].replace(/\\/g, '/') +
+                ': No such file or directory');
+        }
+        // zh-CN: "Get-Content : 找不到路径“X”，因为该路径不存在。"
+        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';
+        // "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';
+        // helpful hint for bash scripts
+        if (/\.sh'?/.test(line) && /is not recognized/.test(line)) {
+            return line + ' (fauxnix: .sh scripts cannot run natively on Windows)';
+        }
+        return line;
+    });
+    return out.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+}

package/dist/executor.d.ts

@@ -0,0 +1,27 @@
+import { SegmentPlan } from './translator.js';
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface ExecOptions {
+    timeoutMs?: number;
+    /** Extra environment layered over the session (used by MCP per-call cwd). */
+    cwd?: string;
+}
+/** Session persists cwd and env across segments, like a real shell. */
+export declare class FauxnixSession {
+    cwd: string | null;
+    env: Record<string, string>;
+    /** Exit code of the previous segment — powers bash's `$?`. */
+    prevExit: number | null;
+    private cwdFile;
+    private envFile;
+    private scriptFile;
+    constructor();
+    private syncFromDisk;
+    dispose(): Promise<void>;
+    /** env for the child powershell process. */
+    childEnv(cwdOverride?: string, stdinFile?: string | null): NodeJS.ProcessEnv;
+    run(plans: SegmentPlan[], opts?: ExecOptions): Promise<ExecResult>;
+}

package/dist/executor.js

@@ -0,0 +1,299 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+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 { normalizeStderr } from './errors.js';
+const DEFAULT_TIMEOUT_MS = 120_000;
+const PS_ARGS = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass'];
+/** Resolve /dev/null and POSIX-ish literal targets to real Windows paths. */
+function winTarget(target) {
+    const p = normalizeLiteralPath(target);
+    if (p === '$env:TEMP')
+        return os.tmpdir();
+    if (p.startsWith('$env:TEMP\\'))
+        return path.join(os.tmpdir(), p.slice('$env:TEMP\\'.length));
+    return p;
+}
+function planRedirects(redirects) {
+    const r = {
+        stdinFile: null,
+        stdoutFile: null,
+        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;
+                break;
+            case '>':
+            case '&>':
+                if (target === 'NUL')
+                    r.devNull = true;
+                else {
+                    r.stdoutFile = target;
+                    r.appendStdout = false;
+                    if (red.op === '&>')
+                        r.stderrFile = target;
+                }
+                break;
+            case '>>':
+            case '&>>':
+                if (target === 'NUL')
+                    r.devNull = true;
+                else {
+                    r.stdoutFile = target;
+                    r.appendStdout = true;
+                    if (red.op === '&>>') {
+                        r.stderrFile = target;
+                        r.appendStderr = true;
+                    }
+                }
+                break;
+            case '2>':
+                if (target === 'NUL') {
+                    // 2>/dev/null swallows stderr only
+                    r.stderrFile = null;
+                    r.devNull = false;
+                    r.swallowStderr = true;
+                }
+                else {
+                    r.stderrFile = target;
+                    r.appendStderr = false;
+                }
+                break;
+            case '2>>':
+                if (target !== 'NUL') {
+                    r.stderrFile = target;
+                    r.appendStderr = true;
+                }
+                break;
+            case '2>&1':
+                r.mergeStderr = true;
+                break;
+            case '1>&2':
+                r.mergeStderr = false;
+                r.stdoutToStderr = true;
+                break;
+        }
+    }
+    return r;
+}
+/** Session persists cwd and env across segments, like a real shell. */
+export class FauxnixSession {
+    cwd = null;
+    env = {};
+    /** Exit code of the previous segment — powers bash's `$?`. */
+    prevExit = null;
+    cwdFile;
+    envFile;
+    scriptFile;
+    constructor() {
+        const id = randomUUID().slice(0, 8);
+        this.cwdFile = path.join(os.tmpdir(), 'fauxnix-' + id + '-cwd.txt');
+        this.envFile = path.join(os.tmpdir(), 'fauxnix-' + id + '-env.json');
+        this.scriptFile = path.join(os.tmpdir(), 'fauxnix-' + id + '-script.ps1');
+    }
+    syncFromDisk() {
+        try {
+            if (existsSync(this.cwdFile)) {
+                const c = readFileSync(this.cwdFile, 'utf8').trim();
+                if (c)
+                    this.cwd = c;
+            }
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            if (existsSync(this.envFile)) {
+                const raw = readFileSync(this.envFile, 'utf8');
+                if (raw.trim())
+                    this.env = JSON.parse(raw);
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    async dispose() {
+        await Promise.allSettled([
+            fs.rm(this.cwdFile, { force: true }),
+            fs.rm(this.envFile, { force: true }),
+            fs.rm(this.scriptFile, { force: true }),
+        ]);
+    }
+    /** 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;
+        }
+        env.FAUXNIX_CWD_FILE = this.cwdFile;
+        env.FAUXNIX_ENV_FILE = this.envFile;
+        if (stdinFile)
+            env.FAUXNIX_STDIN_FILE = stdinFile;
+        else
+            delete env.FAUXNIX_STDIN_FILE;
+        if (this.prevExit !== null)
+            env.FAUXNIX_PREV_EXIT = String(this.prevExit);
+        else
+            delete env.FAUXNIX_PREV_EXIT;
+        const cwd = cwdOverride ?? this.cwd;
+        if (cwd)
+            env.FAUXNIX_CWD = cwd;
+        else
+            delete env.FAUXNIX_CWD;
+        return env;
+    }
+    run(plans, opts = {}) {
+        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 = '';
+    let stderr = '';
+    let exitCode = 0;
+    // 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.
+    let chainOk = true;
+    // redirect targets are relative to the session cwd, not this node process
+    const baseDir = opts.cwd ?? session.cwd ?? process.cwd();
+    const resolveTarget = (t) => path.isAbsolute(t) || /^[A-Za-z]:[\\/]/.test(t) ? t : path.resolve(baseDir, t);
+    for (const plan of plans) {
+        if (plan.op === '&&' && !chainOk)
+            continue;
+        if (plan.op === '||' && chainOk)
+            continue;
+        const red = planRedirects(plan.redirects);
+        red.stdinFile = red.stdinFile ? resolveTarget(red.stdinFile) : null;
+        red.stdoutFile = red.stdoutFile ? resolveTarget(red.stdoutFile) : null;
+        red.stderrFile = red.stderrFile ? resolveTarget(red.stderrFile) : null;
+        // bash: a missing `< file` target aborts the segment before running it
+        if (red.stdinFile && !existsSync(red.stdinFile)) {
+            stderr += 'bash: ' + red.stdinFile + ': No such file or directory\n';
+            exitCode = 1;
+            session.prevExit = exitCode;
+            chainOk = false;
+            continue;
+        }
+        const encoded = encodeCommand(plan.script);
+        // -EncodedCommand is capped by the ~32K command-line limit; heavy
+        // pipelines fall back to a UTF-8 BOM temp script (PS 5.1 honors the BOM
+        // regardless of the console codepage, so non-ASCII stays intact).
+        let psArgs;
+        if (encoded.length > 28000) {
+            writeFileSync(scriptFile, '\ufeff' + plan.script, 'utf8');
+            psArgs = [...PS_ARGS, '-File', scriptFile];
+        }
+        else {
+            psArgs = [...PS_ARGS, '-EncodedCommand', encoded];
+        }
+        const child = spawn('powershell.exe', psArgs, {
+            env: session.childEnv(opts.cwd, red.stdinFile),
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        const running = { proc: child, killed: false };
+        const outBufs = [];
+        const errBufs = [];
+        child.stdout.on('data', (d) => outBufs.push(d));
+        child.stderr.on('data', (d) => errBufs.push(d));
+        child.stdin.end();
+        const timer = setTimeout(() => {
+            running.killed = true;
+            killTree(child.pid);
+        }, timeoutMs);
+        const code = await new Promise((resolve) => {
+            child.on('error', (e) => {
+                stderr += 'fauxnix: failed to start powershell.exe: ' + e.message + '\n';
+                resolve(127);
+            });
+            child.on('close', (c) => resolve(running.killed ? 124 : (c ?? 0)));
+        });
+        clearTimeout(timer);
+        afterSegment();
+        let segOut = decodeOutput(Buffer.concat(outBufs));
+        let segErr = normalizeStderr(decodeOutput(Buffer.concat(errBufs)));
+        if (running.killed) {
+            segErr += '\nbash: command timed out after ' + Math.round(timeoutMs / 1000) + 's';
+        }
+        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 = '';
+        // redirect stdout to file instead of the result stream
+        if (red.stdoutFile) {
+            try {
+                if (red.appendStdout) {
+                    const prev = existsSync(red.stdoutFile) ? readFileSync(red.stdoutFile) : Buffer.alloc(0);
+                    writeFileSync(red.stdoutFile, Buffer.concat([prev, Buffer.from(segOut, 'utf8')]));
+                }
+                else {
+                    writeFileSync(red.stdoutFile, segOut, 'utf8');
+                }
+                segOut = '';
+            }
+            catch (e) {
+                segErr += 'bash: ' + red.stdoutFile + ': cannot create: ' + e.message + '\n';
+                exitCode = 1;
+            }
+        }
+        if (red.stderrFile) {
+            try {
+                const body = red.stderrFile === red.stdoutFile ? segOut + segErr : segErr;
+                if (red.appendStderr && existsSync(red.stderrFile)) {
+                    const prev = readFileSync(red.stderrFile);
+                    writeFileSync(red.stderrFile, Buffer.concat([prev, Buffer.from(body, 'utf8')]));
+                }
+                else if (red.stderrFile === red.stdoutFile && existsSync(red.stderrFile)) {
+                    const prev = readFileSync(red.stderrFile);
+                    writeFileSync(red.stderrFile, Buffer.concat([prev, Buffer.from(body, 'utf8')]));
+                }
+                else {
+                    writeFileSync(red.stderrFile, body, 'utf8');
+                }
+                segErr = '';
+            }
+            catch {
+                /* best effort */
+            }
+        }
+        stdout += segOut;
+        stderr += segErr;
+        exitCode = code ?? 0;
+        session.prevExit = exitCode;
+        chainOk = exitCode === 0;
+    }
+    return { stdout, stderr, exitCode };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runCli } from './cli.js';
+runCli(process.argv.slice(2)).catch((e) => {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+});

package/dist/mcp.d.ts

@@ -0,0 +1,4 @@
+import { translatePipelineBody } from './translator.js';
+import './commands/install-all.js';
+export declare function startMcpServer(): Promise<void>;
+export { translatePipelineBody };

package/dist/mcp.js

@@ -0,0 +1,79 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+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';
+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.
+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 session = new FauxnixSession();
+    server.tool(TOOL_NAME, TOOL_DESCRIPTION, {
+        command: z.string().describe('The bash-style command line to run'),
+        timeout_ms: z
+            .number()
+            .int()
+            .min(1000)
+            .max(600_000)
+            .optional()
+            .describe('Timeout in milliseconds (default 120000)'),
+    }, async ({ command, timeout_ms }) => {
+        try {
+            const plans = translateCommandList(parseCommand(command));
+            const result = await session.run(plans, { timeoutMs: timeout_ms });
+            const parts = [];
+            if (result.stdout.trim())
+                parts.push(result.stdout.replace(/\n$/, ''));
+            if (result.stderr.trim())
+                parts.push(result.stderr.replace(/\n$/, ''));
+            if (result.exitCode !== 0)
+                parts.push('Exit code: ' + result.exitCode);
+            const text = parts.length ? parts.join('\n') : '(no output)';
+            return { content: [{ type: 'text', text }] };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            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 }) => {
+        try {
+            const list = parseCommand(command);
+            const plans = translateCommandList(list);
+            const script = wrapScript(plans.map((p) => p.script).join('\n# ---- next segment ----\n'));
+            return { content: [{ type: 'text', text: script }] };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            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 }) => {
+        if (action === 'reset') {
+            await session.dispose();
+            return { content: [{ type: 'text', text: 'fauxnix: session reset' }] };
+        }
+        const envKeys = Object.keys(session.env).sort();
+        const text = 'cwd: ' + (session.cwd ?? '(inherit from server start)') +
+            '\nenv keys: ' + (envKeys.length ? envKeys.join(', ') : '(none tracked)') +
+            '\ncommands registered: ' + registeredNames().length;
+        return { content: [{ type: 'text', text }] };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+// keep referenced for tree-shaking clarity
+export { translatePipelineBody };

package/dist/parser.d.ts

@@ -0,0 +1,11 @@
+import { CommandList, WordPart } from './ast.js';
+type TokType = 'WORD' | 'OP' | 'EOF';
+interface Token {
+    type: TokType;
+    /** For WORD: the parsed parts. For OP: the operator text. */
+    op?: string;
+    parts?: WordPart[];
+}
+export declare function tokenize(input: string): Token[];
+export declare function parseCommand(input: string): CommandList;
+export {};