fauxnix-cli 0.9.2 → 0.11.0

package/README.md

@@ -58,6 +58,14 @@ Linux command line — file ops, text processing, process management, archives,
 maps cleanly onto PowerShell + .NET. fauxnix implements that subset faithfully and *fails loudly
 and helpfully* on what it can't translate, so the agent never gets silently-wrong results.
 
+Labs now train computer-use agents on fleets of real desktops. Reporting in 2026 (*The
+Information*, widely repeated) has OpenAI buying tens of thousands of Mac mini / Mac Studio
+boxes — no screen, no keyboard — to reinforcement-learn agents that click, edit, test, and
+run bash workflows, and Anthropic renting Mac minis through AWS for the same class of work.
+That scoring environment is macOS. Windows users should not have to install a guest Unix to
+keep up: the agent keeps writing bash; fauxnix makes the Windows box answer like the box the
+agent was trained on. See [`docs/rfc-computer-use-windows.md`](docs/rfc-computer-use-windows.md).
+
 ## Install
 
 ```bash
@@ -90,6 +98,10 @@ fauxnix translate "find . -name '*.log' -mtime +7 -delete"
 
 # check your environment
 fauxnix check
+fauxnix doctor                   # check + encoding, harness config, MCP
+
+# write user-level MCP config (idempotent; also --codex/--opencode/--kimi/--qwen)
+fauxnix install --claude
 
 # run the MCP stdio server (what agent harnesses connect to)
 fauxnix mcp
@@ -101,7 +113,11 @@ with argv-style quoting — no string re-parsing, no quoting bugs.
 ## Use with your agent harness
 
 fauxnix ships an MCP stdio server exposing a `bash` tool (plus `fauxnix_translate` and
-`fauxnix_session`). Point any MCP-capable harness at it:
+`fauxnix_session`). Point any MCP-capable harness at it with
+`fauxnix install --claude` (or `--codex` / `--opencode` / `--kimi` / `--qwen`).
+Idempotent; prints what changed. Manual configs below.
+
+- **Quickstarts** — copy-paste config + a 10-command smoke: [`docs/examples/`](docs/examples/)
 
 **Claude Code**
 ```bash
