fauxnix-cli 0.9.3 → 0.12.0

package/README.md

@@ -85,6 +85,20 @@ npm install -g .
 
 Requires: Windows with PowerShell 5.1+ (built-in) and Node.js ≥ 18.
 
+PowerShell 7 is an opt-in, CI-tested tier:
+
+```powershell
+$env:FAUXNIX_PS = 'pwsh'
+fauxnix check                 # edition: Core
+```
+
+Set the variable before starting `fauxnix` or its MCP harness; restart the
+harness after changing it. Windows PowerShell 5.1 remains the default. Invalid
+values and a missing selected executable fail loudly rather than falling back.
+The default is pinned below `SystemRoot`; `pwsh.exe` is resolved once from
+absolute `PATH` directories, excluding the current working directory.
+See [PowerShell 7 support](docs/powershell-7.md).
+
 ## Quick start
 
 ```bash
@@ -98,18 +112,32 @@ 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
 ```
 
+`translate` only renders a script and does not read command operands. Because
+`sed -f` needs a script file, translate-only mode asks you to use `-e` with
+inline script text; normal command execution continues to support `sed -f`.
+
 Unknown commands (git, node, npm, python, cargo, gh, docker, ...) are **passed through natively**
-with argv-style quoting — no string re-parsing, no quoting bugs.
+with argv-style quoting. Windows `.cmd`/`.bat` shims necessarily pass through `cmd.exe`; fauxnix
+preserves its supported punctuation and fails loudly for `%`, embedded double quotes, NUL, and
+line breaks rather than passing a different argument.
 
 ## 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
@@ -145,12 +173,23 @@ TOML config: `~/.kimi-code/mcp.json`
 }
 ```
 
+**Qwen Code** (`~/.qwen/settings.json`)
+```bash
+fauxnix install --qwen
+```
+The installer preserves the rest of `settings.json` and writes an absolute
+Node + package-entry launcher so Qwen startup does not depend on its working
+directory or `PATH` order. See [the Qwen example](docs/examples/qwen.md) for
+the generated JSON shape.
+
 **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
 
@@ -158,26 +197,30 @@ tool calls — it behaves like a logged-in shell, not a stateless `exec`.
 development:
 
 - **files**: `ls cp mv rm mkdir rmdir touch mktemp ln readlink realpath basename dirname stat file du df find chmod chown diff`
-- **text filters**: `grep egrep sed awk sort uniq cut tr` — sed/awk scripts are parsed at
-  translate time (unsupported constructs throw named errors, never silently misbehave)
+- **text filters**: `grep egrep sed awk sort uniq cut tr` — sed/awk scripts are parsed while
+  preparing an executable plan (unsupported constructs throw named errors, never silently
+  misbehave); inspect-only `translate` keeps `sed -f` file reads out of that path
 - **text I/O**: `echo printf cat head tail wc tee nl tac md5sum sha1sum sha256sum base64 seq yes xargs`
 
-`cp` / `mv` / `rm` / `touch` / `du` / `ls` / `ll` / `mkdir` / `rmdir` / `mktemp` / `ln` /
-`readlink` / `realpath` / `basename` / `dirname` / `stat` / `file` / `df` / `chmod` / `chown` /
-`diff` / `tee` / `grep` / `head` / `echo` / `printf` / `cat` / `tail` / `wc` 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` /
-`head --lines` / `du --max-depth`. `fauxnix list --json` and `docs/command-specs.md` dump the
-same metadata.
+The curated **agent-daily 60** carry a `CommandSpec`: unknown options fail with a GNU-style
+usage error instead of being ignored. The generated [`docs/command-specs.md`](docs/command-specs.md)
+is the exact list, coverage count, option table, and exclusion rationale; `fauxnix list --json`
+exposes the same per-command metadata. `find` stays unspec'd so predicates like `-name` still
+compile; `sed`/`awk`/`egrep` keep their command-specific parsers; `tar` remains native to
+`tar.exe` so supported bsdtar options reach the executable. Implemented GNU holes include
+`cp -n` / `mv -n` / `touch -c` / `tee --append` / `grep -m` / `head --lines` /
+`du --max-depth` / `env -u` / `ps -f` / `command -V` / `date --date=@SECONDS`.
 - **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.
