@pyric/cli 0.1.0-alpha.9

package/dist/credentials/node/from-service-account.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Build a `ProjectScope` from a Google service
+ * account JSON file. Exchanges the SA key for a short-lived OAuth
+ * access token via the standard JWT-bearer flow, and wires
+ * `memoizeTtl` internally so consumers get caching for free.
+ *
+ * No `firebase-admin` dependency — uses only Node's built-in
+ * `crypto` for RS256 signing and `fetch` for the token exchange.
+ *
+ * **Node-only credential adapter**: the function itself requires
+ * `node:fs/promises` + `node:crypto`.
+ */
+import type { ProjectScope } from '../core/types.js';
+/**
+ * Read the service account from a JSON file and return a
+ * `ProjectScope` whose `resolveToken` is memoized internally.
+ *
+ * The JSON file path can be:
+ * - An absolute / relative filesystem path (Node only).
+ * - A base64-encoded JSON string (when prefixed with `base64:`),
+ *   for environments that ship the SA in an env var.
+ */
+export declare function fromServiceAccount(saJsonOrPath: string): Promise<ProjectScope>;
+//# sourceMappingURL=from-service-account.d.ts.map

package/dist/credentials/node/from-service-account.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-service-account.d.ts","sourceRoot":"","sources":["../../../src/credentials/node/from-service-account.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAsBrD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,YAAY,CAAC,CAcvB"}

package/dist/credentials/node/from-service-account.js

