crewly 1.5.18 → 1.5.19

package/dist/backend/backend/src/services/provisioning/provisioning.service.js

@@ -0,0 +1,261 @@
+/**
+ * DigitalOcean Provisioning Service
+ *
+ * Wraps the DigitalOcean REST API v2 for automated Droplet lifecycle
+ * management. Provides create, destroy, status, list, and wait-for-ready
+ * operations with structured error handling.
+ *
+ * All API interactions use the native `fetch` API — no external HTTP
+ * libraries required.
+ *
+ * @module services/provisioning/provisioning.service
+ */
+import { ProvisioningError, isDropletStatus, DO_API_BASE_URL, DEFAULT_IMAGE_SLUG, DEFAULT_DROPLET_SIZE, DEFAULT_REGION, CREWLY_DROPLET_TAG, DEFAULT_READY_TIMEOUT_MS, POLLING_INTERVAL_MS, } from './provisioning.types.js';
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+/**
+ * Service for managing DigitalOcean Droplets via the REST API v2.
+ *
+ * @example
+ * ```typescript
+ * const svc = new ProvisioningService({ apiToken: 'dop_v1_xxx' });
+ * const droplet = await svc.createDroplet({ name: 'my-node' });
+ * const ready = await svc.waitForDropletReady(droplet.id);
+ * console.log(ready.networks); // [{ ipAddress: '...', type: 'public' }]
+ * ```
+ */
+export class ProvisioningService {
+    apiToken;
+    defaultRegion;
+    defaultSize;
+    /**
+     * Create a new ProvisioningService.
+     *
+     * @param config - Service configuration
+     * @param config.apiToken - DigitalOcean personal access token
+     * @param config.defaultRegion - Default region slug (defaults to nyc1)
+     * @param config.defaultSize - Default size slug (defaults to s-2vcpu-4gb)
+     */
+    constructor(config) {
+        if (!config.apiToken) {
+            throw new ProvisioningError('AUTH_FAILURE', 'API token is required');
+        }
+        this.apiToken = config.apiToken;
+        this.defaultRegion = config.defaultRegion ?? DEFAULT_REGION;
+        this.defaultSize = config.defaultSize ?? DEFAULT_DROPLET_SIZE;
+    }
+    // -----------------------------------------------------------------------
+    // Public API
+    // -----------------------------------------------------------------------
+    /**
+     * Create a new DigitalOcean Droplet.
+     *
+     * The Droplet is always tagged with the `crewly-pro` tag. Additional tags
+     * may be specified via `config.tags`.
+     *
+     * @param config - Droplet creation configuration
+     * @returns Normalized Droplet info after creation (status will be 'new')
+     * @throws {ProvisioningError} On API failure
+     *
+     * @example
+     * ```typescript
+     * const info = await svc.createDroplet({
+     *   name: 'worker-1',
+     *   region: 'sfo3',
+     *   userData: '#!/bin/bash\napt-get update',
+     * });
+     * ```
+     */
+    async createDroplet(config) {
+        const tags = [CREWLY_DROPLET_TAG, ...(config.tags ?? [])];
+        const body = {
+            name: config.name,
+            region: config.region ?? this.defaultRegion,
+            size: config.size ?? this.defaultSize,
+            image: config.image ?? DEFAULT_IMAGE_SLUG,
+            tags,
+            user_data: config.userData,
+            ssh_keys: config.sshKeys,
+        };
+        const response = await this.doRequest('/droplets', 'POST', body);
+        return this.normalizeDroplet(response.droplet);
+    }
+    /**
+     * Destroy (permanently delete) a Droplet by ID.
+     *
+     * @param dropletId - The Droplet ID to destroy
+     * @throws {ProvisioningError} On API failure (e.g. NOT_FOUND)
+     */
+    async destroyDroplet(dropletId) {
+        await this.doRequest(`/droplets/${dropletId}`, 'DELETE');
+    }
+    /**
+     * Get the current status of a Droplet.
+     *
+     * @param dropletId - The Droplet ID to query
+     * @returns The Droplet's current status
+     * @throws {ProvisioningError} On API failure
+     */
+    async getDropletStatus(dropletId) {
+        const response = await this.doRequest(`/droplets/${dropletId}`, 'GET');
+        const status = response.droplet.status;
+        if (isDropletStatus(status)) {
+            return status;
+        }
+        return 'new';
+    }
+    /**
+     * List Droplets, optionally filtered by tag.
+     *
+     * @param tag - Tag to filter by (defaults to listing all Droplets)
+     * @returns Array of normalized Droplet info objects
+     * @throws {ProvisioningError} On API failure
+     */
+    async listDroplets(tag) {
+        const queryParams = tag ? `?tag_name=${encodeURIComponent(tag)}` : '';
+        const response = await this.doRequest(`/droplets${queryParams}`, 'GET');
+        return response.droplets.map((d) => this.normalizeDroplet(d));
+    }
+    /**
+     * Poll until a Droplet reaches the 'active' status.
+     *
+     * @param dropletId - The Droplet ID to watch
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 300s)
+     * @returns Normalized Droplet info once active
+     * @throws {ProvisioningError} With code 'TIMEOUT' if the Droplet does not
+     *   become active within the timeout period
+     *
+     * @example
+     * ```typescript
+     * const ready = await svc.waitForDropletReady(droplet.id, 60_000);
+     * ```
+     */
+    async waitForDropletReady(dropletId, timeoutMs = DEFAULT_READY_TIMEOUT_MS) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const response = await this.doRequest(`/droplets/${dropletId}`, 'GET');
+            const droplet = this.normalizeDroplet(response.droplet);
+            if (droplet.status === 'active') {
+                return droplet;
+            }
+            await this.sleep(POLLING_INTERVAL_MS);
+        }
+        throw new ProvisioningError('TIMEOUT', `Droplet ${dropletId} did not become active within ${timeoutMs}ms`, dropletId);
+    }
+    // -----------------------------------------------------------------------
+    // Internal Helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Make an authenticated request to the DigitalOcean API.
+     *
+     * @param path - API path (e.g. '/droplets')
+     * @param method - HTTP method
+     * @param body - Optional request body (will be JSON-serialized)
+     * @returns Parsed JSON response body
+     * @throws {ProvisioningError} On HTTP errors or network failures
+     */
+    async doRequest(path, method, body) {
+        const url = `${DO_API_BASE_URL}${path}`;
+        const headers = {
+            'Authorization': `Bearer ${this.apiToken}`,
+            'Content-Type': 'application/json',
+        };
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new ProvisioningError('NETWORK_ERROR', `Network request failed: ${message}`);
+        }
+        // DELETE returns 204 No Content on success
+        if (method === 'DELETE' && response.status === 204) {
+            return undefined;
+        }
+        if (!response.ok) {
+            await this.handleErrorResponse(response);
+        }
+        const data = await response.json();
+        return data;
+    }
+    /**
+     * Map an HTTP error response to a structured ProvisioningError.
+     *
+     * @param response - The failed fetch Response
+     * @throws {ProvisioningError} Always throws
+     */
+    async handleErrorResponse(response) {
+        let errorMessage = `DigitalOcean API error: ${response.status} ${response.statusText}`;
+        try {
+            const errorBody = (await response.json());
+            if (errorBody.message) {
+                errorMessage = errorBody.message;
+            }
+        }
+        catch {
+            // Ignore JSON parse errors — use default message
+        }
+        const code = this.mapHttpStatusToErrorCode(response.status);
+        throw new ProvisioningError(code, errorMessage);
+    }
+    /**
+     * Map an HTTP status code to a ProvisioningErrorCode.
+     *
+     * @param status - HTTP status code
+     * @returns Corresponding error code
+     */
+    mapHttpStatusToErrorCode(status) {
+        if (status === 401 || status === 403) {
+            return 'AUTH_FAILURE';
+        }
+        if (status === 404) {
+            return 'NOT_FOUND';
+        }
+        if (status === 429) {
+            return 'RATE_LIMITED';
+        }
+        if (status >= 500) {
+            return 'SERVER_ERROR';
+        }
+        return 'UNKNOWN';
+    }
+    /**
+     * Normalize a raw DO API Droplet object into our DropletInfo shape.
+     *
+     * @param raw - Raw Droplet from the DO API
+     * @returns Normalized DropletInfo
+     */
+    normalizeDroplet(raw) {
+        const networks = (raw.networks?.v4 ?? []).map((n) => ({
+            ipAddress: n.ip_address,
+            type: n.type === 'private' ? 'private' : 'public',
+        }));
+        const status = isDropletStatus(raw.status) ? raw.status : 'new';
+        return {
+            id: raw.id,
+            name: raw.name,
+            status,
+            region: raw.region?.slug ?? '',
+            size: raw.size?.slug ?? '',
+            image: raw.image?.slug ?? '',
+            tags: raw.tags ?? [],
+            networks,
+            createdAt: raw.created_at,
+        };
+    }
+    /**
+     * Sleep for a given number of milliseconds.
+     *
+     * @param ms - Duration in milliseconds
+     * @returns Promise that resolves after the delay
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=provisioning.service.js.map

package/dist/backend/backend/src/services/provisioning/provisioning.service.js.map

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

package/dist/backend/backend/src/services/provisioning/provisioning.types.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Provisioning Types
+ *
+ * TypeScript type definitions for the DigitalOcean provisioning service.
+ * Includes configuration, Droplet models, error types, and type guards.
+ *
+ * @module services/provisioning/provisioning.types
+ */
+/** Default Ubuntu 24.04 LTS image slug for DigitalOcean. */
+export declare const DEFAULT_IMAGE_SLUG = "ubuntu-24-04-x64";
+/** Default Droplet size (2 vCPUs, 4 GB RAM). */
+export declare const DEFAULT_DROPLET_SIZE = "s-2vcpu-4gb";
+/** Default region for new Droplets. */
+export declare const DEFAULT_REGION = "nyc1";
+/** Tag applied to all Crewly-managed Droplets. */
+export declare const CREWLY_DROPLET_TAG = "crewly-pro";
+/** DigitalOcean API v2 base URL. */
+export declare const DO_API_BASE_URL = "https://api.digitalocean.com/v2";
+/** Default timeout (in ms) for waitForDropletReady polling. */
+export declare const DEFAULT_READY_TIMEOUT_MS = 300000;
+/** Polling interval (in ms) for waitForDropletReady. */
+export declare const POLLING_INTERVAL_MS = 5000;
+/** Firewall ports opened on Crewly Droplets. */
+export declare const CREWLY_FIREWALL_PORTS: {
+    readonly SSH: 22;
+    readonly WEB_UI: 8787;
+};
+/**
+ * Configuration for the ProvisioningService constructor.
+ *
+ * @param apiToken - DigitalOcean personal access token
+ * @param defaultRegion - Region slug for new Droplets (default: nyc1)
+ * @param defaultSize - Size slug for new Droplets (default: s-2vcpu-4gb)
+ */
+export interface ProvisioningServiceConfig {
+    /** DigitalOcean personal access token. */
+    apiToken: string;
+    /** Region slug override (e.g. 'sfo3', 'ams3'). */
+    defaultRegion?: string;
+    /** Size slug override (e.g. 's-4vcpu-8gb'). */
+    defaultSize?: string;
+}
+/** Valid Droplet status values as reported by the DO API. */
+export type DropletStatus = 'new' | 'active' | 'off' | 'archive';
+/**
+ * Networking information for a Droplet.
+ */
+export interface DropletNetwork {
+    /** IPv4 address. */
+    ipAddress: string;
+    /** Network type (public or private). */
+    type: 'public' | 'private';
+}
+/**
+ * Normalized information about a DigitalOcean Droplet.
+ */
+export interface DropletInfo {
+    /** Unique Droplet identifier. */
+    id: number;
+    /** Human-readable name. */
+    name: string;
+    /** Current status. */
+    status: DropletStatus;
+    /** Region slug where the Droplet is deployed. */
+    region: string;
+    /** Size slug describing the Droplet's resources. */
+    size: string;
+    /** Image slug or ID used to create the Droplet. */
+    image: string;
+    /** Tags applied to the Droplet. */
+    tags: string[];
+    /** Network interfaces. */
+    networks: DropletNetwork[];
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+}
+/**
+ * Configuration for creating a new Droplet.
+ */
+export interface CreateDropletConfig {
+    /** Human-readable name for the Droplet. */
+    name: string;
+    /** Region slug (overrides service default). */
+    region?: string;
+    /** Size slug (overrides service default). */
+    size?: string;
+    /** Image slug (defaults to Ubuntu 24.04 LTS). */
+    image?: string;
+    /** Tags to apply in addition to the default crewly-pro tag. */
+    tags?: string[];
+    /** Cloud-init user data script for initial setup. */
+    userData?: string;
+    /** SSH key IDs or fingerprints to include. */
+    sshKeys?: (number | string)[];
+}
+/**
+ * Shape of a Droplet object in the DigitalOcean API response.
+ * Only includes the fields we actually consume.
+ */
+export interface DoApiDroplet {
+    id: number;
+    name: string;
+    status: string;
+    region: {
+        slug: string;
+    };
+    size: {
+        slug: string;
+    };
+    image: {
+        slug: string;
+    };
+    tags: string[];
+    networks: {
+        v4: Array<{
+            ip_address: string;
+            type: string;
+        }>;
+    };
+    created_at: string;
+}
+/** Shape of the DO API response for creating/getting a single Droplet. */
+export interface DoApiDropletResponse {
+    droplet: DoApiDroplet;
+}
+/** Shape of the DO API response for listing Droplets. */
+export interface DoApiDropletsListResponse {
+    droplets: DoApiDroplet[];
+}
+/** Shape of a DigitalOcean API error response body. */
+export interface DoApiErrorResponse {
+    id: string;
+    message: string;
+}
+/** Error codes specific to provisioning operations. */
+export type ProvisioningErrorCode = 'RATE_LIMITED' | 'AUTH_FAILURE' | 'NOT_FOUND' | 'SERVER_ERROR' | 'TIMEOUT' | 'NETWORK_ERROR' | 'UNKNOWN';
+/**
+ * Custom error class for provisioning failures.
+ * Wraps DigitalOcean API errors with structured metadata.
+ */
+export declare class ProvisioningError extends Error {
+    /** Structured error code for programmatic handling. */
+    readonly code: ProvisioningErrorCode;
+    /** Associated Droplet ID, if applicable. */
+    readonly dropletId?: number;
+    /**
+     * Create a new ProvisioningError.
+     *
+     * @param code - Structured error code
+     * @param message - Human-readable error description
+     * @param dropletId - Associated Droplet ID (optional)
+     */
+    constructor(code: ProvisioningErrorCode, message: string, dropletId?: number);
+}
+/**
+ * Check whether a string is a valid DropletStatus.
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid DropletStatus
+ */
+export declare function isDropletStatus(value: unknown): value is DropletStatus;
+/**
+ * Check whether a value is a valid ProvisioningErrorCode.
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid ProvisioningErrorCode
+ */
+export declare function isProvisioningErrorCode(value: unknown): value is ProvisioningErrorCode;
+/**
+ * Check whether a value looks like a DoApiDroplet (duck-type check).
+ * Validates the minimum fields required for normalization.
+ *
+ * @param value - Value to check
+ * @returns True if value has the expected shape
+ */
+export declare function isDoApiDroplet(value: unknown): value is DoApiDroplet;
+/**
+ * Check whether a value is a ProvisioningError instance.
+ *
+ * @param value - Value to check
+ * @returns True if value is a ProvisioningError
+ */
+export declare function isProvisioningError(value: unknown): value is ProvisioningError;
+//# sourceMappingURL=provisioning.types.d.ts.map