@@ -185,9 +228,9 @@ Exit codes follow bash conventions: 0 ok, 1 fail, 2 usage/serious, 127 command n
 ## How it works
 
 ```
-bash command ──parser──▶ AST ──translator──▶ PowerShell script ──executor──▶ powershell.exe
+bash command ──parser──▶ AST ──translator──▶ PowerShell script ──executor──▶ selected PowerShell
                                                                               │
-agent ◀── GNU-style output, bash-style errors ◀── decoder (UTF-8 → GBK fallback) ◀┘
+agent ◀── GNU-style output, bash-style errors ◀── UTF-8 framed host protocol ◀┘
 ```
 
 - **Deterministic translation, zero LLM calls** at runtime.
@@ -195,9 +238,10 @@ agent ◀── GNU-style output, bash-style errors ◀── decoder (UTF-8 →
   "Fauxnix contract": string-per-line stdout, `[Console]::Error.WriteLine` for bash-style
   stderr, `$script:fx_exit` for exit codes, `$input` for stdin.
 - The executor wraps every script with UTF-8 enforcement (`[Console]::OutputEncoding`,
-  `$OutputEncoding`, `chcp 65001`), decodes output as strict-UTF-8 with a GBK(936) fallback for
-  legacy native tools, strips CLIXML serialization and PowerShell noise from stderr, and rewrites
-  common PowerShell errors (including zh-CN locale messages) into bash phrasing.
+  `$OutputEncoding`, `chcp 65001`), decodes native output at the process boundary (UTF-8 by
+  default or GBK(936) in `ansi` mode), keeps host frames UTF-8, strips CLIXML serialization and
+  PowerShell noise from stderr, and rewrites common PowerShell errors (including zh-CN locale
+  messages) into bash phrasing.
 - Scripts run via `-EncodedCommand` (UTF-16LE) and transparently fall back to a temp `.ps1` file
   when the 32 KB command-line limit would be exceeded.
 
