fauxnix-cli 0.5.0 → 0.5.1

package/README.md

@@ -193,7 +193,8 @@ 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`
+- `tail -f`, `eval`, `alias`, heredocs, `while`/`until`/`case`, word-level
+  `$((...))` arithmetic expansion
   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.)

package/dist/ast.d.ts

@@ -12,7 +12,8 @@
  *
  * Explicitly unsupported (parser throws a helpful FauxnixError):
  *   heredocs, subshells (...), background &, while/until/case,
- *   globs inside quotes, process substitution <(...).
+ *   word-level $((...)) arithmetic expansion, globs inside quotes,
+ *   process substitution <(...).
  */
 export interface CommandList {
     kind: 'CommandList';

package/dist/ast.js

@@ -12,7 +12,8 @@
  *
  * Explicitly unsupported (parser throws a helpful FauxnixError):
  *   heredocs, subshells (...), background &, while/until/case,
- *   globs inside quotes, process substitution <(...).
+ *   word-level $((...)) arithmetic expansion, globs inside quotes,
+ *   process substitution <(...).
  */
 export function wordToString(w) {
     return w.map(partToString).join('');

package/dist/mcp.js

@@ -30,18 +30,18 @@ const SESSION_ANNOTATIONS = {
     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.
-Output is formatted to look like GNU/Linux tooling (ls -l, ps aux, df -h ...), errors look like bash errors, and text encoding (UTF-8/GBK) is handled automatically.
-
-Supported: pipes (|), && / || / ;, redirections (> >> 2> 2>&1 < /dev/null), variables ($VAR $HOME ~), command substitution $(...), and ${registeredNames().length}+ coreutils-style commands (${registeredNames().slice(0, 18).join(', ')}...).
-Unknown commands (git, node, npm, python, cargo...) are passed through and executed natively with argv-style quoting.
-Not supported: heredocs, while/until/case, background jobs. if/then/else/fi and for-in loops are supported.
-
-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).
-
+const TOOL_DESCRIPTION = `Execute a Linux/bash-style command on this Windows machine.
+
+Commands are deterministically translated to PowerShell and executed natively — no WSL or VM.
+Output is formatted to look like GNU/Linux tooling (ls -l, ps aux, df -h ...), errors look like bash errors, and text encoding (UTF-8/GBK) is handled automatically.
+
+Supported: pipes (|), && / || / ;, redirections (> >> 2> 2>&1 < /dev/null), variables ($VAR $HOME ~), command substitution $(...), and ${registeredNames().length}+ coreutils-style commands (${registeredNames().slice(0, 18).join(', ')}...).
+Unknown commands (git, node, npm, python, cargo...) are passed through and executed natively with argv-style quoting.
+Not supported: heredocs, while/until/case, word-level \$((...)) arithmetic expansion, background jobs. if/then/else/fi and for-in loops are supported.
+
+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).
+
 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: {} } });

package/dist/parser.js

@@ -256,6 +256,12 @@ 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.
+    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 ]]');
+    }
     // $(cmd substitution) — captured with balanced parens; the translator
     // recursively translates this text before embedding it.
     if (input[j] === '(') {

package/dist/translator.d.ts

@@ -85,5 +85,7 @@ export declare function translateCommandList(list: CommandList): SegmentPlan[];
 /**
  * Wrap a pipeline body with the Fauxnix executor contract:
  * UTF-8 everywhere, bash-style exit codes, cwd/env persistence channels.
+ * Only the fx- helpers the body actually calls are emitted — the full
+ * catalog is ~170 lines and was paid on every `echo hi`.
  */
 export declare function wrapScript(body: string): string;

package/dist/translator.js

@@ -775,11 +775,72 @@ export function translateCommandList(list) {
     }
     return plans;
 }