package/dist/backend/backend/src/services/provisioning/provisioning.types.d.ts.map

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

package/dist/backend/backend/src/services/provisioning/provisioning.types.js

@@ -0,0 +1,119 @@
+/**
+ * Provisioning Types
+ *
+ * TypeScript type definitions for the DigitalOcean provisioning service.
+ * Includes configuration, Droplet models, error types, and type guards.
+ *
+ * @module services/provisioning/provisioning.types
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default Ubuntu 24.04 LTS image slug for DigitalOcean. */
+export const DEFAULT_IMAGE_SLUG = 'ubuntu-24-04-x64';
+/** Default Droplet size (2 vCPUs, 4 GB RAM). */
+export const DEFAULT_DROPLET_SIZE = 's-2vcpu-4gb';
+/** Default region for new Droplets. */
+export const DEFAULT_REGION = 'nyc1';
+/** Tag applied to all Crewly-managed Droplets. */
+export const CREWLY_DROPLET_TAG = 'crewly-pro';
+/** DigitalOcean API v2 base URL. */
+export const DO_API_BASE_URL = 'https://api.digitalocean.com/v2';
+/** Default timeout (in ms) for waitForDropletReady polling. */
+export const DEFAULT_READY_TIMEOUT_MS = 300_000;
+/** Polling interval (in ms) for waitForDropletReady. */
+export const POLLING_INTERVAL_MS = 5_000;
+/** Firewall ports opened on Crewly Droplets. */
+export const CREWLY_FIREWALL_PORTS = {
+    SSH: 22,
+    WEB_UI: 8787,
+};
+/**
+ * Custom error class for provisioning failures.
+ * Wraps DigitalOcean API errors with structured metadata.
+ */
+export class ProvisioningError extends Error {
+    /** Structured error code for programmatic handling. */
+    code;
+    /** Associated Droplet ID, if applicable. */
+    dropletId;
+    /**
+     * Create a new ProvisioningError.
+     *
+     * @param code - Structured error code
+     * @param message - Human-readable error description
+     * @param dropletId - Associated Droplet ID (optional)
+     */
+    constructor(code, message, dropletId) {
+        super(message);
+        this.name = 'ProvisioningError';
+        this.code = code;
+        this.dropletId = dropletId;
+    }
+}
+// ---------------------------------------------------------------------------
+// Type Guards
+// ---------------------------------------------------------------------------
+/** Valid Droplet status strings. */
+const VALID_DROPLET_STATUSES = new Set([
+    'new',
+    'active',
+    'off',
+    'archive',
+]);
+/**
+ * Check whether a string is a valid DropletStatus.
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid DropletStatus
+ */
+export function isDropletStatus(value) {
+    return typeof value === 'string' && VALID_DROPLET_STATUSES.has(value);
+}
+/**
+ * Check whether a value is a valid ProvisioningErrorCode.
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid ProvisioningErrorCode
+ */
+export function isProvisioningErrorCode(value) {
+    const codes = new Set([
+        'RATE_LIMITED',
+        'AUTH_FAILURE',
+        'NOT_FOUND',
+        'SERVER_ERROR',
+        'TIMEOUT',
+        'NETWORK_ERROR',
+        'UNKNOWN',
+    ]);
+    return typeof value === 'string' && codes.has(value);
+}
+/**
+ * Check whether a value looks like a DoApiDroplet (duck-type check).
+ * Validates the minimum fields required for normalization.
+ *
+ * @param value - Value to check
+ * @returns True if value has the expected shape
+ */
+export function isDoApiDroplet(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const obj = value;
+    return (typeof obj['id'] === 'number' &&
+        typeof obj['name'] === 'string' &&
+        typeof obj['status'] === 'string' &&
+        typeof obj['region'] === 'object' &&
+        obj['region'] !== null &&
+        typeof obj['created_at'] === 'string');
+}
+/**
+ * Check whether a value is a ProvisioningError instance.
+ *
+ * @param value - Value to check
+ * @returns True if value is a ProvisioningError
+ */
+export function isProvisioningError(value) {
+    return value instanceof ProvisioningError;
+}
+//# sourceMappingURL=provisioning.types.js.map

