typekro 0.23.0 → 0.24.1

package/dist/factories/clickstack/types.js

@@ -0,0 +1,302 @@
+/**
+ * ClickStack (HyperDX) Type Definitions
+ *
+ * ArkType schemas as the single source of truth for config shapes, with types
+ * inferred via `typeof Schema.infer` (mirrors the clickhouse/dagster families).
+ *
+ * Wraps the OFFICIAL ClickStack Helm chart (MIT):
+ * - Chart: `clickstack` 3.0.x from https://clickhouse.github.io/ClickStack-helm-charts
+ *   (classic Helm repo, NOT OCI). The old hyperdxio/helm-charts repo is archived
+ *   and its `hdx-oss-v2` chart is deprecated — do not use them.
+ * - Components: the HyperDX app (UI + API + OpAMP server on 4320 that remotely
+ *   configures the collector), an OTel gateway collector (the chart's only Helm
+ *   dependency: the official `opentelemetry-collector` subchart, alias
+ *   `otel-collector`), and schema "goose" migrations run by the collector at
+ *   startup that auto-create `otel_logs` / `otel_traces` / `otel_metrics_*` /
+ *   `hyperdx_sessions`.
+ *
+ * EXTERNAL CLICKHOUSE ONLY: this family hard-codes `clickhouse.enabled: false`
+ * and `mongodb.enabled: false`. The chart's bundled ClickHouse/Keeper and
+ * MongoDB are CRDs owned by the separate `clickstack-operators` prerequisite
+ * chart (ClickHouse Inc.'s own operator + a MongoDB community operator), which
+ * we deliberately do NOT install — its ClickHouse CRDs would collide with the
+ * Altinity clickhouse-operator that manages our ClickHouseInstallation.
+ *
+ * BUILD-TIME vs RUNTIME SPLIT: choices that decide WHICH resources exist or
+ * how values trees are shaped (the Mongo mode, internal-Mongo storage, static
+ * raw chart values) are CONSTRUCTION-time options on
+ * `makeClickstackBootstrap(...)` / `makeClickstackK8sTelemetry(...)` — plain
+ * JS branches on them are safe because they are always concrete. The runtime
+ * spec (these schemas) carries only proxy-safe VALUES (names, namespaces,
+ * endpoints, versions, credentials) that serialize cleanly as CEL refs in KRO
+ * mode.
+ *
+ * SCHEMA / REPLICATION CAVEAT: the collector's auto-migrations create plain
+ * single-node MergeTree tables — fine for a 1-replica CHI (dev-first sizing);
+ * multi-replica / `ON CLUSTER` schemas are NOT supported by ClickStack's
+ * tooling. Revisit before scaling the external ClickHouse beyond one replica.
+ *
+ * @see https://github.com/ClickHouse/ClickStack-helm-charts
+ * @see https://clickhouse.com/docs/use-cases/observability/clickstack
+ */
+import { type } from 'arktype';
+// ============================================================================
+// ClickHouse version-coupling guidance
+// ============================================================================
+/**
+ * Loose ClickHouse version coupling facts for the external-ClickHouse mode,
+ * exported for downstream platform layers that own the CHI sizing/versioning.
+ *
+ * Sources (verified 2026-07-06 against ClickHouse/ClickStack-helm-charts main):
+ * - The chart vendors ClickHouse `25.7-alpine` for its (disabled here) bundled
+ *   cluster (charts/clickstack/values.yaml `clickhouse.cluster.spec.containerTemplate`).
+ * - ClickStack's seed schemas ship a "<26.2 compatibility" variant, so recent
+ *   25.x/26.x servers are accepted — the coupling is loose, not pinned.
+ * - The optional JSON-typed schema is gated behind the
+ *   `HYPERDX_OTEL_EXPORTER_CLICKHOUSE_JSON_ENABLE` env flag and wants
+ *   ClickHouse 25.3+ (native JSON type maturity).
+ */
+export const CLICKSTACK_CLICKHOUSE_GUIDANCE = {
+    /** ClickHouse version the chart vendors/tests against for its bundled cluster. */
+    chartVendoredClickHouseVersion: '25.7',
+    /** Minimum recommended ClickHouse version for an external cluster. */
+    minRecommendedClickHouseVersion: '25.3',
+    /** Env flag (in `hyperdx.config`) enabling the JSON-typed OTel schema. */
+    jsonSchemaFlag: 'HYPERDX_OTEL_EXPORTER_CLICKHOUSE_JSON_ENABLE',
+    /** Minimum ClickHouse version for the JSON-typed schema. */
+    jsonSchemaMinClickHouseVersion: '25.3',
+    /**
+     * The collector's goose migrations create single-node MergeTree tables only;
+     * multi-replica / ON CLUSTER schemas are not supported by ClickStack tooling.
+     */
+    singleNodeSchemaOnly: true,
+};
+// ============================================================================
+// Shared ArkType shapes
+// ============================================================================
+const resourceRequirementsShape = {
+    'requests?': { 'cpu?': 'string', 'memory?': 'string' },
+    'limits?': { 'cpu?': 'string', 'memory?': 'string' },
+};
+const imageShape = {
+    'repository?': 'string',
+    'tag?': 'string',
+    'pullPolicy?': '"Always" | "IfNotPresent" | "Never"',
+};
+// ============================================================================
+// Bootstrap runtime spec (external ClickHouse)
+// ============================================================================
+const bootstrapBaseShape = {
+    /** Release name for the Helm installation. */
+    name: 'string',
+    /** Namespace for the stack (default: 'clickstack'). */
+    'namespace?': 'string',
+    /** Chart version (default: '3.0.1'). */
+    'version?': 'string',
+    // SECRETS CAVEAT: `password`/`appPassword` below (and `apiKey` further
+    // down) travel as PLAINTEXT runtime spec values all the way into the
+    // generated HelmRelease's `spec.values.hyperdx.secrets.*` — a Kubernetes
+    // object stored in etcd, readable by anyone with read access to the
+    // HelmRelease/RGD instance (`kubectl get helmrelease -o yaml`), unlike
+    // `k8s-telemetry.ts`'s `apiKeySecret` (a `secretKeyRef` env var — the
+    // value never appears in any CR spec). There is currently NO
+    // existing-Secret / secretKeyRef alternative for these three fields.
+    // Treat them as no more protected than any other spec field; do not
+    // consider this family production-ready for credentials that need
+    // stronger-than-etcd-RBAC protection until that gap is closed.
+    /** External ClickHouse connection (REQUIRED — external-only build-around). */
+    clickhouse: {
+        /** DNS host of the external ClickHouse service (no scheme, no port). */
+        host: 'string',
+        /** Native TCP port (default: 9000) → `CLICKHOUSE_ENDPOINT`/`CLICKHOUSE_SERVER_ENDPOINT`. */
+        'nativePort?': 'number',
+        /** HTTP port (default: 8123) → HyperDX UI `defaultConnections` host. */
+        'httpPort?': 'number',
+        /** OTel export target database (default: 'default') → `HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE`. */
+        'database?': 'string',
+        /** Ingest/collector user (default: 'default') → `hyperdx.config.CLICKHOUSE_USER`. Needs SELECT,INSERT,CREATE,SHOW on the database. */
+        'username?': 'string',
+        /** Ingest/collector password → `hyperdx.secrets.CLICKHOUSE_PASSWORD` (default: ''). PLAINTEXT in the HelmRelease spec — see the secrets caveat above. */
+        'password?': 'string',
+        /** Read-mostly UI user for HyperDX connections (default: `username`). Needs SHOW + SELECT. */
+        'appUsername?': 'string',
+        /** UI user password → `hyperdx.secrets.CLICKHOUSE_APP_PASSWORD` (default: `password`). PLAINTEXT in the HelmRelease spec — see the secrets caveat above. */
+        'appPassword?': 'string',
+    },
+    /** HyperDX ingestion API key → `hyperdx.secrets.HYPERDX_API_KEY`. PLAINTEXT in the HelmRelease spec — see the secrets caveat above `clickhouse`. */
+    'apiKey?': 'string',
+    /** HyperDX app (UI/API) conveniences. */
+    'hyperdx?': {
+        'replicas?': 'number',
+        'resources?': resourceRequirementsShape,
+        'image?': imageShape,
+        /** Public URL of the HyperDX UI → `hyperdx.config.FRONTEND_URL`. */
+        'frontendUrl?': 'string',
+    },
+    // NOTE: `customValues` is NOT part of this schema, so KRO-mode callers
+    // (validated against this shape) can't use it — the mapped values tree
+    // carries CEL templates (CLICKHOUSE_ENDPOINT, defaultConnections, ...),
+    // and the runtime values merge cannot embed template leaves inside a KRO
+    // map-merge expression (the serialized CEL comes out invalid, verified
+    // empirically). `ClickStackBootstrapRuntimeConfig` below re-adds
+    // `customValues` as an internal, DIRECT-MODE-ONLY escape hatch (only a
+    // concrete object merges — see helm-values-mapper.ts) with no test
+    // coverage backing it as a supported feature. For anything beyond ad hoc
+    // direct-mode tweaks, use build-time raw chart overrides instead
+    // (`makeClickstackBootstrap({ values })`), where the merge happens on
+    // concrete objects before serialization.
+};
+/**
+ * Runtime spec for the internal-Mongo variant (the default
+ * `clickstackBootstrap`). Mongo needs no runtime config — mode and storage
+ * are build-time (`makeClickstackBootstrap`).
+ */
+export const ClickStackBootstrapConfigSchema = type(bootstrapBaseShape);
+/**
+ * Runtime spec for the external-Mongo variant: base + a required `mongoUri`.
+ */
+export const ClickStackExternalMongoBootstrapConfigSchema = type({
+    ...bootstrapBaseShape,
+    /** Full MongoDB connection URI → `hyperdx.config.MONGO_URI` (verbatim). */
+    mongoUri: 'string',
+});
+// ============================================================================
+// Bootstrap status — a typed service contract, not just readiness
+// ============================================================================
+/**
+ * Observed ClickStack status. Downstream compositions consume connection
+ * details from here instead of reconstructing chart service-naming rules —
+ * e.g. `clickstackK8sTelemetry` wiring:
+ * `{ endpoint: stack.status.gateway.otlpHttpEndpoint }`.
+ *
+ * Naming anchor: the values mapper pins `fullnameOverride` to the release
+ * name, so the HyperDX app Service is named exactly `<name>` (the chart's
+ * `clickstack.hyperdx.fullname` helper skips its `-app` suffix when
+ * `fullnameOverride` is set) and the gateway Service is
+ * `<name>-otel-collector` (subchart naming off `.Release.Name`).
+ *
+ * KRO STATUS vs CLIENT-HYDRATED SPLIT: fields anchored on the owned
+ * HelmRelease resource serialize as KRO status CEL and appear on the live
+ * KRO CR's status (GitOps/KRO consumers can read them): `ready`, `phase`,
+ * `ui.url`, `gateway.otlpHttpEndpoint`, `gateway.otlpGrpcEndpoint`,
+ * `app.host` — natural JS template literals over
+ * `clickstackHelmRelease.metadata.name`/`.namespace` (bimodal on typekro
+ * >= 0.24.0: status CEL in `factory('kro')`, concrete strings via direct-mode
+ * re-execution), never `schema.spec.*` (KRO status CEL cannot reference the
+ * instance spec). The BARE build-time constants `app.appPort` (3000) and
+ * `app.apiPort` (8000), plus the spec-derived `version`, have no resource
+ * anchor and are hydrated CLIENT-SIDE by TypeKro (absent from the KRO CR
+ * status); the ports remain KRO-visible inside the URL fields.
+ * Ports are the chart defaults (`hyperdx.ports`, `otel-collector.ports`);
+ * port overrides via build-time raw values are NOT reflected here.
+ */
+export const ClickStackBootstrapStatusSchema = type({
+    /** Overall readiness from the owned HelmRelease Ready condition. */
+    ready: 'boolean',
+    /** Coarse phase from the owned HelmRelease Ready condition. */
+    phase: '"Ready" | "Installing" | "Failed"',
+    /** Configured chart version. */
+    'version?': 'string',
+    /** HyperDX UI. */
+    ui: {
+        /** In-cluster URL of the HyperDX UI (app port 3000). */
+        url: 'string',
+    },
+    /** OTel gateway collector ingest endpoints (the `otel-collector` subchart Service). */
+    gateway: {
+        /** OTLP/HTTP ingest endpoint (servicePort 4318). */
+        otlpHttpEndpoint: 'string',
+        /** OTLP/gRPC ingest endpoint (servicePort 4317). */
+        otlpGrpcEndpoint: 'string',
+    },
+    /** HyperDX app Service coordinates. */
+    app: {
+        /** In-cluster DNS host of the HyperDX app Service. */
+        host: 'string',
+        /** UI port. */
+        appPort: 'number',
+        /** API port. */
+        apiPort: 'number',
+    },
+});
+/**
+ * ArkType schema for ClickStackK8sTelemetryConfig (runtime spec).
+ *
+ * The documented ClickStack Kubernetes ingestion pattern: TWO instances of the
+ * STOCK `opentelemetry-collector` chart —
+ * - a daemonset instance (presets: logsCollection, hostMetrics,
+ *   kubernetesAttributes, kubeletMetrics), and
+ * - a deployment instance (presets: kubernetesAttributes, kubernetesEvents,
+ *   clusterMetrics),
+ * both exporting `otlphttp` to the ClickStack gateway collector with
+ * `authorization: <HYPERDX_API_KEY>` header auth.
+ *
+ * @see https://clickhouse.com/docs/use-cases/observability/clickstack/ingesting-data/kubernetes
+ */
+export const ClickStackK8sTelemetryConfigSchema = type({
+    /** Base release name; the composition derives `<name>-daemonset` and `<name>-deployment`. */
+    name: 'string',
+    /** Namespace for the collectors (default: 'clickstack-telemetry'). */
+    'namespace?': 'string',
+    /** Stock opentelemetry-collector chart version (default: '0.146.1'). */
+    'version?': 'string',
+    /**
+     * OTLP/HTTP endpoint of the ClickStack gateway collector. Wire it from the
+     * bootstrap's status contract (`stack.status.gateway.otlpHttpEndpoint`).
+     * Default assumes the canonical install (`name: 'clickstack'` in namespace
+     * 'clickstack').
+     */
+    'endpoint?': 'string',
+    /**
+     * Existing Secret holding the HyperDX ingestion API key (REQUIRED). Wired as
+     * an env var via `secretKeyRef` and referenced from the exporter's
+     * `authorization` header via OTel `${env:...}` config expansion — the key
+     * value never lands in Helm values.
+     */
+    apiKeySecret: {
+        name: 'string',
+        /** Key inside the Secret (default: 'HYPERDX_API_KEY'). */
+        'key?': 'string',
+    },
+});
+/** Observed status of the k8s telemetry collectors. */
+export const ClickStackK8sTelemetryStatusSchema = type({
+    /** Both collector HelmReleases report Ready. */
+    ready: 'boolean',
+    phase: '"Ready" | "Installing"',
+});
+// ============================================================================
+// Shared HelmRepository singletons
+// ============================================================================
+/** Spec accepted by the shared ClickStack HelmRepository singleton. */
+export const ClickStackHelmRepositorySingletonSpecSchema = type({
+    name: 'string',
+    namespace: 'string',
+    url: 'string',
+});
+/** Status surfaced by the shared ClickStack HelmRepository singleton. */
+export const ClickStackHelmRepositorySingletonStatusSchema = type({
+    ready: 'boolean',
+});
+/** Spec accepted by the shared OpenTelemetry HelmRepository singleton. */
+export const OtelHelmRepositorySingletonSpecSchema = type({
+    name: 'string',
+    namespace: 'string',
+    url: 'string',
+});
+/** Status surfaced by the shared OpenTelemetry HelmRepository singleton. */
+export const OtelHelmRepositorySingletonStatusSchema = type({
+    ready: 'boolean',
+});
+// ============================================================================
+// Helm wrapper configs
+// ============================================================================
+/** Configuration for the ClickStack/OTel HelmRepository wrappers. */
+export const ClickStackHelmRepositoryConfigSchema = type({
+    'name?': 'string',
+    'namespace?': 'string',
+    'url?': 'string',
+    'interval?': 'string',
+    'id?': 'string',
+});
+//# sourceMappingURL=types.js.map

