fauxnix-cli 0.7.1 → 0.9.0

package/dist/registry.d.ts

@@ -77,3 +77,57 @@ export interface WordArgs {
  * shortValues: single-char options that consume a value (e.g. ['n']).
  */
 export declare function parseWords(args: Word[], shortValues?: string[], longValues?: string[]): WordArgs;
+export type CommandEffect = 'read' | 'write' | 'delete' | 'network' | 'process';
+export type OptionSupport = 'implemented' | 'unsupported';
+/** One short/long alias group. Unknown options on a spec'd command fail loud. */
+export interface OptionSpec {
+    /** Short flag letter without dash (e.g. `'n'`). */
+    short?: string;
+    /** Long option including dashes (e.g. `'--no-clobber'`). */
+    long?: string;
+    /** Consumes a following argument (`-n 5`, `--lines=5`). */
+    takesValue?: boolean;
+    support: OptionSupport;
+    /** Extra phrase for unsupported options (`interactive prompt`). */
+    reason?: string;
+}
+export interface CommandSpec {
+    names: string[];
+    options: OptionSpec[];
+    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. */
+export declare function registerSpec(spec: CommandSpec): void;
+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 | {
+        options: Array<{
+            short?: string;
+            long?: string;
+            takesValue: boolean;
+            support: OptionSupport;
+            reason?: string;
+        }>;
+        effects: CommandEffect[];
+        platform: 'windows-ps51' | 'portable-translate';
+        dispatch: 'translated' | 'native' | 'dynamic';
+    };
+}
+/** Capability dump for `fauxnix list --json` / MCP introspection. */
+export declare function listCommandsJson(): ListedCommand[];
+/**
+ * Walk argv against a CommandSpec. Returns a PowerShell error script, or
+ * null when every option is recognized and implemented.
+ */
+export declare function specOptionError(spec: CommandSpec, args: Word[], cmdName: string): string | null;

package/dist/registry.js

@@ -153,3 +153,185 @@ export function parseWords(args, shortValues = [], longValues = []) {
     }
     return { flags, longs, values, missingValue, operandWords };
 }
+const specs = new Map();
+/** Register a spec'd command. Unknown/unsupported options become GNU-style usage errors. */
+export function registerSpec(spec) {
+    for (const name of spec.names) {
+        const wrapped = (args, ctx) => {
+            const err = specOptionError(spec, args, name);
+            if (err)
+                return err;
+            return spec.handler(args, ctx);
+        };
+        registry.set(name, wrapped);
+        specs.set(name, spec);
+    }
+}
+export function registerSpecs(list) {
+    for (const spec of list)
+        registerSpec(spec);
+}
+export function lookupSpec(name) {
+    return specs.get(name);
+}
+/** Unique specs in registration order. */
+export function registeredSpecs() {
+    const seen = new Set();
+    const out = [];
+    for (const spec of specs.values()) {
+        if (seen.has(spec))
+            continue;
+        seen.add(spec);
+        out.push(spec);
+    }
+    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) => {
+        const spec = lookupSpec(name);
+        if (!spec)
+            return { name, spec: null };
+        return {
+            name,
+            spec: {
+                options: spec.options.map((o) => ({
+                    ...(o.short ? { short: o.short } : {}),
+                    ...(o.long ? { long: o.long } : {}),
+                    takesValue: o.takesValue === true,
+                    support: o.support,
+                    ...(o.reason ? { reason: o.reason } : {}),
+                })),
+                effects: spec.effects,
+                platform: spec.platform ?? 'windows-ps51',
+                dispatch: spec.dispatch ?? 'translated',
+            },
+        };
+    });
+}
+/**
+ * Walk argv against a CommandSpec. Returns a PowerShell error script, or
+ * 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) {
+        if (o.short)
+            shorts.set(o.short, o);
+        if (o.long)
+            longs.set(o.long, o);
+    }
+    let i = 0;
+    let onlyOperands = false;
+    while (i < args.length) {
+        const t = wordToString(args[i]);
+        if (onlyOperands) {
+            i++;
+            continue;
+        }
+        if (t === '--') {
+            onlyOperands = true;
+            i++;
+            continue;
+        }
+        if (t.startsWith('--')) {
+            const eq = t.indexOf('=');
+            const name = eq >= 0 ? t.slice(0, eq) : t;
+            const opt = longs.get(name);
+            if (!opt)
+                return fail("unrecognized option '" + name + "'");
+            if (opt.support === 'unsupported') {
+                return fail(unsupportedMsg(opt, name));
+            }
+            if (!opt.takesValue && eq >= 0) {
+                return fail("option '" + name + "' doesn't allow an argument");
+            }
+            if (opt.takesValue && eq < 0) {
+                if (i + 1 < args.length)
+                    i++;
+                else
+                    return fail("option '" + name + "' requires an argument");
+            }
+            i++;
+            continue;
+        }
+        if (t.startsWith('-') && t.length > 1 && !/^-?\d/.test(t.slice(1, 2))) {
+            const body = t.slice(1);
+            for (let c = 0; c < body.length; c++) {
+                const ch = body[c];
+                const opt = shorts.get(ch);
+                if (!opt)
+                    return fail("invalid option -- '" + ch + "'");
+                if (opt.support === 'unsupported') {
+                    return fail(unsupportedMsg(opt, '-' + ch));
+                }
+                if (opt.takesValue) {
+                    const rest = body.slice(c + 1);
+                    if (!rest) {
+                        if (i + 1 < args.length)
+                            i++;
+                        else
+                            return fail("option requires an argument -- '" + ch + "'");
+                    }
+                    break;
+                }
+            }
+            i++;
+            continue;
+        }
+        i++;
+    }
+    return null;
+}
+function unsupportedMsg(opt, shown) {
+    const reason = opt.reason ? ' (' + opt.reason + ')' : '';
+    return "option '" + shown + "' is not supported by fauxnix" + reason;
+}
+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 = ' +
+        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,13 +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 }
-  $fx_proto.WriteLine(($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)
+  }
 }
 `.trim();

package/package.json

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