fauxnix-cli 0.7.1 → 0.8.0

package/dist/registry.d.ts

@@ -77,3 +77,53 @@ 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';
+    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[];
+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,145 @@ 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;
+}
+/** 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 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 optionFail(cmdName, "unrecognized option '" + name + "'");
+            if (opt.support === 'unsupported') {
+                return optionFail(cmdName, unsupportedMsg(opt, name));
+            }
+            if (!opt.takesValue && eq >= 0) {
+                return optionFail(cmdName, "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");
+            }
+            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 optionFail(cmdName, "invalid option -- '" + ch + "'");
+                if (opt.support === 'unsupported') {
+                    return optionFail(cmdName, unsupportedMsg(opt, '-' + ch));
+                }
+                if (opt.takesValue) {
+                    const rest = body.slice(c + 1);
+                    if (!rest) {
+                        if (i + 1 < args.length)
+                            i++;
+                        else
+                            return optionFail(cmdName, "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) {
+    return ('[Console]::Error.WriteLine(' +
+        psStr(cmd + ': ' + msg) +
+        '); [Console]::Error.WriteLine(' +
+        psStr("Try '" + cmd + " --help' for more information.") +
+        '); $script:fx_exit = 1');
+}

package/dist/translator.js

@@ -1268,6 +1268,13 @@ while ($true) {
   $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))
+  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.8.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": {