+const WRAP_HELPER_ORDER = [
+    'fx-readlines',
+    'fx-csub',
+    'fx-svenc',
+    'fx-svdec',
+    'fx-arrload',
+    'fx-scalar0',
+    'fx-ifs1',
+    'fx-arrdrop',
+    'fx-arrhas',
+    'fx-arrpackget',
+    'fx-arrpackset',
+    'fx-arrput',
+    'fx-arrclr',
+    'fx-subget',
+];
+const WRAP_HELPER_DEPS = {
+    'fx-readlines': [],
+    'fx-csub': [],
+    'fx-svenc': [],
+    'fx-svdec': [],
+    'fx-arrload': ['fx-scalar0', 'fx-svdec'],
+    'fx-scalar0': ['fx-svdec'],
+    'fx-ifs1': ['fx-scalar0'],
+    'fx-arrdrop': [],
+    'fx-arrhas': [],
+    'fx-arrpackget': [],
+    'fx-arrpackset': ['fx-arrdrop'],
+    'fx-arrput': ['fx-arrdrop', 'fx-svenc'],
+    'fx-arrclr': ['fx-arrdrop'],
+    'fx-subget': ['fx-arrload', 'fx-ifs1'],
+};
+/** Helpers the body calls that wrapScript still has to emit (not already defined there). */
+function wrapHelpersNeeded(body) {
+    const defined = new Set();
+    const defRe = /function\s+(fx-[A-Za-z0-9]+)/g;
+    let m;
+    while ((m = defRe.exec(body)))
+        defined.add(m[1]);
+    const seeds = [];
+    const callRe = /\b(fx-[A-Za-z0-9]+)\b/g;
+    while ((m = callRe.exec(body))) {
+        const n = m[1];
+        if (!defined.has(n) && n in WRAP_HELPER_DEPS)
+            seeds.push(n);
+    }
+    const needed = new Set();
+    const stack = seeds.slice();
+    while (stack.length) {
+        const n = stack.pop();
+        if (needed.has(n) || defined.has(n))
+            continue;
+        needed.add(n);
+        for (const d of WRAP_HELPER_DEPS[n])
+            stack.push(d);
+    }
+    return needed;
+}
 /**
  * Wrap a pipeline body with the Fauxnix executor contract:
  * UTF-8 everywhere, bash-style exit codes, cwd/env persistence channels.
+ * Only the fx- helpers the body actually calls are emitted — the full
+ * catalog is ~170 lines and was paid on every `echo hi`.
  */
 export function wrapScript(body) {
+    const needed = wrapHelpersNeeded(body);
     const lines = [
         '$ErrorActionPreference = "Continue"',
         "$ProgressPreference = 'SilentlyContinue'",
@@ -803,175 +864,191 @@ export function wrapScript(body) {
         // .NET APIs (ReadAllBytes & friends) resolve relative paths against the
         // process working directory, NOT the PS location — keep them in sync.
         'try { [Environment]::CurrentDirectory = (Get-Location).ProviderPath } catch {}',
-        // byte-sniffing line reader for `< file` stdin redirects (UTF-8 → GBK)
-        'function fx-readlines($p) {',
-        '  $b = [IO.File]::ReadAllBytes($p)',
-        '  $t = $null',
-        '  try { $t = (New-Object System.Text.UTF8Encoding($false, $true)).GetString($b) } catch {}',
-        "  if ($null -eq $t) { try { $t = [System.Text.Encoding]::GetEncoding(936).GetString($b) } catch { $t = [System.Text.Encoding]::ASCII.GetString($b) } }",
-        '  $t = $t -replace "`r`n", "`n"',
-        '  $t = $t -replace "`r", "`n"',
-        '  $parts = @($t.Split("`n"))',
-        "  if ($parts.Count -eq 1 -and $parts[0] -eq '') { return @() }",
-        "  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] {',
-        "  [Console]::Error.WriteLine('bash: ' + $_.Exception.TargetName + ': command not found')",
-        '  $script:fx_exit = 127',
-        '} catch {',
-        '  [Console]::Error.WriteLine(($_.Exception.Message).Split("`n")[0])',
-        '  $script:fx_exit = 1',
-        '}',
-        '# persist session cwd and environment for the next segment',
-        'try { [IO.File]::WriteAllText($env:FAUXNIX_CWD_FILE, (Get-Location).Path) } catch {}',
-        'if ((Get-Location).Path -ne $fx_oldcwd) { $env:FAUXNIX_OLDPWD = $fx_oldcwd }',
-        'try {',
-        '  $envObj = @{}',
-        '  Get-ChildItem Env: | ForEach-Object { $envObj[$_.Name] = $_.Value }',
-        '  [IO.File]::WriteAllText($env:FAUXNIX_ENV_FILE, (ConvertTo-Json $envObj -Compress))',
-        '} catch {}',
-        'exit $script:fx_exit',
     ];
+    const helpers = {
+        'fx-readlines': [
+            'function fx-readlines($p) {',
+            '  $b = [IO.File]::ReadAllBytes($p)',
+            '  $t = $null',
+            '  try { $t = (New-Object System.Text.UTF8Encoding($false, $true)).GetString($b) } catch {}',
+            "  if ($null -eq $t) { try { $t = [System.Text.Encoding]::GetEncoding(936).GetString($b) } catch { $t = [System.Text.Encoding]::ASCII.GetString($b) } }",
+            '  $t = $t -replace "`r`n", "`n"',
+            '  $t = $t -replace "`r", "`n"',
+            '  $parts = @($t.Split("`n"))',
+            "  if ($parts.Count -eq 1 -and $parts[0] -eq '') { return @() }",
+            "  if ($parts[$parts.Count - 1] -eq '') { $parts = $parts[0..($parts.Count - 2)] }",
+            '  return $parts',
+            '}',
+        ],
+        'fx-csub': [
+            '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',
+            '}',
+        ],
+        'fx-svenc': [
+            '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))',
+            '}',
+        ],
+        'fx-svdec': [
+            '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',
+            '}',
+        ],
+        'fx-arrload': [
+            '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)',
+            '}',
+        ],
+        'fx-scalar0': [
+            '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',
+            '}',
+        ],
+        'fx-ifs1': [
+            'function fx-ifs1 {',
+            "  $s = fx-scalar0 'IFS'",
+            "  if ($null -eq $s) { return ' ' }",
+            "  if ([string]$s -eq '') { return '' }",
+            '  return [string]$s[0]',
+            '}',
+        ],
+        'fx-arrdrop': [
+            '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)',
+            '}',
+        ],
+        'fx-arrhas': [
+            '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',
+            '}',
+        ],
+        'fx-arrpackget': [
+            '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',
+            '}',
+        ],
+        'fx-arrpackset': [
+            '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)",
+            '}',
+        ],
+        'fx-arrput': [
+            '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)",
+            '}',
+        ],
+        'fx-arrclr': [
+            '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)',
+            '}',
+        ],
+        'fx-subget': [
+            '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]',
+            '}',
+        ],
+    };
+    for (const name of WRAP_HELPER_ORDER) {
+        if (needed.has(name))
+            lines.push(...helpers[name]);
+    }
+    lines.push('try {', ...body.split('\n').map((l) => '  ' + l), '} catch [System.Management.Automation.CommandNotFoundException] {', "  [Console]::Error.WriteLine('bash: ' + $_.Exception.TargetName + ': command not found')", '  $script:fx_exit = 127', '} catch {', '  [Console]::Error.WriteLine(($_.Exception.Message).Split("`n")[0])', '  $script:fx_exit = 1', '}', '# persist session cwd and environment for the next segment', 'try { [IO.File]::WriteAllText($env:FAUXNIX_CWD_FILE, (Get-Location).Path) } catch {}', 'if ((Get-Location).Path -ne $fx_oldcwd) { $env:FAUXNIX_OLDPWD = $fx_oldcwd }', 'try {', '  $envObj = @{}', '  Get-ChildItem Env: | ForEach-Object { $envObj[$_.Name] = $_.Value }', '  [IO.File]::WriteAllText($env:FAUXNIX_ENV_FILE, (ConvertTo-Json $envObj -Compress))', '} catch {}', 'exit $script:fx_exit');
     return lines.join('\n');
 }

package/package.json

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