@@ -0,0 +1,108 @@
+/**
+ * Build a `ProjectScope` from a Google service
+ * account JSON file. Exchanges the SA key for a short-lived OAuth
+ * access token via the standard JWT-bearer flow, and wires
+ * `memoizeTtl` internally so consumers get caching for free.
+ *
+ * No `firebase-admin` dependency — uses only Node's built-in
+ * `crypto` for RS256 signing and `fetch` for the token exchange.
+ *
+ * **Node-only credential adapter**: the function itself requires
+ * `node:fs/promises` + `node:crypto`.
+ */
+import { memoizeTtl } from '../core/memoize-ttl.js';
+const GOOGLE_TOKEN_URI = 'https://oauth2.googleapis.com/token';
+const SCOPE = [
+    // Project verification and inspection use Firebase and Google Cloud APIs.
+    'https://www.googleapis.com/auth/firebase',
+    'https://www.googleapis.com/auth/cloud-platform',
+].join(' ');
+/**
+ * Read the service account from a JSON file and return a
+ * `ProjectScope` whose `resolveToken` is memoized internally.
+ *
+ * The JSON file path can be:
+ * - An absolute / relative filesystem path (Node only).
+ * - A base64-encoded JSON string (when prefixed with `base64:`),
+ *   for environments that ship the SA in an env var.
+ */
+export async function fromServiceAccount(saJsonOrPath) {
+    const sa = await loadServiceAccount(saJsonOrPath);
+    const resolveToken = memoizeTtl(async () => {
+        const { access_token, expires_in } = await exchangeJwtForAccessToken(sa);
+        return { token: access_token, expiresIn: expires_in };
+    });
+    // Freeze the returned scope so `projectId` can't be mutated at
+    // runtime. TS `readonly` is compile-time-only; Object.freeze
+    // enforces it at runtime — defense in depth for the
+    // security-relevant identity field.
+    return Object.freeze({
+        projectId: sa.project_id,
+        resolveToken,
+    });
+}
+async function loadServiceAccount(saJsonOrPath) {
+    let raw;
+    if (saJsonOrPath.startsWith('base64:')) {
+        raw = Buffer.from(saJsonOrPath.slice('base64:'.length), 'base64').toString('utf-8');
+    }
+    else if (saJsonOrPath.trim().startsWith('{')) {
+        raw = saJsonOrPath;
+    }
+    else {
+        // Dynamic import keeps `node:fs/promises` out of browser bundles
+        // when this function isn't called.
+        const { readFile } = await import('node:fs/promises');
+        raw = await readFile(saJsonOrPath, 'utf-8');
+    }
+    const parsed = JSON.parse(raw);
+    if (!parsed.client_email || !parsed.private_key || !parsed.project_id) {
+        throw new Error('fromServiceAccount: input is missing required fields (client_email, private_key, project_id)');
+    }
+    return parsed;
+}
+async function exchangeJwtForAccessToken(sa) {
+    const jwt = await buildSignedJwt(sa);
+    const res = await fetch(sa.token_uri ?? GOOGLE_TOKEN_URI, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+            assertion: jwt,
+        }).toString(),
+    });
+    if (!res.ok) {
+        throw new Error(`fromServiceAccount: token exchange failed (${res.status}): ${await res.text()}`);
+    }
+    return (await res.json());
+}
+async function buildSignedJwt(sa) {
+    // Dynamic import keeps `node:crypto` out of browser bundles when
+    // `fromServiceAccount` is never called.
+    const { createSign } = await import('node:crypto');
+    const now = Math.floor(Date.now() / 1000);
+    const header = { alg: 'RS256', typ: 'JWT' };
+    const claims = {
+        iss: sa.client_email,
+        scope: SCOPE,
+        aud: sa.token_uri ?? GOOGLE_TOKEN_URI,
+        exp: now + 3600,
+        iat: now,
+    };
+    const headerB64 = base64UrlEncode(JSON.stringify(header));
+    const claimsB64 = base64UrlEncode(JSON.stringify(claims));
+    const signingInput = `${headerB64}.${claimsB64}`;
+    const signer = createSign('RSA-SHA256');
+    signer.update(signingInput);
+    signer.end();
+    const signature = signer.sign(sa.private_key);
+    const signatureB64 = base64UrlEncodeBuffer(signature);
+    return `${signingInput}.${signatureB64}`;
+}
+function base64UrlEncode(s) {
+    return base64UrlEncodeBuffer(Buffer.from(s, 'utf-8'));
+}
+function base64UrlEncodeBuffer(b) {
+    return b.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+//# sourceMappingURL=from-service-account.js.map

package/dist/credentials/node/from-service-account.js.map

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

package/dist/credentials/node/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Node-only credentials used by hosted Rules Test API verification.
+ * Pyric does not own an interactive Google login or credential store.
+ */
+export { fromAdc } from './from-adc.js';
+export { fromServiceAccount } from './from-service-account.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/credentials/node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/credentials/node/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/credentials/node/index.js

@@ -0,0 +1,7 @@
+/**
+ * Node-only credentials used by hosted Rules Test API verification.
+ * Pyric does not own an interactive Google login or credential store.
+ */
+export { fromAdc } from './from-adc.js';
+export { fromServiceAccount } from './from-service-account.js';
+//# sourceMappingURL=index.js.map

package/dist/credentials/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/credentials/node/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/discover/concurrency.d.ts

@@ -0,0 +1,42 @@
+/**
+ * FIFO counting semaphore. `acquire()` resolves immediately while
+ * fewer than `max` permits are checked out, otherwise it queues until
+ * a `release()` frees a slot. Waiters are served in arrival order.
+ *
+ * `release()` without a prior `acquire()` is a no-op (does not go
+ * negative). This is intentional — it lets defensive `try/finally`
+ * release in error paths without bookkeeping.
+ */
+export declare class Semaphore {
+    private readonly max;
+    private active;
+    private queue;
+    constructor(max: number);
+    acquire(): Promise<void>;
+    release(): void;
+    /**
+     * Number of permits currently checked out. For tests and instrumentation
+     * only; do not branch on this in production logic.
+     */
+    get inFlight(): number;
+    /**
+     * Number of waiters queued. For tests and instrumentation only.
+     */
+    get pending(): number;
+}
+/**
+ * Run `items` through `producer` concurrently, capping in-flight calls
+ * at `limit`. Returns results in input order (same shape as
+ * `Promise.all(items.map(producer))` — but bounded).
+ *
+ * `producer` may throw; the rejection propagates after in-flight work
+ * settles. Other items continue running so the rejection isn't masked
+ * by a Promise.all-style fast-fail leaving zombie pending work.
+ *
+ * Implementation detail: uses an internal `Semaphore(limit)`; callers
+ * who need to share a permit pool across multiple `runWithLimit` calls
+ * (e.g. crawler global RPC cap) should use the `Semaphore` class
+ * directly via `acquire`/`release`.
+ */
+export declare function runWithLimit<T, R>(items: readonly T[], limit: number, producer: (item: T, index: number) => Promise<R>): Promise<R[]>;
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/discover/concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../../src/discover/concurrency.ts"],"names":[],"mappings":"AAiBA;;;;;;;;GAQG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,KAAK,CAAyB;gBAE1B,GAAG,EAAE,MAAM;IASjB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAa9B,OAAO,IAAI,IAAI;IAOf;;;OAGG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,MAAM,CAEpB;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,CAAC,EACrC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAC/C,OAAO,CAAC,CAAC,EAAE,CAAC,CAgCd"}

package/dist/discover/concurrency.js

@@ -0,0 +1,113 @@
+/**
+ * Bounded concurrency primitives for the Firestore discover_paths crawler.
+ *
+ * Phase 0.3 of the validation plan locked layered BFS with `Promise.all`-per-
+ * layer as the production strategy (38× faster than serial DFS on the
+ * representative corpus). This module provides the two pieces every layer
+ * needs:
+ *
+ *   - `Semaphore` — FIFO-ordered counting semaphore with `acquire`/`release`.
+ *   - `runWithLimit` — ergonomic wrapper that maps a list of async producers
+ *     through the semaphore and resolves to the ordered results.
+ *
+ * Kept self-contained so the `firestore/discover` subsystem owns its own
+ * concurrency contract.
+ */
+'use strict';
+/**
+ * FIFO counting semaphore. `acquire()` resolves immediately while
+ * fewer than `max` permits are checked out, otherwise it queues until
+ * a `release()` frees a slot. Waiters are served in arrival order.
+ *
+ * `release()` without a prior `acquire()` is a no-op (does not go
+ * negative). This is intentional — it lets defensive `try/finally`
+ * release in error paths without bookkeeping.
+ */
+export class Semaphore {
+    max;
+    active = 0;
+    queue = [];
+    constructor(max) {
+        if (!Number.isInteger(max) || max < 1) {
+            throw new RangeError(`Semaphore: max must be a positive integer, got ${max}`);
+        }
+        this.max = max;
+    }
+    async acquire() {
+        if (this.active < this.max) {
+            this.active++;
+            return;
+        }
+        return new Promise((resolve) => {
+            this.queue.push(() => {
+                this.active++;
+                resolve();
+            });
+        });
+    }
+    release() {
+        if (this.active === 0)
+            return; // never go negative
+        this.active--;
+        const next = this.queue.shift();
+        if (next)
+            next();
+    }
+    /**
+     * Number of permits currently checked out. For tests and instrumentation
+     * only; do not branch on this in production logic.
+     */
+    get inFlight() {
+        return this.active;
+    }
+    /**
+     * Number of waiters queued. For tests and instrumentation only.
+     */
+    get pending() {
+        return this.queue.length;
+    }
+}
+/**
+ * Run `items` through `producer` concurrently, capping in-flight calls
+ * at `limit`. Returns results in input order (same shape as
+ * `Promise.all(items.map(producer))` — but bounded).
+ *
+ * `producer` may throw; the rejection propagates after in-flight work
+ * settles. Other items continue running so the rejection isn't masked
+ * by a Promise.all-style fast-fail leaving zombie pending work.
+ *
+ * Implementation detail: uses an internal `Semaphore(limit)`; callers
+ * who need to share a permit pool across multiple `runWithLimit` calls
+ * (e.g. crawler global RPC cap) should use the `Semaphore` class
+ * directly via `acquire`/`release`.
+ */
+export async function runWithLimit(items, limit, producer) {
+    if (!Number.isInteger(limit) || limit < 1) {
+        throw new RangeError(`runWithLimit: limit must be a positive integer, got ${limit}`);
+    }
+    if (items.length === 0)
+        return [];
+    const sem = new Semaphore(limit);
+    const results = new Array(items.length);
+    const errors = [];
+    await Promise.all(items.map(async (item, index) => {
+        await sem.acquire();
+        try {
+            results[index] = await producer(item, index);
+        }
+        catch (error) {
+            errors.push({ index, error });
+        }
+        finally {
+            sem.release();
+        }
+    }));
+    if (errors.length > 0) {
+        // Surface the first error in input order — agents/tests can rely on
+        // a deterministic surface even when multiple producers throw.
+        errors.sort((a, b) => a.index - b.index);
+        throw errors[0].error;
+    }
+    return results;
+}
+//# sourceMappingURL=concurrency.js.map

package/dist/discover/concurrency.js.map

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

package/dist/discover/crawler-adapter.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Adapter wrapping {@link LocalEnvironment} so it satisfies the
+ * `CrawlerFirestore` + `CollectionGroupCapableFirestore` contracts that
+ * `firestore_discover_paths` and `firestore_find_collection_group`
+ * depend on.
+ *
+ * Why this exists:
+ *   The discover tools normally target firebase-admin's `Firestore`
+ *   over the network. Driving them against {@link LocalEnvironment}
+ *   instead lets unit + integration tests run hermetically — no
+ *   service-account credentials, no live project, no permissions
+ *   surprises. The adapter:
+ *     - derives collection IDs from the in-memory keyspace
+ *     - synthesizes `_fieldsProto` via {@link ../simulator/wire-encoder}
+ *       so the crawler's wire-format reader sees what it expects
+ *     - implements `collectionGroup(id)` by scanning paths whose
+ *       penultimate segment matches `id`
+ *
+ * Phantom parent docs (Item 4):
+ *   `LocalEnvironment.listDocuments(parent)` synthesizes empty records
+ *   for any parent id whose only existence is via descendant paths. This
+ *   adapter forwards those phantoms as doc refs whose `.get()` returns
+ *   an empty `_fieldsProto` — matching how live Firestore exposes parent
+ *   docs that have subcollections but no fields. Phantom refs are
+ *   detected via the `phantom` flag on the list result.
+ *
+ * Limitations:
+ *   - `collectionGroup().select()` is a no-op chainable: the discover
+ *     tools call `.select()` with no args (refs only), so projection
+ *     semantics aren't needed.
+ */
+import type { LocalEnvironment } from 'pyric/sandbox/internal';
+import type { CrawlerCollectionRef, CrawlerDocumentRef, CrawlerFirestore, CollectionGroupCapableFirestore, CollectionGroupQuery } from './firestore-source.js';
+/**
+ * Wrap a {@link LocalEnvironment} as a Firestore root that satisfies
+ * the discover/crawler + find-collection-group contracts.
+ */
+export declare class LocalEnvironmentCrawlerAdapter implements CrawlerFirestore, CollectionGroupCapableFirestore {
+    private readonly env;
+    constructor(env: LocalEnvironment);
+    listCollections(): Promise<CrawlerCollectionRef[]>;
+    collection(path: string): CrawlerCollectionRef;
+    doc(path: string): CrawlerDocumentRef;
+    collectionGroup(collectionId: string): CollectionGroupQuery;
+    private makeCollectionRef;
+    private makeDocRef;
+}
+//# sourceMappingURL=crawler-adapter.d.ts.map

package/dist/discover/crawler-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crawler-adapter.d.ts","sourceRoot":"","sources":["../../src/discover/crawler-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,+BAA+B,EAC/B,oBAAoB,EAGrB,MAAM,uBAAuB,CAAC;AAG/B;;;GAGG;AACH,qBAAa,8BACX,YAAW,gBAAgB,EAAE,+BAA+B;IAEhD,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,gBAAgB;IAE5C,eAAe,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAIxD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB;IAI9C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB;IAIrC,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB;IAkB3D,OAAO,CAAC,iBAAiB;IAmBzB,OAAO,CAAC,UAAU;CA0BnB"}

package/dist/discover/crawler-adapter.js

@@ -0,0 +1,92 @@
+import { encodeFieldsProto } from 'pyric/sandbox/internal';
+/**
+ * Wrap a {@link LocalEnvironment} as a Firestore root that satisfies
+ * the discover/crawler + find-collection-group contracts.
+ */
+export class LocalEnvironmentCrawlerAdapter {
+    env;
+    constructor(env) {
+        this.env = env;
+    }
+    async listCollections() {
+        return this.env.listRootCollections().map((id) => this.makeCollectionRef(id));
+    }
+    collection(path) {
+        return this.makeCollectionRef(path);
+    }
+    doc(path) {
+        return this.makeDocRef(path);
+    }
+    collectionGroup(collectionId) {
+        // Scan the keyspace for docs whose penultimate segment equals `collectionId`.
+        // A document path is always odd-segments-deep — collection/doc/collection/doc...
+        // so segments.length is even and segments[length-2] is the host collection ID.
+        const matches = [];
+        for (const path of Object.keys(this.env.snapshot())) {
+            const segments = path.split('/');
+            if (segments.length < 2 || segments.length % 2 !== 0)
+                continue;
+            const hostId = segments[segments.length - 2];
+            if (hostId !== collectionId)
+                continue;
+            const parentPath = segments.slice(0, -1).join('/');
+            matches.push({ ref: { parent: { path: parentPath } } });
+        }
+        return makeChainableQuery(matches);
+    }
+    // ─── Internal factories ───────────────────────────────────────────────
+    makeCollectionRef(path) {
+        const id = path.split('/').pop();
+        const env = this.env;
+        const adapter = this;
+        return {
+            id,
+            path,
+            async listDocuments() {
+                return env.listDocuments(path).map(({ path: docPath, data, phantom }) => 
+                // Phantom parents: pass `{}` so `.get()` materializes an empty
+                // `_fieldsProto`, matching live Firestore's parent-with-only-
+                // subcollections shape. We feed `knownData` either way so the
+                // crawler avoids a redundant lookup against a non-existent doc.
+                adapter.makeDocRef(docPath, phantom ? {} : data));
+            },
+        };
+    }
+    makeDocRef(path, knownData) {
+        const id = path.split('/').pop();
+        const env = this.env;
+        const adapter = this;
+        return {
+            id,
+            path,
+            async listCollections() {
+                return env
+                    .listSubcollections(path)
+                    .map((subId) => adapter.makeCollectionRef(`${path}/${subId}`));
+            },
+            async get() {
+                // Prefer cached data from the listDocuments traversal; fall back to
+                // a fresh lookup for ad-hoc doc() refs (e.g., the resume path).
+                const data = knownData ?? env.getDocument(path) ?? {};
+                return {
+                    _fieldsProto: encodeFieldsProto(data),
+                    ref: { path },
+                };
+            },
+        };
+    }
+}
+/**
+ * Build a chainable {@link CollectionGroupQuery} over an in-memory match
+ * list. Mirrors the firebase-admin `Query` shape used by `findCollectionGroup`:
+ * `select()` is a no-op (refs only); `limit(n)` truncates; `get()` resolves.
+ */
+function makeChainableQuery(matches) {
+    const build = (current) => ({
+        select: () => build(current),
+        limit: (n) => build(current.slice(0, n)),
+        get: async () => ({ docs: current }),
+    });
+    return build(matches);
+}
+//# sourceMappingURL=crawler-adapter.js.map

package/dist/discover/crawler-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crawler-adapter.js","sourceRoot":"","sources":["../../src/discover/crawler-adapter.ts"],"names":[],"mappings":"AAyCA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;GAGG;AACH,MAAM,OAAO,8BAA8B;IAGZ;IAA7B,YAA6B,GAAqB;QAArB,QAAG,GAAH,GAAG,CAAkB;IAAG,CAAC;IAEtD,KAAK,CAAC,eAAe;QACnB,OAAO,IAAI,CAAC,GAAG,CAAC,mBAAmB,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,EAAE,CAAC,CAAC,CAAC;IAChF,CAAC;IAED,UAAU,CAAC,IAAY;QACrB,OAAO,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,eAAe,CAAC,YAAoB;QAClC,8EAA8E;QAC9E,iFAAiF;QACjF,+EAA+E;QAC/E,MAAM,OAAO,GAA8B,EAAE,CAAC;QAC9C,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC;YACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACjC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC;gBAAE,SAAS;YAC/D,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;YAC9C,IAAI,MAAM,KAAK,YAAY;gBAAE,SAAS;YACtC,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACnD,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC;QAC1D,CAAC;QACD,OAAO,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IAED,yEAAyE;IAEjE,iBAAiB,CAAC,IAAY;QACpC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAG,CAAC;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACrB,MAAM,OAAO,GAAG,IAAI,CAAC;QACrB,OAAO;YACL,EAAE;YACF,IAAI;YACJ,KAAK,CAAC,aAAa;gBACjB,OAAO,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;gBACtE,+DAA+D;gBAC/D,8DAA8D;gBAC9D,8DAA8D;gBAC9D,gEAAgE;gBAChE,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CACjD,CAAC;YACJ,CAAC;SACF,CAAC;IACJ,CAAC;IAEO,UAAU,CAChB,IAAY,EACZ,SAAmC;QAEnC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAG,CAAC;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACrB,MAAM,OAAO,GAAG,IAAI,CAAC;QACrB,OAAO;YACL,EAAE;YACF,IAAI;YACJ,KAAK,CAAC,eAAe;gBACnB,OAAO,GAAG;qBACP,kBAAkB,CAAC,IAAI,CAAC;qBACxB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC;YACnE,CAAC;YACD,KAAK,CAAC,GAAG;gBACP,oEAAoE;gBACpE,gEAAgE;gBAChE,MAAM,IAAI,GAAG,SAAS,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACtD,OAAO;oBACL,YAAY,EAAE,iBAAiB,CAAC,IAAI,CAAC;oBACrC,GAAG,EAAE,EAAE,IAAI,EAAE;iBACd,CAAC;YACJ,CAAC;SACF,CAAC;IACJ,CAAC;CACF;AAED;;;;GAIG;AACH,SAAS,kBAAkB,CAAC,OAAkC;IAC5D,MAAM,KAAK,GAAG,CAAC,OAAkC,EAAwB,EAAE,CAAC,CAAC;QAC3E,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC;QAC5B,KAAK,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAChD,GAAG,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;KACrC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC;AACxB,CAAC"}