@@ -137,12 +153,23 @@ TOML config: `~/.kimi-code/mcp.json`
 }
 ```
 
+**Qwen Code** (`~/.qwen/settings.json`)
+```json
+{
+  "mcpServers": {
+    "fauxnix": { "command": "fauxnix", "args": ["mcp"] }
+  }
+}
+```
+
 **Any MCP client** — stdio server: `fauxnix mcp`. The tool name is `bash` (override with
 `FAUXNIX_TOOL_NAME`). Tool description already teaches the model the supported subset, so no
 system-prompt changes are required.
 
-The MCP session persists `cwd`, environment variables, `export`/`unset` and `cd -`/OLDPWD across
-tool calls — it behaves like a logged-in shell, not a stateless `exec`.
+The MCP session persists `cwd`, environment variables, `export`/`unset`, `cd -`/OLDPWD, and
+positional parameters (`set --` / `$1` / `"$@"`) across tool calls — it behaves like a logged-in
+shell, not a stateless `exec`. `$0` is the MCP tool name (`bash` / `FAUXNIX_TOOL_NAME`), not a
+Windows path.
 
 ## What's translated
 
@@ -156,20 +183,24 @@ development:
 
 `cp` / `mv` / `rm` / `touch` / `du` / `ls` / `ll` / `mkdir` / `rmdir` / `mktemp` / `ln` /
 `readlink` / `realpath` / `basename` / `dirname` / `stat` / `file` / `df` / `chmod` / `chown` /
-`diff` / `tee` / `grep` / `head` carry a `CommandSpec`: unknown options fail with a GNU-style
+`diff` / `tee` / `grep` / `head` / `echo` / `printf` / `cat` / `tail` / `wc` / `sort` / `uniq` /
+`cut` / `tr` / `gzip` / `gunzip` / `zcat` / `zip` / `unzip` carry a `CommandSpec`: unknown options fail with a GNU-style
 usage error instead of being ignored (`find` stays unspec'd so predicates like `-name` still
-compile). Implemented GNU holes: `cp -n` / `mv -n` / `touch -c` / `tee --append` / `grep -m` /
+compile; `sed`/`awk`/`egrep` stay unspec'd; `tar` stays unspec'd because it is fx-native to
+`tar.exe` and unknown GNU flags must reach bsdtar). Implemented GNU holes: `cp -n` / `mv -n` / `touch -c` / `tee --append` / `grep -m` /
 `head --lines` / `du --max-depth`. `fauxnix list --json` and `docs/command-specs.md` dump the
 same metadata.
 - **shell/system**: `cd pwd export unset env printenv ps kill pkill pgrep sleep which type whoami
   id groups date uname hostname uptime free nproc clear true false test [ [[ : pushd popd dirs sudo
-  timeout man history less more source . eval exit alias set`
+  timeout man history less more source . eval exit alias set shift`
 - **network**: `curl wget ping netstat ss ip ifconfig nslookup dig host`
 - **archives**: `tar gzip gunzip zcat zip unzip`
 
 Plus shell syntax: pipes, `&&` / `||` / `;`, redirections (`> >> 2> 2>&1 < &>`, `/dev/null`),
-quoting, `$VAR` `$(...)` command substitution, `VAR=x cmd` prefixes, `~` expansion, and
-POSIX-style path normalization (`/tmp`, `/d/foo` → `D:\foo`).
+quoting, `$VAR` `$1` `$#` `"$@"` `set --` `shift`, `${name:-word}` `${name//pat/str}`
+`${name:off:len}` `${name[n]}` `${#name[@]}`, `A=(x y z)` array assignment, `$(...)` command
+substitution, `VAR=x cmd` prefixes, `~` expansion, and POSIX-style path normalization
+(`/tmp`, `/d/foo` → `D:\foo`).
 
 Exit codes follow bash conventions: 0 ok, 1 fail, 2 usage/serious, 127 command not found,
 124 timeout.
@@ -203,11 +234,15 @@ 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,
   `env -i`/`--ignore-environment`,
-  and background `&` are rejected with actionable error messages instead of misbehaving.
-  (`if/then/elif/else/fi`, `for x in ...`, backtick substitution, `command -v`, pipeline `read`,
-  dotenv-style `source`, and word-level `$((...))` arithmetic expansion are supported.)
+  background `&`, and stdout redirects (`>` `>>` `&>` `&>>`) on a non-last
+  pipeline stage (`echo hi >f | cat`) are rejected with actionable error
+  messages instead of misbehaving.
+  (`if/then/elif/else/fi`, `for x in ...`, `while`/`until`, `case ... esac` (`;;` only; `;&`/`;;&` fail loud),
+  backtick substitution, `command -v`, pipeline `read`,
+  dotenv-style `source`, word-level `$((...))` arithmetic expansion, `A=(x y z)` arrays, and
+  `${name//pat/str}` / `${name:off:len}` are supported.)
 - `command -v <builtin>` prints `/usr/bin/<name>` where bash prints the bare builtin name;
   exit codes and empty-result semantics match.
 - `chmod` maps only the read-only bit; exec bits are no-ops on Windows. `chown` is a silent no-op
@@ -237,6 +272,8 @@ npm run build
 npx tsx scratch/run.mjs "any bash command"   # quick live check
 ```
 
+Differential vs Git Bash is opt-in (`FAUXNIX_DIFF_ORACLE=1`; skips if unset or `bash.exe` is missing — Git Bash is not required). See [`test/differential/README.md`](test/differential/README.md). This is grown from the 40-case RFC C-7 scaffold, not the 200-case 1.0 gate. The weekly oracle is opt-in via the scheduled workflow (`.github/workflows/differential.yml`) when Git Bash is on the runner.
+
 Architecture map: `src/parser.ts` (bash subset → AST) · `src/translator.ts` (AST → PowerShell +
 executor wrapper) · `src/executor.ts` (spawn, redirects, session persistence) ·
 `src/commands/*.ts` (per-command generators) · `src/mcp.ts` (MCP server) · `src/cli.ts`.
@@ -244,6 +281,11 @@ executor wrapper) · `src/executor.ts` (spawn, redirects, session persistence)
 Roadmap: [docs/rfc-roadmap-to-1.0.md](docs/rfc-roadmap-to-1.0.md) — tracks, milestones,
 and the RFC process for proposing waves.
 
+## Security
+
+Trust model, host protocol, kill semantics, network guard, and reporting:
+[SECURITY.md](SECURITY.md).
+
 ## License
 
 MIT © 20000419

package/dist/ast.d.ts

@@ -6,13 +6,16 @@
  *   - lists:                cmd1 ; cmd2 && cmd3 || cmd4   (newlines act as ';')
  *   - redirections:         > >> 2> 2>> &> 2>&1 1>&2 <
  *   - quoting:              'literal'  "interp $VAR $(cmd)"
- *   - variables:            $VAR ${VAR} ${VAR[n]} plus special cases ($HOME $USER $PATH ...)
+ *   - variables:            $VAR ${VAR} ${VAR[n]} ${name//pat/str} ${name:off:len}
+ *                           plus special cases ($HOME $USER $PATH $1 $# $@ $0 ...)
  *   - command substitution: $(...) and `...` (recursively translated)
  *   - arithmetic expansion: $((...)) (existing fx-arith engine)
  *   - env assignment prefix: VAR=value cmd
+ *   - control:              if/then/elif/else/fi, for-in, while/until, case
+ *   - array assignment:     A=(x y z)  (sidecar FAUXNIX_ARRS)
  *
  * Explicitly unsupported (parser throws a helpful FauxnixError):
- *   heredocs, subshells (...), background &, while/until/case,
+ *   heredocs, subshells (...), background &,
  *   globs inside quotes, process substitution <(...).
  */
 export interface CommandList {
@@ -25,7 +28,7 @@ export interface ListSegment {
     /** ';' for the first segment, otherwise the operator seen before this one. */
     op: ';' | '&&' | '||';
 }
-export type ShellCommand = SimpleCommand | IfCommand | ForCommand;
+export type ShellCommand = SimpleCommand | IfCommand | ForCommand | WhileCommand | CaseCommand;
 export interface Pipeline {
     kind: 'Pipeline';
     commands: ShellCommand[];
@@ -44,6 +47,24 @@ export interface ForCommand {
     body: CommandList;
     redirects: Redirect[];
 }
+export interface WhileCommand {
+    kind: 'While';
+    /** true for `until TEST; do BODY; done`. */
+    until: boolean;
+    test: CommandList;
+    body: CommandList;
+    redirects: Redirect[];
+}
+export interface CaseArm {
+    patterns: Word[];
+    body: CommandList;
+}
+export interface CaseCommand {
+    kind: 'Case';
+    word: Word;
+    arms: CaseArm[];
+    redirects: Redirect[];
+}
 export interface SimpleCommand {
     kind: 'SimpleCommand';
     /** `VAR=value` prefixes before the command name. */
@@ -55,7 +76,10 @@ export interface SimpleCommand {
 }
 export interface Assignment {
     name: string;
+    /** Scalar value; for arrays, first element (or empty Word) so export paths stay valid. */
     value: Word;
+    /** Set ⇒ bash array assignment `A=(x y z)`. */
+    values?: Word[];
 }
 export type RedirectOp = '>' | '>>' | '2>' | '2>>' | '&>' | '&>>' | '2>&1' | '1>&2' | '<';
 export interface Redirect {
@@ -86,6 +110,17 @@ export type WordPart = {
     };
     /** `${#name}` / `${#name[@]}` — string/array length expansion. */
     length?: boolean;
+    /** `${name/pat/str}` (first) / `${name//pat/str}` (global). Pattern is a bash glob. */
+    replace?: {
+        global: boolean;
+        pat: string;
+        repl: string;
+    };
+    /** `${name:offset}` / `${name:offset:length}` — scalar substring. */
+    slice?: {
+        offset: string;
+        length?: string;
+    };
 } | {
     kind: 'CmdSub';
     cmd: string;

package/dist/ast.js

@@ -6,13 +6,16 @@
  *   - lists:                cmd1 ; cmd2 && cmd3 || cmd4   (newlines act as ';')
  *   - redirections:         > >> 2> 2>> &> 2>&1 1>&2 <
  *   - quoting:              'literal'  "interp $VAR $(cmd)"
- *   - variables:            $VAR ${VAR} ${VAR[n]} plus special cases ($HOME $USER $PATH ...)
+ *   - variables:            $VAR ${VAR} ${VAR[n]} ${name//pat/str} ${name:off:len}
+ *                           plus special cases ($HOME $USER $PATH $1 $# $@ $0 ...)
  *   - command substitution: $(...) and `...` (recursively translated)
  *   - arithmetic expansion: $((...)) (existing fx-arith engine)
  *   - env assignment prefix: VAR=value cmd
+ *   - control:              if/then/elif/else/fi, for-in, while/until, case
+ *   - array assignment:     A=(x y z)  (sidecar FAUXNIX_ARRS)
  *
  * Explicitly unsupported (parser throws a helpful FauxnixError):
- *   heredocs, subshells (...), background &, while/until/case,
+ *   heredocs, subshells (...), background &,
  *   globs inside quotes, process substitution <(...).
  */
 export function wordToString(w) {
@@ -37,6 +40,23 @@ function partToString(p) {
         case 'DoubleQuoted':
             return p.parts.map(partToString).join('');
         case 'Var':
+            if (p.replace) {
+                const sep = p.replace.global ? '//' : '/';
+                return `\${${p.name}${sep}${p.replace.pat}/${p.replace.repl}}`;
+            }
+            if (p.slice) {
+                return p.slice.length !== undefined
+                    ? `\${${p.name}:${p.slice.offset}:${p.slice.length}}`
+                    : `\${${p.name}:${p.slice.offset}}`;
+            }
+            if (p.length) {
+                return p.index !== undefined
+                    ? `\${#${p.name}[${p.index}]}`
+                    : `\${#${p.name}}`;
+            }
+            if (p.param) {
+                return `\${${p.name}${p.param.op}${p.param.word}}`;
+            }
             return p.index !== undefined ? `\${${p.name}[${p.index}]}` : `$${p.name}`;
         case 'CmdSub':
             return '$(' + p.cmd + ')';

package/dist/cli.d.ts

@@ -1,2 +1,3 @@
 import './commands/install-all.js';
+export declare const USAGE = "fauxnix \u2014 run Linux-style commands on Windows via PowerShell translation\n\nUsage:\n  fauxnix \"ls -la | head -5\"        translate + execute a bash-style command\n  fauxnix -c \"cmd\"                   same as above\n  fauxnix translate \"cmd\"            show the PowerShell translation only\n  fauxnix mcp                        start the MCP stdio server (for agent harnesses)\n  fauxnix list                       list translated commands\n  fauxnix list --json                same list as machine-readable capability metadata\n  fauxnix list --markdown            CommandSpec tables (same text as docs/command-specs.md)\n  fauxnix check                      verify the local PowerShell environment\n  fauxnix doctor                     check + encoding, harness config, MCP readiness\n  fauxnix install --claude|--codex|--opencode|--kimi|--qwen\n  fauxnix --version\n\nNotes:\n  Unknown commands (git, node, npm, python, cargo, ...) pass through and run natively.";
 export declare function runCli(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -5,9 +5,11 @@ import { translateCommandList } from './translator.js';
 import { listCommandsJson, registeredNames, specsMarkdown } from './registry.js';
 import { encodeCommand } from './encoding.js';
 import { startMcpServer } from './mcp.js';
+import { collectDoctorReport } from './doctor.js';
+import { runInstall } from './install.js';
 import { packageVersion } from './version.js';
 import './commands/install-all.js';
-const USAGE = `fauxnix — run Linux-style commands on Windows via PowerShell translation
+export const USAGE = `fauxnix — run Linux-style commands on Windows via PowerShell translation
 
 Usage:
   fauxnix "ls -la | head -5"        translate + execute a bash-style command
@@ -18,6 +20,8 @@ Usage:
   fauxnix list --json                same list as machine-readable capability metadata
   fauxnix list --markdown            CommandSpec tables (same text as docs/command-specs.md)
   fauxnix check                      verify the local PowerShell environment
+  fauxnix doctor                     check + encoding, harness config, MCP readiness
+  fauxnix install --claude|--codex|--opencode|--kimi|--qwen
   fauxnix --version
 
 Notes:
@@ -52,6 +56,18 @@ export async function runCli(argv) {
         await runCheck();
         return;
     }
+    if (verb === 'doctor') {
+        await runDoctor();
+        return;
+    }
+    if (verb === 'install') {
+        const result = runInstall(rest);
+        for (const line of result.lines)
+            console.log(line);
+        if (!result.ok)
+            process.exitCode = 1;
+        return;
+    }
     if (verb === 'mcp') {
         await startMcpServer();
         return;
@@ -80,6 +96,14 @@ export async function runCli(argv) {
     process.exit(result.exitCode);
 }
 const PS_ARGS = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass'];
+async function runDoctor() {
+    await runCheck();
+    const report = await collectDoctorReport();
+    for (const line of report.lines)
+        console.log(line);
+    if (!report.ok)
+        process.exitCode = 1;
+}
 async function runCheck() {
     console.log('powershell : powershell.exe (Windows built-in)');
     const probeCmd = '$PSVersionTable.PSVersion.ToString()';

package/dist/commands/archive.d.ts

@@ -1,2 +1,3 @@
-import { Handler } from '../registry.js';
+import { CommandSpec, Handler } from '../registry.js';
+export declare const specs: CommandSpec[];
 export declare const handlers: Record<string, Handler>;

package/dist/commands/archive.js

@@ -201,6 +201,8 @@ const gunzip = (args, ctx) => gzBlock(args, ctx, { decompress: true });
 const zcat = (args, ctx) => gzBlock(args, ctx, { decompress: true, stdout: true });
 /* ------------------------------------------------------------------ */
 /* tar — Windows 10+ ships bsdtar as tar.exe, pass everything through  */
+/* Intentionally unspec'd: registerSpec fail-loud would reject GNU     */
+/* flags bsdtar accepts (--numeric-owner, …). Same class as find.      */
 /* ------------------------------------------------------------------ */
 const tar = (args) => {
     return [
@@ -214,8 +216,9 @@ const tar = (args) => {
         '  if ($fx_c) { $fx_tar = $fx_c.Source } else { $fx_tar = $null }',
         '}',
         'if ($fx_tar) {',
-        '  & $fx_tar @($fx_args) | ForEach-Object { [string]$_ }',
-        '  if ($LASTEXITCODE -gt 0) { $script:fx_exit = $LASTEXITCODE }',
+        // fx-native captures stdout as pipeline strings and sets fx_exit.
+        // [object[]]@(...) keeps an empty argv from unwrapping to $null on PS 5.1.
+        '  fx-native $fx_tar ([object[]]@($fx_args))',
         '} else {',
         "  [Console]::Error.WriteLine('tar: fauxnix: tar.exe not found (Windows 10+ ships bsdtar as tar.exe)')",
         '  $script:fx_exit = 1',
@@ -373,8 +376,87 @@ const unzip = (args) => {
     ].join('\n');
 };
 /* ------------------------------------------------------------------ */
-/* exports                                                             */
+/* CommandSpec (C-5 archive slice)                                     */
+/* tar stays unspec'd: fx-native to tar.exe; unknown GNU flags must    */
+/* reach bsdtar. gzip -f is a no-op today and the stdin-from-terminal  */
+/* message advertises it, so it is unsupported (force from terminal)   */
+/* rather than a silent ignore.                                        */
 /* ------------------------------------------------------------------ */
+const gzipOptions = [
+    { short: 'd', long: '--decompress', support: 'implemented' },
+    { long: '--uncompress', support: 'implemented' },
+    { short: 'k', long: '--keep', support: 'implemented' },
+    { short: 'c', long: '--stdout', support: 'implemented' },
+    { long: '--to-stdout', support: 'implemented' },
+    { short: 't', long: '--test', support: 'implemented' },
+    { short: '1', long: '--fast', support: 'implemented' },
+    { short: '2', support: 'implemented' },
+    { short: '3', support: 'implemented' },
+    { short: '4', support: 'implemented' },
+    { short: '5', support: 'implemented' },
+    { short: '6', support: 'implemented' },
+    { short: '7', support: 'implemented' },
+    { short: '8', support: 'implemented' },
+    { short: '9', long: '--best', support: 'implemented' },
+    { short: 'f', long: '--force', support: 'unsupported', reason: 'force from terminal' },
+    { short: 'q', long: '--quiet', support: 'unsupported', reason: 'quiet' },
+    { short: 'v', long: '--verbose', support: 'unsupported', reason: 'verbose' },
+    { short: 'n', long: '--no-name', support: 'unsupported', reason: 'no-name' },
+    { short: 'r', long: '--recursive', support: 'unsupported', reason: 'recursive' },
+    { short: 'S', long: '--suffix', takesValue: true, support: 'unsupported', reason: 'suffix' },
+];
+export const specs = [
+    {
+        names: ['gzip'],
+        options: gzipOptions,
+        effects: ['read', 'write', 'delete'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: gzip,
+    },
+    {
+        names: ['gunzip'],
+        options: gzipOptions,
+        effects: ['read', 'write', 'delete'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: gunzip,
+    },
+    {
+        names: ['zcat'],
+        options: gzipOptions,
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: zcat,
+    },
+    {
+        names: ['zip'],
+        options: [
+            // Compress-Archive always recurses directory inputs; -q is already quiet.
+            { short: 'r', support: 'implemented' },
+            { short: 'q', support: 'implemented' },
+            { short: 'x', long: '--exclude', takesValue: true, support: 'unsupported', reason: 'exclude patterns' },
+        ],
+        effects: ['read', 'write'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: zip,
+    },
+    {
+        names: ['unzip'],
+        options: [
+            { short: 'l', support: 'implemented' },
+            { short: 'o', support: 'implemented' },
+            { short: 'q', support: 'implemented' },
+            { short: 'd', long: '--directory', takesValue: true, support: 'implemented' },
+        ],
+        effects: ['read', 'write'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: unzip,
+    },
+];
 export const handlers = {
     tar,
     gzip,

package/dist/commands/files.js

@@ -55,7 +55,7 @@ function psIsLink(it) {
 /* ls                                                                  */
 /* ------------------------------------------------------------------ */
 const ls = (args) => {
-    const { flags, longs, values, operandWords } = parseWords(args, [], ['--format']);
+    const { flags, longs, values, operandWords } = parseWords(args, [], ['--format', '--color']);
     const long = flags.has('l') || longs.has('--long') || values.get('--format') === 'long';
     const all = flags.has('a') || longs.has('--all');
     const almost = flags.has('A') || longs.has('--almost-all');
@@ -725,7 +725,7 @@ const find = (args) => {
     const preds = raw.slice(pathEnd);
     if (preds.includes('-exec') || preds.includes('-execdir')) {
         return ('[Console]::Error.WriteLine(' +
-            psStr('find: -exec is not supported by fauxnix; pipe into the command instead (e.g. `find . -name "*.log" | xargs rm`)') +
+            psStr('find: -exec is not supported by fauxnix; use `find . -name "*.log" -delete` or grep -r instead') +
             '); $script:fx_exit = 1');
     }
     const plan = parseFindPreds(preds);
@@ -967,6 +967,8 @@ export const specs = [
         opt('S', undefined),
         opt('r', undefined),
         opt('R', '--recursive', 'unsupported', { reason: 'recursive listing' }),
+        // GNU optional WHEN; takesValue so --color=auto is valid. No ANSI.
+        opt(undefined, '--color', 'implemented', { takesValue: true }),
     ], ls),
     fileSpec(['mkdir'], ['write'], [opt('p', '--parents'), opt('v', '--verbose')], mkdir),
     fileSpec(['rmdir'], ['delete'], [], rmdir),

package/dist/commands/install-all.js

@@ -4,7 +4,7 @@ import { handlers as textFilters, specs as textFilterSpecs } from './text-filter
 import { handlers as textIo, specs as textIoSpecs } from './text-io.js';
 import { handlers as sysinfo } from './sysinfo.js';
 import { handlers as net } from './net.js';
-import { handlers as archive } from './archive.js';
+import { handlers as archive, specs as archiveSpecs } from './archive.js';
 /** Register every built-in Linux command translator. Side-effectful import. */
 export function installAll() {
     registerAll(files);
@@ -16,5 +16,6 @@ export function installAll() {
     registerSpecs(fileSpecs);
     registerSpecs(textIoSpecs);
     registerSpecs(textFilterSpecs);
+    registerSpecs(archiveSpecs);
 }
 installAll();

package/dist/commands/net.js

@@ -79,10 +79,9 @@ function synthWord(text) {
 }
 /** A native-exe invocation obeying the fauxnix contract (string lines + exit code). */
 function nativeCall(exe, argArray) {
-    return [
-        '& ' + psStr(exe) + ' @(' + argArray + ') | ForEach-Object { [string]$_ }',
-        'if ($LASTEXITCODE -gt 0) { $script:fx_exit = $LASTEXITCODE }',
-    ].join('\n');
+    // fx-native captures stdout as pipeline strings and sets fx_exit.
+    // [object[]]@(...) keeps an empty argv from unwrapping to $null on PS 5.1.
+    return 'fx-native ' + psStr(exe) + ' ([object[]]@(' + argArray + '))';
 }
 /* ------------------------------------------------------------------ */
 /* curl                                                                */

package/dist/commands/sysinfo.js

@@ -1,6 +1,6 @@
 import { FauxnixParseError, isUnquotedLiteral, wordToString } from '../ast.js';
 import { lookup, parseWords, psStr, registeredNames } from '../registry.js';
-import { argListExpr, exprOfWord, operandExpr, translateSimple, wrapTempEnv, encodeSetValExpr, escapeDq, translateCmdSub, normalizeLiteralPath, pathExpr, paramExpr, varExpr, arithExpr, setArithHelperPreamble, } from '../translator.js';
+import { argListExpr, exprOfWord, operandExpr, translateSimple, wrapTempEnv, encodeSetValExpr, escapeDq, translateCmdSub, normalizeLiteralPath, pathExpr, paramExpr, varExpr, varExtraOf, arithExpr, setArithHelperPreamble, isSpecialShellVar, } from '../translator.js';
 import { handlers as textIoHandlers } from './text-io.js';
 /* ------------------------------------------------------------------ */
 /* Shared TS helpers                                                   */
@@ -210,7 +210,7 @@ const env = (args, ctx) => {
         }
         if (t === '-i' || t === '--ignore-environment') {
             return ('[Console]::Error.WriteLine(' +
-                psStr('fauxnix: env -i/--ignore-environment is not supported (would silently keep inherited secrets)') +
+                psStr('fauxnix: env -i/--ignore-environment is not supported (would silently keep inherited secrets). Use env -u NAME or unset first instead.') +
                 '); $script:fx_exit = 2');
         }
         if (t === '-u' || t === '--unset') {
@@ -1398,6 +1398,10 @@ function kshExprOfWord(w) {
         return arithExpr(expanded[0].parts);
     }
     if (!tilde && expanded.length === 1 && expanded[0].kind === 'Var') {
+        const extra = varExtraOf(expanded[0]);
+        if (extra && (extra.replace || extra.slice)) {
+            return varExpr(expanded[0].name, expanded[0].index, expanded[0].param, expanded[0].length === true, extra);
+        }
         if (expanded[0].param) {
             return paramExpr(expanded[0].name, expanded[0].param.op, expanded[0].param.word);
         }
@@ -1407,6 +1411,8 @@ function kshExprOfWord(w) {
         if (expanded[0].index !== undefined) {
             return '(fx-subget ' + psStr(expanded[0].name) + ' ' + psStr(expanded[0].index) + ')';
         }
+        if (isSpecialShellVar(expanded[0].name))
+            return varExpr(expanded[0].name);
         return '(fx-envget ' + psStr(expanded[0].name) + ')';
     }
     const literal = !tilde && expanded.every((p) => p.kind === 'Text' || p.kind === 'SingleQuoted');
@@ -1427,14 +1433,28 @@ function kshExprOfWord(w) {
                 for (const q of p.parts)
                     emitPart(q);
                 break;
-            case 'Var':
-                out +=
-                    p.param
-                        ? '$(' + paramExpr(p.name, p.param.op, p.param.word) + ')'
-                        : p.index !== undefined
-                            ? '$(fx-subget ' + psStr(p.name) + ' ' + psStr(p.index) + ')'
-                            : '$(fx-envget ' + psStr(p.name) + ')';
+            case 'Var': {
+                const extra = varExtraOf(p);
+                if (extra && (extra.replace || extra.slice)) {
+                    out += '$(' + varExpr(p.name, p.index, p.param, p.length === true, extra) + ')';
+                }
+                else if (p.param) {
+                    out += '$(' + paramExpr(p.name, p.param.op, p.param.word) + ')';
+                }
+                else if (p.length) {
+                    out += '$(' + varExpr(p.name, p.index, undefined, true) + ')';
+                }
+                else if (p.index !== undefined) {
+                    out += '$(fx-subget ' + psStr(p.name) + ' ' + psStr(p.index) + ')';
+                }
+                else if (isSpecialShellVar(p.name)) {
+                    out += '$(' + varExpr(p.name) + ')';
+                }
+                else {
+                    out += '$(fx-envget ' + psStr(p.name) + ')';
+                }
                 break;
+            }
             case 'CmdSub':
                 // [[ ]] does not IFS-split, so keep the newline contract.
                 out += '$(' + translateCmdSub(p.cmd, true) + ')';
@@ -2478,7 +2498,7 @@ const source = (args) => {
     ].join('\n');
 };
 const evalCmd = () => {
-    return ("[Console]::Error.WriteLine('fauxnix: eval is not supported; pass the command itself'); $script:fx_exit = 1");
+    return ("[Console]::Error.WriteLine('fauxnix: eval is not supported; pass the command itself instead'); $script:fx_exit = 1");
 };
 const exitCmd = (args) => {
     const w = args[0];
@@ -2510,9 +2530,15 @@ const alias = (args) => {
     });
     if (!has)
         return '';
-    return "[Console]::Error.WriteLine('fauxnix: alias is not supported'); $script:fx_exit = 1";
+    return "[Console]::Error.WriteLine('fauxnix: alias is not supported. Invoke the real command instead.'); $script:fx_exit = 1";
 };
 const set = (args) => {
+    if (args.length > 0 && wordToString(args[0]) === '--') {
+        return [
+            '$fx_pv = [object[]](' + argListExpr(args.slice(1)) + ')',
+            'fx-posset $fx_pv',
+        ].join('\n');
+    }
     const raw = args.map(wordToString);
     const unsupported = raw.filter((t) => t === '-e' ||
         t === '-u' ||
@@ -2529,11 +2555,20 @@ const set = (args) => {
         /^-.*[eux]/.test(t));
     if (unsupported.length > 0) {
         return ('[Console]::Error.WriteLine(' +
-            psStr('fauxnix: set -e/-u/-x is not supported (would silently lie); use explicit || exit') +
+            psStr('fauxnix: set -e/-u/-x is not supported (would silently lie); use explicit || exit instead') +
             '); $script:fx_exit = 2');
     }
     return '';
 };
+const shiftCmd = (args) => {
+    if (args.length === 0)
+        return 'fx-posshift 1';
+    return [
+        '$fx_sn = [string](' + exprOfWord(args[0]) + ')',
+        "if ($fx_sn -notmatch '^-?[0-9]+$') { [Console]::Error.WriteLine('bash: shift: ' + $fx_sn + ': numeric argument required'); $script:fx_exit = 1 }",
+        'else { fx-posshift $fx_sn }',
+    ].join('\n');
+};
 /* ------------------------------------------------------------------ */
 export const handlers = {
     cd,
@@ -2582,4 +2617,5 @@ export const handlers = {
     exit: exitCmd,
     alias,
     set,
+    shift: shiftCmd,
 };

package/dist/commands/text-filters.d.ts

@@ -1,3 +1,4 @@
 import { CommandSpec, Handler } from '../registry.js';
 export declare const specs: CommandSpec[];
+/** sed/awk stay unspec'd (custom script parsers). egrep injects -E and stays its own handler. */
 export declare const handlers: Record<string, Handler>;