fauxnix-cli 0.6.0 → 0.7.0

package/README.md

@@ -193,11 +193,10 @@ fauxnix optimizes for the commands agents actually run. Documented deviations:
   word expansion precedes the temporary environment).
 - `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`, `eval`, `alias`, heredocs, `while`/`until`/`case`, word-level
-  `$((...))` arithmetic expansion
+- `tail -f`, `eval`, `alias`, heredocs, `while`/`until`/`case`,
   and background `&` are rejected with actionable error messages instead of misbehaving.
-  (`if/then/else/fi`, `for x in ...`, backtick substitution, `command -v`, pipeline `read`,
-  and dotenv-style `source` are supported.)
+  (`if/then/elif/else/fi`, `for x in ...`, backtick substitution, `command -v`, pipeline `read`,
+  dotenv-style `source`, and word-level `$((...))` arithmetic expansion are supported.)
 - `command -v <builtin>` prints `/usr/bin/<name>` where bash prints the bare builtin name;
   exit codes and empty-result semantics match.
 - `chmod` maps only the read-only bit; exec bits are no-ops on Windows. `chown` is a silent no-op
@@ -231,6 +230,9 @@ Architecture map: `src/parser.ts` (bash subset → AST) · `src/translator.ts` (
 executor wrapper) · `src/executor.ts` (spawn, redirects, session persistence) ·
 `src/commands/*.ts` (per-command generators) · `src/mcp.ts` (MCP server) · `src/cli.ts`.
 
+Roadmap: [docs/rfc-roadmap-to-1.0.md](docs/rfc-roadmap-to-1.0.md) — tracks, milestones,
+and the RFC process for proposing waves.
+
 ## License
 
 MIT © 20000419

package/dist/ast.d.ts

@@ -8,12 +8,12 @@
  *   - quoting:              'literal'  "interp $VAR $(cmd)"
  *   - variables:            $VAR ${VAR} ${VAR[n]} plus special cases ($HOME $USER $PATH ...)
  *   - command substitution: $(...) and `...` (recursively translated)
+ *   - arithmetic expansion: $((...)) (existing fx-arith engine)
  *   - env assignment prefix: VAR=value cmd
  *
  * Explicitly unsupported (parser throws a helpful FauxnixError):
  *   heredocs, subshells (...), background &, while/until/case,
