@aws-blocks/core 0.1.0

package/dist/pipeline/types.d.ts

@@ -0,0 +1,351 @@
+import type * as cdk from 'aws-cdk-lib';
+import type * as codebuild from 'aws-cdk-lib/aws-codebuild';
+/**
+ * Configuration for the pipeline source (GitHub/CodeConnections).
+ *
+ * Uses AWS CodeConnections (formerly CodeStar Connections) for OAuth-based
+ * access to GitHub repositories. No token management required — the
+ * connection is created once via the AWS Console.
+ */
+export interface PipelineSourceConfig {
+    /**
+     * Repository in `owner/repo` format.
+     *
+     * @example 'my-org/my-app'
+     */
+    readonly repo: string;
+    /**
+     * ARN of the AWS CodeConnections connection.
+     *
+     * **Important:** This connection requires a one-time OAuth handshake via the
+     * AWS Console before it can be used. After creating the connection resource
+     * (via CDK, CLI, or Console), you must complete the OAuth flow in the
+     * Console under **Developer Tools → Connections** — the connection will be
+     * in `PENDING` status until authorized.
+     *
+     * Steps:
+     * 1. Create the connection (Console or CLI)
+     * 2. Navigate to **Developer Tools → Connections** in the AWS Console
+     * 3. Select the pending connection and click "Update pending connection"
+     * 4. Authorize the GitHub app and select your repository/organization
+     * 5. The status changes to `AVAILABLE` — the pipeline can now pull source
+     *
+     * @see https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-github.html
+     *
+     * @example 'arn:aws:codeconnections:us-east-1:123456789:connection/abc-def'
+     */
+    readonly connectionArn: string;
+    /**
+     * Whether to trigger the pipeline on push to the branch.
+     *
+     * @default true
+     */
+    readonly triggerOnPush?: boolean;
+    /**
+     * Path-based trigger filters for monorepo support.
+     *
+     * When specified, the pipeline only triggers on pushes that modify files
+     * matching these path patterns. Useful for monorepos where multiple
+     * pipelines share a single repository.
+     *
+     * @example ['packages/backend/**', 'shared/**']
+     */
+    readonly triggerFilters?: string[];
+}
+/**
+ * Configuration for the synth step (build + CDK synth).
+ *
+ * The synth step installs dependencies and runs `cdk synth` to produce
+ * the CloudFormation template. The pipeline is self-mutating: if the
+ * synth output changes the pipeline definition, it updates itself first.
+ */
+export interface PipelineSynthConfig {
+    /**
+     * Shell commands to run during the synth step.
+     *
+     * @default ['npm ci', 'npx cdk synth'] — installs dependencies and synthesizes the CDK app.
+     * Override if you need Node version upgrades, custom build steps, or a non-standard cdk.json app path.
+     * If your app requires Node 22+, prepend `'n 22'` to commands or use {@link installCommands}.
+     */
+    readonly commands?: string[];
+    /**
+     * Commands to run in the CodeBuild install phase (before synth commands).
+     *
+     * @default [] — no install commands. The default build image (Amazon Linux 2023 standard:5.0)
+     * includes Node 22. Set this if you need additional global tools or a different Node version.
+     *
+     * @example ['n 20'] — downgrade Node to version 20
+     */
+    readonly installCommands?: string[];
+    /**
+     * The CodeBuild build image to use for the synth step.
+     *
+     * The default image (Amazon Linux 2023 standard:5.0) includes Node 22 and
+     * Amazon Linux 2023. Override this if you need a different OS or runtime set.
+     *
+     * @default codebuild.LinuxBuildImage.AMAZON_LINUX_2023_5
+     */
+    readonly buildImage?: codebuild.IBuildImage;
+    /**
+     * Environment variables available during synth.
+     *
+     * Note: `NODE_OPTIONS` is automatically prepended with `--conditions=cdk`
+     * (required for ESM conditional exports). Your custom NODE_OPTIONS will be
+     * appended after this flag.
+     */
+    readonly env?: Record<string, string>;
+    /**
+     * Primary output directory for the CDK cloud assembly.
+     *
+     * Override this for monorepos where `cdk synth` outputs to a
+     * subdirectory (e.g., `packages/infra/cdk.out`).
+     *
+     * @default 'cdk.out'
+     */
+    readonly primaryOutputDirectory?: string;
+    /**
+     * Whether to enable Docker for the synth step.
+     *
+     * Required when your CDK app uses Docker image assets (e.g., Lambda
+     * container images, ECS task definitions with Dockerfile builds).
+     *
+     * @default false
+     */
+    readonly dockerEnabled?: boolean;
+    /**
+     * CodeBuild compute type for the synth step.
+     *
+     * Controls the CPU/memory allocation for the build environment.
+     * Increase this if you encounter OOM (exit code 137) during synth/bundling.
+     *
+     * - `SMALL`: 2 vCPU, 3 GB
+     * - `MEDIUM`: 4 vCPU, 7 GB
+     * - `LARGE`: 8 vCPU, 15 GB
+     *
+     * @default ComputeType.MEDIUM (7GB RAM, 4 vCPU) — sufficient for most apps with
+     * Lambda bundling + frontend builds. Use SMALL for trivial apps or LARGE for monorepos.
+     */
+    readonly computeType?: codebuild.ComputeType;
+}
+/**
+ * Configuration for a deployment stage.
+ *
+ * Each stage represents a deployment environment (e.g., beta, prod).
+ * Stages are deployed in the order they appear in the `stages` array.
+ */
+export interface PipelineStageConfig<TConfig = Record<string, unknown>> {
+    /**
+     * Logical name for this stage (e.g., 'beta', 'prod').
+     * Used as the CDK Stage construct id.
+     */
+    readonly name: string;
+    /**
+     * Target AWS account and region for this stage.
+     * When omitted, deploys to the pipeline's own account/region.
+     */
+    readonly env?: cdk.Environment;
+    /**
+     * Whether to require manual approval before deploying to this stage.
+     *
+     * @default false
+     */
+    readonly requireApproval?: boolean;
+    /**
+     * Optional comment shown in the approval notification.
+     * Only relevant when `requireApproval` is true.
+     */
+    readonly approvalComment?: string;
+    /**
+     * Optional baking time after deployment before proceeding.
+     * Useful for canary validation — gives time for alarms to fire.
+     *
+     * Implemented as a CodeBuild `sleep` step (~$0.005/min on
+     * `BUILD_GENERAL1_SMALL`). An explicit timeout of bakeTime + 10 minutes
+     * is set on the CodeBuild step to prevent pipeline hangs.
+     *
+     * For longer baking periods, use `requireApproval: true` with
+     * external monitoring/alerting instead.
+     */
+    readonly bakeTime?: cdk.Duration;
+    /**
+     * User-defined configuration passed through to the `stageFactory`.
+     *
+     * Use this for per-stage settings like domain names, feature flags,
+     * scaling parameters, etc.
+     *
+     * @example { domain: 'myapp.com', enableCanary: true }
+     */
+    readonly config?: TConfig;
+    /**
+     * Environment variables to set on `process.env` when importing the app file for this stage.
+     *
+     * These are synthesis-time variables (available during `cdk synth`), not deployment-time.
+     * Use this for per-stage configuration that your CDK app reads from `process.env`
+     * (e.g., domain names, feature flags). Only applies when using the `appFile` prop.
+     *
+     * @example { DOMAIN: 'myapp.com', ENABLE_CANARY: 'true' }
+     */
+    readonly environment?: Record<string, string>;
+}
+/**
+ * Configuration for a single branch pipeline.
+ *
+ * Each branch entry creates its own independent CodePipeline that triggers
+ * on pushes to the specified branch and deploys through its own ordered stages.
+ */
+export interface BranchConfig<TConfig = Record<string, unknown>> {
+    /**
+     * Git branch that triggers this pipeline.
+     *
+     * @example 'main'
+     */
+    readonly branch: string;
+    /**
+     * Ordered list of deployment stages for this branch's pipeline.
+     */
+    readonly stages: Array<PipelineStageConfig<TConfig>>;
+    /**
+     * Whether to trigger this branch's pipeline on push.
+     *
+     * Overrides the top-level `source.triggerOnPush` for this specific branch.
+     * Useful when you want most branches to auto-trigger but disable it for
+     * specific branches (e.g., a release branch that deploys on manual trigger only).
+     *
+     * @default inherits from source.triggerOnPush (which defaults to true)
+     */
+    readonly triggerOnPush?: boolean;
+}
+/**
+ * Props for the {@link Pipeline} L3 construct.
+ *
+ * @example Multi-branch configuration
+ * ```ts
+ * new Pipeline(stack, 'Pipeline', {
+ *   source: {
+ *     repo: 'my-org/my-app',
+ *     connectionArn: 'arn:aws:codeconnections:us-east-1:123456789:connection/abc',
+ *   },
+ *   branches: [
+ *     {
+ *       branch: 'main',
+ *       stages: [
+ *         { name: 'beta' },
+ *         { name: 'prod', requireApproval: true, config: { domain: 'myapp.com' } },
+ *       ],
+ *     },
+ *     {
+ *       branch: 'develop',
+ *       stages: [
+ *         { name: 'alpha', config: { domain: 'alpha.myapp.com' } },
+ *       ],
+ *     },
+ *   ],
+ *   stageFactory: (scope, stageConfig) => {
+ *     new MyAppStack(scope, 'App', {
+ *       stackName: `my-app-${stageConfig.name}`,
+ *       env: stageConfig.env,
+ *     });
+ *   },
+ * });
+ * ```
+ *
+ * @example With custom synth and bake time
+ * ```ts
+ * new Pipeline(stack, 'Pipeline', {
+ *   source: {
+ *     repo: 'my-org/my-app',
+ *     connectionArn: 'arn:aws:codeconnections:...',
+ *   },
+ *   branches: [
+ *     {
+ *       branch: 'release',
+ *       stages: [
+ *         { name: 'beta' },
+ *         { name: 'prod', requireApproval: true, bakeTime: Duration.minutes(30) },
+ *       ],
+ *     },
+ *   ],
+ *   synth: {
+ *     commands: ['npm ci', 'npm run build', 'npx cdk synth'],
+ *   },
+ *   stageFactory: (scope, stageConfig) => {
+ *     new MyAppStack(scope, 'App', { env: stageConfig.env });
+ *   },
+ * });
+ * ```
+ */
+export interface PipelineProps<TConfig = Record<string, unknown>> {
+    /** Source repository configuration. */
+    readonly source: PipelineSourceConfig;
+    /** Synth step configuration. */
+    readonly synth?: PipelineSynthConfig;
+    /**
+     * Branch configurations. Each entry creates a separate CodePipeline.
+     *
+     * A single source repository can have multiple branch pipelines, each
+     * with its own set of deployment stages and configuration.
+     */
+    readonly branches: Array<BranchConfig<TConfig>>;
+    /**
+     * Factory function that populates a CDK Stage with stacks.
+     *
+     * Called once per stage across all branches. The factory receives the Stage
+     * scope and the full stage configuration object (including `name`, `env`,
+     * and any user-defined `config`).
+     *
+     * May be async when using constructs that require async initialization
+     * (e.g., `BlocksStack.create()`). When async, use `Pipeline.create()` instead
+     * of `new Pipeline()` to ensure all stages are fully resolved before synth.
+     *
+     * Mutually exclusive with `appFile`. One of `stageFactory` or `appFile` must be provided
+     * for the sync constructor (`new Pipeline()`). When using `Pipeline.create()`, if neither
+     * is provided, `appFile` defaults to `'./index.cdk.ts'`.
+     *
+     * @param scope - The CDK Stage construct to add stacks to.
+     * @param stageConfig - The full stage configuration including name, env, and user-defined config.
+     */
+    readonly stageFactory?: (scope: cdk.Stage, stageConfig: PipelineStageConfig<TConfig>) => void | Promise<void>;
+    /**
+     * Path to the CDK app file to import for each stage.
+     *
+     * When provided, the pipeline will dynamically import this file once per stage,
+     * with the ambient `__PIPELINE_STAGE_SCOPE__` set on globalThis so that
+     * `BlocksStack.create()` automatically attaches to the correct stage scope.
+     *
+     * The path is resolved **relative to the calling file** (not CWD), using
+     * `Error.stack` to determine the caller's directory. Absolute paths are
+     * used as-is.
+     *
+     * Each stage's `environment` vars are set on `process.env` before the import
+     * and cleaned up afterward.
+     *
+     * Mutually exclusive with `stageFactory`. When using `Pipeline.create()` and
+     * neither `appFile` nor `stageFactory` is provided, defaults to `'./index.cdk.ts'`
+     * (resolved relative to the calling file).
+     *
+     * **Security:** This path is dynamically imported during CDK synth, executing
+     * the module's code in the synth process. It MUST originate from a trusted source
+     * (developer's pipeline definition file). Never wire this from external input
+     * (environment variables, build args, plugin configs, or user-supplied values).
+     * A path-containment check enforces that the resolved file stays within the
+     * project root, and only `.ts`, `.js`, `.mjs`, `.cjs` extensions are accepted.
+     *
+     * @default './index.cdk.ts' (when using Pipeline.create() without stageFactory)
+     * @example './infra/app.ts'
+     */
+    readonly appFile?: string;
+    /**
+     * Whether the pipeline should self-mutate (update its own definition).
+     *
+     * @default true
+     */
+    readonly selfMutation?: boolean;
+    /**
+     * Cross-account keys for artifact encryption.
+     * Enable when deploying to accounts different from the pipeline account.
+     *
+     * @default false
+     */
+    readonly crossAccountKeys?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/pipeline/types.d.ts.map

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

package/dist/pipeline/types.js

@@ -0,0 +1,3 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+export {};

package/dist/raw-route.cdk.d.ts

@@ -0,0 +1,47 @@
+import { Scope } from './cdk/index.js';
+import type { ScopeParent } from './common/index.js';
+import { type RawRouteOptions } from './raw-route.js';
+export { RawRouteErrors, type RawRouteOptions, type HttpMethod } from './raw-route.js';
+/**
+ * Raw HTTP route Building Block (CDK).
+ *
+ * Provides raw HTTP endpoints with full request/response control, beyond the
+ * default RPC-only `POST /api` pattern. Routes are dispatched by the Lambda
+ * handler and dev server based on HTTP method + path pattern matching.
+ *
+ * ## Path
+ *
+ * When `path` is provided, it is used exactly as given. When omitted, the
+ * path is derived from the scope-chain IDs (excluding the root BlocksStack):
+ *
+ * ```typescript
+ * // Explicit path — used as-is
+ * new RawRoute(scope, 'health', { method: 'GET', path: '/health', handler });
+ *
+ * // Derived path — scope chain determines the URL
+ * new RawRoute(scope, 'health', { method: 'GET', handler });
+ * // If scope is the top-level Scope('my-app'), path becomes /health
+ * ```
+ *
+ * **Caution:** Changing the construct tree structure changes derived URLs.
+ * Use explicit paths for routes that must remain stable.
+ *
+ * ## Path syntax (when explicit)
+ *
+ * - `/health`       — exact match
+ * - `/users/{id}`   — named path parameter (captures one segment)
+ * - `/v1/*`         — wildcard (captures everything after prefix)
+ *
+ * ## How it works
+ *
+ * - At construction time, the route is registered in a global registry.
+ * - The Lambda handler and dev server check the registry before falling through to RPC dispatch.
+ * - The CDK side only validates the route (duplicate detection). No additional AWS resources
+ *   are created — the existing catch-all API Gateway proxy routes all paths to the Lambda.
+ */
+export declare class RawRoute extends Scope {
+    /** The resolved path this route is registered at. */
+    readonly path: string;
+    constructor(scope: ScopeParent, id: string, options: RawRouteOptions);
+}
+//# sourceMappingURL=raw-route.cdk.d.ts.map

package/dist/raw-route.cdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-route.cdk.d.ts","sourceRoot":"","sources":["../src/raw-route.cdk.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAmC,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEvF,OAAO,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,qDAAqD;IACrD,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAEjB,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe;CAKrE"}

package/dist/raw-route.cdk.js

@@ -0,0 +1,51 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Scope } from './cdk/index.js';
+import { registerRoute, resolveRoutePath } from './raw-route.js';
+export { RawRouteErrors } from './raw-route.js';
+/**
+ * Raw HTTP route Building Block (CDK).
+ *
+ * Provides raw HTTP endpoints with full request/response control, beyond the
+ * default RPC-only `POST /api` pattern. Routes are dispatched by the Lambda
+ * handler and dev server based on HTTP method + path pattern matching.
+ *
+ * ## Path
+ *
+ * When `path` is provided, it is used exactly as given. When omitted, the
+ * path is derived from the scope-chain IDs (excluding the root BlocksStack):
+ *
+ * ```typescript
+ * // Explicit path — used as-is
+ * new RawRoute(scope, 'health', { method: 'GET', path: '/health', handler });
+ *
+ * // Derived path — scope chain determines the URL
+ * new RawRoute(scope, 'health', { method: 'GET', handler });
+ * // If scope is the top-level Scope('my-app'), path becomes /health
+ * ```
+ *
+ * **Caution:** Changing the construct tree structure changes derived URLs.
+ * Use explicit paths for routes that must remain stable.
+ *
+ * ## Path syntax (when explicit)
+ *
+ * - `/health`       — exact match
+ * - `/users/{id}`   — named path parameter (captures one segment)
+ * - `/v1/*`         — wildcard (captures everything after prefix)
+ *
+ * ## How it works
+ *
+ * - At construction time, the route is registered in a global registry.
+ * - The Lambda handler and dev server check the registry before falling through to RPC dispatch.
+ * - The CDK side only validates the route (duplicate detection). No additional AWS resources
+ *   are created — the existing catch-all API Gateway proxy routes all paths to the Lambda.
+ */
+export class RawRoute extends Scope {
+    /** The resolved path this route is registered at. */
+    path;
+    constructor(scope, id, options) {
+        super(id, { parent: scope });
+        this.path = resolveRoutePath(scope, id, options);
+        registerRoute({ ...options, path: this.path });
+    }
+}

