looply-cli 0.0.0-stage → 0.2.0

package/dist/exec-domains.js

@@ -0,0 +1,287 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.containedRoot = containedRoot;
+exports.buildUntrustedGateEnv = buildUntrustedGateEnv;
+exports.containedPath = containedPath;
+exports.buildAgentEnv = buildAgentEnv;
+exports.buildProviderEnv = buildProviderEnv;
+exports.buildNotifyEnv = buildNotifyEnv;
+exports.protectedPaths = protectedPaths;
+exports.untrustedGrants = untrustedGrants;
+exports.sharedGrantPaths = sharedGrantPaths;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const untrusted_exec_1 = require("./untrusted-exec");
+const trusted_git_1 = require("./trusted-git");
+/**
+ * Where a contained child keeps the profile Windows insists it has.
+ *
+ * An AppContainer needs USERPROFILE/APPDATA/LOCALAPPDATA to start at all — the
+ * loader resolves the container's redirected storage through them. Pointing
+ * them at the daemon's profile would hand back everything the container exists
+ * to keep away: `~/.looply/machine.json`, `~/.claude`, `~/.gitconfig`. So the
+ * child gets its own, created beside the system temp directory and granted to
+ * it explicitly.
+ *
+ * Per project and per domain, so a gate cannot read what an agent left behind.
+ */
+function containedRoot(kind, projectKey) {
+    const digest = (0, node_crypto_1.createHash)('sha256').update(projectKey, 'utf8').digest('hex').slice(0, 16);
+    const root = (0, node_path_1.join)((0, node_os_1.tmpdir)(), 'looply-contained', `${kind}-${digest}`);
+    for (const sub of ['', 'appdata', 'local', 'temp']) {
+        (0, node_fs_1.mkdirSync)(sub === '' ? root : (0, node_path_1.join)(root, sub), { recursive: true });
+    }
+    return root;
+}
+/** Platform values a child cannot start without, and nothing else. */
+function platformOnly() {
+    const out = {};
+    for (const name of untrusted_exec_1.PLATFORM_BASE) {
+        // The profile roots are deliberately NOT copied from the daemon: they are
+        // replaced below with the contained child's own.
+        if (/^(USERPROFILE|APPDATA|LOCALAPPDATA|TEMP|TMP|HOME)$/i.test(name))
+            continue;
+        const v = process.env[name];
+        if (typeof v === 'string' && v.length > 0)
+            out[name] = v;
+    }
+    /**
+     * 🔴 SystemRoot IS RESOLVED, NOT MERELY COPIED — AND THIS WAS THE SIXTH SITE
+     * THAT DID NOT ASK.
+     *
+     * The loop above copies whatever the parent happens to hold, which leaves two
+     * holes that `systemRoot()` exists to close and that an environment built from
+     * an allowlist makes reachable rather than theoretical:
+     *
+     *   absent   — `systemRoot`'s own comment says a child of a contained child
+     *              legitimately has no `SystemRoot` at all, because THIS function
+     *              is what builds its block. The loop then omits the variable, and
+     *              CreateProcess fails with ERROR_ENVVAR_NOT_FOUND (203), which
+     *              names no variable — an unreadable failure one level down.
+     *   relative — a non-empty `SystemRoot=C:Windows` is copied through verbatim.
+     *              That is the dropped-backslash value this module has been bitten
+     *              by twice, handed to a child whose working directory is the
+     *              project worktree.
+     *
+     * `systemRoot()` returns the parent's value unchanged whenever it is a real
+     * absolute path, so this is identical in the ordinary case and a repair in the
+     * two that are not.
+     */
+    out['SystemRoot'] = (0, untrusted_exec_1.systemRoot)();
+    return out;
+}
+function profileOf(root) {
+    return {
+        USERPROFILE: root,
+        HOME: root,
+        APPDATA: (0, node_path_1.join)(root, 'appdata'),
+        LOCALAPPDATA: (0, node_path_1.join)(root, 'local'),
+        TEMP: (0, node_path_1.join)(root, 'temp'),
+        TMP: (0, node_path_1.join)(root, 'temp'),
+    };
+}
+/**
+ * The environment for project-controlled test, build and typecheck commands.
+ *
+ * Carries no credential of any kind. The two extras are both about making the
+ * boundary work rather than about trust:
+ *
+ * `NODE_OPTIONS` — an AppContainer cannot stat `C:\`, and Node's module
+ * resolution walks to the drive root, so without these flags nothing Node runs
+ * at all. Scoped here rather than set on the daemon.
+ *
+ * `GIT_CONFIG_NOSYSTEM` — defence in depth only. It removes the system git
+ * config, and with it the ambient credential helper, from anything the gate
+ * runs. It is NOT the boundary: a determined process can clear a variable. The
+ * container is the boundary.
+ */
+function buildUntrustedGateEnv(projectKey, toolchain) {
+    const root = containedRoot('gate', projectKey);
+    return {
+        ...platformOnly(),
+        ...profileOf(root),
+        PATH: containedPath(projectKey, toolchain),
+        NODE_OPTIONS: '--preserve-symlinks --preserve-symlinks-main',
+        GIT_CONFIG_NOSYSTEM: '1',
+        GIT_TERMINAL_PROMPT: '0',
+    };
+}
+/**
+ * The search path a contained child gets.
+ *
+ * Built, not inherited. The daemon's PATH names sixty-odd directories the
+ * container cannot read, and — worse — it names the real toolchain directory,
+ * which on this machine also holds `claude`, `eas` and `heroku` shims. A gate
+ * that could resolve those would be a gate that could deploy.
+ *
+ * So: Looply's own runtime copy first, then the project's own `.bin` (which is
+ * inside the granted worktree and is how `tsc`, `jest` and friends are found),
+ * then the two system directories a shell needs to function.
+ */
+function containedPath(projectKey, toolchain) {
+    const win = (0, untrusted_exec_1.systemRoot)();
+    const parts = [
+        ...(toolchain === undefined ? [] : [toolchain]),
+        (0, node_path_1.join)(projectKey, 'node_modules', '.bin'),
+        (0, node_path_1.join)(win, 'System32'),
+        win,
+    ];
+    return parts.join(';');
+}
+/**
+ * The environment for the coding agent.
+ *
+ * Separate from the gate's because the agent legitimately needs its model
+ * provider — and separate so that giving the agent something never gives it to
+ * the gate. It still carries no Looply machine token and no broker credential:
+ * using the model is the agent's job, speaking for the machine is not.
+ */
+function buildAgentEnv(projectKey, provider = {}, toolchain) {
+    const root = containedRoot('agent', projectKey);
+    return {
+        ...platformOnly(),
+        ...profileOf(root),
+        PATH: containedPath(projectKey, toolchain),
+        NODE_OPTIONS: '--preserve-symlinks --preserve-symlinks-main',
+        ...provider,
+    };
+}
+/**
+ * The environment for the PROVIDER TRANSPORT.
+ *
+ * This one is different in kind from the others, and the difference is the
+ * point of the whole decomposition. The transport is not contained — it cannot
+ * be, because the packaged provider spawns children with piped stdio and an
+ * AppContainer cannot create the named pipes that needs. So it runs as the
+ * daemon user, and the only thing standing between it and the machine's
+ * authority is what Looply chooses to hand it.
+ *
+ * Which is: the platform baseline, its own profile, and whatever the person
+ * named in `agent.env`. Built up rather than filtered down, so a Looply
+ * credential added to the daemon's environment next year does not silently
+ * appear here.
+ *
+ * It carries NO PATH into the project. The transport has no reason to resolve
+ * anything from the worktree; the tools it can call are served over MCP and run
+ * somewhere else entirely.
+ */
+function buildProviderEnv(sessionDir, provider = {}) {
+    const win = (0, untrusted_exec_1.systemRoot)();
+    return {
+        ...platformOnly(),
+        ...profileOf(sessionDir),
+        // System directories only. Not the project's `.bin`, and not the machine's
+        // toolchain directory, which on this machine also holds `claude`, `eas` and
+        // `heroku` shims.
+        PATH: [(0, node_path_1.join)(win, 'System32'), win].join(';'),
+        ...provider,
+    };
+}
+/**
+ * The environment for the user's own notification script.
+ *
+ * NOT contained: this file is the person's, stored under their home directory,
+ * and running it is the product working as intended. But it inherited the whole
+ * daemon environment — every secret the daemon holds — for no reason at all. A
+ * notification does not need the machine token.
+ */
+function buildNotifyEnv() {
+    const out = {};
+    for (const name of [...untrusted_exec_1.PLATFORM_BASE, 'HOME']) {
+        const v = process.env[name];
+        if (typeof v === 'string' && v.length > 0)
+            out[name] = v;
+    }
+    return out;
+}
+/**
+ * Paths inside a granted worktree that untrusted execution must never reach.
+ *
+ * Derived from the execution kind rather than chosen per call site, because a
+ * caller that forgets one is a caller that quietly hands over the authority
+ * state.
+ *
+ * `.looply/state` holds every durable fact Phase 6 rests on — the grant, the
+ * receipts, the launch and claim records, the ledger, the human control file.
+ * `.git` is where a repository-controlled config can turn a trusted git command
+ * into arbitrary execution. `config.yaml` is the one file the person edits by
+ * hand, and it names the gate commands and the rails: a round that could write
+ * it could weaken every round after it.
+ *
+ * `<projectDir>/.git` IS PROTECTED WHATEVER IT TURNS OUT TO BE. In a linked
+ * worktree it is a pointer file rather than a directory, and a write to it
+ * redirects every later git command at metadata of the writer's choosing — so
+ * it is protected for its own sake, not merely as a route to a directory.
+ *
+ * AND WHEREVER THE METADATA REALLY LIVES, appended below. In a linked worktree
+ * the real gitdir is `<common>/worktrees/<name>` and the config that decides
+ * what git executes is in the shared common dir; neither is under `projectDir`,
+ * so neither is covered by the three literals.
+ *
+ * ⚠️ THE THREE LITERALS STAY AT THE TOP OF THE BODY, and the prose stays up
+ * here. `project-memory-reachability.spec.ts` pins them by slicing the first 400
+ * characters after the signature — a deliberate guard on the ground under
+ * `source: 'human'` — and a comment inside the body pushes them out of it.
+ */
+function protectedPaths(projectDir) {
+    const paths = [
+        (0, node_path_1.join)(projectDir, '.git'),
+        (0, node_path_1.join)(projectDir, '.looply', 'state'),
+        (0, node_path_1.join)(projectDir, '.looply', 'config.yaml'),
+    ];
+    /**
+     * Resolution failures are swallowed on purpose: this list is consulted while
+     * building a container, a directory that is not a repository has nothing more
+     * to protect, and `repoConfigTroubleAt` is the check that refuses on
+     * unreadable metadata. Making this throw would turn "not a repository" into a
+     * crash at every call site.
+     */
+    const meta = (0, trusted_git_1.worktreeMetadata)(projectDir);
+    if (meta !== null) {
+        for (const p of [meta.gitDir, meta.commonDir]) {
+            if (!paths.includes(p))
+                paths.push(p);
+        }
+    }
+    return paths;
+}
+/** What untrusted execution is granted: the worktree, and its own profile. */
+function untrustedGrants(kind, projectDir) {
+    return [
+        { path: projectDir, write: true },
+        { path: containedRoot(kind, projectDir), write: true },
+        // READ AND EXECUTE ONLY. The runtime is Looply's, and untrusted code that
+        // could replace `node.exe` would be untrusted code choosing what every
+        // later gate runs.
+        /**
+         * 🔴 THE TOOLCHAIN IS NO LONGER GRANTED HERE, AND THAT IS THE n122 REPAIR.
+         *
+         * It is SHARED — every workspace, every project and every concurrent looply
+         * process on this machine resolves `node.exe` through it — so granting it
+         * per launch added one permanent inheritable ACE per container identity and
+         * nothing ever removed one. Measured before the repair: 262 container ACEs
+         * on the mirror and 509 on the tool-worker directory, against a DACL capped
+         * near 64 KB.
+         *
+         * Shared paths now go through `ensureSharedAccess`, which takes the same
+         * lock the removal takes — the addition and the removal of one shared DACL
+         * cannot be serialised by locking only one of them — records what it
+         * granted so a later mirror move does not orphan the entry, and does no
+         * work at all for an identity that already holds it.
+         *
+         * Run-OWNED paths stay here: the workspace and the contained root have a
+         * single owner, so they need no lock and are removed with the workspace.
+         */
+    ];
+}
+/**
+ * The shared directories a contained execution needs, which are granted under
+ * the shared-grant lock rather than per launch. `toolchain` is absent for the
+ * built-in provider, which resolves its own.
+ */
+function sharedGrantPaths(toolchain, extra = []) {
+    return [...(toolchain === undefined ? [] : [toolchain]), ...extra].filter((p) => p.length > 0);
+}
+//# sourceMappingURL=exec-domains.js.map