- *   word-level $((...)) arithmetic expansion, globs inside quotes,
- *   process substitution <(...).
+ *   globs inside quotes, process substitution <(...).
  */
 export interface CommandList {
     kind: 'CommandList';
@@ -89,6 +89,9 @@ export type WordPart = {
 } | {
     kind: 'CmdSub';
     cmd: string;
+} | {
+    kind: 'Arith';
+    parts: WordPart[];
 };
 export declare function wordToString(w: Word): string;
 /** True when every part is unquoted Text and the concatenation equals `tok`. */

package/dist/ast.js

@@ -8,12 +8,12 @@
  *   - quoting:              'literal'  "interp $VAR $(cmd)"
  *   - variables:            $VAR ${VAR} ${VAR[n]} plus special cases ($HOME $USER $PATH ...)
  *   - command substitution: $(...) and `...` (recursively translated)
+ *   - arithmetic expansion: $((...)) (existing fx-arith engine)
  *   - env assignment prefix: VAR=value cmd
  *
  * Explicitly unsupported (parser throws a helpful FauxnixError):
  *   heredocs, subshells (...), background &, while/until/case,
- *   word-level $((...)) arithmetic expansion, globs inside quotes,
- *   process substitution <(...).
+ *   globs inside quotes, process substitution <(...).
  */
 export function wordToString(w) {
     return w.map(partToString).join('');
@@ -40,6 +40,8 @@ function partToString(p) {
             return p.index !== undefined ? `\${${p.name}[${p.index}]}` : `$${p.name}`;
         case 'CmdSub':
             return '$(' + p.cmd + ')';
+        case 'Arith':
+            return '$((' + p.parts.map(partToString).join('') + '))';
     }
 }
 /** Best-effort "raw literal" view: is this word free of interpolation? */

package/dist/commands/sysinfo.js

@@ -1,6 +1,6 @@
 import { FauxnixParseError, isUnquotedLiteral, wordToString } from '../ast.js';
 import { lookup, parseWords, psStr, registeredNames } from '../registry.js';
-import { argListExpr, exprOfWord, operandExpr, translateSimple, wrapTempEnv, encodeSetValExpr, escapeDq, translateCmdSub, normalizeLiteralPath, pathExpr, paramExpr, varExpr, } from '../translator.js';
+import { argListExpr, exprOfWord, operandExpr, translateSimple, wrapTempEnv, encodeSetValExpr, escapeDq, translateCmdSub, normalizeLiteralPath, pathExpr, paramExpr, varExpr, arithExpr, setArithHelperPreamble, } from '../translator.js';
 import { handlers as textIoHandlers } from './text-io.js';
 /* ------------------------------------------------------------------ */
 /* Shared TS helpers                                                   */
@@ -1373,6 +1373,7 @@ const FX_ENVGET_FN = [
     '  return [string]$fx_ev.Value',
     '}',
 ].join('\n');
+setArithHelperPreamble(FX_TNK_FN + '\n' + FX_ENVGET_FN);
 /** Like exprOfWord, but $var is an exact-case env lookup (bash, not $env:). */
 function kshExprOfWord(w) {
     const expanded = [];
@@ -1392,6 +1393,9 @@ function kshExprOfWord(w) {
     }
     if (tilde && expanded.length === 0)
         return '(fx-home)';
+    if (!tilde && expanded.length === 1 && expanded[0].kind === 'Arith') {
+        return arithExpr(expanded[0].parts);
+    }
     if (!tilde && expanded.length === 1 && expanded[0].kind === 'Var') {
         if (expanded[0].param) {
             return paramExpr(expanded[0].name, expanded[0].param.op, expanded[0].param.word);
@@ -1434,6 +1438,9 @@ function kshExprOfWord(w) {
                 // [[ ]] does not IFS-split, so keep the newline contract.
                 out += '$(' + translateCmdSub(p.cmd, true) + ')';
                 break;
+            case 'Arith':
+                out += arithExpr(p.parts);
+                break;
         }
     };
     for (const p of expanded)

package/dist/executor.d.ts

@@ -25,6 +25,8 @@ export declare class FauxnixSession {
     private bindFiles;
     private syncFromDisk;
     private ensureHost;
+    /** Boot powershell.exe now so the first run() is not the 1.1s cold start. */
+    prewarm(): Promise<void>;
     dispose(): Promise<void>;
     /** env for the child powershell process. */
     childEnv(cwdOverride?: string, stdinFile?: string | null): NodeJS.ProcessEnv;

package/dist/executor.js

@@ -195,6 +195,10 @@ export class FauxnixSession {
         }
         return this.host;
     }
+    /** Boot powershell.exe now so the first run() is not the 1.1s cold start. */
+    async prewarm() {
+        await this.ensureHost().ready();
+    }
     async dispose() {
         if (this.host) {
             await this.host.stop();

package/dist/mcp.js

@@ -37,15 +37,16 @@ Output is formatted to look like GNU/Linux tooling (ls -l, ps aux, df -h ...), e
 
 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, while/until/case, word-level \$((...)) arithmetic expansion, background jobs. if/then/else/fi and for-in loops are supported.
+Not supported: heredocs, while/until/case, background jobs. if/then/elif/else/fi, for-in loops, and word-level \$((...)) arithmetic expansion are supported.
 
-CWD, environment variables, export/unset and cd persist across calls within this session — a resident PowerShell 5.1 host is reused, so batching with ; or && is still nicer but many tiny calls no longer each pay a powershell.exe spawn.
+CWD, environment variables, export/unset and cd persist across calls within this session — a resident PowerShell 5.1 host is started when the MCP session begins (and after reset), so the first bash tool call is already warm.
 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: pkgVersion }, { capabilities: { tools: {} } });
     let session = new FauxnixSession();
+    await session.prewarm();
     server.tool(TOOL_NAME, TOOL_DESCRIPTION, {
         command: z.string().describe('The bash-style command line to run'),
         timeout_ms: z
@@ -95,6 +96,7 @@ export async function startMcpServer() {
         if (action === 'reset') {
             await session.dispose();
             session = new FauxnixSession();
+            await session.prewarm();
             return { content: [{ type: 'text', text: 'fauxnix: session reset' }] };
         }
         const envKeys = Object.keys(session.env).sort();

package/dist/parser.js

@@ -217,7 +217,32 @@ function readBacktick(input, i) {
     }
     throw new FauxnixParseError('fauxnix: unclosed backtick');
 }
-/** Parse $VAR, ${VAR}, $(cmd substitution). Returns null when not a valid dollar construct. */
+/** Expand `$…` constructs that appear inside `$((…))`. */
+function readArithParts(input) {
+    const parts = [];
+    let buf = '';
+    let i = 0;
+    while (i < input.length) {
+        if (input[i] === '$') {
+            const v = readDollar(input, i);
+            if (v) {
+                if (buf) {
+                    parts.push({ kind: 'Text', text: buf });
+                    buf = '';
+                }
+                parts.push(v.part);
+                i = v.next;
+                continue;
+            }
+        }
+        buf += input[i];
+        i++;
+    }
+    if (buf)
+        parts.push({ kind: 'Text', text: buf });
+    return parts;
+}
+/** Parse $VAR, ${VAR}, $(cmd substitution), $((arith)). Returns null when not a valid dollar construct. */
 function readDollar(input, i) {
     const n = input.length;
     if (input[i] !== '$')
@@ -256,11 +281,41 @@ function readDollar(input, i) {
         }
         return { part: { kind: 'Var', name }, next: end + 1 };
     }
-    // $((...)) is arithmetic expansion, not command substitution of a
-    // parenthesized body. Today it was parsed as $( (expr) ) and became an
-    // empty/confusing command. Reject loudly until word-level arith lands.
+    // $((...)) arithmetic expansion — distinct from `$( (cmd) )` (space after
+    // the first paren is command substitution of a grouped body).
     if (input[j] === '(' && j + 1 < n && input[j + 1] === '(') {
-        throw new FauxnixParseError('fauxnix: $((...)) arithmetic expansion is not supported; compute the value in the agent or compare with [[ $n -eq m ]]');
+        let depth = 0;
+        let k = j;
+        while (k < n) {
+            const c = input[k];
+            if (c === "'" || c === '"') {
+                const q = c;
+                k++;
+                while (k < n && input[k] !== q) {
+                    if (input[k] === '\\')
+                        k++;
+                    k++;
+                }
+                k++;
+                continue;
+            }
+            if (c === '(')
+                depth++;
+            else if (c === ')') {
+                depth--;
+                if (depth === 0) {
+                    k++;
+                    break;
+                }
+            }
+            k++;
+        }
+        if (depth !== 0)
+            throw new FauxnixParseError('fauxnix: unclosed $(( ))');
+        return {
+            part: { kind: 'Arith', parts: readArithParts(input.slice(j + 2, k - 2)) },
+            next: k,
+        };
     }
     // $(cmd substitution) — captured with balanced parens; the translator
     // recursively translates this text before embedding it.
@@ -642,14 +697,24 @@ export function parseCommand(input) {
         }
         return { kind: 'CommandList', segments };
     };
-    const parseIf = () => {
-        expectKw('if');
+    const parseIf = (start = 'if') => {
+        expectKw(start);
         const test = parseListUntil(['then']);
         expectKw('then');
         const thenL = parseListUntil(['else', 'elif', 'fi']);
         let elseL;
         if (peekKw() === 'elif') {
-            throw new FauxnixParseError('fauxnix: elif is not supported yet; use else + if');
+            // bash `elif` is `else` + nested `if`; the innermost clause eats `fi`.
+            elseL = {
+                kind: 'CommandList',
+                segments: [
+                    {
+                        op: ';',
+                        pipeline: { kind: 'Pipeline', commands: [parseIf('elif')] },
+                    },
+                ],
+            };
+            return { kind: 'If', test, then: thenL, else: elseL, redirects: [] };
         }
         if (peekKw() === 'else') {
             next();

package/dist/ps-host.d.ts

@@ -37,6 +37,8 @@ export declare class PowerShellHost {
     private startLock;
     private invokeLock;
     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>;
     stop(): Promise<void>;
     private invokeSerial;

package/dist/ps-host.js

@@ -46,6 +46,10 @@ export class PowerShellHost {
         this.hostFile = hostFile;
         this.envFn = envFn;
     }
+    /** Start the resident process and wait for the ready handshake (B1 prewarm). */
+    async ready() {
+        return this.ensureStarted();
+    }
     async invoke(script, env, timeoutMs) {
         const run = this.invokeLock.then(() => this.invokeSerial(script, env, timeoutMs));
         this.invokeLock = run.then(() => undefined, () => undefined);

package/dist/translator.d.ts

@@ -1,4 +1,4 @@
-import { Assignment, CommandList, Redirect, SimpleCommand, IfCommand, ForCommand, Word } from './ast.js';
+import { Assignment, CommandList, Redirect, SimpleCommand, IfCommand, ForCommand, Word, WordPart } from './ast.js';
 import { PipelineCtx } from './registry.js';
 /** `${name:-word}` and friends using case-exact fx-scalar0. */
 export declare function paramExpr(name: string, op: ':-' | ':=' | ':+' | ':?' | '-' | '+' | '?', word: string): string;
@@ -25,6 +25,10 @@ export declare function pathExpr(s: string): string;
 export declare function exprOfWord(w: Word, opts?: {
     preserveCmdSub?: boolean;
 }): string;
+/** Registered by sysinfo so wrapScript can emit fx-arith without a circular import. */
+export declare function setArithHelperPreamble(s: string): void;
+/** PowerShell expression: evaluate `$((…))` via fx-arith; errors are loud, expansion empty. */
+export declare function arithExpr(parts: WordPart[]): string;
 /** Literal text of a word when it contains no interpolation, else null. */
 export declare function literalOfWord(w: Word): string | null;
 /**

package/dist/translator.js

@@ -161,6 +161,9 @@ export function exprOfWord(w, opts) {
     if (expanded.length === 1 && expanded[0].kind === 'CmdSub') {
         return '$(' + translateCmdSub(expanded[0].cmd, opts?.preserveCmdSub === true) + ')';
     }
+    if (expanded.length === 1 && expanded[0].kind === 'Arith') {
+        return arithExpr(expanded[0].parts);
+    }
     const literal = expanded.every((p) => p.kind === 'Text' || p.kind === 'SingleQuoted');
     if (literal) {
         const text = expanded.map((p) => p.text).join('');
@@ -186,6 +189,9 @@ export function exprOfWord(w, opts) {
             case 'CmdSub':
                 out += '$(' + translateCmdSub(p.cmd, quoted || opts?.preserveCmdSub === true) + ')';
                 break;
+            case 'Arith':
+                out += arithExpr(p.parts);
+                break;
         }
     };
     for (const p of expanded)
@@ -193,6 +199,62 @@ export function exprOfWord(w, opts) {
     out += '"';
     return out;
 }
+let arithHelperPreamble = '';
+/** Registered by sysinfo so wrapScript can emit fx-arith without a circular import. */
+export function setArithHelperPreamble(s) {
+    arithHelperPreamble = s;
+}
+function injectArithHelpers(body) {
+    if (!arithHelperPreamble)
+        return body;
+    if (!/\bfx-arith\b/.test(body))
+        return body;
+    if (/function\s+fx-arith\b/.test(body))
+        return body;
+    return arithHelperPreamble + '\n' + body;
+}
+/** PowerShell expression: evaluate `$((…))` via fx-arith; errors are loud, expansion empty. */
+export function arithExpr(parts) {
+    const src = arithSourceExpr(parts);
+    return ('$(try { [string](fx-arith (' +
+        src +
+        ')) } catch { [Console]::Error.WriteLine((\'bash: \' + [string](' +
+        src +
+        ') + \': integer expression expected\')); $script:fx_exit = 1; \'\' })');
+}
+function arithSourceExpr(parts) {
+    if (parts.length === 0)
+        return "''";
+    if (parts.every((p) => p.kind === 'Text')) {
+        return psStr(parts.map((p) => p.text).join(''));
+    }
+    let out = '"';
+    const emit = (p) => {
+        switch (p.kind) {
+            case 'Text':
+            case 'SingleQuoted':
+                out += escapeDq(p.text);
+                break;
+            case 'DoubleQuoted':
+                for (const q of p.parts)
+                    emit(q);
+                break;
+            case 'Var':
+                out += '$(' + varExpr(p.name, p.index, p.param, p.length === true) + ')';
+                break;
+            case 'CmdSub':
+                out += '$(' + translateCmdSub(p.cmd, true) + ')';
+                break;
+            case 'Arith':
+                out += arithExpr(p.parts);
+                break;
+        }
+    };
+    for (const p of parts)
+        emit(p);
+    out += '"';
+    return out;
+}
 /** Literal text of a word when it contains no interpolation, else null. */
 export function literalOfWord(w) {
     if (!w.every((p) => p.kind === 'Text' || p.kind === 'SingleQuoted'))
@@ -895,6 +957,7 @@ function wrapBodyAndPersist(body, exitProcess) {
  */
 export function wrapScript(body, opts = {}) {
     const mode = opts.mode ?? 'spawn';
+    body = injectArithHelpers(body);
     const needed = mode === 'host' ? new Set() : wrapHelpersNeeded(body);
     const lines = mode === 'host'
         ? wrapCwdPreamble()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fauxnix-cli",
-  "version": "0.6.0",
+  "version": "0.7.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": {