fauxnix-cli 0.3.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/ast.d.ts

@@ -6,7 +6,7 @@
  *   - 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 ...)
+ *   - variables:            $VAR ${VAR} ${VAR[n]} plus special cases ($HOME $USER $PATH ...)
  *   - command substitution: $(...) (recursively translated)
  *   - env assignment prefix: VAR=value cmd
  *
@@ -62,6 +62,7 @@ export type WordPart = {
 } | {
     kind: 'Var';
     name: string;
+    index?: string;
 } | {
     kind: 'CmdSub';
     cmd: string;

package/dist/ast.js

@@ -6,7 +6,7 @@
  *   - 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 ...)
+ *   - variables:            $VAR ${VAR} ${VAR[n]} plus special cases ($HOME $USER $PATH ...)
  *   - command substitution: $(...) (recursively translated)
  *   - env assignment prefix: VAR=value cmd
  *
@@ -36,7 +36,7 @@ function partToString(p) {
         case 'DoubleQuoted':
             return p.parts.map(partToString).join('');
         case 'Var':
-            return `$${p.name}`;
+            return p.index !== undefined ? `\${${p.name}[${p.index}]}` : `$${p.name}`;
         case 'CmdSub':
             return '$(' + p.cmd + ')';
     }

package/dist/cli.js