package/dist/factories/clickstack/types.js.map

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

package/dist/factories/clickstack/utils/helm-values-mapper.d.ts

@@ -0,0 +1,118 @@
+/**
+ * ClickStack Helm values mappers.
+ *
+ * Pure functions mapping typed factory config onto OFFICIAL chart values.
+ * Bootstrap-only fields (name, namespace, chart version, Flux repository
+ * names) stay in TypeKro resource configuration and are never forwarded.
+ *
+ * BUILD-TIME vs RUNTIME: the mappers take the runtime spec (proxy-safe VALUES
+ * only — concrete in direct mode, schema refs in KRO mode) plus concrete
+ * build-time options (`mongoMode`, static raw `values`). All plain-JS
+ * branching happens on the build-time options; runtime fields are only ever
+ * embedded as values or wrapped in explicit `has()`-guarded CEL.
+ *
+ * Values keys verified 2026-07-06 against
+ * https://github.com/ClickHouse/ClickStack-helm-charts
+ * charts/clickstack/values.yaml (chart 3.0.1, appVersion 2.29.0):
+ * - `hyperdx.config.*` env map: `CLICKHOUSE_ENDPOINT` (native, tcp://…),
+ *   `CLICKHOUSE_SERVER_ENDPOINT` (host:port), `CLICKHOUSE_USER`,
+ *   `HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE`, `MONGO_URI`, `FRONTEND_URL`.
+ * - `hyperdx.secrets.*`: `CLICKHOUSE_PASSWORD` (collector/ingest user),
+ *   `CLICKHOUSE_APP_PASSWORD` (UI user), `HYPERDX_API_KEY`,
+ *   `MONGODB_PASSWORD` (unused here — internal Mongo runs authless, external
+ *   Mongo carries credentials in its URI).
+ * - DOC-VS-TEMPLATE DISCREPANCY: several docs describe `defaultConnections` /
+ *   `defaultSources` directly under `hyperdx.*`, but the chart templates read
+ *   them from `hyperdx.deployment.defaultConnections` /
+ *   `hyperdx.deployment.defaultSources` (values.yaml lines 100/110) — the
+ *   deployment block is what we set. The same block offers
+ *   `useExistingConfigSecret`/`existingConfigSecret` for external secret
+ *   management (reachable via the build-time `values` passthrough).
+ * - `clickhouse.enabled` / `mongodb.enabled`: both HARD-PINNED to false here.
+ *   The bundled ClickHouse/Keeper are `ClickHouseCluster`/`KeeperCluster`
+ *   CRDs and the bundled Mongo is a `MongoDBCommunity` CRD — all owned by the
+ *   separate `clickstack-operators` prerequisite chart we refuse to install
+ *   (ClickHouse Inc.'s operator CRDs would collide with our Altinity
+ *   operator). These pins beat the raw `values` passthrough in BOTH modes
+ *   because the merge happens at construction time on concrete objects.
+ * - `fullnameOverride`: pinned to the release name — the status contract's
+ *   naming anchor. With it set, the chart's `clickstack.hyperdx.fullname`
+ *   helper names the HyperDX app resources exactly `<release>` (no `-app`
+ *   suffix), and the gateway Service stays `<release>-otel-collector`
+ *   (subchart naming from `.Release.Name`), so the bootstrap status can
+ *   derive endpoints deterministically.
+ * - `otel-collector.*`: the gateway subchart (alias) stays enabled with chart
+ *   defaults; it reads the shared `clickstack-config` ConfigMap and
+ *   `clickstack-secret` Secret via `extraEnvsFrom`, so the external-CH env
+ *   above reconfigures it too (its goose migrations create the otel_* tables
+ *   in the external ClickHouse at startup).
+ */
+import type { TypeKroChartValues } from '../../../core/types/common.js';
+import type { ClickStackBootstrapRuntimeConfig, ClickStackHelmValues, ClickStackK8sTelemetryConfig, ClickStackMappedHelmValues, OtelCollectorHelmValues, OtelCollectorMappedHelmValues } from '../types.js';
+/** Default namespace for a ClickStack install. */
+export declare const DEFAULT_CLICKSTACK_NAMESPACE = "clickstack";
+/** Default namespace for the k8s telemetry collectors. */
+export declare const DEFAULT_CLICKSTACK_TELEMETRY_NAMESPACE = "clickstack-telemetry";
+/**
+ * Default OTLP/HTTP endpoint of the ClickStack gateway collector, assuming
+ * the canonical `clickstackBootstrap` install (release name 'clickstack' in
+ * namespace 'clickstack'). The chart names the gateway Service
+ * `<release>-otel-collector` (templates/_helpers.tpl `clickstack.otel.fullname`)
+ * and exposes otlp-http on servicePort 4318 (values.yaml `otel-collector.ports`).
+ * Prefer wiring `stack.status.gateway.otlpHttpEndpoint` instead of relying on
+ * this default.
+ */
+export declare const DEFAULT_CLICKSTACK_GATEWAY_ENDPOINT = "http://clickstack-otel-collector.clickstack.svc.cluster.local:4318";
+/**
+ * Collector image for the k8s telemetry instances. The stock chart ships an
+ * empty `image.repository` on purpose; the ClickStack k8s ingestion docs use
+ * the contrib distribution (it carries the k8s receivers the presets enable).
+ */
+export declare const DEFAULT_K8S_TELEMETRY_COLLECTOR_IMAGE = "otel/opentelemetry-collector-contrib";
+/** Name of the HyperDX connection emitted into `defaultConnections`/`defaultSources`. */
+export declare const CLICKSTACK_CONNECTION_NAME = "External ClickHouse";
+/** Concrete build-time options consumed by the bootstrap values mapper. */
+export interface ClickStackValuesMapperOptions {
+    /** Which Mongo wiring to emit (build-time; default 'internal'). */
+    mongoMode?: 'internal' | 'external';
+    /** Static raw chart values merged after the typed mapping (pins re-applied after). */
+    values?: TypeKroChartValues<ClickStackHelmValues>;
+}
+/** Values pair for the two stock collector instances. */
+export interface ClickStackK8sTelemetryValues {
+    daemonset: OtelCollectorMappedHelmValues;
+    deployment: OtelCollectorMappedHelmValues;
+}
+/**
+ * Map typed ClickStack runtime config + build options into official
+ * clickstack chart values.
+ *
+ * Handles both composition modes: concrete config (direct mode) emits plain
+ * values; schema-proxy config (KRO mode) emits `has()`-guarded CEL so chart
+ * defaults resolve per instance.
+ */
+export declare function mapClickStackConfigToHelmValues(config: ClickStackBootstrapRuntimeConfig, options?: ClickStackValuesMapperOptions): ClickStackMappedHelmValues;
+/** Concrete build-time options consumed by the telemetry values mapper. */
+export interface ClickStackK8sTelemetryMapperOptions {
+    daemonset?: {
+        values?: TypeKroChartValues<OtelCollectorHelmValues>;
+    };
+    deployment?: {
+        values?: TypeKroChartValues<OtelCollectorHelmValues>;
+    };
+}
+/**
+ * Map k8s telemetry runtime config + build options onto values for TWO stock
+ * `opentelemetry-collector` chart instances — the documented ClickStack
+ * Kubernetes ingestion pattern (verified 2026-07-06 against
+ * https://clickhouse.com/docs/use-cases/observability/clickstack/ingesting-data/kubernetes
+ * and the stock chart's values.yaml preset names).
+ *
+ * The API key reaches the exporter via OTel config `${env:HYPERDX_API_KEY}`
+ * expansion backed by a `secretKeyRef` env var — the key value itself never
+ * enters Helm values. In KRO mode the literal `${env:…}` would be parsed as a
+ * KRO CEL template, so it is emitted as the CEL concat `"$" + "{env:…}"`,
+ * which KRO evaluates back to the literal at instance materialization.
+ */
+export declare function mapK8sTelemetryConfigToHelmValues(config: ClickStackK8sTelemetryConfig, options?: ClickStackK8sTelemetryMapperOptions): ClickStackK8sTelemetryValues;
+//# sourceMappingURL=helm-values-mapper.d.ts.map

