fauxnix-cli 0.1.0

package/dist/parser.js

@@ -0,0 +1,400 @@
+import { FauxnixParseError, } from './ast.js';
+const OPERATORS = [
+    '&&', '||', '>>', '<<', '2>&1', '1>&2', '2>', '&>>', '&>', '>', '<', '|', ';',
+];
+export function tokenize(input) {
+    const tokens = [];
+    let i = 0;
+    const n = input.length;
+    const pushWord = (parts) => {
+        if (parts.length > 0)
+            tokens.push({ type: 'WORD', parts });
+    };
+    let cur = [];
+    let fdDigits = '';
+    const flush = () => {
+        pushWord(cur);
+        cur = [];
+        fdDigits = '';
+    };
+    while (i < n) {
+        const ch = input[i];
+        // whitespace separates words; newline acts as ';'
+        if (ch === ' ' || ch === '\t' || ch === '\r') {
+            flush();
+            i++;
+            continue;
+        }
+        if (ch === '\n') {
+            flush();
+            tokens.push({ type: 'OP', op: ';' });
+            i++;
+            continue;
+        }
+        // comments
+        if (ch === '#' && cur.length === 0) {
+            while (i < n && input[i] !== '\n')
+                i++;
+            continue;
+        }
+        // line continuation
+        if (ch === '\\' && i + 1 < n && input[i + 1] === '\n') {
+            i += 2;
+            continue;
+        }
+        // try operators (longest first — list above is ordered)
+        let matched;
+        for (const op of OPERATORS) {
+            if (input.startsWith(op, i)) {
+                matched = op;
+                break;
+            }
+        }
+        if (matched) {
+            // bash folds a leading fd digit into the redirect: `2>`, `2>>`, `2>&1`
+            const isRedirectish = matched[0] === '>' || matched[0] === '<' || matched === '&>' || matched === '&>>';
+            const curIsFd = fdDigits.length > 0 &&
+                cur.length === fdDigits.length &&
+                cur.every((p, idx) => p.kind === 'Text' && p.text === fdDigits[idx]);
+            let advance = matched.length;
+            if (isRedirectish && matched !== '<<' && curIsFd) {
+                cur = []; // drop the digits from the pending word
+                if (matched === '>>')
+                    matched = fdDigits + '>>';
+                else if (matched === '>') {
+                    if (input.startsWith('&1', i + 1))
+                        matched = fdDigits + '>&1';
+                    else if (input.startsWith('&2', i + 1))
+                        matched = fdDigits + '>&2';
+                    else
+                        matched = fdDigits + '>';
+                }
+                // the fd digits were consumed earlier; advance past the operator tail only
+                advance = matched.length - fdDigits.length;
+                fdDigits = '';
+            }
+            if (matched === '<<') {
+                throw new FauxnixParseError('fauxnix: heredocs (<<) are not supported yet. Pass the text via echo pipe or a temp file instead.');
+            }
+            flush();
+            tokens.push({ type: 'OP', op: matched });
+            i += advance;
+            continue;
+        }
+        // single quotes — fully literal
+        if (ch === "'") {
+            const end = input.indexOf("'", i + 1);
+            if (end === -1)
+                throw new FauxnixParseError('fauxnix: unclosed single quote');
+            cur.push({ kind: 'SingleQuoted', text: input.slice(i + 1, end) });
+            i = end + 1;
+            continue;
+        }
+        // double quotes — interpolated
+        if (ch === '"') {
+            i++;
+            const parts = [];
+            let buf = '';
+            while (i < n && input[i] !== '"') {
+                const c = input[i];
+                if (c === '\\' && i + 1 < n && '"$`\\'.includes(input[i + 1])) {
+                    buf += input[i + 1];
+                    i += 2;
+                    continue;
+                }
+                if (c === '$') {
+                    const v = readDollar(input, i);
+                    if (v) {
+                        if (buf) {
+                            parts.push({ kind: 'Text', text: buf });
+                            buf = '';
+                        }
+                        parts.push(v.part);
+                        i = v.next;
+                        continue;
+                    }
+                }
+                buf += c;
+                i++;
+            }
+            if (i >= n)
+                throw new FauxnixParseError('fauxnix: unclosed double quote');
+            i++;
+            if (buf)
+                parts.push({ kind: 'Text', text: buf });
+            cur.push({ kind: 'DoubleQuoted', parts });
+            continue;
+        }
+        // dollar — variable or command substitution
+        if (ch === '$') {
+            const v = readDollar(input, i);
+            if (v) {
+                cur.push(v.part);
+                i = v.next;
+                continue;
+            }
+            cur.push({ kind: 'Text', text: '$' });
+            i++;
+            continue;
+        }
+        if (ch === '`') {
+            throw new FauxnixParseError('fauxnix: backticks are not supported. Use $(...) command substitution instead.');
+        }
+        // escape outside quotes
+        if (ch === '\\' && i + 1 < n) {
+            cur.push({ kind: 'Text', text: input[i + 1] });
+            i += 2;
+            continue;
+        }
+        // track leading digits (potential fd number for redirects)
+        if (/[0-9]/.test(ch) && cur.length === 0 && fdDigits.length < 2) {
+            fdDigits += ch;
+            cur.push({ kind: 'Text', text: ch });
+            i++;
+            continue;
+        }
+        fdDigits = '';
+        cur.push({ kind: 'Text', text: ch });
+        i++;
+    }
+    flush();
+    tokens.push({ type: 'EOF' });
+    return tokens;
+}
+function isNameStart(c) {
+    return /[A-Za-z_]/.test(c);
+}
+function isNameChar(c) {
+    return /[A-Za-z0-9_]/.test(c);
+}
+/** Parse $VAR, ${VAR}, $(cmd substitution). Returns null when not a valid dollar construct. */
+function readDollar(input, i) {
+    const n = input.length;
+    if (input[i] !== '$')
+        return null;
+    let j = i + 1;
+    if (j >= n)
+        return null;
+    // ${...}
+    if (input[j] === '{') {
+        const end = input.indexOf('}', j);
+        if (end === -1)
+            throw new FauxnixParseError('fauxnix: unclosed ${');
+        const name = input.slice(j + 1, end);
+        if (!isNameStart(name[0]) || !name.split('').every(isNameChar)) {
+            // ${VAR:-default} etc. — unsupported, kept as raw text
+            return { part: { kind: 'Text', text: input.slice(i, end + 1) }, next: end + 1 };
+        }
+        return { part: { kind: 'Var', name }, next: end + 1 };
+    }
+    // $(cmd substitution) — captured with balanced parens; the translator
+    // recursively translates this text before embedding it.
+    if (input[j] === '(') {
+        let depth = 1;
+        let k = j + 1;
+        while (k < n && depth > 0) {
+            if (input[k] === '(')
+                depth++;
+            else if (input[k] === ')')
+                depth--;
+            else if (input[k] === "'" || input[k] === '"') {
+                const q = input[k];
+                k++;
+                while (k < n && input[k] !== q) {
+                    if (input[k] === '\\')
+                        k++;
+                    k++;
+                }
+            }
+            k++;
+        }
+        if (depth !== 0)
+            throw new FauxnixParseError('fauxnix: unclosed $( )');
+        const cmdText = input.slice(j + 1, k - 1);
+        return { part: { kind: 'CmdSub', cmd: cmdText }, next: k };
+    }
+    // $NAME
+    if (isNameStart(input[j])) {
+        let len = 1;
+        while (j + len < n && isNameChar(input[j + len]))
+            len++;
+        return { part: { kind: 'Var', name: input.slice(j, j + len) }, next: j + len };
+    }
+    // special: $? $$ $0-$9 — kept as symbolic Var; the translator maps them
+    if ('?$_'.includes(input[j]) || /[0-9]/.test(input[j])) {
+        return { part: { kind: 'Var', name: input[j] }, next: j + 1 };
+    }
+    return null;
+}
+/* ------------------------------------------------------------------ */
+/* Parser                                                              */
+/* ------------------------------------------------------------------ */
+export function parseCommand(input) {
+    const tokens = tokenize(input);
+    let pos = 0;
+    const peek = () => tokens[pos];
+    const next = () => tokens[pos++];
+    const parseList = () => {
+        const segments = [];
+        let op = ';';
+        while (peek().type === 'OP' && peek().op === ';')
+            next();
+        while (peek().type !== 'EOF') {
+            const pipeline = parsePipeline();
+            segments.push({ pipeline, op });
+            const t = peek();
+            if (t.type === 'OP' && (t.op === '&&' || t.op === '||' || t.op === ';')) {
+                op = t.op;
+                next();
+                while (peek().type === 'OP' && peek().op === ';')
+                    next(); // trailing / duplicate ;
+            }
+            else if (t.type === 'EOF') {
+                break;
+            }
+            else {
+                throw new FauxnixParseError('fauxnix: unexpected token after pipeline');
+            }
+        }
+        if (segments.length === 0)
+            throw new FauxnixParseError('fauxnix: empty command');
+        return { kind: 'CommandList', segments };
+    };
+    const parsePipeline = () => {
+        const commands = [];
+        for (;;) {
+            commands.push(parseSimple());
+            const t = peek();
+            if (t.type === 'OP' && t.op === '|') {
+                next();
+                continue;
+            }
+            break;
+        }
+        return { kind: 'Pipeline', commands };
+    };
+    const parseSimple = () => {
+        const assignments = [];
+        let redirects = [];
+        let name = null;
+        const args = [];
+        for (;;) {
+            const t = peek();
+            if (t.type === 'EOF')
+                break;
+            // possible redirect operator
+            if (t.type === 'OP' && isRedirectOp(t.op)) {
+                const op = t.op;
+                next();
+                // fd-dup operators (2>&1, 1>&2) carry their own target
+                const target = op === '2>&1' || op === '1>&2' ? '' : readRedirectTarget();
+                redirects.push({ op: normalizeRedirect(op), target });
+                continue;
+            }
+            if (t.type === 'OP')
+                break;
+            const word = t.parts;
+            // assignment prefix before command name?
+            if (name === null && isAssignment(word)) {
+                next();
+                const split = splitAssignment(word);
+                if (split) {
+                    assignments.push(split);
+                    continue;
+                }
+            }
+            if (name === null) {
+                name = word;
+                next();
+            }
+            else {
+                args.push(word);
+                next();
+            }
+        }
+        if (!name)
+            throw new FauxnixParseError('fauxnix: expected a command');
+        return { kind: 'SimpleCommand', assignments, name, args, redirects };
+    };
+    const readRedirectTarget = () => {
+        const t = next();
+        if (t.type !== 'WORD')
+            throw new FauxnixParseError('fauxnix: redirect target expected');
+        return wordToStringSafe(t.parts);
+    };
+    // ---- helpers on words (joined raw view) ----
+    function wordToStringSafe(w) {
+        return w
+            .map((p) => {
+            switch (p.kind) {
+                case 'Text':
+                case 'SingleQuoted':
+                    return p.text;
+                case 'DoubleQuoted':
+                    return p.parts
+                        .map((q) => (q.kind === 'Text' || q.kind === 'SingleQuoted' ? q.text : ''))
+                        .join('');
+                default:
+                    return '';
+            }
+        })
+            .join('');
+    }
+    function isAssignment(w) {
+        return splitAssignment(w) !== null;
+    }
+    /**
+     * Split `NAME=value` at the first unquoted '=' — char-level, so single-part
+     * words like [Text 'FOO=bar'] split correctly. Returns null when the word
+     * is not a valid assignment.
+     */
+    function splitAssignment(w) {
+        // merge adjacent Text parts first — the tokenizer emits per-char parts
+        const merged = [];
+        for (const p of w) {
+            const last = merged[merged.length - 1];
+            if (p.kind === 'Text' && last && last.kind === 'Text') {
+                last.text += p.text;
+            }
+            else if (p.kind === 'SingleQuoted' && last && last.kind === 'SingleQuoted') {
+                last.text += p.text;
+            }
+            else {
+                merged.push({ ...p });
+            }
+        }
+        for (let idx = 0; idx < merged.length; idx++) {
+            const p = merged[idx];
+            if (p.kind !== 'Text')
+                continue;
+            const eq = p.text.indexOf('=');
+            if (eq <= 0)
+                continue;
+            const name = merged
+                .slice(0, idx)
+                .map((q) => (q.kind === 'Text' || q.kind === 'SingleQuoted' ? q.text : ''))
+                .join('') + p.text.slice(0, eq);
+            if (!isNameStart(name[0]) || !name.split('').every(isNameChar))
+                continue;
+            const value = [];
+            const tail = p.text.slice(eq + 1);
+            if (tail)
+                value.push({ kind: 'Text', text: tail });
+            value.push(...merged.slice(idx + 1));
+            return { name, value };
+        }
+        return null;
+    }
+    return parseList();
+}
+function isRedirectOp(op) {
+    if (!op)
+        return false;
+    return ['>', '>>', '2>', '2>>', '&>', '&>>', '2>&1', '1>&2', '<'].includes(op);
+}
+function normalizeRedirect(op) {
+    const known = ['>', '>>', '2>', '2>>', '&>', '&>>', '2>&1', '1>&2', '<'];
+    if (known.includes(op))
+        return op;
+    throw new FauxnixParseError('fauxnix: unsupported redirect: ' + op);
+}