@@ -26,7 +26,7 @@ export async function runCli(argv) {
     }
     const [verb, ...rest] = argv;
     if (verb === '--version' || verb === '-v') {
-        console.log('fauxnix 0.3.0');
+        console.log('fauxnix 0.4.0');
         return;
     }
     if (verb === 'list') {

package/dist/commands/archive.js

@@ -1,6 +1,6 @@
 import { wordToString } from '../ast.js';
 import { psStr } from '../registry.js';
-import { exprOfWord, operandExpr } from '../translator.js';
+import { argListExpr, exprOfWord, operandExpr } from '../translator.js';
 /* ------------------------------------------------------------------ */
 /* gzip family — .NET GZipStream helpers                               */
 /* ------------------------------------------------------------------ */
@@ -188,7 +188,7 @@ function gzBlock(args, ctx, forced) {
     fileLoop.push('  }');
     return [
         PS_GZ_FNS,
-        '$fx_files = @(' + (p.files.length ? p.files.map(operandExpr).join(', ') : '') + ')',
+        '$fx_files = ' + (p.files.length ? argListExpr(p.files, operandExpr) : '@()'),
         'if ($fx_files.Count -eq 0) {',
         stdinBranch,
         '} else {',
@@ -204,7 +204,7 @@ const zcat = (args, ctx) => gzBlock(args, ctx, { decompress: true, stdout: true
 /* ------------------------------------------------------------------ */
 const tar = (args) => {
     return [
-        "$fx_args = @(" + args.map(exprOfWord).join(', ') + ')',
+        '$fx_args = ' + argListExpr(args, exprOfWord),
         // Prefer the Windows-shipped bsdtar (System32): it accepts both path
         // styles. A PATH lookup could resolve to Git Bash's GNU tar, which
         // misreads `C:\...` argv as a remote-host spec (host:path syntax).
@@ -255,10 +255,10 @@ const zip = (args) => {
             "[Console]::Error.WriteLine('zip error: Nothing to do! (fauxnix: usage: zip [-r] ARCHIVE FILES...)'); $script:fx_exit = 12");
     }
     const arc = operandExpr(rest[0]);
-    const inputs = rest.slice(1).map(operandExpr).join(', ');
+    const inputs = argListExpr(rest.slice(1), operandExpr);
     return [
         note + '$fx_arc = ' + arc,
-        '$fx_inputs = @(' + inputs + ')',
+        '$fx_inputs = ' + inputs,
         '$fx_valid = @()',
         'foreach ($fx_p in $fx_inputs) {',
         '  if (Test-Path -LiteralPath $fx_p) { $fx_valid += $fx_p }',

package/dist/commands/files.js

@@ -1,6 +1,6 @@
 import { wordToString } from '../ast.js';
 import { parseWords, psStr } from '../registry.js';
-import { exprOfWord, operandExpr } from '../translator.js';
+import { argListExpr, exprOfWord, operandExpr } from '../translator.js';
 /* ------------------------------------------------------------------ */
 /* Shared PS snippets                                                  */
 /* ------------------------------------------------------------------ */
@@ -45,9 +45,7 @@ const PS_HSIZE_FN = [
 ].join('\n');
 /** Operand Words → PS array expression of string exprs. */
 function psArray(words, fn = operandExpr) {
-    if (words.length === 0)
-        return '@()';
-    return '@(' + words.map(fn).join(', ') + ')';
+    return argListExpr(words, fn);
 }
 /* ------------------------------------------------------------------ */
 /* ls                                                                  */
@@ -63,7 +61,7 @@ const ls = (args) => {
     const sortByTime = flags.has('t');
     const sortBySize = flags.has('S');
     const reverse = flags.has('r');
-    const targets = operandWords.length ? operandWords.map((w) => operandExpr(w)) : ["'.'"];
+    const targets = operandWords.length ? argListExpr(operandWords) : "@('.')";
     return [
         PS_GLOB_FN,
         PS_FTIME_FN,
@@ -84,7 +82,7 @@ const ls = (args) => {
         '  }',
         '  return $n',
         '}',
-        '$fx_targets = @(' + targets.join(', ') + ')',
+        '$fx_targets = ' + targets,
         '$fx_all = @()',
         'foreach ($fx_t in $fx_targets) {',
         '  foreach ($fx_g in (fx-glob $fx_t)) {',
@@ -126,12 +124,10 @@ const cp = (args) => {
     const { flags, longs, operandWords } = parseWords(args);
     const recurse = flags.has('r') || flags.has('R') || longs.has('--recursive');
     const verbose = flags.has('v') || longs.has('--verbose');
-    const srcs = psArray(operandWords.slice(0, -1));
-    const dst = operandWords.length >= 2 ? operandExpr(operandWords[operandWords.length - 1]) : "''";
     return [
         PS_GLOB_FN,
-        '$fx_srcs = ' + srcs,
-        '$fx_dst = ' + dst,
+        '$fx_all = ' + argListExpr(operandWords),
+        "if ($fx_all.Count -lt 2) { $fx_srcs = @(); $fx_dst = '' } else { $fx_dst = [string]$fx_all[$fx_all.Count - 1]; $fx_srcs = @($fx_all[0..($fx_all.Count - 2)]) }",
         "if ($fx_srcs.Count -eq 0) { [Console]::Error.WriteLine('cp: missing file operand'); $script:fx_exit = 1 }",
         "elseif ($fx_dst -eq '') { [Console]::Error.WriteLine('cp: missing destination file operand'); $script:fx_exit = 1 }",
         'else {',
@@ -154,12 +150,10 @@ const cp = (args) => {
 const mv = (args) => {
     const { flags, longs, operandWords } = parseWords(args);
     const verbose = flags.has('v') || longs.has('--verbose');
-    const srcs = psArray(operandWords.slice(0, -1));
-    const dst = operandWords.length >= 2 ? operandExpr(operandWords[operandWords.length - 1]) : "''";
     return [
         PS_GLOB_FN,
-        '$fx_srcs = ' + srcs,
-        '$fx_dst = ' + dst,
+        '$fx_all = ' + argListExpr(operandWords),
+        "if ($fx_all.Count -lt 2) { $fx_srcs = @(); $fx_dst = '' } else { $fx_dst = [string]$fx_all[$fx_all.Count - 1]; $fx_srcs = @($fx_all[0..($fx_all.Count - 2)]) }",
         "if ($fx_srcs.Count -eq 0) { [Console]::Error.WriteLine('mv: missing file operand'); $script:fx_exit = 1 }",
         "elseif ($fx_dst -eq '') { [Console]::Error.WriteLine('mv: missing destination file operand'); $script:fx_exit = 1 }",
         'elseif ($fx_srcs.Count -gt 1 -and -not (Test-Path -LiteralPath $fx_dst -PathType Container)) { [Console]::Error.WriteLine("mv: target \'" + $fx_dst + "\' is not a directory"); $script:fx_exit = 1 }',
@@ -274,13 +268,11 @@ const mktemp = (args) => {
 const ln = (args) => {
     const { flags, operandWords } = parseWords(args);
     const sym = flags.has('s');
-    const src = operandWords.length >= 2 ? operandExpr(operandWords[0]) : "''";
-    const dst = operandWords.length >= 2 ? operandExpr(operandWords[1]) : "''";
     const kind = sym ? 'SymbolicLink' : 'HardLink';
     const label = sym ? 'symbolic link' : 'hard link';
     return [
-        '$fx_src = ' + src,
-        '$fx_dst = ' + dst,
+        '$fx_ops = ' + argListExpr(operandWords),
+        "if ($fx_ops.Count -lt 2) { $fx_src = ''; $fx_dst = '' } else { $fx_src = [string]$fx_ops[0]; $fx_dst = [string]$fx_ops[1] }",
         "if ($fx_src -eq '' -or $fx_dst -eq '') { [Console]::Error.WriteLine('ln: missing file operand'); $script:fx_exit = 1 }",
         'else {',
         '  if (Test-Path -LiteralPath $fx_dst -PathType Container) { $fx_dst = Join-Path $fx_dst (Split-Path $fx_src -Leaf) }',
@@ -321,29 +313,28 @@ const realpath = (args) => {
 /* basename / dirname                                                  */
 /* ------------------------------------------------------------------ */
 const basename = (args) => {
-    if (args.length === 2) {
-        return [
-            '$fx_p = ' + exprOfWord(args[0]),
-            '$fx_sfx = ' + exprOfWord(args[1]),
-            "$fx_n = [IO.Path]::GetFileName(($fx_p.TrimEnd('/')).TrimEnd('\\'))",
-            "if ($fx_n -eq '') { $fx_n = '/' }",
-            "if ($fx_sfx -ne '' -and $fx_n.EndsWith($fx_sfx) -and ($fx_n.Length -gt $fx_sfx.Length)) { $fx_n = $fx_n.Substring(0, $fx_n.Length - $fx_sfx.Length) }",
-            '$fx_n',
-        ].join('\n');
-    }
     return [
-        '$fx_ps = @(' + args.map(exprOfWord).join(', ') + ')',
+        '$fx_ps = ' + argListExpr(args, exprOfWord),
         "if ($fx_ps.Count -eq 0) { [Console]::Error.WriteLine('basename: missing operand'); $script:fx_exit = 1 }",
-        'foreach ($fx_p in $fx_ps) {',
+        'elseif ($fx_ps.Count -eq 2) {',
+        '  $fx_p = [string]$fx_ps[0]',
+        '  $fx_sfx = [string]$fx_ps[1]',
         "  $fx_n = [IO.Path]::GetFileName(($fx_p.TrimEnd('/')).TrimEnd('\\'))",
         "  if ($fx_n -eq '') { $fx_n = '/' }",
+        "  if ($fx_sfx -ne '' -and $fx_n.EndsWith($fx_sfx) -and ($fx_n.Length -gt $fx_sfx.Length)) { $fx_n = $fx_n.Substring(0, $fx_n.Length - $fx_sfx.Length) }",
         '  $fx_n',
+        '} else {',
+        '  foreach ($fx_p in $fx_ps) {',
+        "    $fx_n = [IO.Path]::GetFileName(($fx_p.TrimEnd('/')).TrimEnd('\\'))",
+        "    if ($fx_n -eq '') { $fx_n = '/' }",
+        '    $fx_n',
+        '  }',
         '}',
     ].join('\n');
 };
 const dirname = (args) => {
     return [
-        '$fx_ps = @(' + args.map(exprOfWord).join(', ') + ')',
+        '$fx_ps = ' + argListExpr(args, exprOfWord),
         "if ($fx_ps.Count -eq 0) { [Console]::Error.WriteLine('dirname: missing operand'); $script:fx_exit = 1 }",
         'foreach ($fx_p in $fx_ps) {',
         "  $fx_n = ($fx_p.TrimEnd('/')).TrimEnd('\\')",
@@ -428,7 +419,7 @@ const du = (args) => {
     const { flags, longs, operandWords } = parseWords(args, [], ['--max-depth']);
     const sum = flags.has('s') || longs.has('--summarize');
     const human = flags.has('h') || longs.has('--human-readable');
-    const targets = operandWords.length ? operandWords.map((w) => operandExpr(w)) : ["'.'"];
+    const targets = operandWords.length ? argListExpr(operandWords) : "@('.')";
     return [
         PS_HSIZE_FN,
         'function fx-size($p) {',
@@ -436,7 +427,7 @@ const du = (args) => {
         '  Get-ChildItem -LiteralPath $p -Recurse -Force -File -ErrorAction SilentlyContinue | ForEach-Object { $t += $_.Length }',
         '  return [math]::Ceiling($t / 1KB)',
         '}',
-        '$fx_ts = @(' + targets.join(', ') + ')',
+        '$fx_ts = ' + targets,
         'foreach ($fx_t in $fx_ts) {',
         '  if (-not (Test-Path -LiteralPath $fx_t)) { [Console]::Error.WriteLine("du: cannot access \'" + $fx_t + "\': No such file or directory"); $script:fx_exit = 1; continue }',
         '  if (' + (sum ? '$true' : '$false') + ') {',
@@ -500,7 +491,7 @@ const find = (args) => {
     const sizeExpr = extractValue(preds, ['-size']);
     const mtimeExpr = extractValue(preds, ['-mtime']);
     const wantDelete = preds.includes('-delete');
-    const paths = pathWords.length ? pathWords.map((w) => operandExpr(w)) : ["'.'"];
+    const paths = pathWords.length ? argListExpr(pathWords) : "@('.')";
     const conditions = [];
     if (namePat !== null)
         conditions.push("($fx_i.Name -like '" + likeOf(namePat) + "')");
@@ -516,7 +507,7 @@ const find = (args) => {
     const sizeCond = sizeOf(sizeExpr);
     const mtimeCond = mtimeOf(mtimeExpr);
     return [
-        '$fx_paths = @(' + paths.join(', ') + ')',
+        '$fx_paths = ' + paths,
         'foreach ($fx_p in $fx_paths) {',
         '  if (-not (Test-Path -LiteralPath $fx_p)) { [Console]::Error.WriteLine("find: \'" + $fx_p + "\': No such file or directory"); $script:fx_exit = 1; continue }',
         '  $fx_root = (Get-Item -LiteralPath $fx_p -Force).FullName',
@@ -632,13 +623,11 @@ const diff = (args) => {
     const unified = flags.has('u') || flags.has('U');
     const brief = flags.has('q') || flags.has('brief');
     void unified;
-    const a = operandWords.length > 0 ? operandExpr(operandWords[0]) : "''";
-    const b = operandWords.length > 1 ? operandExpr(operandWords[1]) : "''";
     return [
         PS_READTEXT_FN,
         'function fx-dr($x, $y) { if ($x -eq $y) { return [string]$x } else { return ([string]$x) + \',\' + ([string]$y) } }',
-        '$fx_a = ' + a,
-        '$fx_b = ' + b,
+        '$fx_ops = ' + argListExpr(operandWords),
+        "if ($fx_ops.Count -lt 2) { $fx_a = ''; $fx_b = '' } else { $fx_a = [string]$fx_ops[0]; $fx_b = [string]$fx_ops[1] }",
         "if ($fx_a -eq '' -or $fx_b -eq '') { [Console]::Error.WriteLine('diff: missing operand'); $script:fx_exit = 2 }",
         'elseif (-not (Test-Path -LiteralPath $fx_a)) { [Console]::Error.WriteLine("diff: " + $fx_a + ": No such file or directory"); $script:fx_exit = 2 }',
         'elseif (-not (Test-Path -LiteralPath $fx_b)) { [Console]::Error.WriteLine("diff: " + $fx_b + ": No such file or directory"); $script:fx_exit = 2 }',

package/dist/commands/net.js

@@ -1,6 +1,6 @@
 import { wordToString } from '../ast.js';
 import { parseWords, psErr, psStr } from '../registry.js';
-import { exprOfWord, literalOfWord, operandExpr } from '../translator.js';
+import { argListExpr, exprOfWord, literalOfWord, operandExpr } from '../translator.js';
 /* ------------------------------------------------------------------ */
 /* Shared PS snippets                                                  */
 /* ------------------------------------------------------------------ */
@@ -94,7 +94,7 @@ const curl = (args) => {
     // refuses private/loopback URLs before the process is even started.
     return [
         PS_NETGUARD_FNS,
-        "$fx_args = @(" + args.map(exprOfWord).join(', ') + ')',
+        '$fx_args = ' + argListExpr(args, exprOfWord),
         '$fx_bad = $false',
         "foreach ($fx_a in $fx_args) { if (fx-netguard 'curl' $fx_a) { $fx_bad = $true } }",
         'if ($fx_bad) { $script:fx_exit = 1 }',
@@ -212,11 +212,11 @@ function mapWgetArgs(args) {
     return { margs, sawOutput, urls };
 }
 const wget = (args) => {
-    const orig = args.map(exprOfWord);
+    const orig = args.map((w) => exprOfWord(w));
     const mapped = mapWgetArgs(args);
     return [
         PS_NETGUARD_FNS,
-        '$fx_args = @(' + orig.join(', ') + ')',
+        '$fx_args = ' + argListExpr(args, exprOfWord),
         '$fx_margs = @(' + mapped.margs.join(', ') + ')',
         '$fx_bad = $false',
         "foreach ($fx_a in $fx_args) { if (fx-netguard 'wget' $fx_a) { $fx_bad = $true } }",
@@ -456,7 +456,10 @@ const ifconfig = (args) => {
 /* ------------------------------------------------------------------ */
 /* nslookup / dig / host                                               */
 /* ------------------------------------------------------------------ */
-const nslookup = (args) => nativeCall('nslookup.exe', args.map(exprOfWord).join(', '));
+const nslookup = (args) => [
+    '$fx_args = ' + argListExpr(args, exprOfWord),
+    nativeCall('nslookup.exe', '$fx_args'),
+].join('\n');
 const dig = (args) => {
     const raw = args.map(wordToString);
     let short = false;

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 { exprOfWord, operandExpr, translateSimple, wrapTempEnv, encodeSetValExpr, escapeDq, translateCmdSub, normalizeLiteralPath, pathExpr, } from '../translator.js';
+import { argListExpr, exprOfWord, operandExpr, translateSimple, wrapTempEnv, encodeSetValExpr, escapeDq, translateCmdSub, normalizeLiteralPath, pathExpr, } from '../translator.js';
 import { handlers as textIoHandlers } from './text-io.js';
 /* ------------------------------------------------------------------ */
 /* Shared TS helpers                                                   */
@@ -10,6 +10,7 @@ const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function emitSetValPut(nameLit, valueExpr) {
     const n = nameLit.replace(/'/g, "''");
     return [
+        "fx-arrdrop '" + n + "'",
         '$fx_sv = @()',
         'foreach ($fx_pair in @($env:FAUXNIX_SETVALS -split [string][char]10)) {',
         '  $fx_eq = $fx_pair.IndexOf([char]61)',
@@ -22,6 +23,7 @@ function emitSetValPut(nameLit, valueExpr) {
 }
 function emitSetValDelRuntime(nameVar) {
     return [
+        'fx-arrdrop ' + nameVar,
         '$fx_sv = @()',
         'foreach ($fx_pair in @($env:FAUXNIX_SETVALS -split [string][char]10)) {',
         '  $fx_eq = $fx_pair.IndexOf([char]61)',
@@ -62,9 +64,7 @@ function splitAssignWord(w) {
 }
 /** Text Words -> PS array expression. */
 function textArgs(words) {
-    if (words.length === 0)
-        return '@()';
-    return '@(' + words.map(exprOfWord).join(', ') + ')';
+    return argListExpr(words, exprOfWord);
 }
 /** Drop dash-arguments, return operand words. */
 function stripFlags(args) {
@@ -128,10 +128,12 @@ const cd = (args) => {
         ].join('\n');
     }
     return [
-        '$fx_d = ' + operandExpr(args[0]),
+        '$fx_ds = ' + argListExpr([args[0]]),
+        "if ($fx_ds.Count -ne 1) { [Console]::Error.WriteLine('bash: cd: too many arguments'); $script:fx_exit = 1 }",
+        'else { $fx_d = [string]$fx_ds[0]',
         'if (-not (Test-Path -LiteralPath $fx_d)) { [Console]::Error.WriteLine("bash: cd: " + $fx_d + ": No such file or directory"); $script:fx_exit = 1 }',
         'elseif (-not (Test-Path -LiteralPath $fx_d -PathType Container)) { [Console]::Error.WriteLine("bash: cd: " + $fx_d + ": Not a directory"); $script:fx_exit = 1 }',
-        'else { try { Set-Location -LiteralPath $fx_d } catch { [Console]::Error.WriteLine("bash: cd: " + $fx_d + ": No such file or directory"); $script:fx_exit = 1 } }',
+        'else { try { Set-Location -LiteralPath $fx_d } catch { [Console]::Error.WriteLine("bash: cd: " + $fx_d + ": No such file or directory"); $script:fx_exit = 1 } } }',
     ].join('\n');
 };
 const pwd = (args) => {
@@ -162,7 +164,7 @@ const exportCmd = (args) => {
     }
     return sets
         .map((s) => {
-        const val = exprOfWord(s.value);
+        const val = exprOfWord(s.value, { preserveCmdSub: true });
         return ('$fx_exv = ' +
             val +
             '; $env:' +
@@ -886,6 +888,7 @@ const FX_TNK_FN = [
     '  $fx_ev = Get-ChildItem Env: | Where-Object { $_.Name -ceq $n } | Select-Object -First 1',
     '  $nm = if ($fx_ev) { $fx_ev.Name } else { $n }',
     "  Set-Item -LiteralPath ('Env:' + $nm) -Value ([string][long]$v)",
+    '  fx-arrdrop $n',
     "  $env:FAUXNIX_SETVARS = ((@($env:FAUXNIX_SETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) + $n) -join ';')",
     "  $env:FAUXNIX_UNSETVARS = (@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) -join ';')",
     '  $fx_sv = @()',
@@ -1341,6 +1344,9 @@ function kshExprOfWord(w) {
     if (tilde && expanded.length === 0)
         return '(fx-home)';
     if (!tilde && expanded.length === 1 && expanded[0].kind === 'Var') {
+        if (expanded[0].index !== undefined) {
+            return '(fx-subget ' + psStr(expanded[0].name) + ' ' + psStr(expanded[0].index) + ')';
+        }
         return '(fx-envget ' + psStr(expanded[0].name) + ')';
     }
     const literal = !tilde && expanded.every((p) => p.kind === 'Text' || p.kind === 'SingleQuoted');
@@ -1362,10 +1368,14 @@ function kshExprOfWord(w) {
                     emitPart(q);
                 break;
             case 'Var':
-                out += '$(fx-envget ' + psStr(p.name) + ')';
+                out +=
+                    p.index !== undefined
+                        ? '$(fx-subget ' + psStr(p.name) + ' ' + psStr(p.index) + ')'
+                        : '$(fx-envget ' + psStr(p.name) + ')';
                 break;
             case 'CmdSub':
-                out += '$(' + translateCmdSub(p.cmd) + ')';
+                // [[ ]] does not IFS-split, so keep the newline contract.
+                out += '$(' + translateCmdSub(p.cmd, true) + ')';
                 break;
         }
     };
@@ -1378,7 +1388,16 @@ const FX_ISSET_FN = [
     'function fx-isset($n) {',
     '  $n = [string]$n',
     "  if ($n -eq '') { return $false }",
-    "  if ($n -match '^([A-Za-z_][A-Za-z0-9_]*)\\[(0|@|\\*)\\]$') { $n = $Matches[1] }",
+    "  if ($n -match '^([A-Za-z_][A-Za-z0-9_]*)\\[([0-9]+|@|\\*)\\]$') {",
+    '    $fx_ib = $Matches[1]; $fx_ix = [string]$Matches[2]',
+    "    if ($fx_ix -eq '@' -or $fx_ix -eq '*' -or $fx_ix -eq '0') { $n = $fx_ib }",
+    '    else {',
+    '      $fx_ia = @(fx-arrload $fx_ib)',
+    '      $fx_ii = 0',
+    '      if (-not [int]::TryParse($fx_ix, [ref]$fx_ii)) { return $false }',
+    '      return ($fx_ii -ge 0 -and $fx_ii -lt $fx_ia.Count)',
+    '    }',
+    '  }',
     "  elseif ($n -match '^[A-Za-z_][A-Za-z0-9_]*\\[') { return $false }",
     "  if (@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ceq $n }).Count -gt 0) { return $false }",
     "  if (@($env:FAUXNIX_SETVARS -split ';' | Where-Object { $_ -ceq $n }).Count -gt 0) { return $true }",
@@ -1425,18 +1444,11 @@ const FX_RE_FN = [
     '  try {',
     '    $fx_rm = [regex]::Match([string]$a, (fx-posixre ([string]$b)), [Text.RegularExpressions.RegexOptions]::Singleline)',
     '    if ($fx_rm.Success) {',
-    '      $env:BASH_REMATCH = [string]$fx_rm.Value',
-    "      $env:FAUXNIX_SETVARS = ((@($env:FAUXNIX_SETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne 'BASH_REMATCH' }) + 'BASH_REMATCH') -join ';')",
-    "      $env:FAUXNIX_UNSETVARS = (@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne 'BASH_REMATCH' }) -join ';')",
-    '      $fx_enc = ([string]$fx_rm.Value).Replace([string][char]92, ([string][char]92 + [string][char]92)).Replace([string][char]13, ([string][char]92 + [char]114)).Replace([string][char]10, ([string][char]92 + [char]110))',
-    "      $fx_sv = @(); foreach ($fx_pair in @($env:FAUXNIX_SETVALS -split [string][char]10)) { $fx_eq = $fx_pair.IndexOf([char]61); if ($fx_eq -lt 1) { continue }; if ($fx_pair.Substring(0, $fx_eq) -cne 'BASH_REMATCH') { $fx_sv += $fx_pair } }",
-    "      $fx_sv += ('BASH_REMATCH' + [string][char]61 + $fx_enc); $env:FAUXNIX_SETVALS = ($fx_sv -join [string][char]10)",
+    '      $fx_gs = @(); foreach ($fx_g in $fx_rm.Groups) { $fx_gs += ,[string]$fx_g.Value }',
+    "      fx-arrput 'BASH_REMATCH' $fx_gs",
     '      return $true',
     '    }',
-    "    Remove-Item -LiteralPath 'Env:\\BASH_REMATCH' -ErrorAction SilentlyContinue",
-    "    $env:FAUXNIX_SETVARS = (@($env:FAUXNIX_SETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne 'BASH_REMATCH' }) -join ';')",
-    "    $env:FAUXNIX_UNSETVARS = ((@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne 'BASH_REMATCH' }) + 'BASH_REMATCH') -join ';')",
-    "    $fx_sv = @(); foreach ($fx_pair in @($env:FAUXNIX_SETVALS -split [string][char]10)) { $fx_eq = $fx_pair.IndexOf([char]61); if ($fx_eq -lt 1) { continue }; if ($fx_pair.Substring(0, $fx_eq) -cne 'BASH_REMATCH') { $fx_sv += $fx_pair } }; $env:FAUXNIX_SETVALS = ($fx_sv -join [string][char]10)",
+    "    fx-arrclr 'BASH_REMATCH'",
     '    return $false',
     '  }',
     "  catch { [Console]::Error.WriteLine('bash: [[: invalid regular expression'); $script:fx_exit = 2; return $false }",

package/dist/commands/text-filters.js

@@ -3,7 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { FauxnixParseError, wordToString } from '../ast.js';
 import { parseWords, psStr } from '../registry.js';
-import { exprOfWord, literalOfWord, operandExpr } from '../translator.js';
+import { argListExpr, exprOfWord, literalOfWord, operandExpr } from '../translator.js';
 /* ------------------------------------------------------------------ */
 /* Shared PS snippets (same shape as files.ts)                         */
 /* ------------------------------------------------------------------ */
@@ -34,9 +34,7 @@ const PS_SPLITLINES_FN = [
 const STDIN_LINES = '@($input | ForEach-Object { [string]$_ })';
 /** Operand Words → PS array expression of string exprs. */
 function psArray(words, fn = operandExpr) {
-    if (words.length === 0)
-        return '@()';
-    return '@(' + words.map(fn).join(', ') + ')';
+    return argListExpr(words, fn);
 }
 /** PS boolean literal. */
 function pb(v) {

package/dist/commands/text-io.js

@@ -1,6 +1,6 @@
 import { wordToString } from '../ast.js';
 import { lookup, parseWords, psStr } from '../registry.js';
-import { exprOfWord, operandExpr } from '../translator.js';
+import { argListExpr, exprOfWord, operandExpr } from '../translator.js';
 /* ------------------------------------------------------------------ */
 /* Shared PS snippets (same shape as files.ts / text-filters.ts)       */
 /* ------------------------------------------------------------------ */
@@ -80,6 +80,9 @@ const PS_UNESQ_FN = [
 const PS_WRITE_FN = [
     'function fx-write($s, $term) {',
     "  if ($s -eq '') { return }",
+    // Inside quoted/assignment $(...) the collector wants one string object
+    // so interior newlines survive (PS would otherwise join lines with spaces).
+    '  if ($script:fx_csub) { $s; return }',
     '  if (-not $term) { $s; return }',
     '  if (-not $s.EndsWith([string][char]10)) { [Console]::Out.Write($s); return }',
     '  $t = $s.Substring(0, $s.Length - 1)',
@@ -110,9 +113,7 @@ function qErr(cmd, g, msg, lead = 'cannot open ') {
 }
 /** Operand Words → PS array expression of string exprs. */
 function psArray(words, fn = operandExpr) {
-    if (words.length === 0)
-        return '@()';
-    return '@(' + words.map(fn).join(', ') + ')';
+    return argListExpr(words, fn);
 }
 /**
  * Collect file operands through fx-glob into `$fx_srcs`. A literal `-`
@@ -136,8 +137,8 @@ function psCollectFiles(operandWords, missErr, dirErr, stdinDefault = true) {
         const lit = w.every((p) => p.kind === 'Text' || p.kind === 'SingleQuoted')
             ? w.map((p) => p.text).join('')
             : null;
-        out.push('$fx_d = ' + (lit !== null ? psStr(lit) : exprOfWord(w)));
-        out.push('foreach ($fx_g in (fx-glob ' + operandExpr(w) + ')) {');
+        out.push('foreach ($fx_d in ' + argListExpr([w], lit !== null ? operandExpr : exprOfWord) + ') {');
+        out.push('foreach ($fx_g in (fx-glob $fx_d)) {');
         if (dirErr) {
             const dis = lit !== null && /[*?]/.test(lit) ? '$fx_g' : '$fx_d';
             out.push('  if (Test-Path -LiteralPath $fx_g -PathType Container) { ' +
@@ -153,7 +154,7 @@ function psCollectFiles(operandWords, missErr, dirErr, stdinDefault = true) {
             (lit !== null && /[*?]/.test(lit)
                 ? '$fx_names += $fx_g'
                 : '$fx_names += $fx_d'));
-        out.push('}');
+        out.push('}', '}');
     }
     return out;
 }
@@ -915,16 +916,6 @@ const base64 = (args, ctx) => {
 const seq = (args, ctx) => {
     const { flags, values, operandWords } = parseWords(args, ['s']);
     const eq = flags.has('w');
-    const nums = operandWords.map((w) => exprOfWord(w));
-    if (nums.length === 0) {
-        return psErrExpr(psStr('seq: missing operand'));
-    }
-    if (nums.length > 3) {
-        return psErrExpr(psStr('seq: extra operand ') + ' + ' + nums[3]);
-    }
-    const first = nums.length >= 2 ? nums[0] : '1';
-    const inc = nums.length === 3 ? nums[1] : '1';
-    const last = nums.length === 3 ? nums[2] : nums[nums.length - 1];
     const sepExpr = values.has('-s') ? psStr(values.get('-s')) : '[string][char]10';
     return [
         PS_WRITE_FN,
@@ -937,9 +928,17 @@ const seq = (args, ctx) => {
         "  if ([string]$s -match '^[+-]?[0-9]*\\.([0-9]+)') { return $Matches[1].Length }",
         '  return 0',
         '}',
-        '$fx_a = [string](' + first + ')',
-        '$fx_b = [string](' + inc + ')',
-        '$fx_c = [string](' + last + ')',
+        '$fx_nums = ' + argListExpr(operandWords),
+        "if ($fx_nums.Count -eq 0) { " +
+            psErrExpr(psStr('seq: missing operand')) +
+            ' }',
+        "elseif ($fx_nums.Count -gt 3) { " +
+            psErrExpr(psStr('seq: extra operand ') + ' + $fx_nums[3]') +
+            ' }',
+        'else {',
+        "  $fx_a = [string]$(if ($fx_nums.Count -ge 2) { $fx_nums[0] } else { '1' })",
+        "  $fx_b = [string]$(if ($fx_nums.Count -eq 3) { $fx_nums[1] } else { '1' })",
+        '  $fx_c = [string]$(if ($fx_nums.Count -eq 3) { $fx_nums[2] } else { $fx_nums[$fx_nums.Count - 1] })',
         '$fx_first = fx-tod $fx_a',
         '$fx_inc = fx-tod $fx_b',
         '$fx_last = fx-tod $fx_c',
@@ -968,6 +967,7 @@ const seq = (args, ctx) => {
         '  }',
         '  if ($fx_strs.Count -eq 0) { }',
         '  else { fx-write (($fx_strs -join (' + sepExpr + ')) + [string][char]10) $fx_term }',
+        '  }',
         '}',
     ].join('\n');
 };
@@ -1069,8 +1069,6 @@ const xargs = (args) => {
     if (firstLit !== null && lookup(firstLit) !== undefined) {
         return psErrExpr(psStr(XARGS_BUILTIN_MSG));
     }
-    const cmdExpr = exprOfWord(target[0]);
-    const baseArgs = psArray(target.slice(1), exprOfWord);
     const n = chunkN !== null && Number.isFinite(chunkN) && chunkN > 0 ? chunkN : 0;
     const replExpr = repl !== null ? psStr(repl) : null;
     const invoke = [
@@ -1137,8 +1135,8 @@ const xargs = (args) => {
     return [
         PS_SPLITLINES_FN,
         STDIN_INLINES,
-        '$fx_cmd = ' + cmdExpr,
-        '$fx_base = ' + baseArgs,
+        '$fx_tg = ' + argListExpr(target, exprOfWord),
+        "if ($fx_tg.Count -eq 0) { $fx_cmd = ''; $fx_base = @() } else { $fx_cmd = [string]$fx_tg[0]; $fx_base = $(if ($fx_tg.Count -gt 1) { @($fx_tg[1..($fx_tg.Count - 1)]) } else { @() }) }",
         "$fx_args = @($fx_in | Where-Object { $_ -ne '' })",
         ...dispatch,
     ].join('\n');

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.3.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/dist/parser.js

@@ -200,7 +200,11 @@ function readDollar(input, i) {
         if (end === -1)
             throw new FauxnixParseError('fauxnix: unclosed ${');
         const name = input.slice(j + 1, end);
-        if (!isNameStart(name[0]) || !name.split('').every(isNameChar)) {
+        const sub = name.match(/^([A-Za-z_][A-Za-z0-9_]*)\[([0-9]+|@|\*)\]$/);
+        if (sub) {
+            return { part: { kind: 'Var', name: sub[1], index: sub[2] }, next: end + 1 };
+        }
+        if (!name || !isNameStart(name[0]) || !name.split('').every(isNameChar)) {
             // ${VAR:-default} etc. — unsupported, kept as raw text
             return { part: { kind: 'Text', text: input.slice(i, end + 1) }, next: end + 1 };
         }

package/dist/translator.d.ts

@@ -1,7 +1,7 @@
 import { Assignment, CommandList, Redirect, SimpleCommand, Word } from './ast.js';
 import { PipelineCtx } from './registry.js';
 /** Map a bash $VAR name to a PowerShell expression (usable inside $(...)). */
-export declare function varExpr(name: string): string;
+export declare function varExpr(name: string, index?: string): string;
 /** Escape text destined for the inside of a PS double-quoted string. */
 export declare function escapeDq(s: string): string;
 /** Normalize a literal POSIX-ish path to its Windows equivalent. */
@@ -17,7 +17,9 @@ export declare function pathExpr(s: string): string;
  * Literal words become single-quoted strings; dynamic ones become
  * double-quoted strings with $(...) interpolation.
  */
-export declare function exprOfWord(w: Word): string;
+export declare function exprOfWord(w: Word, opts?: {
+    preserveCmdSub?: boolean;
+}): string;
 /** Literal text of a word when it contains no interpolation, else null. */
 export declare function literalOfWord(w: Word): string | null;
 /**
@@ -25,8 +27,25 @@ export declare function literalOfWord(w: Word): string | null;
  * Literal paths get POSIX-ish normalization (/dev/null, /tmp, /d/...).
  */
 export declare function operandExpr(w: Word): string;
-/** Translate the inside of $(...) — pipelines only, no wrappers. */
-export declare function translateCmdSub(cmdText: string): string;
+/**
+ * `${name[@]}` / `"pre${name[@]}post"` — one argv per element.
+ * Unquoted `${name[*]}` also splats (bash); quoted `"${name[*]}"` stays one join.
+ */
+export declare function splatSpec(w: Word): {
+    name: string;
+    prefix: string;
+    suffix: string;
+} | null;
+/** PS expression of a string[]: `@` words splat, others stay one element. */
+export declare function argListExpr(words: Word[], fn?: (w: Word) => string): string;
+/**
+ * Translate the inside of $(...).
+ * `keepNl`: quoted words and assignments keep interior newlines (bash).
+ * Unquoted command words join non-empty lines with a space (IFS
+ * word-split approximation). Handlers often emit one string object, so
+ * a bare `$(…)` interpolation would keep those newlines.
+ */
+export declare function translateCmdSub(cmdText: string, keepNl?: boolean): string;
 export declare function translateSimple(cmd: SimpleCommand, position: PipelineCtx['position'], hasStdin: boolean): string;
 /** PS expr: encode a string so SETVALS records can stay newline-delimited. */
 export declare function encodeSetValExpr(srcExpr: string): string;

package/dist/translator.js

@@ -5,7 +5,13 @@ import { lookup, psStr } from './registry.js';
 /* Variable mapping                                                    */
 /* ------------------------------------------------------------------ */
 /** Map a bash $VAR name to a PowerShell expression (usable inside $(...)). */
-export function varExpr(name) {
+export function varExpr(name, index) {
+    // Indexed reads always go through fx-subget → fx-arrload → fx-scalar0 so
+    // ${PWD[0]} keeps the special mapping and ${bash_rematch[0]} stays
+    // case-exact (a `$env:name` fallback would alias BASH_REMATCH on Windows).
+    if (index !== undefined) {
+        return '(fx-subget ' + psStr(name) + ' ' + psStr(index) + ')';
+    }
     switch (name) {
         case 'HOME':
             return '$HOME';
@@ -85,7 +91,7 @@ export function pathExpr(s) {
  * Literal words become single-quoted strings; dynamic ones become
  * double-quoted strings with $(...) interpolation.
  */
-export function exprOfWord(w) {
+export function exprOfWord(w, opts) {
     // tilde expansion (unquoted leading ~)
     const expanded = [];
     if (w.length > 0 && w[0].kind === 'Text' && w[0].text.startsWith('~')) {
@@ -100,7 +106,12 @@ export function exprOfWord(w) {
     }
     // single bare variable → bare expression
     if (expanded.length === 1 && expanded[0].kind === 'Var') {
-        return varExpr(expanded[0].name);
+        return varExpr(expanded[0].name, expanded[0].index);
+    }
+    // Bare `$(...)` must not sit inside a PS expandable string: the
+    // substitution body contains `"` / `$_` that would break interpolation.
+    if (expanded.length === 1 && expanded[0].kind === 'CmdSub') {
+        return '$(' + translateCmdSub(expanded[0].cmd, opts?.preserveCmdSub === true) + ')';
     }
     const literal = expanded.every((p) => p.kind === 'Text' || p.kind === 'SingleQuoted');
     if (literal) {
@@ -109,7 +120,7 @@ export function exprOfWord(w) {
     }
     // dynamic — build a PS double-quoted string with interpolation
     let out = '"';
-    const emitPart = (p) => {
+    const emitPart = (p, quoted) => {
         switch (p.kind) {
             case 'Text':
                 out += escapeDq(p.text);
@@ -119,18 +130,18 @@ export function exprOfWord(w) {
                 break;
             case 'DoubleQuoted':
                 for (const q of p.parts)
-                    emitPart(q);
+                    emitPart(q, true);
                 break;
             case 'Var':
-                out += '$(' + varExpr(p.name) + ')';
+                out += '$(' + varExpr(p.name, p.index) + ')';
                 break;
             case 'CmdSub':
-                out += '$(' + translateCmdSub(p.cmd) + ')';
+                out += '$(' + translateCmdSub(p.cmd, quoted || opts?.preserveCmdSub === true) + ')';
                 break;
         }
     };
     for (const p of expanded)
-        emitPart(p);
+        emitPart(p, false);
     out += '"';
     return out;
 }
@@ -153,17 +164,96 @@ export function operandExpr(w) {
         return pathExpr(normalizeLiteralPath(lit));
     return exprOfWord(w);
 }
+/** Flatten quotes but remember whether a part sat inside `"..."`. */
+function wordPartsForSplat(w) {
+    const out = [];
+    const walk = (parts, quoted) => {
+        for (const p of parts) {
+            if (p.kind === 'DoubleQuoted')
+                walk(p.parts, true);
+            else
+                out.push({ part: p, quoted });
+        }
+    };
+    walk(w, false);
+    return out;
+}
+/**
+ * `${name[@]}` / `"pre${name[@]}post"` — one argv per element.
+ * Unquoted `${name[*]}` also splats (bash); quoted `"${name[*]}"` stays one join.
+ */
+export function splatSpec(w) {
+    const parts = wordPartsForSplat(w);
+    let name = null;
+    let prefix = '';
+    let suffix = '';
+    let seen = false;
+    for (const { part: p, quoted } of parts) {
+        const splat = p.kind === 'Var' && (p.index === '@' || (p.index === '*' && !quoted));
+        if (splat) {
+            if (seen)
+                return null;
+            seen = true;
+            name = p.name;
+            continue;
+        }
+        if (p.kind !== 'Text' && p.kind !== 'SingleQuoted')
+            return null;
+        if (seen)
+            suffix += p.text;
+        else
+            prefix += p.text;
+    }
+    return name ? { name, prefix, suffix } : null;
+}
+/** PS expression of a string[]: `@` words splat, others stay one element. */
+export function argListExpr(words, fn = exprOfWord) {
+    if (words.length === 0)
+        return '@()';
+    return ('(' +
+        words
+            .map((w) => {
+            const s = splatSpec(w);
+            if (!s)
+                return '@(' + fn(w) + ')';
+            if (!s.prefix && !s.suffix)
+                return '@(fx-arrload ' + psStr(s.name) + ')';
+            return ('@($( $fx_sp = @(fx-arrload ' +
+                psStr(s.name) +
+                '); if ($fx_sp.Count -eq 0) { $fx_sp = @(' +
+                psStr(s.prefix + s.suffix) +
+                ') } else { $fx_sp[0] = ' +
+                psStr(s.prefix) +
+                ' + $fx_sp[0]; $fx_sp[$fx_sp.Count-1] = $fx_sp[$fx_sp.Count-1] + ' +
+                psStr(s.suffix) +
+                ' }; $fx_sp ))');
+        })
+            .join(' + ') +
+        ')');
+}
 /* ------------------------------------------------------------------ */
 /* Command substitution                                                */
 /* ------------------------------------------------------------------ */
-/** Translate the inside of $(...) — pipelines only, no wrappers. */
-export function translateCmdSub(cmdText) {
+/**
+ * Translate the inside of $(...).
+ * `keepNl`: quoted words and assignments keep interior newlines (bash).
+ * Unquoted command words join non-empty lines with a space (IFS
+ * word-split approximation). Handlers often emit one string object, so
+ * a bare `$(…)` interpolation would keep those newlines.
+ */
+export function translateCmdSub(cmdText, keepNl = false) {
     const list = parseCommand(cmdText);
     if (list.segments.length !== 1) {
         throw new FauxnixParseError('fauxnix: command substitution with ; && || is not supported yet');
     }
     const { defs, call } = translatePipelineBody(list.segments[0].pipeline);
-    return defs ? defs + '\n' + call : call;
+    const inner = defs ? defs + '\n' + call : call;
+    const collected = '(fx-csub { ' + inner + ' })';
+    if (keepNl)
+        return collected;
+    return ('((' +
+        collected +
+        " -split [string][char]10 | Where-Object { $_ -ne '' }) -join ' ')");
 }
 /* ------------------------------------------------------------------ */
 /* Simple command translation                                          */
@@ -182,8 +272,26 @@ export function translateSimple(cmd, position, hasStdin) {
         return exportHandler ? exportHandler(words, { position, hasStdin }) : '';
     }
     const nameLit = literalOfWord(cmd.name);
+    const nameSplat = splatSpec(cmd.name);
     let body;
-    if (nameLit !== null) {
+    if (nameSplat) {
+        const invoke = '& $fx_cmd @fx_na';
+        body = [
+            '$fx_cw = @(fx-arrload ' + psStr(nameSplat.name) + ')',
+            'if ($fx_cw.Count -eq 0) { $fx_cw = @(' + psStr(nameSplat.prefix + nameSplat.suffix) + ') }',
+            'else { $fx_cw[0] = ' +
+                psStr(nameSplat.prefix) +
+                ' + $fx_cw[0]; $fx_cw[$fx_cw.Count-1] = $fx_cw[$fx_cw.Count-1] + ' +
+                psStr(nameSplat.suffix) +
+                ' }',
+            '$fx_cmd = [string]$fx_cw[0]',
+            '$fx_na = ' + argListExpr(cmd.args),
+            'if ($fx_cw.Count -gt 1) { $fx_na = @($fx_cw[1..($fx_cw.Count - 1)]) + $fx_na }',
+            (hasStdin ? '($input | ' + invoke + ')' : invoke) + ' | ForEach-Object { [string]$_ }',
+            'if ($LASTEXITCODE -gt 0) { $script:fx_exit = $LASTEXITCODE } elseif ($LASTEXITCODE -lt 0) { $script:fx_exit = 1 }',
+        ].join('\n');
+    }
+    else if (nameLit !== null) {
         const handler = lookup(nameLit);
         if (handler && !(nameLit === '[[' && !isUnquotedLiteral(cmd.name, '[['))) {
             body = handler(cmd.args, { position, hasStdin });
@@ -193,12 +301,11 @@ export function translateSimple(cmd, position, hasStdin) {
             // invoked with the call operator and an argv-style argument array —
             // no string re-parsing of user text.
             const nameExpr = psStr(nameLit);
-            const argExprs = cmd.args.map((a) => exprOfWord(a));
-            const args = argExprs.length ? ' @(' + argExprs.join(', ') + ')' : '';
-            const call = '& ' + nameExpr + args;
+            const invoke = '& ' + nameExpr + ' @fx_na';
             body = [
+                '$fx_na = ' + argListExpr(cmd.args),
                 // feed pipeline stdin into the native process when we are a non-first stage
-                (hasStdin ? '($input | ' + call + ')' : call) + ' | ForEach-Object { [string]$_ }',
+                (hasStdin ? '($input | ' + invoke + ')' : invoke) + ' | ForEach-Object { [string]$_ }',
                 'if ($LASTEXITCODE -gt 0) { $script:fx_exit = $LASTEXITCODE } elseif ($LASTEXITCODE -lt 0) { $script:fx_exit = 1 }',
             ].join('\n');
         }
@@ -206,11 +313,10 @@ export function translateSimple(cmd, position, hasStdin) {
     else {
         // dynamic command name — evaluate it
         const nameExpr = exprOfWord(cmd.name);
-        const argExprs = cmd.args.map((a) => exprOfWord(a));
-        const args = argExprs.length ? ' @(' + argExprs.join(', ') + ')' : '';
-        const call = '& (' + nameExpr + ')' + args;
+        const invoke = '& (' + nameExpr + ') @fx_na';
         body = [
-            (hasStdin ? '($input | ' + call + ')' : call) + ' | ForEach-Object { [string]$_ }',
+            '$fx_na = ' + argListExpr(cmd.args),
+            (hasStdin ? '($input | ' + invoke + ')' : invoke) + ' | ForEach-Object { [string]$_ }',
             'if ($LASTEXITCODE -gt 0) { $script:fx_exit = $LASTEXITCODE } elseif ($LASTEXITCODE -lt 0) { $script:fx_exit = 1 }',
         ].join('\n');
     }
@@ -288,11 +394,14 @@ export function wrapTempEnv(sets, body, extra) {
     }
     if (names.length === 0)
         return body;
+    const assigned = new Set(sets.map((s) => s.name));
     const id = tempEnvSeq++;
     const save = '$fx_es' + id;
+    const arrSave = '$fx_ar' + id;
     const keep = persistWords && persistWords.length > 0 ? '$fx_ek' + id : '';
     const lines = [
         save + ' = @{}',
+        arrSave + ' = @{}',
         '$fx_sv0' + id + ' = $env:FAUXNIX_SETVARS',
         '$fx_uv0' + id + ' = $env:FAUXNIX_UNSETVARS',
         '$fx_xv0' + id + ' = $env:FAUXNIX_SETVALS',
@@ -307,17 +416,19 @@ export function wrapTempEnv(sets, body, extra) {
             ') { [string](Get-Item -LiteralPath ' +
             p +
             ').Value } else { $null })');
+        lines.push(arrSave + '[' + psStr(n) + '] = (fx-arrpackget ' + psStr(n) + ')');
     }
     const valVars = [];
     for (let i = 0; i < sets.length; i++) {
         const vn = '$fx_ev' + id + '_' + i;
         valVars.push(vn);
-        lines.push(vn + ' = ' + exprOfWord(sets[i].value));
+        lines.push(vn + ' = ' + exprOfWord(sets[i].value, { preserveCmdSub: true }));
     }
     lines.push('try {');
     for (const u of unsets) {
         const uq = u.replace(/'/g, "''");
         lines.push('  Remove-Item -LiteralPath ' + psStr('Env:\\' + u) + ' -ErrorAction SilentlyContinue');
+        lines.push('  fx-arrdrop ' + psStr(u));
         // `env -u NAME` must hide NAME from fx-envget / fx-isset for the
         // wrapped body. Removing Env:\NAME is not enough: an earlier
         // `export NAME=x` still lives in SETVARS/SETVALS, and special
@@ -338,6 +449,7 @@ export function wrapTempEnv(sets, body, extra) {
         const n = sets[i].name;
         const nq = n.replace(/'/g, "''");
         lines.push('  $env:' + n + ' = ' + valVars[i]);
+        lines.push('  fx-arrdrop ' + psStr(n));
         lines.push("  $env:FAUXNIX_SETVARS = ((@($env:FAUXNIX_SETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne '" +
             nq +
             "' }) + '" +
@@ -415,8 +527,14 @@ export function wrapTempEnv(sets, body, extra) {
                 psStr(n) +
                 '] }');
         }
+        const restoreArr = 'fx-arrpackset ' + psStr(n) + ' ' + arrSave + '[' + psStr(n) + ']';
+        if (keep) {
+            lines.push('  if (-not $fx_skip) { ' + restoreArr + ' }');
+        }
+        else {
+            lines.push('  ' + restoreArr);
+        }
     }
-    const assigned = new Set(sets.map((s) => s.name));
     for (const n of persistNames) {
         const nq = n.replace(/'/g, "''");
         const ep = psStr('Env:\\' + n);
@@ -562,6 +680,144 @@ export function wrapScript(body) {
         "  if ($parts[$parts.Count - 1] -eq '') { $parts = $parts[0..($parts.Count - 2)] }",
         '  return $parts',
         '}',
+        'function fx-csub([scriptblock]$b) {',
+        '  $fx_prevcs = $script:fx_csub',
+        '  $script:fx_csub = $true',
+        '  try { $fx_o = @(& $b | ForEach-Object { [string]$_ }) }',
+        '  finally { $script:fx_csub = $fx_prevcs }',
+        '  $fx_s = ($fx_o -join [string][char]10)',
+        '  while ($fx_s.Length -gt 0 -and $fx_s[$fx_s.Length - 1] -eq [char]10) {',
+        '    $fx_s = $fx_s.Substring(0, $fx_s.Length - 1)',
+        '  }',
+        '  return $fx_s',
+        '}',
+        'function fx-svenc($s) {',
+        '  return ([string]$s).Replace([string][char]92, ([string][char]92 + [string][char]92)).Replace([string][char]13, ([string][char]92 + [char]114)).Replace([string][char]10, ([string][char]92 + [char]110))',
+        '}',
+        'function fx-svdec($s) {',
+        '  $s = [string]$s',
+        '  $sb = New-Object System.Text.StringBuilder',
+        '  $i = 0',
+        '  while ($i -lt $s.Length) {',
+        '    $c = $s[$i]',
+        '    if ($c -eq [char]92 -and ($i + 1) -lt $s.Length) {',
+        '      $n2 = $s[$i + 1]',
+        '      if ($n2 -eq [char]110) { [void]$sb.Append([char]10); $i += 2; continue }',
+        '      if ($n2 -eq [char]114) { [void]$sb.Append([char]13); $i += 2; continue }',
+        '      if ($n2 -eq [char]92) { [void]$sb.Append([char]92); $i += 2; continue }',
+        '    }',
+        '    [void]$sb.Append($c)',
+        '    $i++',
+        '  }',
+        '  return [string]$sb',
+        '}',
+        'function fx-arrload($n) {',
+        '  $n = [string]$n',
+        '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -split [string][char]10)) {',
+        '    $fx_eq = $fx_pair.IndexOf([char]61)',
+        '    if ($fx_eq -lt 1) { continue }',
+        '    if ($fx_pair.Substring(0, $fx_eq) -cne $n) { continue }',
+        '    $out = @()',
+        '    foreach ($el in @($fx_pair.Substring($fx_eq + 1) -split [string][char]30)) { $out += ,(fx-svdec $el) }',
+        '    return $out',
+        '  }',
+        '  $s0 = fx-scalar0 $n',
+        '  if ($null -eq $s0) { return @() }',
+        '  return @([string]$s0)',
+        '}',
+        'function fx-scalar0($n) {',
+        '  $n = [string]$n',
+        "  if (@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ceq $n }).Count -gt 0) { return $null }",
+        '  foreach ($fx_pair in @($env:FAUXNIX_SETVALS -split [string][char]10)) {',
+        '    $fx_eq = $fx_pair.IndexOf([char]61)',
+        '    if ($fx_eq -lt 1) { continue }',
+        '    if ($fx_pair.Substring(0, $fx_eq) -ceq $n) { return (fx-svdec $fx_pair.Substring($fx_eq + 1)) }',
+        '  }',
+        "  if ($n -ceq 'HOME') { return [string]$HOME }",
+        "  if ($n -ceq 'PWD') { return [string]$PWD.Path }",
+        "  if ($n -ceq 'USER' -or $n -ceq 'LOGNAME') { return [string]$env:USERNAME }",
+        "  if ($n -ceq 'PATH') { return [string]$env:PATH }",
+        "  if ($n -ceq 'SHELL') { return 'powershell' }",
+        "  if ($n -ceq 'TERM') { return 'xterm-256color' }",
+        "  if ($n -ceq 'OLDPWD') { return $(if ($env:FAUXNIX_OLDPWD) { [string]$env:FAUXNIX_OLDPWD } else { $null }) }",
+        "  if ($n -ceq 'HOSTNAME') { return [string]$env:COMPUTERNAME }",
+        '  $ev = Get-ChildItem Env: | Where-Object { $_.Name -ceq $n } | Select-Object -First 1',
+        '  if ($ev) { return [string]$ev.Value }',
+        '  return $null',
+        '}',
+        'function fx-ifs1 {',
+        "  $s = fx-scalar0 'IFS'",
+        "  if ($null -eq $s) { return ' ' }",
+        "  if ([string]$s -eq '') { return '' }",
+        '  return [string]$s[0]',
+        '}',
+        'function fx-arrdrop($n) {',
+        '  $n = [string]$n',
+        '  $fx_sm = @()',
+        '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -split [string][char]10)) {',
+        '    $fx_eq = $fx_pair.IndexOf([char]61)',
+        '    if ($fx_eq -lt 1) { continue }',
+        '    if ($fx_pair.Substring(0, $fx_eq) -cne $n) { $fx_sm += $fx_pair }',
+        '  }',
+        '  $env:FAUXNIX_ARRS = ($fx_sm -join [string][char]10)',
+        '}',
+        'function fx-arrhas($n) {',
+        '  $n = [string]$n',
+        '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -split [string][char]10)) {',
+        '    $fx_eq = $fx_pair.IndexOf([char]61)',
+        '    if ($fx_eq -lt 1) { continue }',
+        '    if ($fx_pair.Substring(0, $fx_eq) -ceq $n) { return $true }',
+        '  }',
+        '  return $false',
+        '}',
+        'function fx-arrpackget($n) {',
+        '  $n = [string]$n',
+        '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -split [string][char]10)) {',
+        '    $fx_eq = $fx_pair.IndexOf([char]61)',
+        '    if ($fx_eq -lt 1) { continue }',
+        '    if ($fx_pair.Substring(0, $fx_eq) -ceq $n) { return $fx_pair.Substring($fx_eq + 1) }',
+        '  }',
+        '  return $null',
+        '}',
+        'function fx-arrpackset($n, $pay) {',
+        '  fx-arrdrop $n',
+        '  if ($null -eq $pay) { return }',
+        "  $env:FAUXNIX_ARRS = ((@($env:FAUXNIX_ARRS -split [string][char]10 | Where-Object { $_ -ne '' }) + ([string]$n + [string][char]61 + [string]$pay)) -join [string][char]10)",
+        '}',
+        'function fx-arrput($n, $vals) {',
+        '  $n = [string]$n',
+        '  $vals = @($vals)',
+        '  fx-arrdrop $n',
+        '  if ($vals.Count -eq 0) { } else {',
+        '    $encs = @(); foreach ($v in $vals) { $encs += (fx-svenc $v) }',
+        "    $env:FAUXNIX_ARRS = ((@($env:FAUXNIX_ARRS -split [string][char]10 | Where-Object { $_ -ne '' }) + ($n + [string][char]61 + ($encs -join [string][char]30))) -join [string][char]10)",
+        '  }',
+        "  $fx_0 = $(if ($vals.Count -gt 0) { [string]$vals[0] } else { '' })",
+        '  Set-Item -LiteralPath (\'Env:\\\' + $n) -Value $fx_0',
+        "  $env:FAUXNIX_SETVARS = ((@($env:FAUXNIX_SETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) + $n) -join ';')",
+        "  $env:FAUXNIX_UNSETVARS = (@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) -join ';')",
+        '  $fx_sv = @(); foreach ($fx_pair in @($env:FAUXNIX_SETVALS -split [string][char]10)) { $fx_eq = $fx_pair.IndexOf([char]61); if ($fx_eq -lt 1) { continue }; if ($fx_pair.Substring(0, $fx_eq) -cne $n) { $fx_sv += $fx_pair } }',
+        "  $fx_sv += ($n + [string][char]61 + (fx-svenc $fx_0)); $env:FAUXNIX_SETVALS = ($fx_sv -join [string][char]10)",
+        '}',
+        'function fx-arrclr($n) {',
+        '  $n = [string]$n',
+        '  fx-arrdrop $n',
+        "  Remove-Item -LiteralPath ('Env:\\' + $n) -ErrorAction SilentlyContinue",
+        "  $env:FAUXNIX_SETVARS = (@($env:FAUXNIX_SETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) -join ';')",
+        "  $env:FAUXNIX_UNSETVARS = ((@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) + $n) -join ';')",
+        '  $fx_sv = @(); foreach ($fx_pair in @($env:FAUXNIX_SETVALS -split [string][char]10)) { $fx_eq = $fx_pair.IndexOf([char]61); if ($fx_eq -lt 1) { continue }; if ($fx_pair.Substring(0, $fx_eq) -cne $n) { $fx_sv += $fx_pair } }; $env:FAUXNIX_SETVALS = ($fx_sv -join [string][char]10)',
+        '}',
+        'function fx-subget($n, $ix) {',
+        '  $arr = @(fx-arrload $n)',
+        '  $ix = [string]$ix',
+        // argv-level `@` is expanded by argListExpr; this is the scalar/quoted-* join.
+        "  if ($ix -eq '*') { return ($arr -join (fx-ifs1)) }",
+        "  if ($ix -eq '@') { return ($arr -join (fx-ifs1)) }",
+        '  $i = 0',
+        '  if (-not [int]::TryParse($ix, [ref]$i)) { return \'\' }',
+        "  if ($i -lt 0 -or $i -ge $arr.Count) { return '' }",
+        '  return [string]$arr[$i]',
+        '}',
         'try {',
         ...body.split('\n').map((l) => '  ' + l),
         '} catch [System.Management.Automation.CommandNotFoundException] {',

package/package.json

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