fauxnix-cli 0.7.0 → 0.8.0

package/dist/parser.js

@@ -586,28 +586,62 @@ export function parseCommand(input) {
     let pos = 0;
     const peek = () => tokens[pos];
     const next = () => tokens[pos++];
+    const isListSep = (o) => o === ';' || o === '\n';
+    /** Consume `;` / newline / `&&` / `||`. Trailing `&&`/`||` and `;;` fail loud (bash). */
+    const consumeListOp = (stops) => {
+        const t = peek();
+        if (t.type !== 'OP')
+            return null;
+        if (!(t.op === '&&' || t.op === '||' || isListSep(t.op)))
+            return null;
+        if (t.op === ';') {
+            next();
+            if (peek().type === 'OP' && peek().op === ';') {
+                throw new FauxnixParseError("fauxnix: syntax error near unexpected token `;;'");
+            }
+            return ';';
+        }
+        if (t.op === '\n') {
+            next();
+            while (peek().type === 'OP' && peek().op === '\n')
+                next();
+            return ';';
+        }
+        const sep = t.op;
+        next();
+        while (peek().type === 'OP' && peek().op === '\n')
+            next();
+        const n = peek();
+        const kw = peekKw();
+        if (n.type === 'OP' && n.op === ';') {
+            throw new FauxnixParseError("fauxnix: syntax error near unexpected token `" + sep + "'");
+        }
+        if (n.type === 'EOF' || (stops && kw && stops.has(kw))) {
+            throw new FauxnixParseError(n.type === 'EOF'
+                ? 'fauxnix: syntax error: unexpected end of file after `' + sep + "'"
+                : "fauxnix: syntax error near unexpected token `" + sep + "'");
+        }
+        return sep;
+    };
     const parseList = () => {
         const segments = [];
         let op = ';';
-        const isListSep = (o) => o === ';' || o === '\n';
-        while (peek().type === 'OP' && isListSep(peek().op))
+        while (peek().type === 'OP' && isListSep(peek().op)) {
+            if (peek().op === ';' && tokens[pos + 1]?.type === 'OP' && tokens[pos + 1]?.op === ';') {
+                throw new FauxnixParseError("fauxnix: syntax error near unexpected token `;;'");
+            }
             next();
+        }
         while (peek().type !== 'EOF') {
             const pipeline = parsePipeline();
             segments.push({ pipeline, op });
-            const t = peek();
-            if (t.type === 'OP' && (t.op === '&&' || t.op === '||' || isListSep(t.op))) {
-                op = t.op === '\n' ? ';' : t.op;
-                next();
-                while (peek().type === 'OP' && isListSep(peek().op))
-                    next();
-            }
-            else if (t.type === 'EOF') {
-                break;
-            }
-            else {
+            const nextOp = consumeListOp();
+            if (nextOp === null) {
+                if (peek().type === 'EOF')
+                    break;
                 throw new FauxnixParseError('fauxnix: unexpected token after pipeline');
             }
+            op = nextOp;
         }
         if (segments.length === 0)
             throw new FauxnixParseError('fauxnix: empty command');
@@ -672,25 +706,22 @@ export function parseCommand(input) {
         const stop = new Set(stops);
         const segments = [];
         let op = ';';
-        const isListSep = (o) => o === ';' || o === '\n';
-        while (peek().type === 'OP' && isListSep(peek().op))
+        while (peek().type === 'OP' && isListSep(peek().op)) {
+            if (peek().op === ';' && tokens[pos + 1]?.type === 'OP' && tokens[pos + 1]?.op === ';') {
+                throw new FauxnixParseError("fauxnix: syntax error near unexpected token `;;'");
+            }
             next();
+        }
         while (peek().type !== 'EOF') {
             const kw = peekKw();
             if (kw && stop.has(kw))
                 break;
             const pipeline = parsePipeline();
             segments.push({ pipeline, op });
-            const t = peek();
-            if (t.type === 'OP' && (t.op === '&&' || t.op === '||' || isListSep(t.op))) {
-                op = t.op === '\n' ? ';' : t.op;
-                next();
-                while (peek().type === 'OP' && isListSep(peek().op))
-                    next();
-            }
-            else {
+            const nextOp = consumeListOp(stop);
+            if (nextOp === null)
                 break;
-            }
+            op = nextOp;
         }
         if (segments.length === 0) {
             throw new FauxnixParseError('fauxnix: empty command');

package/dist/ps-host.d.ts

@@ -1,9 +1,13 @@
 export declare const PS_MISSING_MESSAGE: string;
+export declare const DEFAULT_STDOUT_LIMIT = 8388608;
+export declare const DEFAULT_STDERR_LIMIT = 1048576;
 export interface HostInvokeResult {
     stdout: Buffer;
     stderr: Buffer;
     exitCode: number;
     timedOut: boolean;
+    cancelled: boolean;
+    truncated: boolean;
     spawnError?: 'ENOENT' | 'START';
     spawnMessage?: string;
 }
@@ -39,8 +43,10 @@ export declare class PowerShellHost {
     constructor(hostFile: string, envFn: () => NodeJS.ProcessEnv);
     /** Start the resident process and wait for the ready handshake (B1 prewarm). */
     ready(): Promise<HostInvokeResult | null>;
-    invoke(script: string, env: HostRequestEnv, timeoutMs: number): Promise<HostInvokeResult>;
+    invoke(script: string, env: HostRequestEnv, timeoutMs: number, signal?: AbortSignal): Promise<HostInvokeResult>;
+    drainNativeStderr(): Buffer;
     stop(): Promise<void>;
+    private cancelledResult;
     private invokeSerial;
     private ensureStarted;
     private deadRestart;

package/dist/ps-host.js

@@ -6,6 +6,8 @@ const READY_TIMEOUT_MS = 30_000;
 export const PS_MISSING_MESSAGE = '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';
+export const DEFAULT_STDOUT_LIMIT = 8_388_608;
+export const DEFAULT_STDERR_LIMIT = 1_048_576;
 export function encodeHostRequest(id, script, env) {
     return JSON.stringify({
         id,
@@ -50,11 +52,18 @@ export class PowerShellHost {
     async ready() {
         return this.ensureStarted();
     }
-    async invoke(script, env, timeoutMs) {
-        const run = this.invokeLock.then(() => this.invokeSerial(script, env, timeoutMs));
+    async invoke(script, env, timeoutMs, signal) {
+        const run = this.invokeLock.then(() => this.invokeSerial(script, env, timeoutMs, signal));
         this.invokeLock = run.then(() => undefined, () => undefined);
         return run;
     }
+    drainNativeStderr() {
+        if (!this.stderrChunks.length)
+            return Buffer.alloc(0);
+        const b = Buffer.concat(this.stderrChunks);
+        this.stderrChunks = [];
+        return b;
+    }
     async stop() {
         const proc = this.proc;
         this.proc = null;
@@ -82,10 +91,24 @@ export class PowerShellHost {
             });
         });
     }
-    async invokeSerial(script, env, timeoutMs) {
+    cancelledResult() {
+        return {
+            stdout: Buffer.alloc(0),
+            stderr: Buffer.alloc(0),
+            exitCode: 130,
+            timedOut: false,
+            cancelled: true,
+            truncated: false,
+        };
+    }
+    async invokeSerial(script, env, timeoutMs, signal) {
+        if (signal?.aborted) {
+            await this.stop();
+            return this.cancelledResult();
+        }
         const started = await this.ensureStarted();
         if (started)
-            return started;
+            return { ...started, cancelled: false, truncated: false };
         const id = 'f' + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
         const line = encodeHostRequest(id, script, env);
         try {
@@ -98,24 +121,45 @@ export class PowerShellHost {
                 stderr: Buffer.from('fauxnix: powershell host exited unexpectedly\n', 'utf8'),
                 exitCode: 1,
                 timedOut: false,
+                cancelled: false,
+                truncated: false,
                 spawnMessage: e.message,
             };
         }
+        let cancelled = false;
+        const onAbort = () => {
+            cancelled = true;
+            void this.stop();
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
         try {
             const raw = await this.nextJsonLine(timeoutMs, id);
             const msg = decodeHostResponse(raw);
+            const native = this.drainNativeStderr();
             return {
                 stdout: msg.stdout,
-                stderr: msg.stderr,
+                stderr: native.length ? Buffer.concat([msg.stderr, native]) : msg.stderr,
                 exitCode: msg.exitCode,
                 timedOut: false,
+                cancelled: false,
+                truncated: false,
             };
         }
         catch (e) {
             const timedOut = e.timedOut === true;
             await this.stop();
+            this.drainNativeStderr();
+            if (cancelled || signal?.aborted)
+                return this.cancelledResult();
             if (timedOut) {
-                return { stdout: Buffer.alloc(0), stderr: Buffer.alloc(0), exitCode: 124, timedOut: true };
+                return {
+                    stdout: Buffer.alloc(0),
+                    stderr: Buffer.alloc(0),
+                    exitCode: 124,
+                    timedOut: true,
+                    cancelled: false,
+                    truncated: false,
+                };
             }
             if (this.closeErr && this.closeErr.code === 'ENOENT') {
                 return {
@@ -123,6 +167,8 @@ export class PowerShellHost {
                     stderr: Buffer.from(PS_MISSING_MESSAGE, 'utf8'),
                     exitCode: 127,
                     timedOut: false,
+                    cancelled: false,
+                    truncated: false,
                     spawnError: 'ENOENT',
                 };
             }
@@ -134,8 +180,13 @@ export class PowerShellHost {
                     '\n', 'utf8'),
                 exitCode: code === 0 ? 1 : code,
                 timedOut: false,
+                cancelled: false,
+                truncated: false,
             };
         }
+        finally {
+            signal?.removeEventListener('abort', onAbort);
+        }
     }
     async ensureStarted() {
         if (this.proc && !this.closed)
@@ -154,6 +205,8 @@ export class PowerShellHost {
                     stderr: Buffer.from(PS_MISSING_MESSAGE, 'utf8'),
                     exitCode: 127,
                     timedOut: false,
+                    cancelled: false,
+                    truncated: false,
                     spawnError: 'ENOENT',
                 };
             }
@@ -162,6 +215,8 @@ export class PowerShellHost {
                 stderr: Buffer.from('fauxnix: failed to start powershell.exe: ' + err.message + '\n', 'utf8'),
                 exitCode: 127,
                 timedOut: false,
+                cancelled: false,
+                truncated: false,
                 spawnError: 'START',
                 spawnMessage: err.message,
             };
@@ -189,14 +244,26 @@ export class PowerShellHost {
             windowsHide: true,
         });
         this.proc = child;
-        child.stdout.on('data', (d) => this.onStdout(d));
-        child.stderr.on('data', (d) => this.stderrChunks.push(d));
+        child.stdout.on('data', (d) => {
+            if (this.proc !== child)
+                return;
+            this.onStdout(d);
+        });
+        child.stderr.on('data', (d) => {
+            if (this.proc !== child)
+                return;
+            this.stderrChunks.push(d);
+        });
         child.on('error', (e) => {
+            if (this.proc !== child)
+                return;
             this.closeErr = e;
             this.closed = true;
             this.failWaiters(e);
         });
         child.on('close', (c) => {
+            if (this.proc !== child)
+                return;
             this.closeCode = c;
             this.closed = true;
             this.proc = null;

package/dist/registry.d.ts

@@ -77,3 +77,53 @@ export interface WordArgs {
  * shortValues: single-char options that consume a value (e.g. ['n']).
  */
 export declare function parseWords(args: Word[], shortValues?: string[], longValues?: string[]): WordArgs;
+export type CommandEffect = 'read' | 'write' | 'delete' | 'network' | 'process';
+export type OptionSupport = 'implemented' | 'unsupported';
+/** One short/long alias group. Unknown options on a spec'd command fail loud. */
+export interface OptionSpec {
+    /** Short flag letter without dash (e.g. `'n'`). */
+    short?: string;
+    /** Long option including dashes (e.g. `'--no-clobber'`). */
+    long?: string;
+    /** Consumes a following argument (`-n 5`, `--lines=5`). */
+    takesValue?: boolean;
+    support: OptionSupport;
+    /** Extra phrase for unsupported options (`interactive prompt`). */
+    reason?: string;
+}
+export interface CommandSpec {
+    names: string[];
+    options: OptionSpec[];
+    effects: CommandEffect[];
+    platform?: 'windows-ps51' | 'portable-translate';
+    dispatch?: 'translated' | 'native' | 'dynamic';
+    handler: Handler;
+}
+/** Register a spec'd command. Unknown/unsupported options become GNU-style usage errors. */
+export declare function registerSpec(spec: CommandSpec): void;
+export declare function registerSpecs(list: CommandSpec[]): void;
+export declare function lookupSpec(name: string): CommandSpec | undefined;
+/** Unique specs in registration order. */
+export declare function registeredSpecs(): CommandSpec[];
+export interface ListedCommand {
+    name: string;
+    spec: null | {
+        options: Array<{
+            short?: string;
+            long?: string;
+            takesValue: boolean;
+            support: OptionSupport;
+            reason?: string;
+        }>;
+        effects: CommandEffect[];
+        platform: 'windows-ps51' | 'portable-translate';
+        dispatch: 'translated' | 'native' | 'dynamic';
+    };
+}
+/** Capability dump for `fauxnix list --json` / MCP introspection. */
+export declare function listCommandsJson(): ListedCommand[];
+/**
+ * Walk argv against a CommandSpec. Returns a PowerShell error script, or
+ * null when every option is recognized and implemented.
+ */
+export declare function specOptionError(spec: CommandSpec, args: Word[], cmdName: string): string | null;

package/dist/registry.js

@@ -153,3 +153,145 @@ export function parseWords(args, shortValues = [], longValues = []) {
     }
     return { flags, longs, values, missingValue, operandWords };
 }
+const specs = new Map();
+/** Register a spec'd command. Unknown/unsupported options become GNU-style usage errors. */
+export function registerSpec(spec) {
+    for (const name of spec.names) {
+        const wrapped = (args, ctx) => {
+            const err = specOptionError(spec, args, name);
+            if (err)
+                return err;
+            return spec.handler(args, ctx);
+        };
+        registry.set(name, wrapped);
+        specs.set(name, spec);
+    }
+}
+export function registerSpecs(list) {
+    for (const spec of list)
+        registerSpec(spec);
+}
+export function lookupSpec(name) {
+    return specs.get(name);
+}
+/** Unique specs in registration order. */
+export function registeredSpecs() {
+    const seen = new Set();
+    const out = [];
+    for (const spec of specs.values()) {
+        if (seen.has(spec))
+            continue;
+        seen.add(spec);
+        out.push(spec);
+    }
+    return out;
+}
+/** Capability dump for `fauxnix list --json` / MCP introspection. */
+export function listCommandsJson() {
+    return registeredNames().map((name) => {
+        const spec = lookupSpec(name);
+        if (!spec)
+            return { name, spec: null };
+        return {
+            name,
+            spec: {
+                options: spec.options.map((o) => ({
+                    ...(o.short ? { short: o.short } : {}),
+                    ...(o.long ? { long: o.long } : {}),
+                    takesValue: o.takesValue === true,
+                    support: o.support,
+                    ...(o.reason ? { reason: o.reason } : {}),
+                })),
+                effects: spec.effects,
+                platform: spec.platform ?? 'windows-ps51',
+                dispatch: spec.dispatch ?? 'translated',
+            },
+        };
+    });
+}
+/**
+ * Walk argv against a CommandSpec. Returns a PowerShell error script, or
+ * null when every option is recognized and implemented.
+ */
+export function specOptionError(spec, args, cmdName) {
+    const shorts = new Map();
+    const longs = new Map();
+    for (const o of spec.options) {
+        if (o.short)
+            shorts.set(o.short, o);
+        if (o.long)
+            longs.set(o.long, o);
+    }
+    let i = 0;
+    let onlyOperands = false;
+    while (i < args.length) {
+        const t = wordToString(args[i]);
+        if (onlyOperands) {
+            i++;
+            continue;
+        }
+        if (t === '--') {
+            onlyOperands = true;
+            i++;
+            continue;
+        }
+        if (t.startsWith('--')) {
+            const eq = t.indexOf('=');
+            const name = eq >= 0 ? t.slice(0, eq) : t;
+            const opt = longs.get(name);
+            if (!opt)
+                return optionFail(cmdName, "unrecognized option '" + name + "'");
+            if (opt.support === 'unsupported') {
+                return optionFail(cmdName, unsupportedMsg(opt, name));
+            }
+            if (!opt.takesValue && eq >= 0) {
+                return optionFail(cmdName, "option '" + name + "' doesn't allow an argument");
+            }
+            if (opt.takesValue && eq < 0) {
+                if (i + 1 < args.length)
+                    i++;
+                else
+                    return optionFail(cmdName, "option '" + name + "' requires an argument");
+            }
+            i++;
+            continue;
+        }
+        if (t.startsWith('-') && t.length > 1 && !/^-?\d/.test(t.slice(1, 2))) {
+            const body = t.slice(1);
+            for (let c = 0; c < body.length; c++) {
+                const ch = body[c];
+                const opt = shorts.get(ch);
+                if (!opt)
+                    return optionFail(cmdName, "invalid option -- '" + ch + "'");
+                if (opt.support === 'unsupported') {
+                    return optionFail(cmdName, unsupportedMsg(opt, '-' + ch));
+                }
+                if (opt.takesValue) {
+                    const rest = body.slice(c + 1);
+                    if (!rest) {
+                        if (i + 1 < args.length)
+                            i++;
+                        else
+                            return optionFail(cmdName, "option requires an argument -- '" + ch + "'");
+                    }
+                    break;
+                }
+            }
+            i++;
+            continue;
+        }
+        i++;
+    }
+    return null;
+}
+function unsupportedMsg(opt, shown) {
+    const reason = opt.reason ? ' (' + opt.reason + ')' : '';
+    return "option '" + shown + "' is not supported by fauxnix" + reason;
+}
+function optionFail(cmd, msg) {
+    return ('[Console]::Error.WriteLine(' +
+        psStr(cmd + ': ' + msg) +
+        '); [Console]::Error.WriteLine(' +
+        psStr("Try '" + cmd + " --help' for more information.") +
+        '); $script:fx_exit = 1');
+}

package/dist/translator.js

@@ -719,6 +719,8 @@ export function wrapTempEnv(sets, body, extra) {
 }
 /** Unique suffix for generated stage functions (nested pipelines included). */
 let stageSeq = 0;
+/** Unique suffix for generated pipeline wrappers and their local status arrays. */
+let pipelineSeq = 0;
 /**
  * Pipeline body. A lone command runs as a plain script-block expression;
  * multi-command pipelines become generated functions chained with `|`
@@ -784,6 +786,12 @@ function translateFor(cmd) {
     return lines.join('\n');
 }
 export function translatePipelineBody(p) {
+    // Every pipeline stage needs its own status slot. Handlers deliberately use
+    // `$script:fx_exit` because their helper functions run in child scopes; in a
+    // pipeline that shared flag lets an earlier failure leak into a successful
+    // last stage. Reserve the wrapper id before translating bodies so nested
+    // command substitutions cannot reuse it.
+    const pipelineId = p.commands.length > 1 ? pipelineSeq++ : -1;
     const bodies = [];
     for (let i = 0; i < p.commands.length; i++) {
         const c = p.commands[i];
@@ -801,16 +809,36 @@ export function translatePipelineBody(p) {
     }
     const names = [];
     const defs = [];
+    const statusVar = '$fx_pipe_status' + pipelineId;
     for (let i = 0; i < bodies.length; i++) {
         const name = '__fx_s' + stageSeq++;
         names.push(name);
-        const indented = bodies[i]
+        const isolatedBody = bodies[i].split('$script:fx_exit').join(statusVar + '[' + i + ']');
+        const indented = isolatedBody
             .split('\n')
             .map((l) => (l ? '  ' + l : l))
             .join('\n');
         defs.push('function ' + name + ' {\n' + indented + '\n}');
     }
-    return { defs: defs.join('\n'), call: names.join(' | ') };
+    const pipelineName = '__fx_p' + pipelineId;
+    const statuses = bodies.map(() => '0').join(', ');
+    const pipelineCall = names.join(' | ');
+    defs.push([
+        'function ' + pipelineName + ' {',
+        '  ' + statusVar + ' = @(' + statuses + ')',
+        '  try {',
+        // The wrapper forwards redirect input to stage zero. With no input,
+        // PowerShell still invokes a regular function once, which preserves the
+        // existing no-stdin pipeline behavior on Windows PowerShell 5.1.
+        '    $input | ' + pipelineCall,
+        '  } finally {',
+        // Bash defaults to pipefail off: only the last stage controls the list
+        // status used by a following && / || segment.
+        '    $script:fx_exit = [int]' + statusVar + '[' + (bodies.length - 1) + ']',
+        '  }',
+        '}',
+    ].join('\n'));
+    return { defs: defs.join('\n'), call: pipelineName };
 }
 export function translateCommandList(list) {
     const plans = [];
@@ -1240,6 +1268,13 @@ while ($true) {
   $fx_code = 0
   try { $fx_code = [int]$script:fx_exit } catch { $fx_code = 1 }
   $fx_res = @{ id = $fx_id; stdoutB64 = $fx_outB64; stderrB64 = $fx_errB64; exitCode = $fx_code }
-  $fx_proto.WriteLine(($fx_res | ConvertTo-Json -Compress))
+  try {
+    $fx_json = $fx_res | ConvertTo-Json -Compress
+  } catch {
+    $fx_msg = 'fauxnix: host result exceeded ConvertTo-Json MaxJsonLength (~2MB)'
+    $fx_res = @{ id = $fx_id; stdoutB64 = ''; stderrB64 = [Convert]::ToBase64String($fx_utf8.GetBytes($fx_msg)); exitCode = 1 }
+    $fx_json = $fx_res | ConvertTo-Json -Compress
+  }
+  $fx_proto.WriteLine($fx_json)
 }
 `.trim();

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const packageVersion: string;

package/dist/version.js

@@ -0,0 +1,8 @@
+import { readFileSync } from 'node:fs';
+// src/ and dist/ are both one level below the package root, so package.json is
+// the runtime source of truth in development and in the published tarball.
+const metadata = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+if (typeof metadata.version !== 'string' || metadata.version.length === 0) {
+    throw new Error('fauxnix: package.json does not contain a valid version');
+}
+export const packageVersion = metadata.version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fauxnix-cli",
-  "version": "0.7.0",
+  "version": "0.8.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": {
@@ -13,7 +13,9 @@
   ],
   "scripts": {
     "build": "tsc",
+    "prepare": "npm run build",
     "test": "vitest run",
+    "test:package": "node scripts/package-smoke.mjs",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "dev": "tsx src/index.ts"