@taliesinb/mash 0.0.0-stage → 0.1.0

package/dist/src/vm/fifo.js

@@ -0,0 +1,232 @@
+/**
+ * Named-FIFO fallback for handing VM file descriptors to external commands.
+ *
+ * Node creates child stdio pipes as UNIX socketpairs. macOS lets a child open
+ * `/dev/fd/N` on a socket (it dups the descriptor); Linux reopens the file
+ * through `/proc/self/fd/N`, which fails with ENXIO for sockets. So on Linux a
+ * process substitution (`diff <(a) <(b)`) or an `exec 3<f; cmd /dev/fd/3`
+ * passed to an external command cannot use the socket slot. Instead the child
+ * gets the path of a named FIFO in a private temp dir, and mash pumps between
+ * the FIFO and the VM file (so taps and tracing still see the bytes).
+ *
+ * Opening a FIFO blocks until the other side opens it, and a blocking open
+ * would hold one of libuv's four threadpool threads. So mash never does a
+ * blocking open: everything here uses `O_NONBLOCK` descriptors and polls with
+ * a short backoff (immediate while data flows, at most {@link MAX_DELAY} ms
+ * when idle).
+ *
+ * - **The child reads** (`<(cmd)`): mash polls `open(O_WRONLY|O_NONBLOCK)`,
+ *   which fails with ENXIO until the child has opened the FIFO for reading.
+ *   Only then does it write, so no data can be lost in a pipe nobody holds,
+ *   and closing it at the VM file's EOF gives the child EOF. If the child
+ *   exits without opening it, nothing is consumed from the VM file.
+ * - **The child writes** (`>(cmd)`): mash opens the read side
+ *   `O_RDONLY|O_NONBLOCK` up front (that never blocks, and lets the child's
+ *   own open for writing succeed at once) and polls `read`. A read of 0 means
+ *   "no writer right now", so the pump only stops once the child has exited
+ *   and every writer (including grandchildren) has closed.
+ *
+ * The strategy is chosen per machine: {@link defaultFdPassing} (Linux and the
+ * other non-macOS systems → `fifo`, macOS → `devfd`), overridable with the
+ * `MASH_PROCSUBST=fifo|devfd` environment variable or `MachineOptions.procSubst`.
+ */
+import { execFile } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/** `MASH_PROCSUBST` if set to `fifo`/`devfd`, else `devfd` on macOS and `fifo` elsewhere. */
+export function defaultFdPassing(env = process.env) {
+    const v = env.MASH_PROCSUBST;
+    if (v === 'fifo' || v === 'devfd')
+        return v;
+    return process.platform === 'darwin' ? 'devfd' : 'fifo';
+}
+const MAX_DELAY = 16;
+/** Exponential backoff for polling: 0 (a macrotask turn), 1, 2, 4 … MAX_DELAY ms. */
+class Backoff {
+    delay = 0;
+    reset() {
+        this.delay = 0;
+    }
+    /** Sleep; if `signal` aborts *during* the sleep, wake early. */
+    wait(signal) {
+        const ms = this.delay;
+        this.delay = Math.min(MAX_DELAY, ms === 0 ? 1 : ms * 2);
+        return new Promise((resolve) => {
+            if (signal?.aborted)
+                signal = undefined;
+            const done = () => {
+                clearTimeout(t);
+                signal?.removeEventListener('abort', done);
+                resolve();
+            };
+            const t = ms === 0 ? setTimeout(done, 0) : setTimeout(done, ms);
+            signal?.addEventListener('abort', done, { once: true });
+        });
+    }
+}
+function unlink(p) {
+    try {
+        fs.unlinkSync(p);
+    }
+    catch {
+        // already gone
+    }
+}
+function code(e) {
+    return e?.code;
+}
+/** A private temp dir holding the FIFOs of one external command. */
+export class FifoSet {
+    dir;
+    feeds = [];
+    constructor(dir) {
+        this.dir = dir;
+    }
+    /** Create a private dir with `n` FIFOs (`0`, `1`, …), mode 0600, via one `mkfifo` call. */
+    static async create(n) {
+        const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'mash-fifo-'));
+        const set = new FifoSet(dir);
+        const paths = Array.from({ length: n }, (_, i) => path.join(dir, String(i)));
+        try {
+            await new Promise((resolve, reject) => {
+                execFile('mkfifo', ['-m', '600', ...paths], { env: { PATH: `/usr/bin:/bin:${process.env.PATH ?? ''}` } }, (err) => (err ? reject(err) : resolve()));
+            });
+        }
+        catch (e) {
+            set.cleanup();
+            throw e;
+        }
+        return { set, paths };
+    }
+    /**
+     * Feed the FIFO at `p` from `file` (the child reads it). Resolves at the
+     * file's EOF, when the child stops reading, or once `exited` aborts.
+     */
+    async feed(p, file, exited) {
+        this.feeds.push(p);
+        const C = fs.constants;
+        const backoff = new Backoff();
+        let fd = -1;
+        while (fd < 0) {
+            if (exited.aborted)
+                return;
+            try {
+                fd = fs.openSync(p, C.O_WRONLY | C.O_NONBLOCK);
+            }
+            catch (e) {
+                if (code(e) !== 'ENXIO')
+                    return; // no reader yet is ENXIO; anything else: give up
+                await backoff.wait(exited);
+            }
+        }
+        backoff.reset();
+        try {
+            for (;;) {
+                const chunk = await file.read(exited);
+                if (chunk === null)
+                    return; // EOF (or the child exited: nothing consumed)
+                let off = 0;
+                while (off < chunk.length) {
+                    if (exited.aborted) {
+                        file.unread(chunk.subarray(off));
+                        return;
+                    }
+                    try {
+                        off += fs.writeSync(fd, chunk, off, chunk.length - off);
+                        backoff.reset();
+                    }
+                    catch (e) {
+                        if (code(e) === 'EAGAIN') {
+                            await backoff.wait(exited);
+                            continue;
+                        }
+                        // EPIPE: the child closed it; leave the rest for other readers of a shared file
+                        file.unread(chunk.subarray(off));
+                        return;
+                    }
+                }
+            }
+        }
+        catch {
+            // reading the source failed: the child gets EOF
+        }
+        finally {
+            fs.closeSync(fd);
+            // a second open for reading would wait for a writer forever: make it fail instead
+            unlink(p);
+        }
+    }
+    /**
+     * Drain the FIFO at `p` into `file` (the child writes it). Resolves once
+     * the child has exited and no writer holds the FIFO, or when `file` has no
+     * readers left (the child's writes then fail with EPIPE/SIGPIPE).
+     */
+    async drain(p, file, exited) {
+        const C = fs.constants;
+        let fd;
+        try {
+            fd = fs.openSync(p, C.O_RDONLY | C.O_NONBLOCK);
+        }
+        catch {
+            return;
+        }
+        const buf = Buffer.allocUnsafe(65536);
+        const backoff = new Backoff();
+        try {
+            for (;;) {
+                let n;
+                try {
+                    n = fs.readSync(fd, buf, 0, buf.length, null);
+                }
+                catch (e) {
+                    if (code(e) !== 'EAGAIN')
+                        return;
+                    await backoff.wait(); // a writer is connected but has nothing yet
+                    continue;
+                }
+                if (n > 0) {
+                    backoff.reset();
+                    await file.write(Buffer.from(buf.subarray(0, n)));
+                    continue;
+                }
+                // n === 0: no writer at the moment (not opened yet, or closed)
+                if (exited.aborted)
+                    return;
+                await backoff.wait(exited);
+            }
+        }
+        catch {
+            // BrokenPipeError: nobody reads any more. A later open for writing must fail, not block
+            unlink(p);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    /**
+     * Remove the FIFOs and the dir. A reader of a fed FIFO still blocked in
+     * `open` (a grandchild that opened it late) is released first: a brief
+     * non-blocking writer open lets its open return, and it reads EOF.
+     */
+    cleanup() {
+        const C = fs.constants;
+        for (const p of this.feeds) {
+            if (!fs.existsSync(p))
+                continue;
+            try {
+                fs.closeSync(fs.openSync(p, C.O_WRONLY | C.O_NONBLOCK));
+            }
+            catch {
+                // ENXIO: no reader waiting
+            }
+        }
+        try {
+            fs.rmSync(this.dir, { recursive: true, force: true });
+        }
+        catch {
+            // best effort
+        }
+    }
+}
+//# sourceMappingURL=fifo.js.map

package/dist/src/vm/fifo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fifo.js","sourceRoot":"","sources":["../../../src/vm/fifo.ts"],"names":[],"mappings":"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"}

package/dist/src/vm/interp.d.ts

@@ -0,0 +1,209 @@
+/**
+ * The tree-walking interpreter. Every command node emits a `step` event
+ * before it runs; simple commands are expanded, resolved, assessed against
+ * the policy (through {@link Runtime.assess}, which consults behavior
+ * definitions and hooks), and only then have their redirections opened and
+ * run. Pipelines run their stages concurrently over in-memory pipes; external
+ * commands are real child processes whose stdio is pumped through the VM's
+ * channels so it can be observed.
+ */
+import type * as A from '../parser/ast.ts';
+import { literalOf } from '../parser/parser.ts';
+import type { Effect } from '../policy/effects.ts';
+import type { CommandKind, SubshellReason, TraceEvent } from '../trace/events.ts';
+import { type ArithEnv } from './arith.ts';
+import { Expander } from './expand.ts';
+import { type SpawnFn } from './external.ts';
+import type { FdPassing } from './fifo.ts';
+import { FdTable, type Channel, type ChannelKind, type DataListener } from './io.ts';
+import { Proc, type Job } from './proc.ts';
+import { ShellState } from './state.ts';
+import { evalTest } from './test.ts';
+export interface ExecIntent {
+    execId: number;
+    node: A.SimpleCommand;
+    argv: string[];
+    kind: CommandKind;
+    path?: string;
+    cwd: string;
+    env: Record<string, string>;
+    redirectEffects: Effect[];
+    stdinKind: 'pipe' | 'file' | 'null' | 'terminal' | 'unknown';
+    pid: number;
+}
+export type Assessment = {
+    action: 'run';
+    readsStdin: boolean | 'maybe';
+} | {
+    action: 'deny';
+    reason: string;
+    status: number;
+} | {
+    action: 'abort';
+    reason: string;
+    status: number;
+} | {
+    action: 'simulate';
+    stdout: string;
+    stderr: string;
+    status: number;
+};
+export interface Runtime {
+    emit(event: TraceEvent): void;
+    readonly listeners: DataListener[];
+    channel(kind: ChannelKind, label: string, extra?: Partial<Channel>): Channel;
+    nextPid(): number;
+    nextExecId(): number;
+    readonly shellPid: number;
+    assess(intent: ExecIntent): Promise<Assessment>;
+    /** Policy check for redirections of compound commands (no command to attach them to). */
+    assessRedirects(effects: Effect[], node: A.Node, proc: Proc): Promise<Assessment>;
+    afterCommand(execId: number, status: number): Promise<void>;
+    spawn: SpawnFn;
+    readonly signal: AbortSignal;
+    /** Source text of a node (from whichever parse produced it). */
+    text(node: {
+        id: number;
+        span: A.Span;
+    }): string;
+    /** 1-based line number of a node in its source. */
+    line(node: {
+        id: number;
+        span: A.Span;
+    }): number;
+    /** Parse source text (eval, source, trap actions), registering it for text()/line(). */
+    parse(source: string, origin: string, opts?: {
+        partial?: boolean;
+    }): A.Script;
+    findJob(pid: number): Job | undefined;
+    /** Pending background work (process substitutions) to settle at the end. */
+    track(p: Promise<unknown>): void;
+    registerJob(job: Job): void;
+    /** Execute nested bash/sh scripts inside the VM. */
+    readonly inlineScripts: boolean;
+    /** Emulate xargs and find -exec/-delete so each resulting command is traced and checked. */
+    readonly emulate: boolean;
+    /** How `/dev/fd/N` arguments naming VM fds reach external commands (see fifo.ts). */
+    readonly fdPassing: FdPassing;
+}
+interface ResolvedRedirect {
+    node: A.Redirect;
+    fd: number;
+    op: A.RedirectOp;
+    /** Absolute path for file redirections. */
+    path?: string;
+    /** Special device handling. */
+    special?: 'null' | {
+        dup: number;
+    };
+    dupFd?: number;
+    close?: boolean;
+    content?: string;
+    fdVar?: string;
+}
+export declare class Interpreter {
+    readonly rt: Runtime;
+    readonly expander: Expander;
+    constructor(rt: Runtime);
+    /** Run a parsed script in `proc` (the top-level shell). Returns the exit status. */
+    runTop(script: A.Script, proc: Proc): Promise<number>;
+    /**
+     * Execute a script's top-level statements like bash reads them: an
+     * expansion error discards only the current top-level command, and a
+     * syntax error further down (partial parse) is reported when reached.
+     */
+    execTopLevel(script: A.Script, proc: Proc): Promise<number>;
+    private handleTermination;
+    private runExitTrap;
+    write(proc: Proc, fd: number, text: string | Uint8Array): Promise<void>;
+    errorMessage(proc: Proc, message: string): void;
+    execList(stmts: A.Stmt[], proc: Proc): Promise<number>;
+    execStmt(stmt: A.Stmt, proc: Proc): Promise<number>;
+    private startBackground;
+    /** Run `fn` as the body of subshell `child`, handling exit, traps and fd cleanup. */
+    runSubshell(child: Proc, fn: () => Promise<number>, reason: SubshellReason, nodeId: number): Promise<number>;
+    private inErrTrap;
+    /** After a failing command outside a condition: run the ERR trap, then apply `set -e`. */
+    private checkErrexit;
+    private step;
+    private stepCount;
+    execCommand(cmd: A.Command, proc: Proc): Promise<number>;
+    private execCompound;
+    private execAndOr;
+    private execIf;
+    /** Run a loop body; returns 'break' / 'continue' / status. */
+    private loopBody;
+    private execLoop;
+    private execFor;
+    private execSelect;
+    private execArithFor;
+    private execCase;
+    private execPipeline;
+    private setPipestatus;
+    private expandFieldsChecked;
+    private execSimple;
+    private closeProcSubsts;
+    /** `expand_aliases`: re-parse the command with the alias text substituted for its first word. */
+    private expandAlias;
+    private execSimpleInner;
+    private setUnderscore;
+    private realArgv;
+    private dispatch;
+    /**
+     * Execute a nested shell script (`bash -c ...`, `bash file`, `./script.sh`)
+     * inside the VM as a fresh shell process: only exported variables carry
+     * over, functions and options do not. Its commands are traced and
+     * policy-checked individually instead of disappearing into a child bash.
+     */
+    private runInlineScript;
+    /**
+     * Run an already-expanded argv (for `command`, `builtin`, `exec`): resolve,
+     * assess against the policy, and dispatch.
+     */
+    runArgv(argv: string[], proc: Proc, node: A.SimpleCommand, opts: {
+        skipFunctions?: boolean;
+        externalOnly?: boolean;
+        builtinOnly?: boolean;
+    }): Promise<number>;
+    private withTempVars;
+    callFunction(def: A.FunctionDef, argv: string[], proc: Proc): Promise<number>;
+    private runBuiltin;
+    private redirectOnly;
+    private xtrace;
+    childEnv(proc: Proc, prefix: {
+        name: string;
+        value: string;
+    }[]): Record<string, string>;
+    assignScalar(proc: Proc, name: string, value: string, opts?: {
+        local?: boolean;
+    }): void;
+    /** `name[index]=value` from an already-expanded subscript (`printf -v 'a[1]'`). */
+    assignElement(proc: Proc, name: string, index: string, value: string): Promise<void>;
+    private applyAttrs;
+    /**
+     * Expand an assignment's value now and return an equivalent assignment with
+     * literal parts (so `local x=1 y=$x` sees the old `$x`, as bash expands
+     * all arguments before the builtin runs).
+     */
+    freezeAssign(a: A.Assign, proc: Proc): Promise<A.Assign>;
+    /** Perform an assignment node (prefix, bare, or declaration-builtin argument). */
+    performAssign(a: A.Assign, proc: Proc, opts: {
+        local?: boolean;
+        exported?: boolean;
+        declareKind?: 'indexed' | 'assoc';
+    }): Promise<void>;
+    arithEnv(proc: Proc): ArithEnv;
+    arith(expr: A.ArithExpr | null, proc: Proc): Promise<bigint>;
+    arithText(text: string, proc: Proc): Promise<bigint>;
+    private readonly startTime;
+    dynamicVar(proc: Proc, name: string): string | undefined;
+    commandSubst(node: A.CmdSubst, proc: Proc): Promise<string>;
+    processSubst(node: A.ProcSubst, proc: Proc): Promise<string>;
+    private withCompoundRedirects;
+    resolveRedirects(redirs: A.Redirect[], proc: Proc): Promise<ResolvedRedirect[]>;
+    openRedirects(redirects: ResolvedRedirect[], fds: FdTable, proc: Proc): Promise<void>;
+}
+/** PATH lookup (with the shell's hash table). */
+export declare function resolveCommand(name: string, state: ShellState, pathOverride?: string): string | undefined;
+export { literalOf, evalTest };
+//# sourceMappingURL=interp.d.ts.map

package/dist/src/vm/interp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interp.d.ts","sourceRoot":"","sources":["../../../src/vm/interp.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,KAAK,CAAC,MAAM,kBAAkB,CAAA;AAC1C,OAAO,EAAqB,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAClE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,KAAK,EAAE,WAAW,EAAgB,cAAc,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAE/F,OAAO,EAA6B,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAA;AAErE,OAAO,EAAE,QAAQ,EAAe,MAAM,aAAa,CAAA;AACnD,OAAO,EAAe,KAAK,OAAO,EAAE,MAAM,eAAe,CAAA;AAEzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,EACiC,OAAO,EAC7C,KAAK,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAClD,MAAM,SAAS,CAAA;AAEhB,OAAO,EAA4E,IAAI,EAAgB,KAAK,GAAG,EAAE,MAAM,WAAW,CAAA;AAClI,OAAO,EAAyB,UAAU,EAAiB,MAAM,YAAY,CAAA;AAC7E,OAAO,EAAY,QAAQ,EAAE,MAAM,WAAW,CAAA;AAM9C,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,CAAC,CAAC,aAAa,CAAA;IACrB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,IAAI,EAAE,WAAW,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC3B,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAA;IAC5D,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,MAAM,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE,OAAO,GAAG,OAAO,CAAA;CAAE,GAChD;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAE1E,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;IAC7B,QAAQ,CAAC,SAAS,EAAE,YAAY,EAAE,CAAA;IAClC,OAAO,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;IAC5E,OAAO,IAAI,MAAM,CAAA;IACjB,UAAU,IAAI,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAC/C,yFAAyF;IACzF,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IACjF,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3D,KAAK,EAAE,OAAO,CAAA;IACd,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,gEAAgE;IAChE,IAAI,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAA;KAAE,GAAG,MAAM,CAAA;IAChD,mDAAmD;IACnD,IAAI,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAA;KAAE,GAAG,MAAM,CAAA;IAChD,wFAAwF;IACxF,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,CAAC,CAAC,MAAM,CAAA;IAC7E,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,CAAA;IACrC,4EAA4E;IAC5E,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;IAChC,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAAA;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,qFAAqF;IACrF,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;CAC9B;AAED,UAAU,gBAAgB;IACxB,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAA;IAChB,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,CAAC,CAAC,UAAU,CAAA;IAChB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,GAAG;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAGD,qBAAa,WAAW;IACtB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;gBAEf,EAAE,EAAE,OAAO;IAgBvB,oFAAoF;IAC9E,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAW3D;;;;OAIG;IACG,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAuBjE,OAAO,CAAC,iBAAiB;YAYX,WAAW;IAqBnB,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7E,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAUzC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAQtD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAazD,OAAO,CAAC,eAAe;IA+BvB,qFAAqF;IAC/E,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAqBlH,OAAO,CAAC,SAAS,CAAQ;IAEzB,0FAA0F;YAC5E,YAAY;IAgB1B,OAAO,CAAC,IAAI;IAOZ,OAAO,CAAC,SAAS,CAAI;IAEf,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;YAmChD,YAAY;YA8CZ,SAAS;YAaT,MAAM;IAkBpB,8DAA8D;YAChD,QAAQ;YAeR,QAAQ;YA2BR,OAAO;YAgBP,UAAU;YAqBV,YAAY;YAyBZ,QAAQ;YA+BR,YAAY;IA+C1B,OAAO,CAAC,aAAa;YAUP,mBAAmB;YAInB,UAAU;IAexB,OAAO,CAAC,eAAe;IAOvB,iGAAiG;YACnF,WAAW;YAmBX,eAAe;IA0H7B,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,QAAQ;YAUF,QAAQ;IA4CtB;;;;;OAKG;YACW,eAAe;IAuB7B;;;OAGG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,aAAa,EAAE,IAAI,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;YAoCrJ,YAAY;IAapB,YAAY,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;YA8BrE,UAAU;YA2BV,YAAY;YAwBZ,MAAM;IAMpB,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAavF,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,IAAI;IAc3F,mFAAmF;IAC7E,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB1F,OAAO,CAAC,UAAU;IAelB;;;;OAIG;IACG,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;IAe9D,kFAAkF;IAC5E,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,SAAS,GAAG,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA4F7I,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ;IA2CxB,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAI5D,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAc1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IAEvC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAsBlD,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAuC3D,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;YAsBpD,qBAAqB;IA8B7B,gBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAyC/E,aAAa,CAAC,SAAS,EAAE,gBAAgB,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAwC5F;AA+ID,iDAAiD;AACjD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA0BzG;AAED,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAA"}