@confluentinc/mcp-confluent 1.2.2 → 1.4.0

package/dist/confluent/tools/base-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-tools.js","sourceRoot":"","sources":["../../../src/confluent/tools/base-tools.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAoB;IACxC,YAAY,EAAE,IAAI;CACV,CAAC;AAEX,MAAM,CAAC,MAAM,aAAa,GAAoB;IAC5C,eAAe,EAAE,KAAK;IACtB,YAAY,EAAE,KAAK;CACX,CAAC;AAEX,MAAM,CAAC,MAAM,WAAW,GAAoB;IAC1C,eAAe,EAAE,IAAI;IACrB,YAAY,EAAE,KAAK;CACX,CAAC;AAoCX,MAAM,OAAgB,eAAe;IAoBnC;;;OAGG;IACH,oBAAoB;QAClB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,cAAc,CACZ,OAAe,EACf,UAAmB,KAAK,EACxB,KAA+B;QAE/B,MAAM,QAAQ,GAAmB;YAC/B,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,OAAO;iBACd;aACF;YACD,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,KAAK;SACb,CAAC;QACF,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF"}
+{"version":3,"file":"base-tools.js","sourceRoot":"","sources":["../../../src/confluent/tools/base-tools.ts"],"names":[],"mappings":"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"}

package/dist/confluent/tools/cluster-arg-resolvers.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Cluster-arg resolver for native Kafka handlers. Asymmetric by connection
+ * type:
+ *
+ * - Direct: returns `{ clusterId: undefined, envId: undefined }`. The
+ *   `DirectClientManager` ignores cluster args and uses its eagerly-built
+ *   single-instance client(s); the handler passes the undefineds through.
+ * - OAuth: requires the args; throws with a discovery hint if missing.
+ *   Handlers catch the throw at entry and convert to a `CallToolResult`
+ *   with `isError: true` so the agent receives a normal tool-call error
+ *   rather than an RPC failure.
+ */
+import { ServerRuntime } from "../../server-runtime.js";
+export declare function resolveKafkaClusterArgs(args: {
+    cluster_id?: string;
+    environment_id?: string;
+}, runtime: ServerRuntime, connId: string): {
+    clusterId: string | undefined;
+    envId: string | undefined;
+};
+/**
+ * REST-tool variant of {@link resolveKafkaClusterArgs}. The Kafka REST API
+ * places `cluster_id` directly in the URL path
+ * (e.g. `/kafka/v3/clusters/{id}/topics`), so the handler always needs a
+ * concrete cluster id — even on direct connections that omit the arg and
+ * rely on the configured fallback.
+ *
+ * Direct: `args.clusterId ?? conn.kafka?.cluster_id`; throws if neither.
+ *   `envId` is unused (direct's `kafka.rest_endpoint` already targets the
+ *   per-cluster hostname).
+ * OAuth: both `clusterId` and `environmentId` required. Argument names are
+ *   camelCase to match the existing input-schema convention of these tools
+ *   and `list-clusters`; the native-Kafka tools' snake_case `cluster_id` is
+ *   a separate convention.
+ */
+export declare function resolveKafkaRestArgs(args: {
+    clusterId?: string;
+    environmentId?: string;
+}, runtime: ServerRuntime, connId: string): {
+    clusterId: string;
+    envId: string | undefined;
+};
+/**
+ * Env-only resolver for tools that scope a request to a single CCloud
+ * environment without a cluster identifier (e.g., `list-clusters`).
+ *
+ * Direct: arg wins; falls back to `conn.kafka?.env_id`; throws if neither
+ *   source supplies a value.
+ * OAuth: arg required (no service block to fall back to); throws with a
+ *   discovery hint pointing at `list-environments`.
+ *
+ * Argument name is camelCase (`environmentId`) to match the existing
+ * input-schema convention of cluster-management tools.
+ */
+export declare function resolveEnvArg(args: {
+    environmentId?: string;
+}, runtime: ServerRuntime, connId: string): string;
+/**
+ * Disposes a Kafka client (admin or producer) iff the connection is OAuth-typed.
+ * On direct connections this is a no-op — direct's `AsyncLazy` admin/producer
+ * are manager-owned singletons and must not be disconnected by handlers. On
+ * OAuth, calls `client.disconnect()` and swallows + logs any error so disposal
+ * failure never masks the handler's own error.
+ */
+export declare function disposeIfOAuth(runtime: ServerRuntime, connId: string, client: {
+    disconnect: () => Promise<void>;
+}): Promise<void>;
+/**
+ * Renders any error thrown from a Kafka admin/producer/consumer call into a
+ * single agent-readable string. Preserves per-topic-cause unwrapping for
+ * `KafkaJSAggregateError`, surfaces `KafkaJSError.code` when present, and
+ * falls back gracefully for unknown shapes.
+ */
+export declare function formatKafkaError(err: unknown): string;
+//# sourceMappingURL=cluster-arg-resolvers.d.ts.map