package/dist/raw-route.d.ts

@@ -0,0 +1,119 @@
+import type { BlocksContext } from './api.js';
+import type { ScopeParent } from './common/index.js';
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+export interface RawRouteOptions {
+    method: HttpMethod;
+    /**
+     * URL path pattern. When provided, used exactly as given.
+     * When omitted, derived from the scope-chain IDs.
+     *
+     * - `/health`       — exact match
+     * - `/users/{id}`   — named path parameter (captures one segment)
+     * - `/v1/*`         — wildcard (captures everything after prefix)
+     *
+     * **Scope-chain derivation:** If omitted, the path is built by collecting
+     * each ancestor scope's `id` (excluding the root BlocksStack) and joining
+     * with `/`. For example, `BlocksStack('app') → Scope('v1') → RawRoute('health')`
+     * yields `/v1/health`.
+     */
+    path?: string;
+    handler: (context: BlocksContext) => Promise<void>;
+}
+/**
+ * Typed error constants for RawRoute. Use with `isBlocksError()` in catch blocks.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   new RawRoute(scope, 'dup', { method: 'GET', path: '/health', handler });
+ * } catch (e: unknown) {
+ *   if (isBlocksError(e, RawRouteErrors.DuplicateRoute)) {
+ *     // same method+path already registered
+ *   }
+ * }
+ * ```
+ */
+export declare const RawRouteErrors: {
+    readonly DuplicateRoute: "DuplicateRouteException";
+};
+/**
+ * Derive a URL path from the scope chain.
+ *
+ * Walks the parent chain from `scope` up to (but NOT including) the root
+ * BlocksStack or the top-level user Scope, collects each intermediate scope's
+ * `id`, URL-encodes segments, and joins with `/`. The RawRoute's own `id`
+ * is appended as the final segment.
+ *
+ * A scope is "root-level" if its parent has no `parent` property (i.e., it's
+ * the BlocksStack or the fallback `{ id: ... }` sentinel). Root-level scopes
+ * are excluded from the path — they represent the application boundary, not
+ * a URL segment.
+ *
+ * @example
+ * ```
+ * Scope('app') → RawRoute('health')                    → /health
+ * Scope('app') → Scope('v1') → RawRoute('users')       → /v1/users
+ * Scope('app') → Scope('api') → Scope('v2') → RawRoute('items') → /api/v2/items
+ * ```
+ */
+export declare function derivePathFromScope(scope: ScopeParent, id: string): string;
+/**
+ * Resolve the effective path for a RawRoute — uses the explicit `path` if
+ * provided, otherwise derives it from the scope chain.
+ */
+export declare function resolveRoutePath(scope: ScopeParent, id: string, options: RawRouteOptions): string;
+export interface RegisteredRoute {
+    method: string;
+    /** Normalized path (trailing slashes removed, double slashes collapsed). */
+    path: string;
+    /** Compiled regex for matching incoming request paths. */
+    pattern: RegExp;
+    /** Extracted parameter names in capture-group order. */
+    paramNames: string[];
+    handler: (context: BlocksContext) => Promise<void>;
+}
+/** Prevent further route registration. Call after initialization is complete. */
+export declare function lockRouteRegistry(): void;
+/** Re-allow route registration (useful in tests after lock). */
+export declare function unlockRouteRegistry(): void;
+/**
+ * Register a raw HTTP route for runtime dispatch.
+ *
+ * **Internal.** The public API is `new RawRoute(scope, id, options)`.
+ * Path must be resolved before calling this function.
+ *
+ * @throws If registration is locked (after handler creation).
+ * @throws If the HTTP method is invalid.
+ * @throws If the path is under the reserved namespace (`/aws-blocks` or `/aws-blocks/api/*`).
+ * @throws {RawRouteErrors.DuplicateRoute} If the same method+path is registered twice.
+ */
+export declare function registerRoute(options: RawRouteOptions & {
+    path: string;
+}): void;
+/** Return a read-only snapshot of all registered routes. */
+export declare function getRegisteredRoutes(): readonly RegisteredRoute[];
+/** Remove all registered routes and unlock registration (used by tests). */
+export declare function clearRouteRegistry(): void;
+/**
+ * Match an incoming HTTP request against registered routes.
+ *
+ * @returns The matched route and extracted path parameters, or `null` if no match.
+ */
+export declare function matchRoute(method: string, path: string): {
+    route: RegisteredRoute;
+    params: Record<string, string>;
+} | null;
+/**
+ * Compile a path pattern into a RegExp and extract parameter names.
+ *
+ * Supported syntax:
+ * - `/health`        → exact match
+ * - `/users/{id}`    → captures one path segment as `id`
+ * - `/v1/*`          → captures everything after `/v1/` as `*`
+ * - `/a/{x}/b/{y}`   → multiple named parameters
+ */
+export declare function compilePath(path: string): {
+    pattern: RegExp;
+    paramNames: string[];
+};
+//# sourceMappingURL=raw-route.d.ts.map

package/dist/raw-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-route.d.ts","sourceRoot":"","sources":["../src/raw-route.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAKrD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1F,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,UAAU,CAAC;IACnB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc;;CAEjB,CAAC;AAIX;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAc1E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CAEjG;AAID,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAOD,iFAAiF;AACjF,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED,gEAAgE;AAChE,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAuC/E;AAED,4DAA4D;AAC5D,wBAAgB,mBAAmB,IAAI,SAAS,eAAe,EAAE,CAEhE;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,CAoBnE;AA6BD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAgEnF"}