package/dist/exec-domains.js.map

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

package/dist/exemption-store.d.ts

@@ -0,0 +1,197 @@
+import type { Exemption } from '@looply/core';
+import type { LedgerFs } from './ledger-store';
+/**
+ * Which granted exemptions this machine has already spent — `exemptions.json`
+ * under the state dir.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 THE SINK WITHOUT WHICH THE SOURCE MUST NOT BE WIRED.
+ *
+ * `RoundRunner` refuses to start with `exemptionsFor` wired and no
+ * `spendExemption`, and its constructor says why: "one grant reopening the same
+ * rail every round until it expires". A grant is for ONE item, ONE path, ONCE.
+ * The core model carries `usedInRound` for exactly that, and something has to
+ * remember it after the process exits.
+ *
+ * ⚠️ THE SERVER CANNOT BE THAT SOMETHING, AND THAT IS BY DESIGN RATHER THAN AN
+ * OVERSIGHT. `model Exemption` records a DECISION — granted or refused, by whom,
+ * until when — and has no spent column, because the product's own account says a
+ * grant "is spent on commit, not on check" and "the commit itself carries the
+ * opening in its trailer". The durable audit record is the commit. This file is
+ * only what stops the same grant being handed to a second round on this machine.
+ *
+ * ⚠️ AND THERE IS A WINDOW THIS CANNOT CLOSE. Spending happens AFTER the commit,
+ * deliberately: "a discarded round leaves the door open for the retry; burning
+ * it on a failure would strand the next attempt outside its own door." So a
+ * crash between the commit and this write leaves the grant looking unspent, and
+ * a later run could open that rail once more. Reserving on hand-out would close
+ * it and would contradict the design outright, so the window is documented
+ * rather than engineered away — and the commit trailer is what makes it visible
+ * if it ever happens.
+ */
+export interface SpentFile {
+    version: 1;
+    /** Grant identity → the round that spent it. */
+    spent: Record<string, number>;
+}
+/**
+ * A grant's identity, for a model that has no id of its own.
+ *
+ * 🔴 EXPIRY IS PART OF IT. Two grants for the same item and path with different
+ * expiries are two separate acts of permission — somebody granting the same door
+ * again tomorrow is not re-using yesterday's grant, and keying without the
+ * expiry would silently treat the new one as already spent.
+ *
+ * A NUL separator, so a path containing the separator cannot forge another
+ * grant's key; paths cannot contain NUL on any filesystem this runs on.
+ */
+export declare function grantKey(e: Pick<Exemption, 'itemId' | 'path' | 'expiresAt'>): string;
+export declare class ExemptionStore {
+    private readonly stateDir;
+    private readonly fs;
+    private readonly migrate?;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    private static writes;
+    private spent;
+    private readable;
+    /**
+     * ⚠️ `migrate` RUNS BEFORE ANY READ, AND ITS REFUSAL IS AN UNREADABLE STORE.
+     *
+     * The ledger's home moved out of the repository (see `rails-home.ts`), and a
+     * move is the one moment when "I could not see the old records" and "there
+     * were no old records" look identical. This store's entire safety argument is
+     * that they must never look identical: an unreadable ledger answers `isSpent`
+     * true for everything, because treating a corrupt ledger as "nothing spent"
+     * re-opens every door the machine has already used.
+     *
+     * So a migration that cannot prove what was spent fails the store closed,
+     * exactly as an unparseable `exemptions.json` does. Omitted, there is no
+     * migration and nothing changes — which is what every existing test relies on.
+     */
+    constructor(stateDir: string, fs: LedgerFs, migrate?: (() => Promise<{
+        ok: boolean;
+        because?: string;
+    }>) | undefined);
+    private get path();
+    /**
+     * Where spends are written now: APPEND-ONLY, one JSON object per line.
+     *
+     * 🔴 THE WHOLE-MAP REWRITE BECAME A RAILS BYPASS THE MOMENT THIS LEDGER WAS
+     * SHARED. `record` used to serialise the entire `spent` map from the snapshot
+     * loaded at `open()` and rename it over the file. That was sound while one run
+     * owned one checkout. Phase 1 moved this file to the PROJECT state directory —
+     * so that a single-use grant could not be spent once per workspace — and made
+     * two runs concurrent in the same change. Two runs spending two DIFFERENT
+     * grants then each wrote a map that did not contain the other's spend, and the
+     * loser's spend was erased: a single-use grant over a railed path, spendable
+     * again. The scope fix had turned into a lost-update bug, which is precisely
+     * what the recon warned would happen if the format were left alone.
+     *
+     * An append never loses a concurrent write. `exemptions.json` is still READ,
+     * so a machine that has spent grants before this change keeps them, and it is
+     * never written again — that is the whole migration.
+     */
+    private get spendLogPath();
+    /**
+     * Read what is on disk.
+     *
+     * 🔴 AN UNREADABLE FILE FAILS CLOSED, WHICH IS THE OPPOSITE OF `CursorStore`.
+     *
+     * There it is safe to replay too much, so a corrupt cursor is treated as no
+     * cursor. Here the equivalent — treating a corrupt file as "nothing spent" —
+     * would re-open every door this machine has already used. So an unreadable
+     * store stops handing out grants entirely: `isSpent` answers true for
+     * everything, and every rail stays shut. Deny is the default the whole rails
+     * design rests on.
+     */
+    open(): Promise<'ok' | 'unreadable'>;
+    /**
+     * Fold the append-only spend log over whatever the legacy file held.
+     *
+     * ⚠️ FAILS CLOSED LIKE ITS SIBLING. A log that exists and cannot be read is a
+     * log whose spends cannot be seen, and a store that cannot see a spend would
+     * re-open a door somebody already used. A MALFORMED LINE is different and is
+     * skipped: an append can be torn by a crash mid-write, and discarding every
+     * spend on the strength of one truncated last line would be the same
+     * fail-open by another route.
+     */
+    private readSpendLog;
+    /** True when this grant must not be handed to another round. Fails closed. */
+    isSpent(e: Pick<Exemption, 'itemId' | 'path' | 'expiresAt'>): boolean;
+    /**
+     * Record a grant as spent.
+     *
+     * ⚠️ IDEMPOTENT, AND THE FIRST ROUND WINS. A retry that spends the same grant
+     * again must not rewrite the round number: the round recorded is the one that
+     * actually used the door, and overwriting it would make the trailer and this
+     * file disagree about which commit opened it.
+     *
+     * A store that could not be read refuses to write. Writing a fresh file over
+     * one that failed to parse would discard every spend it contained.
+     */
+    record(e: Exemption): Promise<void>;
+    /** What this machine has spent, for a report or a test. */
+    all(): Record<string, number>;
+}
+/**
+ * The grants a round may be offered for one item.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 THE `!isSpent` HERE IS NOT A DUPLICATE OF THE ONE IN `grantsFromServer`.
+ *
+ * That one runs ONCE, when the run starts. This one runs every time the gate
+ * asks, which is once per item per ROUND — and between two rounds of the same
+ * run a grant can be spent.
+ *
+ * Without it the wiring reproduced exactly the failure `RoundRunner` refuses to
+ * allow: its constructor rejects a grant source with no spend sink because that
+ * is "one grant reopening the same rail every round until it expires". Wiring
+ * both halves satisfied that check STRUCTURALLY while defeating it in fact —
+ * the sink recorded the spend and the source, a plain array captured before the
+ * first round, kept offering the same grant to every round after it. One grant,
+ * one round, was true only across runs and false within one.
+ *
+ * ⚠️ IT READS THE STORE'S IN-MEMORY STATE, WHICH IS WHAT MAKES IT WORK. `record`
+ * assigns `spent[key]` before it awaits the write, so the very next round sees
+ * the spend whether or not the file has landed. A store that cannot be read
+ * answers true for everything and every rail stays shut.
+ *
+ * ⚠️ WHAT IT DOES NOT DO: notice a grant made DURING a run. The source is
+ * fetched once at start, so a person who grants a rail while a run is going
+ * opens it for the NEXT run, not this one. That is a closed door rather than an
+ * open one, so it is recorded here instead of being engineered away with a
+ * mid-run refetch nothing asked for.
+ */
+export declare function offerableFor(grants: readonly Exemption[], itemId: string, isSpent: (e: Pick<Exemption, 'itemId' | 'path' | 'expiresAt'>) => boolean): Exemption[];
+/** A granted exemption as the server sends it — the subset this mapping needs. */
+export interface GrantRow {
+    itemId: string;
+    path: string;
+    decision: string;
+    actor: string;
+    expiresAt: string | null;
+}
+/**
+ * Server rows → the grants a round may be offered.
+ *
+ * 🔴 THREE FILTERS, AND EACH ONE IS LOAD-BEARING.
+ *
+ *   - `decision === 'granted'` — a REFUSAL is recorded in the same table, and
+ *     handing one to a gate would open the door a person explicitly shut.
+ *   - a real `expiresAt` — the model treats a grant with no expiry as no grant;
+ *     `listGranted` already excludes both, and asking again means a source that
+ *     widened cannot widen the rails silently.
+ *   - not already spent on this machine — one grant, one round.
+ *
+ * ⚠️ IT DOES NOT JUDGE THE PATH, AND MUST NOT. Whether a grant opens the file
+ * actually being written is decided at the interlock by `isExemptionValid`,
+ * which is the only place that sees it. Pre-filtering here would be a second
+ * opinion about the same question, free to disagree.
+ */
+export declare function grantsFromServer(rows: readonly GrantRow[], isSpent: (e: Pick<Exemption, 'itemId' | 'path' | 'expiresAt'>) => boolean, fromGrant: (p: {
+    itemId: string;
+    path: string;
+    expiresAt: string;
+    actor: string;
+}) => Exemption): Exemption[];
+//# sourceMappingURL=exemption-store.d.ts.map

