fauxnix-cli 0.8.0 → 0.9.0

package/README.md

@@ -154,9 +154,10 @@ development:
   translate time (unsupported constructs throw named errors, never silently misbehave)
 - **text I/O**: `echo printf cat head tail wc tee nl tac md5sum sha1sum sha256sum base64 seq yes xargs`
 
-`cp` / `mv` / `rm` / `touch` / `tee` carry a `CommandSpec`: unknown options fail with a GNU-style
-usage error instead of being ignored. `cp -n` / `mv -n` / `touch -c` / `tee --append` match GNU
-(no clobber / no-create / append). `fauxnix list --json` dumps the same capability metadata.
+`cp` / `mv` / `rm` / `touch` / `tee` / `grep` / `head` / `du` carry a `CommandSpec`: unknown
+options fail with a GNU-style usage error instead of being ignored. 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`

package/dist/cli.js

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import { FauxnixSession } from './executor.js';
 import { parseCommand } from './parser.js';
 import { translateCommandList } from './translator.js';
-import { listCommandsJson, registeredNames } from './registry.js';
+import { listCommandsJson, registeredNames, specsMarkdown } from './registry.js';
 import { encodeCommand } from './encoding.js';
 import { startMcpServer } from './mcp.js';
 import { packageVersion } from './version.js';
@@ -16,6 +16,7 @@ Usage:
   fauxnix mcp                        start the MCP stdio server (for agent harnesses)
   fauxnix list                       list translated commands
   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 --version
 
@@ -36,6 +37,10 @@ export async function runCli(argv) {
             console.log(JSON.stringify(listCommandsJson(), null, 2));
             return;
         }
+        if (rest[0] === '--markdown') {
+            console.log(specsMarkdown());
+            return;
+        }
         const names = registeredNames();
         console.log(names.length + ' translated commands:');
         for (const n of names)

package/dist/commands/files.js

@@ -51,8 +51,8 @@ function psArray(words, fn = operandExpr) {
 /* ls                                                                  */
 /* ------------------------------------------------------------------ */
 const ls = (args) => {
-    const { flags, longs, operandWords } = parseWords(args);
-    const long = flags.has('l') || longs.has('--format=long') || longs.has('--long');
+    const { flags, longs, values, operandWords } = parseWords(args, [], ['--format']);
+    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');
     const dirOnly = flags.has('d') || longs.has('--directory');
@@ -208,7 +208,7 @@ const rm = (args) => {
 const mkdir = (args) => {
     const { flags, longs, operandWords } = parseWords(args);
     const parents = flags.has('p') || longs.has('--parents');
-    const verbose = flags.has('v');
+    const verbose = flags.has('v') || longs.has('--verbose');
     return [
         '$fx_dirs = ' + psArray(operandWords),
         "if ($fx_dirs.Count -eq 0) { [Console]::Error.WriteLine('mkdir: missing operand'); $script:fx_exit = 1 }",
@@ -254,8 +254,8 @@ const touch = (args) => {
     ].join('\n');
 };
 const mktemp = (args) => {
-    const { flags } = parseWords(args);
-    const dir = flags.has('d');
+    const { flags, longs } = parseWords(args);
+    const dir = flags.has('d') || longs.has('--directory');
     return [
         'try {',
         '  if (' + (dir ? '$true' : '$false') + ') {',
@@ -272,8 +272,8 @@ const mktemp = (args) => {
 /* ln / readlink / realpath                                            */
 /* ------------------------------------------------------------------ */
 const ln = (args) => {
-    const { flags, operandWords } = parseWords(args);
-    const sym = flags.has('s');
+    const { flags, longs, operandWords } = parseWords(args);
+    const sym = flags.has('s') || longs.has('--symbolic');
     const kind = sym ? 'SymbolicLink' : 'HardLink';
     const label = sym ? 'symbolic link' : 'hard link';
     return [
@@ -288,8 +288,8 @@ const ln = (args) => {
     ].join('\n');
 };
 const readlink = (args) => {
-    const { flags, operandWords } = parseWords(args);
-    const canon = flags.has('f');
+    const { flags, longs, operandWords } = parseWords(args);
+    const canon = flags.has('f') || longs.has('--canonicalize');
     return [
         '$fx_p = ' + (operandWords.length ? operandExpr(operandWords[0]) : "''"),
         "if ($fx_p -eq '') { [Console]::Error.WriteLine('readlink: missing operand'); $script:fx_exit = 1 }",
@@ -422,10 +422,31 @@ const file = (args) => {
 /* du / df                                                             */
 /* ------------------------------------------------------------------ */
 const du = (args) => {
-    const { flags, longs, operandWords } = parseWords(args, [], ['--max-depth']);
+    const { flags, longs, values, missingValue, operandWords } = parseWords(args, ['d'], ['--max-depth']);
     const sum = flags.has('s') || longs.has('--summarize');
     const human = flags.has('h') || longs.has('--human-readable');
+    if (missingValue.includes('-d') || missingValue.includes('--max-depth')) {
+        return ('[Console]::Error.WriteLine(' +
+            psStr("du: option requires an argument -- 'max-depth'") +
+            '); $script:fx_exit = 1');
+    }
+    const maxDepthRaw = values.get('-d') ?? values.get('--max-depth');
+    let maxDepth = null;
+    if (maxDepthRaw !== undefined) {
+        if (!/^\d+$/.test(maxDepthRaw)) {
+            return ('[Console]::Error.WriteLine(' +
+                psStr("du: invalid maximum depth '" + maxDepthRaw + "'") +
+                '); $script:fx_exit = 1');
+        }
+        maxDepth = parseInt(maxDepthRaw, 10);
+    }
+    if (sum && maxDepth !== null && maxDepth !== 0) {
+        return ('[Console]::Error.WriteLine(' +
+            psStr('du: summarizing conflicts with --max-depth=' + String(maxDepth)) +
+            '); $script:fx_exit = 1');
+    }
     const targets = operandWords.length ? argListExpr(operandWords) : "@('.')";
+    const onlyRoot = sum || maxDepth === 0;
     return [
         PS_HSIZE_FN,
         'function fx-size($p) {',
@@ -436,7 +457,7 @@ const du = (args) => {
         '$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') + ') {',
+        '  if (' + (onlyRoot ? '$true' : '$false') + ') {',
         '    $fx_kb = fx-size $fx_t',
         '    if (' + (human ? '$true' : '$false') + ') { "{0}`t{1}" -f (fx-hsize ($fx_kb * 1KB)), $fx_t } else { "{0}`t{1}" -f $fx_kb, $fx_t }',
         '  } else {',
@@ -444,6 +465,11 @@ const du = (args) => {
         '    foreach ($fx_d in @(Get-ChildItem -LiteralPath $fx_t -Recurse -Force -Directory -ErrorAction SilentlyContinue)) {',
         '      $fx_kb = fx-size $fx_d.FullName',
         "      $fx_rel = './' + $fx_d.FullName.Substring($fx_root.Length).TrimStart('\\').Replace('\\', '/')",
+        maxDepth !== null && maxDepth > 0
+            ? "      $fx_ddepth = @($fx_rel.ToCharArray() | Where-Object { $_ -eq '/' }).Count; if ($fx_ddepth -gt " +
+                maxDepth +
+                ') { continue }'
+            : '',
         '      if (' + (human ? '$true' : '$false') + ') { "{0}`t{1}" -f (fx-hsize ($fx_kb * 1KB)), $fx_rel } else { "{0}`t{1}" -f $fx_kb, $fx_rel }',
         '    }',
         '    $fx_kb = fx-size $fx_t',
@@ -453,8 +479,8 @@ const du = (args) => {
     ].join('\n');
 };
 const df = (args) => {
-    const { flags } = parseWords(args);
-    const human = flags.has('h') || flags.has('H');
+    const { flags, longs } = parseWords(args);
+    const human = flags.has('h') || flags.has('H') || longs.has('--human-readable');
     return [
         PS_HSIZE_FN,
         '"Filesystem      Size  Used Avail Use% Mounted on"',
@@ -801,9 +827,9 @@ const chown = () => {
 /* diff — LCS-based, GNU normal format (+ -q, -u)                      */
 /* ------------------------------------------------------------------ */
 const diff = (args) => {
-    const { flags, operandWords } = parseWords(args);
-    const unified = flags.has('u') || flags.has('U');
-    const brief = flags.has('q') || flags.has('brief');
+    const { flags, longs, operandWords } = parseWords(args);
+    const unified = flags.has('u') || flags.has('U') || longs.has('--unified');
+    const brief = flags.has('q') || longs.has('--brief');
     void unified;
     return [
         PS_READTEXT_FN,
@@ -910,6 +936,43 @@ export const specs = [
         opt('i', '--interactive', 'unsupported', INTERACTIVE),
     ], rm),
     fileSpec(['touch'], ['write'], [opt('c', '--no-create')], touch),
+    fileSpec(['du'], ['read'], [
+        opt('s', '--summarize'),
+        opt('h', '--human-readable'),
+        opt('d', '--max-depth', 'implemented', { takesValue: true }),
+    ], du),
+    fileSpec(['ls', 'll'], ['read'], [
+        opt('l', '--long'),
+        opt(undefined, '--format', 'implemented', { takesValue: true }),
+        opt('a', '--all'),
+        opt('A', '--almost-all'),
+        opt('d', '--directory'),
+        opt('h', '--human-readable'),
+        opt('F', '--classify'),
+        opt('p', undefined),
+        opt('t', undefined),
+        opt('S', undefined),
+        opt('r', undefined),
+        opt('R', '--recursive', 'unsupported', { reason: 'recursive listing' }),
+    ], ls),
+    fileSpec(['mkdir'], ['write'], [opt('p', '--parents'), opt('v', '--verbose')], mkdir),
+    fileSpec(['rmdir'], ['delete'], [], rmdir),
+    fileSpec(['mktemp'], ['write'], [opt('d', '--directory')], mktemp),
+    fileSpec(['ln'], ['read', 'write'], [opt('s', '--symbolic')], ln),
+    fileSpec(['readlink'], ['read'], [opt('f', '--canonicalize')], readlink),
+    fileSpec(['realpath'], ['read'], [], realpath),
+    fileSpec(['basename'], ['read'], [], basename),
+    fileSpec(['dirname'], ['read'], [], dirname),
+    fileSpec(['stat'], ['read'], [
+        opt('c', undefined, 'implemented', { takesValue: true }),
+        opt(undefined, '--format', 'implemented', { takesValue: true }),
+        opt(undefined, '--printf', 'implemented', { takesValue: true }),
+    ], stat),
+    fileSpec(['file'], ['read'], [], file),
+    fileSpec(['df'], ['read'], [opt('h', '--human-readable'), opt('H', undefined)], df),
+    fileSpec(['chmod'], ['write'], [opt('R', '--recursive', 'unsupported', { reason: 'recursive chmod' })], chmod),
+    fileSpec(['chown'], ['write'], [], chown),
+    fileSpec(['diff'], ['read'], [opt('q', '--brief'), opt('u', '--unified'), opt('U', undefined)], diff),
 ];
 export const handlers = {
     ls,
@@ -924,10 +987,7 @@ export const handlers = {
     dirname,
     stat,
     file,
-    du,
     df,
+    du,
     find,
-    chmod,
-    chown,
-    diff,
 };

package/dist/commands/install-all.js

@@ -1,6 +1,6 @@
 import { registerAll, registerSpecs } from '../registry.js';
 import { handlers as files, specs as fileSpecs } from './files.js';
-import { handlers as textFilters } from './text-filters.js';
+import { handlers as textFilters, specs as textFilterSpecs } from './text-filters.js';
 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';
@@ -15,5 +15,6 @@ export function installAll() {
     registerAll(archive);
     registerSpecs(fileSpecs);
     registerSpecs(textIoSpecs);
+    registerSpecs(textFilterSpecs);
 }
 installAll();

package/dist/commands/text-filters.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/text-filters.js

@@ -268,13 +268,23 @@ const grep = (args) => {
     const excludeDirGlobs = filterOptions
         .filter((o) => o.name === '--exclude-dir')
         .map((o) => o.value.replace(/[\\/]+$/, ''));
-    const { flags, operandWords, values, missingValue } = parseWords(args, ['A', 'B', 'C'], filterOptionNames);
-    const missingFilterOption = missingValue.find((o) => filterOptionNames.includes(o));
+    const { flags, operandWords, values, missingValue } = parseWords(args, ['A', 'B', 'C', 'm', 'e'], [...filterOptionNames, '--max-count', '--regexp']);
+    const missingFilterOption = missingValue.find((o) => [...filterOptionNames, '-m', '--max-count', '-e', '--regexp'].includes(o));
     if (missingFilterOption) {
         return ('[Console]::Error.WriteLine(' +
             psStr("grep: option '" + missingFilterOption + "' requires an argument") +
             '); $script:fx_exit = 2');
     }
+    const maxCountRaw = values.get('-m') ?? values.get('--max-count');
+    let maxCount = null;
+    if (maxCountRaw !== undefined) {
+        if (!/^\d+$/.test(maxCountRaw)) {
+            return ('[Console]::Error.WriteLine(' +
+                psStr("grep: invalid max count '" + maxCountRaw + "'") +
+                '); $script:fx_exit = 2');
+        }
+        maxCount = parseInt(maxCountRaw, 10);
+    }
     const ci = flags.has('i');
     const inv = flags.has('v');
     const num = flags.has('n');
@@ -294,11 +304,12 @@ const grep = (args) => {
     };
     const ctxA = Math.max(toInt(values.get('-A')), toInt(values.get('-C')));
     const ctxB = Math.max(toInt(values.get('-B')), toInt(values.get('-C')));
-    if (operandWords.length === 0) {
+    const ePat = values.get('-e') ?? values.get('--regexp');
+    if (ePat === undefined && operandWords.length === 0) {
         return ("[Console]::Error.WriteLine('usage: grep [OPTION]... PATTERN [FILE]...'); $script:fx_exit = 2");
     }
-    const patternWord = operandWords[0];
-    const fileWords = operandWords.slice(1);
+    const patternWord = ePat !== undefined ? [{ kind: 'Text', text: ePat }] : operandWords[0];
+    const fileWords = ePat !== undefined ? operandWords : operandWords.slice(1);
     const patLit = literalOfWord(patternWord);
     let patExpr;
     if (fixed || patLit === null) {
@@ -435,10 +446,16 @@ const grep = (args) => {
     lines.push('}');
     // --- per-source scan body ----------------------------------------------
     const scan = [];
+    if (maxCount !== null)
+        scan.push('$fx_mleft = ' + maxCount);
     if (cntMode) {
         scan.push('$fx_c = 0');
         scan.push('for ($fx_i = 0; $fx_i -lt $fx_ls.Count; $fx_i++) {');
-        scan.push('  if (fx-gmatch $fx_ls[$fx_i]) { $fx_c++ }');
+        if (maxCount !== null)
+            scan.push('  if ($fx_mleft -le 0) { break }');
+        scan.push('  if (fx-gmatch $fx_ls[$fx_i]) { $fx_c++' +
+            (maxCount !== null ? '; $fx_mleft--; if ($fx_mleft -le 0) { break }' : '') +
+            ' }');
         scan.push('}');
         scan.push('if ($fx_c -gt 0) { $fx_any = $true }');
         scan.push('if ($fx_pre) { $fx_disp + \':\' + [string]$fx_c } else { [string]$fx_c }');
@@ -446,21 +463,29 @@ const grep = (args) => {
     else if (listMode) {
         scan.push('$fx_hit1 = $false');
         scan.push('for ($fx_i = 0; $fx_i -lt $fx_ls.Count; $fx_i++) {');
+        if (maxCount !== null)
+            scan.push('  if ($fx_mleft -le 0) { break }');
         scan.push('  if (fx-gmatch $fx_ls[$fx_i]) { $fx_hit1 = $true; break }');
         scan.push('}');
         scan.push('if ($fx_hit1) { $fx_any = $true; $fx_disp }');
     }
     else if (quiet) {
         scan.push('for ($fx_i = 0; $fx_i -lt $fx_ls.Count; $fx_i++) {');
+        if (maxCount !== null)
+            scan.push('  if ($fx_mleft -le 0) { break }');
         scan.push('  if (fx-gmatch $fx_ls[$fx_i]) { $fx_any = $true; break }');
         scan.push('}');
     }
     else {
         scan.push('$fx_hits = @()');
         scan.push('for ($fx_i = 0; $fx_i -lt $fx_ls.Count; $fx_i++) {');
+        if (maxCount !== null)
+            scan.push('  if ($fx_mleft -le 0) { break }');
         scan.push('  $fx_l = $fx_ls[$fx_i]');
         scan.push('  if (fx-gmatch $fx_l) {');
         scan.push('    $fx_any = $true');
+        if (maxCount !== null)
+            scan.push('    $fx_mleft--');
         if (onlyMatch && !inv) {
             if (fixed) {
                 if (ci) {
@@ -492,6 +517,8 @@ const grep = (args) => {
         else if (!onlyMatch) {
             scan.push('    $fx_hits += $fx_i');
         }
+        if (maxCount !== null)
+            scan.push('    if ($fx_mleft -le 0) { break }');
         scan.push('  }');
         scan.push('}');
         if (!onlyMatch) {
@@ -2347,8 +2374,41 @@ const tr = (args) => {
     return lines.join('\n');
 };
 /* ------------------------------------------------------------------ */
+export const specs = [
+    {
+        names: ['grep'],
+        options: [
+            { short: 'i', support: 'implemented' },
+            { short: 'v', support: 'implemented' },
+            { short: 'n', support: 'implemented' },
+            { short: 'c', support: 'implemented' },
+            { short: 'l', support: 'implemented' },
+            { short: 'r', support: 'implemented' },
+            { short: 'R', support: 'implemented' },
+            { short: 'E', support: 'implemented' },
+            { short: 'F', support: 'implemented' },
+            { short: 'w', support: 'implemented' },
+            { short: 'q', support: 'implemented' },
+            { short: 'o', support: 'implemented' },
+            { short: 'h', support: 'implemented' },
+            { short: 'H', support: 'implemented' },
+            { short: 'A', takesValue: true, support: 'implemented' },
+            { short: 'B', takesValue: true, support: 'implemented' },
+            { short: 'C', takesValue: true, support: 'implemented' },
+            { short: 'm', long: '--max-count', takesValue: true, support: 'implemented' },
+            { short: 'e', long: '--regexp', takesValue: true, support: 'implemented' },
+            { long: '--include', takesValue: true, support: 'implemented' },
+            { long: '--exclude', takesValue: true, support: 'implemented' },
+            { long: '--exclude-dir', takesValue: true, support: 'implemented' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        usageExit: 2,
+        handler: grep,
+    },
+];
 export const handlers = {
-    grep,
     egrep: (args, ctx) => grep([[{ kind: 'Text', text: '-E' }], ...args], ctx), // egrep = grep -E
     sed,
     awk,

package/dist/commands/text-io.js

@@ -419,6 +419,37 @@ const head = (args, ctx) => {
                 continue;
             }
             if (t.startsWith('--')) {
+                const eq = t.indexOf('=');
+                const name = eq >= 0 ? t.slice(0, eq) : t;
+                const inline = eq >= 0 ? t.slice(eq + 1) : null;
+                if (name === '--lines' || name === '--bytes') {
+                    let val = inline;
+                    if (val === null) {
+                        if (i + 1 >= args.length) {
+                            return psErrExpr(psStr('head: option requires an argument -- ' + name.slice(2)));
+                        }
+                        val = wordToString(args[i + 1]);
+                        i += 2;
+                    }
+                    else {
+                        i++;
+                    }
+                    if (name === '--bytes')
+                        nBytes = val;
+                    else
+                        nLines = val;
+                    continue;
+                }
+                if (name === '--quiet' || name === '--silent') {
+                    quiet = true;
+                    i++;
+                    continue;
+                }
+                if (name === '--verbose') {
+                    verbose = true;
+                    i++;
+                    continue;
+                }
                 i++;
                 continue;
             }
@@ -464,6 +495,9 @@ const head = (args, ctx) => {
     }
     const bytesMode = nBytes !== null;
     const countLit = bytesMode ? nBytes : nLines !== null ? nLines : '10';
+    if (!/^[+-]?\d+$/.test(countLit)) {
+        return psErrExpr(psStr("head: invalid number of " + (bytesMode ? 'bytes' : 'lines') + ": '" + countLit + "'"));
+    }
     const lines = [
         PS_GLOB_FN,
         PS_READTEXT_FN,
@@ -516,6 +550,39 @@ const tail = (args, ctx) => {
                 continue;
             }
             if (t.startsWith('--')) {
+                const eq = t.indexOf('=');
+                const name = eq >= 0 ? t.slice(0, eq) : t;
+                const inline = eq >= 0 ? t.slice(eq + 1) : null;
+                if (name === '--lines' || name === '--bytes') {
+                    let val = inline;
+                    if (val === null) {
+                        if (i + 1 >= args.length) {
+                            return psErrExpr(psStr('tail: option requires an argument -- ' + name.slice(2)));
+                        }
+                        val = wordToString(args[i + 1]);
+                        i += 2;
+                    }
+                    else {
+                        i++;
+                    }
+                    if (name === '--bytes')
+                        nBytes = val;
+                    else if (val.startsWith('+'))
+                        fromLine = val.slice(1);
+                    else
+                        nLines = val.replace(/^-/, '');
+                    continue;
+                }
+                if (name === '--quiet' || name === '--silent') {
+                    quiet = true;
+                    i++;
+                    continue;
+                }
+                if (name === '--verbose') {
+                    verbose = true;
+                    i++;
+                    continue;
+                }
                 i++;
                 continue;
             }
@@ -1153,12 +1220,25 @@ export const specs = [
         dispatch: 'translated',
         handler: tee,
     },
+    {
+        names: ['head'],
+        options: [
+            { short: 'n', long: '--lines', takesValue: true, support: 'implemented' },
+            { short: 'c', long: '--bytes', takesValue: true, support: 'implemented' },
+            { short: 'q', long: '--quiet', support: 'implemented' },
+            { long: '--silent', support: 'implemented' },
+            { short: 'v', long: '--verbose', support: 'implemented' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: head,
+    },
 ];
 export const handlers = {
     echo,
     printf,
     cat,
-    head,
     tail,
     wc,
     nl,

package/dist/executor.js

@@ -410,7 +410,7 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
                 FAUXNIX_CWD: currentDir,
                 FAUXNIX_PREV_EXIT: session.prevExit === null ? '' : String(session.prevExit),
                 FAUXNIX_STDIN_FILE: red.stdinFile || '',
-            }, remainingMs, opts.signal);
+            }, remainingMs, opts.signal, { stdoutLimit, stderrLimit });
             if (inv.spawnError === 'ENOENT' || inv.spawnError === 'START') {
                 stderr += inv.stderr.toString('utf8') || PS_MISSING_MESSAGE;
                 exitCode = 127;

package/dist/ps-host.d.ts

@@ -14,7 +14,39 @@ export interface HostInvokeResult {
 export interface HostRequestEnv {
     [key: string]: string;
 }
-export declare function encodeHostRequest(id: string, script: string, env: HostRequestEnv): string;
+export declare function encodeHostRequest(id: string, script: string, env: HostRequestEnv, opts?: {
+    v?: number;
+    stdoutLimit?: number;
+    stderrLimit?: number;
+}): string;
+export type HostV2Frame = {
+    v: 2;
+    type: 'ready';
+    capabilities?: {
+        cancel?: boolean;
+        maxChunkBytes?: number;
+        stderrMarker?: boolean;
+    };
+} | {
+    v: 2;
+    type: 'stdout' | 'stderr';
+    id: string;
+    seq: number;
+    dataB64: string;
+} | {
+    v: 2;
+    type: 'end';
+    id: string;
+    exitCode: number;
+    timedOut?: boolean;
+    cancelled?: boolean;
+    truncated?: boolean;
+};
+export declare function parseHostLine(line: string): {
+    v1Ready?: boolean;
+    v2?: HostV2Frame;
+    v1?: ReturnType<typeof decodeHostResponse>;
+};
 export declare function decodeHostResponse(line: string): {
     id: string;
     stdout: Buffer;
@@ -40,10 +72,14 @@ export declare class PowerShellHost {
     private closed;
     private startLock;
     private invokeLock;
+    protocol: 1 | 2;
     constructor(hostFile: string, envFn: () => NodeJS.ProcessEnv);
     /** Start the resident process and wait for the ready handshake (B1 prewarm). */
     ready(): Promise<HostInvokeResult | null>;
-    invoke(script: string, env: HostRequestEnv, timeoutMs: number, signal?: AbortSignal): Promise<HostInvokeResult>;
+    invoke(script: string, env: HostRequestEnv, timeoutMs: number, signal?: AbortSignal, limits?: {
+        stdoutLimit?: number;
+        stderrLimit?: number;
+    }): Promise<HostInvokeResult>;
     drainNativeStderr(): Buffer;
     stop(): Promise<void>;
     private cancelledResult;
@@ -55,5 +91,7 @@ export declare class PowerShellHost {
     private nextLine;
     private nextReadyLine;
     private nextJsonLine;
+    private collectV2;
+    private waitNativeMarker;
     private failWaiters;
 }

package/dist/ps-host.js

@@ -8,12 +8,27 @@ export const PS_MISSING_MESSAGE = 'fauxnix: powershell.exe not found — fauxnix
     'Run fauxnix on Windows, or install PowerShell and make powershell.exe reachable on PATH.\n';
 export const DEFAULT_STDOUT_LIMIT = 8_388_608;
 export const DEFAULT_STDERR_LIMIT = 1_048_576;
-export function encodeHostRequest(id, script, env) {
-    return JSON.stringify({
+export function encodeHostRequest(id, script, env, opts) {
+    const body = {
         id,
         scriptB64: Buffer.from(script, 'utf8').toString('base64'),
         env,
-    });
+    };
+    if (opts?.v === 2) {
+        body.v = 2;
+        body.type = 'run';
+        body.stdoutLimit = opts.stdoutLimit ?? DEFAULT_STDOUT_LIMIT;
+        body.stderrLimit = opts.stderrLimit ?? DEFAULT_STDERR_LIMIT;
+    }
+    return JSON.stringify(body);
+}
+export function parseHostLine(line) {
+    const j = JSON.parse(line);
+    if (j && j.v === 2 && typeof j.type === 'string')
+        return { v2: j };
+    if (j && j.ready === true)
+        return { v1Ready: true };
+    return { v1: decodeHostResponse(line) };
 }
 export function decodeHostResponse(line) {
     const j = JSON.parse(line);
@@ -44,6 +59,7 @@ export class PowerShellHost {
     closed = false;
     startLock = null;
     invokeLock = Promise.resolve();
+    protocol = 1;
     constructor(hostFile, envFn) {
         this.hostFile = hostFile;
         this.envFn = envFn;
@@ -52,8 +68,8 @@ export class PowerShellHost {
     async ready() {
         return this.ensureStarted();
     }
-    async invoke(script, env, timeoutMs, signal) {
-        const run = this.invokeLock.then(() => this.invokeSerial(script, env, timeoutMs, signal));
+    async invoke(script, env, timeoutMs, signal, limits) {
+        const run = this.invokeLock.then(() => this.invokeSerial(script, env, timeoutMs, signal, limits));
         this.invokeLock = run.then(() => undefined, () => undefined);
         return run;
     }
@@ -101,7 +117,7 @@ export class PowerShellHost {
             truncated: false,
         };
     }
-    async invokeSerial(script, env, timeoutMs, signal) {
+    async invokeSerial(script, env, timeoutMs, signal, limits) {
         if (signal?.aborted) {
             await this.stop();
             return this.cancelledResult();
@@ -110,7 +126,9 @@ export class PowerShellHost {
         if (started)
             return { ...started, cancelled: false, truncated: false };
         const id = 'f' + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
-        const line = encodeHostRequest(id, script, env);
+        const line = encodeHostRequest(id, script, env, this.protocol === 2
+            ? { v: 2, stdoutLimit: limits?.stdoutLimit, stderrLimit: limits?.stderrLimit }
+            : undefined);
         try {
             this.proc.stdin.write(line + '\n');
         }
@@ -133,6 +151,9 @@ export class PowerShellHost {
         };
         signal?.addEventListener('abort', onAbort, { once: true });
         try {
+            if (this.protocol === 2) {
+                return await this.collectV2(id, timeoutMs);
+            }
             const raw = await this.nextJsonLine(timeoutMs, id);
             const msg = decodeHostResponse(raw);
             const native = this.drainNativeStderr();
@@ -271,10 +292,13 @@ export class PowerShellHost {
         });
         try {
             const readyLine = await this.nextReadyLine(READY_TIMEOUT_MS);
-            const msg = decodeHostResponse(readyLine);
-            if (!msg.ready) {
+            const parsed = parseHostLine(readyLine);
+            if (parsed.v2?.type === 'ready')
+                this.protocol = 2;
+            else if (parsed.v1Ready || decodeHostResponse(readyLine).ready)
+                this.protocol = 1;
+            else
                 throw new Error('fauxnix: powershell host handshake failed');
-            }
         }
         catch (e) {
             await this.stop();
@@ -334,8 +358,10 @@ export class PowerShellHost {
             if (!line.trim())
                 continue;
             try {
-                const msg = decodeHostResponse(line);
-                if (msg.ready)
+                const parsed = parseHostLine(line);
+                if (parsed.v2?.type === 'ready' || parsed.v1Ready)
+                    return line;
+                if (parsed.v1?.ready)
                     return line;
             }
             catch {
@@ -367,6 +393,77 @@ export class PowerShellHost {
         err.timedOut = true;
         throw err;
     }
+    async collectV2(id, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        const out = [];
+        const err = [];
+        let outSeq = 0;
+        let errSeq = 0;
+        let end = null;
+        while (!end) {
+            const line = await this.nextLine(Math.max(1, deadline - Date.now()));
+            if (!line.trim())
+                continue;
+            let parsed;
+            try {
+                parsed = parseHostLine(line);
+            }
+            catch {
+                continue;
+            }
+            const f = parsed.v2;
+            if (!f)
+                continue;
+            if (f.type === 'stdout' && f.id === id) {
+                if (f.seq !== outSeq)
+                    throw new Error('fauxnix: host stdout seq gap');
+                out.push(Buffer.from(f.dataB64 ?? '', 'base64'));
+                outSeq++;
+            }
+            else if (f.type === 'stderr' && f.id === id) {
+                if (f.seq !== errSeq)
+                    throw new Error('fauxnix: host stderr seq gap');
+                err.push(Buffer.from(f.dataB64 ?? '', 'base64'));
+                errSeq++;
+            }
+            else if (f.type === 'end' && f.id === id) {
+                end = f;
+            }
+        }
+        let native = Buffer.alloc(0);
+        try {
+            native = Buffer.from(await this.waitNativeMarker(id, 2000));
+        }
+        catch {
+            native = Buffer.from(this.drainNativeStderr());
+        }
+        const capturedErr = Buffer.from(Buffer.concat(err));
+        const n = Number(end.exitCode);
+        return {
+            stdout: Buffer.from(Buffer.concat(out)),
+            stderr: native.length ? Buffer.from(Buffer.concat([capturedErr, native])) : capturedErr,
+            exitCode: Number.isFinite(n) ? n : 0,
+            timedOut: end.timedOut === true,
+            cancelled: end.cancelled === true,
+            truncated: end.truncated === true,
+        };
+    }
+    async waitNativeMarker(id, timeoutMs) {
+        const needle = Buffer.from('FAUXNIX_ERR_END:' + id + '\n', 'utf8');
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const buf = Buffer.concat(this.stderrChunks);
+            const idx = buf.indexOf(needle);
+            if (idx >= 0) {
+                const before = buf.subarray(0, idx);
+                const after = buf.subarray(idx + needle.length);
+                this.stderrChunks = after.length ? [Buffer.from(after)] : [];
+                return Buffer.from(before);
+            }
+            await new Promise((r) => setTimeout(r, 15));
+        }
+        throw new Error('fauxnix: native stderr marker missing');
+    }
     failWaiters(err) {
         const ws = this.waiters.splice(0);
         for (const w of ws) {

package/dist/registry.d.ts

@@ -97,6 +97,8 @@ export interface CommandSpec {
     effects: CommandEffect[];
     platform?: 'windows-ps51' | 'portable-translate';
     dispatch?: 'translated' | 'native' | 'dynamic';
+    /** GNU usage/syntax exit (grep uses 2; cp/mv/rm use 1). */
+    usageExit?: number;
     handler: Handler;
 }
 /** Register a spec'd command. Unknown/unsupported options become GNU-style usage errors. */
@@ -105,6 +107,8 @@ export declare function registerSpecs(list: CommandSpec[]): void;
 export declare function lookupSpec(name: string): CommandSpec | undefined;
 /** Unique specs in registration order. */
 export declare function registeredSpecs(): CommandSpec[];
+/** Markdown dump of every CommandSpec — source for docs/command-specs.md. */
+export declare function specsMarkdown(): string;
 export interface ListedCommand {
     name: string;
     spec: null | {

package/dist/registry.js

@@ -186,6 +186,43 @@ export function registeredSpecs() {
     }
     return out;
 }
+/** Markdown dump of every CommandSpec — source for docs/command-specs.md. */
+export function specsMarkdown() {
+    const lines = [
+        '# Command specs',
+        '',
+        'Generated from `CommandSpec`. Unlisted commands still use unchecked `parseWords` (unknown flags ignored). Spec\'d commands fail loud on unknown or unsupported options.',
+        '',
+    ];
+    for (const spec of registeredSpecs()) {
+        lines.push('## `' + spec.names.join('` / `') + '`');
+        lines.push('');
+        lines.push('Effects: ' + spec.effects.map((e) => '`' + e + '`').join(', '));
+        lines.push('');
+        if (!spec.options.length) {
+            lines.push('No options declared.');
+        }
+        else {
+            lines.push('| Option | Value | Support |');
+            lines.push('| --- | --- | --- |');
+            for (const o of spec.options) {
+                const names = [o.short ? '`-' + o.short + '`' : '', o.long ? '`' + o.long + '`' : '']
+                    .filter((s) => s !== '')
+                    .join(', ');
+                const val = o.takesValue ? 'required' : 'flag';
+                const extra = o.reason ? ' (' + o.reason + ')' : '';
+                lines.push('| ' + names + ' | ' + val + ' | ' + o.support + extra + ' |');
+            }
+        }
+        lines.push('');
+    }
+    const unspec = registeredNames().filter((n) => !lookupSpec(n));
+    lines.push('## Unspec\'d commands');
+    lines.push('');
+    lines.push(unspec.map((n) => '`' + n + '`').join(', '));
+    lines.push('');
+    return lines.join('\n');
+}
 /** Capability dump for `fauxnix list --json` / MCP introspection. */
 export function listCommandsJson() {
     return registeredNames().map((name) => {
@@ -214,6 +251,8 @@ export function listCommandsJson() {
  * null when every option is recognized and implemented.
  */
 export function specOptionError(spec, args, cmdName) {
+    const usageExit = spec.usageExit ?? 1;
+    const fail = (msg) => optionFail(cmdName, msg, usageExit);
     const shorts = new Map();
     const longs = new Map();
     for (const o of spec.options) {
@@ -240,18 +279,18 @@ export function specOptionError(spec, args, cmdName) {
             const name = eq >= 0 ? t.slice(0, eq) : t;
             const opt = longs.get(name);
             if (!opt)
-                return optionFail(cmdName, "unrecognized option '" + name + "'");
+                return fail("unrecognized option '" + name + "'");
             if (opt.support === 'unsupported') {
-                return optionFail(cmdName, unsupportedMsg(opt, name));
+                return fail(unsupportedMsg(opt, name));
             }
             if (!opt.takesValue && eq >= 0) {
-                return optionFail(cmdName, "option '" + name + "' doesn't allow an argument");
+                return fail("option '" + name + "' doesn't allow an argument");
             }
             if (opt.takesValue && eq < 0) {
                 if (i + 1 < args.length)
                     i++;
                 else
-                    return optionFail(cmdName, "option '" + name + "' requires an argument");
+                    return fail("option '" + name + "' requires an argument");
             }
             i++;
             continue;
@@ -262,9 +301,9 @@ export function specOptionError(spec, args, cmdName) {
                 const ch = body[c];
                 const opt = shorts.get(ch);
                 if (!opt)
-                    return optionFail(cmdName, "invalid option -- '" + ch + "'");
+                    return fail("invalid option -- '" + ch + "'");
                 if (opt.support === 'unsupported') {
-                    return optionFail(cmdName, unsupportedMsg(opt, '-' + ch));
+                    return fail(unsupportedMsg(opt, '-' + ch));
                 }
                 if (opt.takesValue) {
                     const rest = body.slice(c + 1);
@@ -272,7 +311,7 @@ export function specOptionError(spec, args, cmdName) {
                         if (i + 1 < args.length)
                             i++;
                         else
-                            return optionFail(cmdName, "option requires an argument -- '" + ch + "'");
+                            return fail("option requires an argument -- '" + ch + "'");
                     }
                     break;
                 }
@@ -288,10 +327,11 @@ function unsupportedMsg(opt, shown) {
     const reason = opt.reason ? ' (' + opt.reason + ')' : '';
     return "option '" + shown + "' is not supported by fauxnix" + reason;
 }
-function optionFail(cmd, msg) {
+function optionFail(cmd, msg, code = 1) {
     return ('[Console]::Error.WriteLine(' +
         psStr(cmd + ': ' + msg) +
         '); [Console]::Error.WriteLine(' +
         psStr("Try '" + cmd + " --help' for more information.") +
-        '); $script:fx_exit = 1');
+        '); $script:fx_exit = ' +
+        String(code));
 }

package/dist/translator.js

@@ -1209,12 +1209,36 @@ $fx_reader = New-Object System.IO.StreamReader($fx_in, $fx_utf8, $true, 8192, $t
 $fx_proto = New-Object System.IO.StreamWriter($fx_out, $fx_utf8, 8192, $true)
 $fx_proto.NewLine = [string][char]10
 $fx_proto.AutoFlush = $true
-$fx_proto.WriteLine('{"ready":true}')
+$fx_proto.WriteLine('{"v":2,"type":"ready","capabilities":{"cancel":false,"maxChunkBytes":65536,"stderrMarker":true}}')
+function fx-b64([byte[]]$bytes, $off, $len) {
+  if ($len -le 0) { return '' }
+  $slice = New-Object byte[] $len
+  [Array]::Copy($bytes, $off, $slice, 0, $len)
+  return [Convert]::ToBase64String($slice)
+}
+function fx-emit-chunks($type, $id, [byte[]]$bytes, $limit, [ref]$seq) {
+  $n = 0
+  if ($null -ne $bytes) { $n = $bytes.Length }
+  $use = $n
+  $trunc = $false
+  if ($use -gt $limit) { $use = $limit; $trunc = $true }
+  $off = 0
+  while ($off -lt $use) {
+    $len = $use - $off
+    if ($len -gt 65536) { $len = 65536 }
+    $b64 = fx-b64 $bytes $off $len
+    $fx_proto.WriteLine('{"v":2,"type":"' + $type + '","id":"' + $id + '","seq":' + $seq.Value + ',"dataB64":"' + $b64 + '"}')
+    $seq.Value = $seq.Value + 1
+    $off += $len
+  }
+  return $trunc
+}
 while ($true) {
   $fx_line = $fx_reader.ReadLine()
   if ($null -eq $fx_line) { break }
   if ($fx_line -eq '') { continue }
   $fx_id = ''
+  $fx_req = $null
   $fx_msOut = $null
   $fx_msErr = $null
   $fx_outW = $null
@@ -1261,20 +1285,47 @@ while ($true) {
     try { [Console]::SetOut($fx_oldOut) } catch {}
     try { [Console]::SetError($fx_oldErr) } catch {}
   }
-  $fx_outB64 = ''
-  $fx_errB64 = ''
-  if ($null -ne $fx_msOut) { $fx_outB64 = [Convert]::ToBase64String($fx_msOut.ToArray()) }
-  if ($null -ne $fx_msErr) { $fx_errB64 = [Convert]::ToBase64String($fx_msErr.ToArray()) }
   $fx_code = 0
   try { $fx_code = [int]$script:fx_exit } catch { $fx_code = 1 }
-  $fx_res = @{ id = $fx_id; stdoutB64 = $fx_outB64; stderrB64 = $fx_errB64; exitCode = $fx_code }
-  try {
-    $fx_json = $fx_res | ConvertTo-Json -Compress
-  } catch {
-    $fx_msg = 'fauxnix: host result exceeded ConvertTo-Json MaxJsonLength (~2MB)'
-    $fx_res = @{ id = $fx_id; stdoutB64 = ''; stderrB64 = [Convert]::ToBase64String($fx_utf8.GetBytes($fx_msg)); exitCode = 1 }
-    $fx_json = $fx_res | ConvertTo-Json -Compress
+  $fx_v2 = $false
+  if ($null -ne $fx_req -and $null -ne $fx_req.PSObject.Properties['v']) {
+    if ([int]$fx_req.v -eq 2) { $fx_v2 = $true }
+  }
+  $fx_outBytes = New-Object byte[] 0
+  $fx_errBytes = New-Object byte[] 0
+  if ($null -ne $fx_msOut) { $fx_outBytes = $fx_msOut.ToArray() }
+  if ($null -ne $fx_msErr) { $fx_errBytes = $fx_msErr.ToArray() }
+  if ($fx_v2) {
+    $fx_outLimit = 8388608
+    $fx_errLimit = 1048576
+    if ($null -ne $fx_req.PSObject.Properties['stdoutLimit']) { $fx_outLimit = [int]$fx_req.stdoutLimit }
+    if ($null -ne $fx_req.PSObject.Properties['stderrLimit']) { $fx_errLimit = [int]$fx_req.stderrLimit }
+    $fx_outSeq = 0
+    $fx_errSeq = 0
+    $fx_trunc = $false
+    if (fx-emit-chunks 'stdout' $fx_id $fx_outBytes $fx_outLimit ([ref]$fx_outSeq)) { $fx_trunc = $true }
+    if (fx-emit-chunks 'stderr' $fx_id $fx_errBytes $fx_errLimit ([ref]$fx_errSeq)) { $fx_trunc = $true }
+    $fx_nativeErr = [Console]::OpenStandardError()
+    $fx_mark = $fx_utf8.GetBytes(('FAUXNIX_ERR_END:' + $fx_id + [char]10))
+    $fx_nativeErr.Write($fx_mark, 0, $fx_mark.Length)
+    $fx_nativeErr.Flush()
+    $fx_end = '{"v":2,"type":"end","id":"' + $fx_id + '","exitCode":' + $fx_code + ',"timedOut":false,"cancelled":false,"truncated":'
+    if ($fx_trunc) { $fx_end = $fx_end + 'true}' } else { $fx_end = $fx_end + 'false}' }
+    $fx_proto.WriteLine($fx_end)
+  } else {
+    $fx_outB64 = ''
+    $fx_errB64 = ''
+    if ($fx_outBytes.Length -gt 0) { $fx_outB64 = [Convert]::ToBase64String($fx_outBytes) }
+    if ($fx_errBytes.Length -gt 0) { $fx_errB64 = [Convert]::ToBase64String($fx_errBytes) }
+    $fx_res = @{ id = $fx_id; stdoutB64 = $fx_outB64; stderrB64 = $fx_errB64; exitCode = $fx_code }
+    try {
+      $fx_json = $fx_res | ConvertTo-Json -Compress
+    } catch {
+      $fx_msg = 'fauxnix: host result exceeded ConvertTo-Json MaxJsonLength (~2MB)'
+      $fx_res = @{ id = $fx_id; stdoutB64 = ''; stderrB64 = [Convert]::ToBase64String($fx_utf8.GetBytes($fx_msg)); exitCode = 1 }
+      $fx_json = $fx_res | ConvertTo-Json -Compress
+    }
+    $fx_proto.WriteLine($fx_json)
   }
-  $fx_proto.WriteLine($fx_json)
 }
 `.trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fauxnix-cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Fauxnix — run Linux-style commands on Windows via deterministic PowerShell translation. No VM, no WSL. MCP server + CLI for AI agents.",
   "type": "module",
   "bin": {