package/dist/confluent/tools/cluster-arg-resolvers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-arg-resolvers.d.ts","sourceRoot":"","sources":["../../../src/confluent/tools/cluster-arg-resolvers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,wBAAgB,uBAAuB,CACrC,IAAI,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,EACtD,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,MAAM,GACb;IAAE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAe9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,EACpD,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,MAAM,GACb;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAqBlD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,EAChC,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,MAAM,GACb,MAAM,CAaR;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,GAC1C,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAoBrD"}

package/dist/confluent/tools/cluster-arg-resolvers.js

@@ -0,0 +1,127 @@
+/**
+ * Cluster-arg resolver for native Kafka handlers. Asymmetric by connection
+ * type:
+ *
+ * - Direct: returns `{ clusterId: undefined, envId: undefined }`. The
+ *   `DirectClientManager` ignores cluster args and uses its eagerly-built
+ *   single-instance client(s); the handler passes the undefineds through.
+ * - OAuth: requires the args; throws with a discovery hint if missing.
+ *   Handlers catch the throw at entry and convert to a `CallToolResult`
+ *   with `isError: true` so the agent receives a normal tool-call error
+ *   rather than an RPC failure.
+ */
+import { KafkaJS } from "@confluentinc/kafka-javascript";
+import { logger } from "../../logger.js";
+export function resolveKafkaClusterArgs(args, runtime, connId) {
+    const conn = runtime.config.connections[connId];
+    if (conn.type === "direct") {
+        return { clusterId: undefined, envId: undefined };
+    }
+    if (args.cluster_id === undefined || args.environment_id === undefined) {
+        throw new Error("cluster_id and environment_id are required under OAuth connection type. " +
+            "Discover the environment via list-environments, then call list-clusters " +
+            "with environment_id and pass the cluster's `id` and `spec.environment.id`.");
+    }
+    return { clusterId: args.cluster_id, envId: args.environment_id };
+}
+/**
+ * REST-tool variant of {@link resolveKafkaClusterArgs}. The Kafka REST API
+ * places `cluster_id` directly in the URL path
+ * (e.g. `/kafka/v3/clusters/{id}/topics`), so the handler always needs a
+ * concrete cluster id — even on direct connections that omit the arg and
+ * rely on the configured fallback.
+ *
+ * Direct: `args.clusterId ?? conn.kafka?.cluster_id`; throws if neither.
+ *   `envId` is unused (direct's `kafka.rest_endpoint` already targets the
+ *   per-cluster hostname).
+ * OAuth: both `clusterId` and `environmentId` required. Argument names are
+ *   camelCase to match the existing input-schema convention of these tools
+ *   and `list-clusters`; the native-Kafka tools' snake_case `cluster_id` is
+ *   a separate convention.
+ */
+export function resolveKafkaRestArgs(args, runtime, connId) {
+    const conn = runtime.config.connections[connId];
+    if (conn.type === "direct") {
+        const clusterId = args.clusterId ?? conn.kafka?.cluster_id;
+        if (!clusterId) {
+            throw new Error("clusterId is required: pass it as a tool argument or set kafka.cluster_id in the connection config.");
+        }
+        return { clusterId, envId: undefined };
+    }
+    if (!args.clusterId || !args.environmentId) {
+        throw new Error("clusterId and environmentId are required under OAuth connection type. " +
+            "Discover the environment via list-environments, then call list-clusters " +
+            "with environmentId and pass the cluster's `id` and `spec.environment.id`.");
+    }
+    return { clusterId: args.clusterId, envId: args.environmentId };
+}
+/**
+ * Env-only resolver for tools that scope a request to a single CCloud
+ * environment without a cluster identifier (e.g., `list-clusters`).
+ *
+ * Direct: arg wins; falls back to `conn.kafka?.env_id`; throws if neither
+ *   source supplies a value.
+ * OAuth: arg required (no service block to fall back to); throws with a
+ *   discovery hint pointing at `list-environments`.
+ *
+ * Argument name is camelCase (`environmentId`) to match the existing
+ * input-schema convention of cluster-management tools.
+ */
+export function resolveEnvArg(args, runtime, connId) {
+    const conn = runtime.config.connections[connId];
+    const fallback = conn.type === "direct" ? conn.kafka?.env_id : undefined;
+    const resolved = args.environmentId ?? fallback;
+    if (!resolved) {
+        throw new Error("environmentId is required: pass it as a tool argument or " +
+            (conn.type === "direct"
+                ? "set kafka.env_id in the connection config."
+                : "call list-environments to discover available environments."));
+    }
+    return resolved;
+}
+/**
+ * Disposes a Kafka client (admin or producer) iff the connection is OAuth-typed.
+ * On direct connections this is a no-op — direct's `AsyncLazy` admin/producer
+ * are manager-owned singletons and must not be disconnected by handlers. On
+ * OAuth, calls `client.disconnect()` and swallows + logs any error so disposal
+ * failure never masks the handler's own error.
+ */
+export async function disposeIfOAuth(runtime, connId, client) {
+    if (runtime.config.connections[connId].type !== "oauth")
+        return;
+    try {
+        await client.disconnect();
+    }
+    catch (err) {
+        logger.warn({ err, connId }, "OAuth Kafka client disconnect failed");
+    }
+}
+/**
+ * Renders any error thrown from a Kafka admin/producer/consumer call into a
+ * single agent-readable string. Preserves per-topic-cause unwrapping for
+ * `KafkaJSAggregateError`, surfaces `KafkaJSError.code` when present, and
+ * falls back gracefully for unknown shapes.
+ */
+export function formatKafkaError(err) {
+    if (err instanceof KafkaJS.KafkaJSAggregateError) {
+        const details = err.errors
+            .map((inner) => {
+            if (inner instanceof KafkaJS.KafkaJSCreateTopicError) {
+                return `- ${inner.topic}: ${inner.message}`;
+            }
+            if (inner instanceof KafkaJS.KafkaJSError) {
+                return `- ${inner.code ?? "unknown"}: ${inner.message}`;
+            }
+            return `- ${typeof inner === "string" ? inner : String(inner)}`;
+        })
+            .join("\n");
+        return `${err.message}\n${details}`;
+    }
+    if (err instanceof KafkaJS.KafkaJSError) {
+        return `Kafka error (${err.code ?? "unknown"}): ${err.message}`;
+    }
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+//# sourceMappingURL=cluster-arg-resolvers.js.map

package/dist/confluent/tools/cluster-arg-resolvers.js.map

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

package/dist/confluent/tools/connection-predicates.d.ts

@@ -0,0 +1,176 @@
+import type { ConnectionConfig } from "../../config/models.js";
+/**
+ * A connection predicate's verdict on whether a tool should be enabled for a
+ * given connection. Carries a {@linkcode ToolDisabledReason} when disabled so
+ * that downstream consumers (startup logging, diagnostic tooling) can group
+ * identical failures and render actionable messages to the user.
+ */
+export type PredicateResult = {
+    readonly enabled: true;
+} | {
+    readonly enabled: false;
+    readonly reason: ToolDisabledReason;
+};
+export type ConnectionPredicate = (conn: ConnectionConfig) => PredicateResult;
+export declare const ENABLED: PredicateResult;
+/**
+ * Block-level — required by any tool that needs Kafka access regardless of
+ * transport (native client or REST proxy).
+ */
+export declare function hasKafka(conn: ConnectionConfig): PredicateResult;
+/**
+ * Field-level — required by tools that drive the native Kafka
+ * admin/producer/consumer client (the broker address lives on
+ * `bootstrap_servers`).
+ */
+export declare function hasKafkaBootstrap(conn: ConnectionConfig): PredicateResult;
+/**
+ * Field-level — required by tools that perform authenticated Kafka calls.
+ */
+export declare function hasKafkaAuth(conn: ConnectionConfig): PredicateResult;
+/**
+ * Field-level — required by tools that talk to the Kafka REST proxy
+ * (`/kafka/v3` endpoints); needs both `rest_endpoint` and `auth` on the
+ * `kafka` block.
+ */
+export declare function hasKafkaRestWithAuth(conn: ConnectionConfig): PredicateResult;
+/**
+ * Block-level — required by tools that read or write through the Schema
+ * Registry.
+ */
+export declare function hasSchemaRegistry(conn: ConnectionConfig): PredicateResult;
+/**
+ * Block-level — verdict on whether the connection can reach the Confluent
+ * Cloud control-plane REST surface, accepting either flavor. Direct
+ * connections satisfy this when they carry a `confluent_cloud` block; OAuth
+ * connections satisfy it unconditionally (the cloud REST URL is derived from
+ * the Auth0 environment).
+ *
+ * Pair: {@linkcode hasConfluentCloud} for the direct-only verdict.
+ */
+export declare const hasConfluentCloudOrOAuth: ConnectionPredicate;
+/**
+ * Block-level — verdict that holds only for direct connections carrying a
+ * `confluent_cloud` block. Use this on handlers that are not yet OAuth-capable
+ * and call `getSoleDirectConnection()` inside `handle()`. Once a handler
+ * widens to OAuth, switch its predicate to
+ * {@linkcode hasConfluentCloudOrOAuth}.
+ */
+export declare function hasConfluentCloud(conn: ConnectionConfig): PredicateResult;
+/**
+ * Block-level — required by tools that drive Flink SQL or its catalog.
+ */
+export declare function hasFlink(conn: ConnectionConfig): PredicateResult;
+/**
+ * Block-level — required by tools that read metrics from the Telemetry API.
+ */
+export declare function hasTelemetry(conn: ConnectionConfig): PredicateResult;
+/**
+ * Block-level — required by tools that manage Tableflow topics or catalog
+ * entries.
+ */
+export declare function hasTableflow(conn: ConnectionConfig): PredicateResult;
+/**
+ * Field-level — verdict that holds when the connection points at a Confluent
+ * Cloud-hosted Schema Registry that exposes the `/catalog/v1/` Stream Catalog
+ * endpoints. Requires three signals together:
+ *   - a `schema_registry` block, AND
+ *   - `auth.type === "api_key"` on that block, AND
+ *   - a `confluent_cloud` block (Cloud control-plane creds).
+ *
+ * The `confluent_cloud` block is required because `auth.type === "api_key"` is
+ * ambiguous on its own: a self-managed Confluent Platform deployment with HTTP
+ * Basic Auth in front of its SR also models as `auth.type === "api_key"` in
+ * the YAML schema, even though that SR does not serve `/catalog/v1/`. Without
+ * the `confluent_cloud` requirement, this predicate would over-enable Stream
+ * Catalog tools on CP deployments and they would 404 at runtime.
+ */
+export declare function hasCCloudCatalogSupport(conn: ConnectionConfig): PredicateResult;
+/**
+ * Predicate that returns {@linkcode ENABLED} for every connection. Use as
+ * the {@linkcode BaseToolHandler.predicate} for tools with no service-block
+ * requirement (e.g., generic docs search).
+ */
+export declare const alwaysEnabled: ConnectionPredicate;
+/**
+ * Combine predicates with logical AND, short-circuiting on the first
+ * failure. Returns {@linkcode ENABLED} only when every predicate passes for
+ * the given connection; otherwise returns the first failing verdict so the
+ * specific reason propagates downstream to startup logging and the
+ * diagnostic-tool surface.
+ *
+ * Use this — never raw `predA(conn) && predB(conn)`. JavaScript boolean
+ * composition silently drops the first operand because every
+ * `PredicateResult` is a truthy object.
+ */
+export declare function allOf(...predicates: ConnectionPredicate[]): ConnectionPredicate;
+/**
+ * Wrap a predicate so OAuth connections always answer enabled. Use this on
+ * tool handlers that have been adapted to operate against an OAuth-typed
+ * connection at call time — the wrapped predicate's block-based verdict
+ * still governs direct connections, while OAuth's "no service blocks"
+ * early-exit is overridden.
+ */
+export declare function widenForOAuth(predicate: ConnectionPredicate): ConnectionPredicate;
+/**
+ * The native-Kafka client gate, widened to admit OAuth. Direct connections
+ * still need `kafka.bootstrap_servers`; OAuth connections satisfy it
+ * unconditionally (the broker URL is synthesized from the Auth0 environment).
+ * Use on handlers that have been brought into the OAuth fold.
+ */
+export declare const kafkaBootstrapOrOAuth: ConnectionPredicate;
+/**
+ * The Kafka REST client gate, widened to admit OAuth. Direct connections still
+ * need both `kafka.rest_endpoint` and `kafka.auth`; OAuth connections satisfy
+ * it unconditionally (the per-cluster REST URL is resolved at call time via
+ * the cmk REST API and the bearer middleware handles auth). Use on REST-tool
+ * handlers (`get-topic-config`, `alter-topic-config`).
+ */
+export declare const kafkaRestWithAuthOrOAuth: ConnectionPredicate;
+/**
+ * The Schema Registry gate, widened to admit OAuth. Direct connections still
+ * need a `schema_registry` block; OAuth connections satisfy it unconditionally
+ * (the SR cluster + endpoint are auto-resolved at call time from
+ * `environment_id`).
+ */
+export declare const hasSchemaRegistryOrOAuth: ConnectionPredicate;
+/**
+ * Gate for tools that create connectors against the direct Confluent Cloud
+ * REST surface: requires both a `confluent_cloud` block (the `/connect/v1`
+ * endpoint) and `kafka.auth` (the connector spec carries kafka API
+ * credentials). Strict-direct — OAuth connections answer `OAuthNotDirectCapable`
+ * because the handler calls `getSoleDirectConnection()`.
+ */
+export declare const canCreateDirectConnector: ConnectionPredicate;
+/**
+ * Gate for tools that read telemetry metrics about Flink statements:
+ * requires both the `flink` block (to address a statement) and the
+ * `telemetry` block (to query the metrics API).
+ */
+export declare const flinkWithTelemetry: ConnectionPredicate;
+/**
+ * Every reason a {@linkcode ConnectionPredicate} can return `enabled: false`.
+ * The symbol is the wire-stable identifier (referenced from predicate bodies
+ * and tests); the value is the human-readable phrasing surfaced to end users
+ * through startup logs and diagnostic tooling.
+ *
+ * Adding a reason: name the symbol after what's missing from the connection
+ * config (not which predicate emitted it — multiple predicates may share a
+ * reason), and write the value as a declarative phrase a misconfigured user
+ * could act on.
+ */
+export declare enum ToolDisabledReason {
+    MissingKafkaBlock = "no 'kafka' block in connection config",
+    MissingKafkaBootstrap = "'kafka' block does not have 'bootstrap_servers' field",
+    MissingKafkaAuth = "'kafka' block does not have 'auth' field",
+    MissingKafkaRestEndpoint = "'kafka' block does not have 'rest_endpoint' field",
+    MissingSchemaRegistryBlock = "no 'schema_registry' block in connection config",
+    MissingSchemaRegistryApiKeyAuth = "'schema_registry' block does not have 'auth' field of type 'api_key'",
+    MissingConfluentCloudBlock = "no 'confluent_cloud' block in connection config",
+    MissingFlinkBlock = "no 'flink' block in connection config",
+    MissingTelemetryBlock = "no 'telemetry' block in connection config",
+    MissingTableflowBlock = "no 'tableflow' block in connection config",
+    OAuthNoServiceBlocks = "OAuth connections carry no service blocks",
+    OAuthNotDirectCapable = "OAuth connection cannot satisfy a direct-only requirement"
+}
+//# sourceMappingURL=connection-predicates.d.ts.map

package/dist/confluent/tools/connection-predicates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-predicates.d.ts","sourceRoot":"","sources":["../../../src/confluent/tools/connection-predicates.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAErE,MAAM,MAAM,mBAAmB,GAAG,CAAC,IAAI,EAAE,gBAAgB,KAAK,eAAe,CAAC;AAE9E,eAAO,MAAM,OAAO,EAAE,eAAmC,CAAC;AAM1D;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,eAAe,CAMhE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,GAAG,eAAe,CASzE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,eAAe,CAQpE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,gBAAgB,GAAG,eAAe,CAW5E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,GAAG,eAAe,CAOzE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,EAAE,mBACL,CAAC;AAEnC;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,GAAG,eAAe,CAOzE;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,eAAe,CAMhE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,eAAe,CAMpE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,eAAe,CAMpE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,gBAAgB,GACrB,eAAe,CAajB;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,mBAAmC,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CACnB,GAAG,UAAU,EAAE,mBAAmB,EAAE,GACnC,mBAAmB,CAQrB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,mBAAmB,GAC7B,mBAAmB,CAErB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBACF,CAAC;AAEnC;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,EAAE,mBACF,CAAC;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,mBACL,CAAC;AAEnC;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,EAAE,mBAGtC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,mBAGhC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,oBAAY,kBAAkB;IAC5B,iBAAiB,0CAA0C;IAC3D,qBAAqB,0DAA0D;IAC/E,gBAAgB,6CAA6C;IAC7D,wBAAwB,sDAAsD;IAC9E,0BAA0B,oDAAoD;IAC9E,+BAA+B,yEAAyE;IACxG,0BAA0B,oDAAoD;IAC9E,iBAAiB,0CAA0C;IAC3D,qBAAqB,8CAA8C;IACnE,qBAAqB,8CAA8C;IACnE,oBAAoB,8CAA8C;IAClE,qBAAqB,8DAA8D;CACpF"}