package/dist/registry.d.ts

@@ -0,0 +1,79 @@
+import { Word } from './ast.js';
+/**
+ * Command registry — each Linux command maps to a PowerShell generator.
+ *
+ * Contract for generated code (the "Fauxnix contract"):
+ *
+ * 1. The generator returns a block of PowerShell *statements* (NO `& { }`
+ *    wrapper, NO `exit`). The translator either embeds the block in
+ *    `(& { ... })` (single command) or turns it into a generated function
+ *    body chained in a pipeline (multi-command pipelines).
+ * 2. Everything the block emits is a string line (Unix text-stream semantics).
+ *    Never emit raw .NET objects — stringify them ("$_", [string]$x).
+ * 3. Failure must NOT `exit` (that would kill sibling pipeline stages).
+ *    Instead write the bash-style message to stderr and set the shared flag:
+ *        [Console]::Error.WriteLine('cat: foo: No such file or directory')
+ *        $script:fx_exit = 1
+ *    NOTE the exact spelling: `.Error.WriteLine` with a DOT (a `::` chain
+ *    resolves as a static call and throws), and `$script:` (handlers run in
+ *    child scopes — plain `$fx_exit` writes stay local and are lost).
+ *    The executor wrapper reads $script:fx_exit after the pipeline completes.
+ * 4. Stdin = `$input` inside your block:  @($input | ForEach-Object { [string]$_ })
+ *    (empty when there is no upstream). Use ctx.hasStdin to decide whether
+ *    reading stdin is legal.
+ * 5. Output formatting mimics GNU coreutils so agents feel at home.
+ * 6. Target Windows PowerShell 5.1: no ternary, no ?? operator, no
+ *    chainable null-conditional. Plain if/else everywhere.
+ * 7. Blocks must be self-contained (local helper functions allowed) — they
+ *    also run inside $(...) command substitutions without the wrapper preamble.
+ */
+export interface PipelineCtx {
+    /** Position of this command inside the pipeline. */
+    position: 'first' | 'middle' | 'last';
+    /** True when stdin is available (piped input or `< file` redirect). */
+    hasStdin: boolean;
+}
+export type Handler = (args: Word[], ctx: PipelineCtx) => string;
+export declare function register(name: string, handler: Handler): void;
+export declare function registerAll(mod: Record<string, Handler>): void;
+export declare function lookup(name: string): Handler | undefined;
+export declare function registeredNames(): string[];
+/** Escape a JS string into a single-quoted PowerShell string literal. */
+export declare function psStr(s: string): string;
+/** bash-style stderr line + exit-flag, as PS statements. */
+export declare function psErr(cmd: string, msg: string): string;
+/** bash-style stderr line with exit code 2 (serious trouble, like ls). */
+export declare function psErr2(cmd: string, msg: string): string;
+/** Does this argument text contain glob characters? */
+export declare function hasGlob(s: string): boolean;
+/** Options parsing helper: returns { flags: Set<string>, operands: string[] } */
+export interface ParsedArgs {
+    flags: Set<string>;
+    /** long options like --all (kept with dashes) */
+    longs: Set<string>;
+    operands: string[];
+    /** option values consumed via -n 5 style */
+    values: Map<string, string>;
+}
+/**
+ * Parse a Unix-style argv. Supports:
+ *   -a -abc (bundled) --long (with =value or following value via valueOpts)
+ */
+export declare function parseArgs(args: {
+    toDisplay: string;
+}[], valueOpts?: Set<string>): ParsedArgs;
+export interface WordArgs {
+    flags: Set<string>;
+    longs: Set<string>;
+    values: Map<string, string>;
+    /** Options that take a value but were not followed by one. */
+    missingValue: string[];
+    operandWords: Word[];
+}
+/**
+ * Parse argv while keeping operand *Words* (so they can still be translated
+ * with exprOfWord / operandExpr). Supports:
+ *   -a -abc --long --long=v --long v  -n 5  -n5
+ * shortValues: single-char options that consume a value (e.g. ['n']).
+ */
+export declare function parseWords(args: Word[], shortValues?: string[], longValues?: string[]): WordArgs;