package/dist/backend/backend/src/services/provisioning/provisioning.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisioning.types.js","sourceRoot":"","sources":["../../../../../../backend/src/services/provisioning/provisioning.types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,4DAA4D;AAC5D,MAAM,CAAC,MAAM,kBAAkB,GAAG,kBAAkB,CAAC;AAErD,gDAAgD;AAChD,MAAM,CAAC,MAAM,oBAAoB,GAAG,aAAa,CAAC;AAElD,uCAAuC;AACvC,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC;AAErC,kDAAkD;AAClD,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAY,CAAC;AAE/C,oCAAoC;AACpC,MAAM,CAAC,MAAM,eAAe,GAAG,iCAAiC,CAAC;AAEjE,+DAA+D;AAC/D,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;AAEhD,wDAAwD;AACxD,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAEzC,gDAAgD;AAChD,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,GAAG,EAAE,EAAE;IACP,MAAM,EAAE,IAAI;CACJ,CAAC;AA0IX;;;GAGG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,uDAAuD;IAC9C,IAAI,CAAwB;IACrC,4CAA4C;IACnC,SAAS,CAAU;IAE5B;;;;;;OAMG;IACH,YAAY,IAA2B,EAAE,OAAe,EAAE,SAAkB;QAC1E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E,oCAAoC;AACpC,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC;IAC1D,KAAK;IACL,QAAQ;IACR,KAAK;IACL,SAAS;CACV,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,sBAAsB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACxE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,MAAM,KAAK,GAAwB,IAAI,GAAG,CAAC;QACzC,cAAc;QACd,cAAc;QACd,WAAW;QACX,cAAc;QACd,SAAS;QACT,eAAe;QACf,SAAS;KACV,CAAC,CAAC;IACH,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,OAAO,CACL,OAAO,GAAG,CAAC,IAAI,CAAC,KAAK,QAAQ;QAC7B,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ;QAC/B,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,QAAQ;QACjC,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,QAAQ;QACjC,GAAG,CAAC,QAAQ,CAAC,KAAK,IAAI;QACtB,OAAO,GAAG,CAAC,YAAY,CAAC,KAAK,QAAQ,CACtC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,OAAO,KAAK,YAAY,iBAAiB,CAAC;AAC5C,CAAC"}