package/dist/exemption-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exemption-store.d.ts","sourceRoot":"","sources":["../src/exemption-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,CAAC,CAAC;IACX,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAMD;;;;;;;;;;GAUG;AAEH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC,GAAG,MAAM,CAEpF;AAED,qBAAa,cAAc;IAsBvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAvB3B,kFAAkF;IAClF,OAAO,CAAC,MAAM,CAAC,MAAM,CAAK;IAE1B,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,QAAQ,CAAQ;IAExB;;;;;;;;;;;;;OAaG;gBAEgB,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,QAAQ,EACZ,OAAO,CAAC,GAAE,MAAM,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,aAAA;IAG7E,OAAO,KAAK,IAAI,GAEf;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,KAAK,YAAY,GAEvB;IAED;;;;;;;;;;;OAWG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,GAAG,YAAY,CAAC;IAsC1C;;;;;;;;;OASG;YACW,YAAY;IAuB1B,8EAA8E;IAC9E,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC,GAAG,OAAO;IAKrE;;;;;;;;;;OAUG;IACG,MAAM,CAAC,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBzC,2DAA2D;IAC3D,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAG9B;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC,KAAK,OAAO,GACxE,SAAS,EAAE,CAEb;AAED,kFAAkF;AAClF,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,SAAS,QAAQ,EAAE,EACzB,OAAO,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC,KAAK,OAAO,EACzE,SAAS,EAAE,CAAC,CAAC,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,KAAK,SAAS,GAC9F,SAAS,EAAE,CAYb"}