package/dist/registry.js

@@ -0,0 +1,145 @@
+import { wordToString } from './ast.js';
+const registry = new Map();
+export function register(name, handler) {
+    registry.set(name, handler);
+}
+export function registerAll(mod) {
+    for (const [name, handler] of Object.entries(mod))
+        register(name, handler);
+}
+export function lookup(name) {
+    return registry.get(name);
+}
+export function registeredNames() {
+    return [...registry.keys()].sort();
+}
+/* ------------------------------------------------------------------ */
+/* Shared helpers used by command generators                           */
+/* ------------------------------------------------------------------ */
+/** Escape a JS string into a single-quoted PowerShell string literal. */
+export function psStr(s) {
+    return "'" + s.replace(/'/g, "''") + "'";
+}
+/** bash-style stderr line + exit-flag, as PS statements. */
+export function psErr(cmd, msg) {
+    return '[Console]::Error.WriteLine(' + psStr(cmd + ': ' + msg) + '); $script:fx_exit = 1';
+}
+/** bash-style stderr line with exit code 2 (serious trouble, like ls). */
+export function psErr2(cmd, msg) {
+    return '[Console]::Error.WriteLine(' + psStr(cmd + ': ' + msg) + '); $script:fx_exit = 2';
+}
+/** Does this argument text contain glob characters? */
+export function hasGlob(s) {
+    return /[*?]/.test(s);
+}
+/**
+ * Parse a Unix-style argv. Supports:
+ *   -a -abc (bundled) --long (with =value or following value via valueOpts)
+ */
+export function parseArgs(args, valueOpts = new Set()) {
+    const flags = new Set();
+    const longs = new Set();
+    const operands = [];
+    const values = new Map();
+    let i = 0;
+    let onlyOperands = false;
+    while (i < args.length) {
+        const a = args[i].toDisplay;
+        if (!onlyOperands && a === '--') {
+            onlyOperands = true;
+        }
+        else if (!onlyOperands && a.startsWith('--')) {
+            const eq = a.indexOf('=');
+            if (eq >= 0) {
+                longs.add(a.slice(0, eq));
+                values.set(a.slice(0, eq), a.slice(eq + 1));
+            }
+            else if (valueOpts.has(a)) {
+                longs.add(a);
+                if (i + 1 < args.length) {
+                    values.set(a, args[i + 1].toDisplay);
+                    i++;
+                }
+            }
+            else {
+                longs.add(a);
+            }
+        }
+        else if (!onlyOperands && a.startsWith('-') && a.length > 1) {
+            for (const c of a.slice(1))
+                flags.add(c);
+        }
+        else {
+            operands.push(a);
+        }
+        i++;
+    }
+    return { flags, longs, operands, values };
+}
+/**
+ * Parse argv while keeping operand *Words* (so they can still be translated
+ * with exprOfWord / operandExpr). Supports:
+ *   -a -abc --long --long=v --long v  -n 5  -n5
+ * shortValues: single-char options that consume a value (e.g. ['n']).
+ */
+export function parseWords(args, shortValues = [], longValues = []) {
+    const flags = new Set();
+    const longs = new Set();
+    const values = new Map();
+    const missingValue = [];
+    const operandWords = [];
+    let i = 0;
+    let onlyOperands = false;
+    while (i < args.length) {
+        const t = wordToString(args[i]);
+        if (!onlyOperands && t === '--') {
+            onlyOperands = true;
+        }
+        else if (!onlyOperands && t.startsWith('--')) {
+            const eq = t.indexOf('=');
+            if (eq >= 0) {
+                longs.add(t.slice(0, eq));
+                values.set(t.slice(0, eq), t.slice(eq + 1));
+            }
+            else if (longValues.includes(t)) {
+                longs.add(t);
+                if (i + 1 < args.length) {
+                    values.set(t, wordToString(args[i + 1]));
+                    i++;
+                }
+                else
+                    missingValue.push(t);
+            }
+            else {
+                longs.add(t);
+            }
+        }
+        else if (!onlyOperands && t.startsWith('-') && t.length > 1 && !/^-?\d/.test(t.slice(1, 2))) {
+            // bundled short flags; a value-taking short opt consumes the rest (-n5)
+            const body = t.slice(1);
+            for (let c = 0; c < body.length; c++) {
+                const ch = body[c];
+                if (shortValues.includes(ch)) {
+                    // value-taking options report via `values`, not `flags`
+                    const rest = body.slice(c + 1);
+                    if (rest) {
+                        values.set('-' + ch, rest);
+                    }
+                    else if (i + 1 < args.length) {
+                        values.set('-' + ch, wordToString(args[i + 1]));
+                        i++;
+                    }
+                    else
+                        missingValue.push('-' + ch);
+                    break;
+                }
+                flags.add(ch);
+            }
+        }
+        else {
+            operandWords.push(args[i]);
+        }
+        i++;
+    }
+    return { flags, longs, values, missingValue, operandWords };
+}

package/dist/translator.d.ts

@@ -0,0 +1,55 @@
+import { CommandList, Redirect, SimpleCommand, Word } from './ast.js';
+import { PipelineCtx } from './registry.js';
+/** Map a bash $VAR name to a PowerShell expression (usable inside $(...)). */
+export declare function varExpr(name: string): string;
+/** Normalize a literal POSIX-ish path to its Windows equivalent. */
+export declare function normalizeLiteralPath(s: string): string;
+/**
+ * Convert a normalized literal path (see normalizeLiteralPath) into a valid
+ * PowerShell string *expression*. Paths that normalize to `$env:TEMP...`
+ * must NOT go through single-quoting — the variable has to stay expandable.
+ */
+export declare function pathExpr(s: string): string;
+/**
+ * Convert a Word to a PowerShell string expression.
+ * Literal words become single-quoted strings; dynamic ones become
+ * double-quoted strings with $(...) interpolation.
+ */
+export declare function exprOfWord(w: Word): string;
+/** Literal text of a word when it contains no interpolation, else null. */
+export declare function literalOfWord(w: Word): string | null;
+/**
+ * Argument expression for an operand (file path-ish).
+ * Literal paths get POSIX-ish normalization (/dev/null, /tmp, /d/...).
+ */
+export declare function operandExpr(w: Word): string;
+/** Translate the inside of $(...) — pipelines only, no wrappers. */
+export declare function translateCmdSub(cmdText: string): string;
+export declare function translateSimple(cmd: SimpleCommand, position: PipelineCtx['position'], hasStdin: boolean): string;
+export interface PipelineParts {
+    /** Generated function definitions (empty for single commands). */
+    defs: string;
+    /** The pipeline invocation itself. */
+    call: string;
+}
+/**
+ * Pipeline body. A lone command runs as a plain script-block expression;
+ * multi-command pipelines become generated functions chained with `|`
+ * (PS 5.1 forbids parenthesized expressions as non-first pipeline elements).
+ */
+export declare function translatePipelineBody(p: {
+    commands: SimpleCommand[];
+}): PipelineParts;
+export interface SegmentPlan {
+    op: ';' | '&&' | '||';
+    /** Complete PowerShell script for one powershell.exe invocation. */
+    script: string;
+    /** All redirects collected from this segment (executor handles them). */
+    redirects: Redirect[];
+}
+export declare function translateCommandList(list: CommandList): SegmentPlan[];
+/**
+ * Wrap a pipeline body with the Fauxnix executor contract:
+ * UTF-8 everywhere, bash-style exit codes, cwd/env persistence channels.
+ */
+export declare function wrapScript(body: string): string;