@caelo-cms/provisioning 0.10.43 → 0.10.46

package/dist/upgrade/health.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Deep health check after an app-roll (epic #696).
+ *
+ * Cloud Run's readiness only proves the new container listens on its port. A
+ * revision can do that while it cannot reach the database, runs against a
+ * schema its migrations never reached, or is not the release the roll asked
+ * for. After both services moved, the app-roll asks them:
+ *
+ *   - admin   `GET /_caelo/health?deep=1` → `{ ok, version, migrations }`:
+ *             both databases reachable as the expected roles, and every
+ *             migration the image ships recorded as applied.
+ *   - gateway `GET /api/_caelo/health?deep=1` → `{ ok, version }`: its
+ *             database logins work. Under `/api/` because that is the only
+ *             path the gcp load balancer routes to the gateway.
+ *
+ * Both answer with no secrets and no raw database errors. The admin sits
+ * behind IAP, so the probe signs an IAP credential as the install's MCP
+ * service account (`caelo-mcp@`, mcp-iap.ts) exactly like the MCP shim does
+ * (packages/mcp-server/src/ingress-auth.ts): a JWT with `aud` = the admin
+ * origin + `/*`, signed through the IAM Credentials API by whoever runs the
+ * upgrade (the converge step lets every IAP-allowlisted operator sign as
+ * that account). The gateway is public by design and gets no credential.
+ *
+ * Before anything changes, {@link HealthProbe.baseline} proves the probe can
+ * reach both services at all. Otherwise a DNS, certificate or IAP problem
+ * would only show after migrations, as a "failed" health check that rolls a
+ * healthy release back.
+ */
+import type { GcloudRunner, Sleep } from "../gcloud-retry.js";
+import type { HttpFetch } from "../runtime-secrets.js";
+export type HealthOutcome = {
+    readonly ok: true;
+    readonly detail: string;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+export interface HealthProbe {
+    /** Reach both services as they serve now (before any change). */
+    baseline(): Promise<HealthOutcome>;
+    /**
+     * Deep-check both services after the roll, retrying while the new
+     * revisions warm up. `version` is the release the roll targets (null when
+     * a channel tag like `latest` was rolled: then both must report the same
+     * version).
+     */
+    deep(expect: {
+        readonly version: string | null;
+    }): Promise<HealthOutcome>;
+}
+/**
+ * Judge the admin's deep health answer.
+ *
+ * @returns the version the admin runs on success
+ */
+export declare function evaluateAdminDeepHealth(status: number, text: string, expectedVersion: string | null): {
+    ok: true;
+    version: string;
+    detail: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** Judge the gateway's deep health answer against the version the admin runs. */
+export declare function evaluateGatewayDeepHealth(status: number, text: string, expectedVersion: string): HealthOutcome;
+/** Where the probe reaches the install. */
+export interface HealthTarget {
+    readonly provider: "gcp" | "gcp-firebase";
+    readonly projectId: string;
+    readonly domain: string;
+    /** The admin service's `run.app` URL (IAP-gated on gcp-firebase). */
+    readonly adminServiceUrl: string;
+    /** The gateway service's `run.app` URL (public on gcp-firebase). */
+    readonly gatewayServiceUrl: string;
+}
+/**
+ * The origins the probe calls. On gcp the admin's IAP lives on the load
+ * balancer (`admin.<domain>`) and the gateway's ingress is load-balancer-only
+ * (`<domain>/api/*`); on gcp-firebase both `run.app` URLs are reachable — the
+ * admin's through Cloud Run's own IAP, the gateway's publicly.
+ */
+export declare function healthOrigins(target: HealthTarget): {
+    admin: string;
+    gateway: string;
+};
+export interface HealthProbeDeps {
+    readonly run: GcloudRunner;
+    readonly http: HttpFetch;
+    readonly sleep: Sleep;
+    /** Deep-check attempts while the new revisions warm up (default 12). */
+    readonly attempts?: number;
+    /** Pause between attempts in ms (default 5000). */
+    readonly intervalMs?: number;
+    /** Seconds since epoch. */
+    readonly now?: () => number;
+}
+/** The IAP-backed probe of a gcp / gcp-firebase install. */
+export declare function createIapHealthProbe(target: HealthTarget, deps: HealthProbeDeps): HealthProbe;
+//# sourceMappingURL=health.d.ts.map

package/dist/upgrade/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/upgrade/health.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,QAAQ,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;IACnC;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC3E;AAuBD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,GAAG,IAAI,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAuC9E;AAED,iFAAiF;AACjF,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,GACtB,aAAa,CAgBf;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,KAAK,GAAG,cAAc,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,oEAAoE;IACpE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAOtF;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,2BAA2B;IAC3B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAKD,4DAA4D;AAC5D,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,eAAe,GAAG,WAAW,CAqH7F"}

package/dist/upgrade/health.js

@@ -0,0 +1,214 @@
+// SPDX-License-Identifier: MPL-2.0
+import { mcpIapServiceAccountEmail } from "../gcp-names.js";
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Judge the admin's deep health answer.
+ *
+ * @returns the version the admin runs on success
+ */
+export function evaluateAdminDeepHealth(status, text, expectedVersion) {
+    const body = parseJson(text);
+    if (!body)
+        return { ok: false, error: `admin answered HTTP ${status} without JSON` };
+    const m = body.migrations;
+    // Pending migrations come with a 503; name them rather than "unhealthy".
+    for (const [db, state] of [
+        ["cms_admin", m?.admin],
+        ["cms_public", m?.public],
+    ]) {
+        if (state && state.pending !== 0) {
+            return {
+                ok: false,
+                error: `${db} is missing ${state.pending} migration(s) the new admin image ships (applied head: ${state.head ?? "none"})`,
+            };
+        }
+    }
+    if (status !== 200 || body.ok !== true) {
+        const why = body.error ? `${body.error.kind ?? "?"}: ${body.error.message ?? ""}` : "no reason";
+        return { ok: false, error: `admin reports unhealthy (HTTP ${status}, ${why})` };
+    }
+    if (!body.version)
+        return { ok: false, error: "admin reported no version" };
+    if (expectedVersion !== null && body.version !== expectedVersion) {
+        return {
+            ok: false,
+            error: `admin runs ${body.version}, the roll targeted ${expectedVersion}`,
+        };
+    }
+    if (!m?.admin || !m.public) {
+        return {
+            ok: false,
+            error: "admin did not report its migration state (its image predates the deep health check; pass --skip-health-check to roll to such a release)",
+        };
+    }
+    return {
+        ok: true,
+        version: body.version,
+        detail: `admin ${body.version}, migrations at ${m.admin.head ?? "?"} / ${m.public.head ?? "?"}`,
+    };
+}
+/** Judge the gateway's deep health answer against the version the admin runs. */
+export function evaluateGatewayDeepHealth(status, text, expectedVersion) {
+    const body = parseJson(text);
+    if (!body)
+        return { ok: false, error: `gateway answered HTTP ${status} without JSON` };
+    if (status !== 200 || body.ok !== true) {
+        return {
+            ok: false,
+            error: `gateway reports unhealthy (HTTP ${status}, ${body.error?.kind ?? "no reason"})`,
+        };
+    }
+    if (body.version !== expectedVersion) {
+        return {
+            ok: false,
+            error: `gateway runs ${body.version ?? "an unknown version"}, the admin runs ${expectedVersion}`,
+        };
+    }
+    return { ok: true, detail: `gateway ${body.version}` };
+}
+/**
+ * The origins the probe calls. On gcp the admin's IAP lives on the load
+ * balancer (`admin.<domain>`) and the gateway's ingress is load-balancer-only
+ * (`<domain>/api/*`); on gcp-firebase both `run.app` URLs are reachable — the
+ * admin's through Cloud Run's own IAP, the gateway's publicly.
+ */
+export function healthOrigins(target) {
+    return target.provider === "gcp"
+        ? { admin: `https://admin.${target.domain}`, gateway: `https://${target.domain}` }
+        : {
+            admin: new URL(target.adminServiceUrl).origin,
+            gateway: new URL(target.gatewayServiceUrl).origin,
+        };
+}
+const JWT_LIFETIME_S = 600;
+const IAM_CREDENTIALS = "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts";
+/** The IAP-backed probe of a gcp / gcp-firebase install. */
+export function createIapHealthProbe(target, deps) {
+    const origins = healthOrigins(target);
+    const signer = mcpIapServiceAccountEmail(target.projectId);
+    const attempts = deps.attempts ?? 12;
+    const intervalMs = deps.intervalMs ?? 5_000;
+    const now = deps.now ?? (() => Math.floor(Date.now() / 1000));
+    /**
+     * A JWT IAP accepts for the admin origin, signed as the MCP service
+     * account. Never throws: a transport failure is a failed outcome, so the
+     * retries and the app-roll's rollback still run.
+     */
+    async function iapToken() {
+        try {
+            return await signIapToken();
+        }
+        catch (e) {
+            return {
+                ok: false,
+                error: `could not sign an IAP credential as ${signer}: ${e instanceof Error ? e.message : String(e)}`,
+            };
+        }
+    }
+    async function signIapToken() {
+        const token = await deps.run(["auth", "print-access-token"]);
+        const bearer = token.ok ? token.stdout.trim() : "";
+        if (!bearer) {
+            return {
+                ok: false,
+                error: `gcloud auth print-access-token: ${token.stderr.trim() || "empty"}`,
+            };
+        }
+        const iat = now();
+        const res = await deps.http(`${IAM_CREDENTIALS}/${encodeURIComponent(signer)}:signJwt`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${bearer}`, "Content-Type": "application/json" },
+            body: JSON.stringify({
+                payload: JSON.stringify({
+                    iss: signer,
+                    sub: signer,
+                    aud: `${origins.admin}/*`,
+                    iat,
+                    exp: iat + JWT_LIFETIME_S,
+                }),
+            }),
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            return {
+                ok: false,
+                error: `could not sign an IAP credential as ${signer} (HTTP ${res.status}). Your account needs roles/iam.serviceAccountTokenCreator on it — upgrade's converge step grants it to every IAP-allowlisted user. ${text.slice(0, 300)}`,
+            };
+        }
+        const jwt = parseJson(text)?.signedJwt;
+        return jwt ? { ok: true, jwt } : { ok: false, error: "signJwt returned no signedJwt" };
+    }
+    async function get(url, headers) {
+        try {
+            const res = await deps.http(url, { method: "GET", headers });
+            return { reached: true, status: res.status, text: await res.text() };
+        }
+        catch (e) {
+            return { reached: false, error: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    return {
+        async baseline() {
+            const token = await iapToken();
+            if (!token.ok)
+                return token;
+            const auth = { Authorization: `Bearer ${token.jwt}` };
+            const admin = await get(`${origins.admin}/_caelo/health`, auth);
+            if (!admin.reached) {
+                return { ok: false, error: `admin unreachable at ${origins.admin}: ${admin.error}` };
+            }
+            // The serving (old) admin answers its shallow health JSON. Anything
+            // else — IAP's login redirect, a 401/403, an HTML error page — means
+            // the probe would not see the new revision either.
+            const body = parseJson(admin.text);
+            if (!body?.version) {
+                return {
+                    ok: false,
+                    error: `admin at ${origins.admin} did not answer its health check (HTTP ${admin.status}); IAP may not admit ${signer}`,
+                };
+            }
+            const gateway = await get(`${origins.gateway}/api/_caelo/health`, {});
+            if (!gateway.reached) {
+                return { ok: false, error: `gateway unreachable at ${origins.gateway}: ${gateway.error}` };
+            }
+            return { ok: true, detail: `admin ${body.version} and gateway reachable` };
+        },
+        async deep(expect) {
+            let last = { ok: false, error: "no attempt made" };
+            for (let i = 0; i < attempts; i++) {
+                if (i > 0)
+                    await deps.sleep(intervalMs);
+                last = await deepOnce(expect.version);
+                if (last.ok)
+                    return last;
+            }
+            return last;
+        },
+    };
+    async function deepOnce(expectedVersion) {
+        const token = await iapToken();
+        if (!token.ok)
+            return token;
+        const admin = await get(`${origins.admin}/_caelo/health?deep=1`, {
+            Authorization: `Bearer ${token.jwt}`,
+        });
+        if (!admin.reached)
+            return { ok: false, error: `admin unreachable: ${admin.error}` };
+        const a = evaluateAdminDeepHealth(admin.status, admin.text, expectedVersion);
+        if (!a.ok)
+            return a;
+        const gateway = await get(`${origins.gateway}/api/_caelo/health?deep=1`, {});
+        if (!gateway.reached)
+            return { ok: false, error: `gateway unreachable: ${gateway.error}` };
+        const g = evaluateGatewayDeepHealth(gateway.status, gateway.text, a.version);
+        return g.ok ? { ok: true, detail: `${a.detail}; ${g.detail}` } : g;
+    }
+}
+//# sourceMappingURL=health.js.map

package/dist/upgrade/health.js.map

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

package/dist/upgrade/release-images.d.ts

@@ -0,0 +1,125 @@
+/** The two Caelo services shipped as release images. */
+export type ReleaseService = "admin" | "gateway";
+/** The services every install runs, in roll order (admin first, then gateway). */
+export declare const RELEASE_SERVICES: readonly ReleaseService[];
+/** GHCR — the canonical registry (release-images.yml), used by self-hosted Compose. */
+export declare const GHCR_REGISTRY = "ghcr.io";
+export declare const GHCR_NAMESPACE = "caelo-cms";
+/** `ghcr.io/caelo-cms/<service>` — the repository of a service's release image. */
+export declare function ghcrRepository(service: ReleaseService): string;
+/** Where Caelo's release workflows live; every signer identity starts here. */
+export declare const RELEASE_WORKFLOWS_URL = "https://github.com/caelo-cms/caelo-cms/.github/workflows";
+/**
+ * The keyless signer cosign must see on every release image: one of the two
+ * release workflows of the caelo-cms repo, via GitHub's OIDC issuer. A
+ * different identity means a registry compromise, a typosquat, or a fork's
+ * image — every caller refuses to run it.
+ */
+export declare const RELEASE_SIGNER_IDENTITY_REGEXP = "https://github.com/caelo-cms/caelo-cms/.github/workflows/(release-images|release).yml@.*";
+/** OIDC issuer of every Caelo release signature — images and release manifest (GitHub Actions). */
+export declare const RELEASE_OIDC_ISSUER = "https://token.actions.githubusercontent.com";
+/**
+ * The `cosign verify` argv for one image reference pinned by digest.
+ *
+ * @example cosignVerifyArgv("ghcr.io/caelo-cms/admin@sha256:…")
+ */
+export declare function cosignVerifyArgv(imageRef: string): string[];
+/** A `sha256:<64 hex>` image / blob digest. */
+export declare const IMAGE_DIGEST: RegExp;
+/** Whether `s` is a well-formed `sha256:<64 hex>` digest. */
+export declare function isImageDigest(s: string): boolean;
+/**
+ * `s` rebuilt character by character from a constant alphabet when it is a
+ * well-formed digest, else null. The digest comes from a registry's HTTP
+ * header and ends up in files (release.json, the Compose file); rebuilding
+ * it — rather than passing the checked string on — guarantees that nothing
+ * but `sha256:` and 64 hex digits from our own constants is ever written.
+ */
+export declare function canonicalDigest(s: string): string | null;
+/**
+ * A semver release tag (`v0.10.43`, `0.11.0-rc.1`) rebuilt from a constant
+ * alphabet, else null. The tag comes from the GitHub API and is recorded in
+ * release.json, so — like {@link canonicalDigest} — only our own characters
+ * reach the file.
+ */
+export declare function canonicalReleaseTag(s: string): string | null;
+/**
+ * The registry tag for an upgrade request: an explicit version (a leading
+ * `v` dropped, as release tags are `vX.Y.Z` but image tags `X.Y.Z`), else
+ * the channel's moving tag, else `latest`.
+ */
+export declare function releaseTag(opts: {
+    readonly version?: string;
+    readonly channel?: "stable" | "rc" | "beta";
+}): string;
+export type DigestResult = {
+    ok: true;
+    digest: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Resolve `<registryHost>/<repository>:<tag>` to the digest a `docker pull`
+ * of that tag would fetch, through the Docker Registry V2 API anonymously.
+ *
+ * The images are public, but registries differ in how they say so: Artifact
+ * Registry answers the manifest HEAD directly, GHCR answers 401 with a
+ * `WWW-Authenticate: Bearer realm=…,service=…,scope=…` challenge whose realm
+ * hands out an anonymous pull token. Both paths are handled here, so callers
+ * never need registry credentials (end users have none for Caelo's).
+ *
+ * @param repository - path below the host, e.g. `caelo-cms/admin`.
+ */
+export declare function resolveRegistryDigest(registryHost: string, repository: string, tag: string, fetchImpl?: typeof fetch): Promise<DigestResult>;
+/**
+ * The key/value pairs of a `Bearer k="v",k2="v2"` challenge, or null when
+ * it is not a Bearer challenge.
+ *
+ * @example parseBearerChallenge('Bearer realm="https://ghcr.io/token",service="ghcr.io"')
+ * // → { realm: "https://ghcr.io/token", service: "ghcr.io" }
+ */
+export declare function parseBearerChallenge(header: string | null): Record<string, string> | null;
+/**
+ * The tag of the newest stable Caelo release on GitHub (e.g. `v0.10.43`),
+ * or an error reason. Used to turn "upgrade to latest" into an exact
+ * version before anything is resolved, so the version an install records is
+ * a real release, never the moving `latest` tag.
+ */
+export declare function fetchLatestReleaseTag(fetchImpl?: typeof fetch): Promise<{
+    ok: true;
+    tag: string;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/** Where Caelo's release images live (public Artifact Registry repo). */
+export declare const RELEASE_REGISTRY: {
+    readonly region: "europe-west1";
+    readonly project: "caelo-website";
+    readonly repo: "caelo-cms-images";
+};
+/** The digest-pinned reference of release image `slug@digest` in the Artifact Registry mirror. */
+export declare function releaseImageRef(slug: string, digest: string): string;
+/**
+ * Resolve a tag (e.g. `0.2.6` or `latest`) to its digest in the public
+ * Artifact Registry mirror, anonymously through the Registry V2 API
+ * ({@link resolveRegistryDigest}) — the caller's gcloud session needs no IAM
+ * access to the registry's project.
+ */
+export declare function resolveTagDigest(image: string, tag: string): Promise<DigestResult>;
+/**
+ * P21 ship 4 — verify cosign keyless signatures on every planned
+ * image digest. Sigstore Fulcio + Rekor; the certificate identity
+ * must match the Caelo release-images workflow. A mismatch means
+ * either a registry compromise, a typosquat, or the operator pointed
+ * at a fork's image. Either way: refuse to roll.
+ *
+ * Returns true on success (or skips with a clear error and returns
+ * false if cosign isn't installed / verification fails).
+ */
+export declare function verifyCosignAll(plans: readonly {
+    readonly slug: string;
+    readonly digest: string;
+}[]): Promise<boolean>;
+//# sourceMappingURL=release-images.d.ts.map

package/dist/upgrade/release-images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-images.d.ts","sourceRoot":"","sources":["../../src/upgrade/release-images.ts"],"names":[],"mappings":"AAkBA,wDAAwD;AACxD,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,CAAC;AAEjD,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,EAAE,SAAS,cAAc,EAAyB,CAAC;AAEhF,uFAAuF;AACvF,eAAO,MAAM,aAAa,YAAY,CAAC;AACvC,eAAO,MAAM,cAAc,cAAc,CAAC;AAE1C,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAE9D;AAED,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,6DAA6D,CAAC;AAEhG;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,6FAA6D,CAAC;AAEzG,mGAAmG;AACnG,eAAO,MAAM,mBAAmB,gDAAgD,CAAC;AAEjF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAU3D;AAED,+CAA+C;AAC/C,eAAO,MAAM,YAAY,QAA0B,CAAC;AAEpD,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEhD;AAID;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIxD;AAKD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG5D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,IAAI,GAAG,MAAM,CAAC;CAC7C,GAAG,MAAM,CAKT;AAED,MAAM,MAAM,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAUxF;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,YAAY,CAAC,CAsBvB;AAwBD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAQzF;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAepE;AAED,yEAAyE;AACzE,eAAO,MAAM,gBAAgB;;;;CAInB,CAAC;AAEX,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGpE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAGlF;AA2DD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,GACnE,OAAO,CAAC,OAAO,CAAC,CA+BlB"}