@@ -211,11 +255,17 @@ 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 output/fd redirects (`>` `>>` `2>` `2>>` `&>` `&>>`
+  `2>&1` `1>&2`) on a non-last pipeline stage (`echo hi >f | cat`) are
+  rejected with operation-specific, actionable error messages instead of
+  misbehaving. Per-stage `<` remains supported; fully routed per-stage output
+  fds are still tracked by #157.
+  (`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
@@ -238,13 +288,16 @@ fauxnix optimizes for the commands agents actually run. Documented deviations:
 
 ## Development
 
-```bash
+```powershell
 npm install
 npm test          # unit + real-PowerShell integration suite (Windows only, auto-skipped elsewhere)
+$env:FAUXNIX_PS = 'pwsh'; npm test   # same suite through PowerShell 7
 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). The 253-case corpus enforces the RFC C-7 minimum of 200 cases and a 95% identity gate. The weekly oracle runs from `.github/workflows/differential.yml`; two consecutive green **scheduled** runs are still required release evidence after this gate lands.
+
 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`.
@@ -252,6 +305,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,4 @@
 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  FAUXNIX_PS=pwsh selects the opt-in PowerShell 7 host (5.1 is the default).\n  Unknown commands (git, node, npm, python, cargo, ...) pass through and run natively.";
 export declare function runCli(argv: string[]): Promise<void>;
+export declare function runCheck(): Promise<boolean>;

package/dist/cli.js

@@ -1,13 +1,16 @@
 import { spawn } from 'node:child_process';
 import { FauxnixSession } from './executor.js';
 import { parseCommand } from './parser.js';
-import { translateCommandList } from './translator.js';
+import { EXECUTE_TRANSLATION, PURE_TRANSLATION, 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 { POWERSHELL_ARGS, powerShellDisplay, powerShellMissingMessage, resolvePowerShell, } from './powershell.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,9 +21,12 @@ 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:
+  FAUXNIX_PS=pwsh selects the opt-in PowerShell 7 host (5.1 is the default).
   Unknown commands (git, node, npm, python, cargo, ...) pass through and run natively.`;
 export async function runCli(argv) {
     if (argv.length === 0) {
@@ -52,6 +58,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;
@@ -59,7 +77,7 @@ export async function runCli(argv) {
     if (verb === 'translate') {
         const cmd = rest.join(' ');
         const list = parseCommand(cmd);
-        const plans = translateCommandList(list);
+        const plans = translateCommandList(list, PURE_TRANSLATION);
         console.log(plans.map((p) => p.script).join('\n# ---- next segment ----\n'));
         return;
     }
@@ -69,7 +87,7 @@ export async function runCli(argv) {
         return;
     }
     const list = parseCommand(cmd);
-    const plans = translateCommandList(list);
+    const plans = translateCommandList(list, EXECUTE_TRANSLATION);
     const session = new FauxnixSession();
     const result = await session.run(plans);
     if (result.stdout)
@@ -79,28 +97,74 @@ export async function runCli(argv) {
     await session.dispose();
     process.exit(result.exitCode);
 }
-const PS_ARGS = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass'];
-async function runCheck() {
-    console.log('powershell : powershell.exe (Windows built-in)');
-    const probeCmd = '$PSVersionTable.PSVersion.ToString()';
-    const probe = spawn('powershell.exe', [...PS_ARGS, '-EncodedCommand', encodeCommand(probeCmd)], {
+async function runDoctor() {
+    const checkOk = await runCheck();
+    const report = await collectDoctorReport();
+    for (const line of report.lines)
+        console.log(line);
+    if (!checkOk || !report.ok)
+        process.exitCode = 1;
+}
+export async function runCheck() {
+    const selection = resolvePowerShell();
+    console.log('powershell : ' + powerShellDisplay(selection));
+    if (selection.error) {
+        console.error('status     : FAILED');
+        console.error(selection.error);
+        process.exitCode = 1;
+        return false;
+    }
+    const probeCmd = '[Console]::Out.WriteLine($PSVersionTable.PSVersion.ToString()); ' +
+        '[Console]::Out.WriteLine([string]$PSVersionTable.PSEdition)';
+    const probe = spawn(selection.executable, [...POWERSHELL_ARGS, '-EncodedCommand', encodeCommand(probeCmd)], {
         stdio: ['ignore', 'pipe', 'pipe'],
         windowsHide: true,
     });
-    probe.on('error', (e) => {
-        console.error('status     : FAILED to run powershell.exe: ' + e.message);
-        process.exit(1);
-    });
     let out = '';
+    let err = '';
     probe.stdout.on('data', (d) => (out += d.toString('utf8')));
-    const code = await new Promise((resolve) => probe.on('close', (c) => resolve(c ?? 1)));
-    if (code === 0) {
-        console.log('version    : ' + out.trim());
-        console.log('commands   : ' + registeredNames().length + ' translated, others pass through');
-        console.log('status     : OK');
+    probe.stderr.on('data', (d) => (err += d.toString('utf8')));
+    const outcome = await new Promise((resolve) => {
+        let settled = false;
+        const done = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        probe.once('error', (error) => done({ code: 127, error }));
+        probe.once('close', (code) => done({ code: code ?? 1 }));
+    });
+    if (outcome.error) {
+        console.error('status     : FAILED');
+        if (outcome.error.code === 'ENOENT') {
+            console.error(powerShellMissingMessage(selection).trimEnd());
+        }
+        else {
+            console.error(`fauxnix: failed to start ${selection.executable}: ${outcome.error.message}`);
+        }
+        process.exitCode = 1;
+        return false;
+    }
+    if (outcome.code !== 0) {
+        console.error(`status     : FAILED to run ${selection.executable}`);
+        if (err.trim())
+            console.error(err.trim());
+        process.exitCode = 1;
+        return false;
     }
-    else {
-        console.error('status     : FAILED to run powershell.exe');
+    const lines = out.trim().split(/\r?\n/);
+    const version = lines[0] ?? '';
+    const edition = lines[1] ?? '';
+    console.log('version    : ' + version);
+    console.log('edition    : ' + edition);
+    if (edition !== selection.expectedEdition) {
+        console.error(`status     : FAILED: ${selection.executable} reported ${edition || 'no edition'}; ` +
+            `expected ${selection.expectedEdition}`);
         process.exitCode = 1;
+        return false;
     }
+    console.log('commands   : ' + registeredNames().length + ' translated, others pass through');
+    console.log('status     : OK');
+    return true;
 }

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>;