package/dist/factories/clickstack/utils/helm-values-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helm-values-mapper.d.ts","sourceRoot":"","sources":["../../../../src/factories/clickstack/utils/helm-values-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAOH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAGxE,OAAO,KAAK,EACV,gCAAgC,EAChC,oBAAoB,EACpB,4BAA4B,EAC5B,0BAA0B,EAC1B,uBAAuB,EACvB,6BAA6B,EAC9B,MAAM,aAAa,CAAC;AAErB,kDAAkD;AAClD,eAAO,MAAM,4BAA4B,eAAe,CAAC;AAEzD,0DAA0D;AAC1D,eAAO,MAAM,sCAAsC,yBAAyB,CAAC;AAE7E;;;;;;;;GAQG;AACH,eAAO,MAAM,mCAAmC,uEACsB,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,qCAAqC,yCAAyC,CAAC;AAE5F,yFAAyF;AACzF,eAAO,MAAM,0BAA0B,wBAAwB,CAAC;AAEhE,2EAA2E;AAC3E,MAAM,WAAW,6BAA6B;IAC5C,mEAAmE;IACnE,SAAS,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACpC,sFAAsF;IACtF,MAAM,CAAC,EAAE,kBAAkB,CAAC,oBAAoB,CAAC,CAAC;CACnD;AAED,yDAAyD;AACzD,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,6BAA6B,CAAC;IACzC,UAAU,EAAE,6BAA6B,CAAC;CAC3C;AA4ND;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,gCAAgC,EACxC,OAAO,GAAE,6BAAkC,GAC1C,0BAA0B,CAqI5B;AAMD,2EAA2E;AAC3E,MAAM,WAAW,mCAAmC;IAClD,SAAS,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,kBAAkB,CAAC,uBAAuB,CAAC,CAAA;KAAE,CAAC;IACrE,UAAU,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,kBAAkB,CAAC,uBAAuB,CAAC,CAAA;KAAE,CAAC;CACvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,4BAA4B,EACpC,OAAO,GAAE,mCAAwC,GAChD,4BAA4B,CAgH9B"}