pax8-cta 0.1.0

package/dist/lib/error-handler.js

@@ -0,0 +1,458 @@
+/**
+ * Copyright 2024 Pax8, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import chalk from "chalk";
+import { AuthError, GdapError, SolutionError, AgentResolutionError, ConfigValidationError, NetworkError, ErrorCode, isCtaError, } from "@pax8-cta/core";
+const LEGACY_QUEUE_ERROR_MESSAGE = "Legacy deployment queue support is unavailable in the open-source CLI";
+const LEGACY_QUEUE_ERROR_CAUSES = [
+    "A Redis-backed worker was referenced by older tooling or configuration",
+    "The CLI now deploys directly and does not use a queue",
+    "An outdated command or environment variable is still pointing at Redis",
+];
+const LEGACY_QUEUE_ERROR_RECOVERY = [
+    "Remove any legacy queue-related flags or configuration",
+    "Use the direct deployment flow instead:",
+    "  deploy --direct --all --solution ./agent.zip",
+    "If this is coming from older automation, update it to call the direct CLI",
+];
+/**
+ * Structured CLI error with recovery guidance.
+ *
+ * This wraps any error (typed or untyped) into a presentation-friendly
+ * format with causes, recovery steps, and context for the CLI output.
+ */
+export class CtaError extends Error {
+    code;
+    causes;
+    recovery;
+    context;
+    constructor(code, message, causes, recovery, context) {
+        super(message);
+        this.code = code;
+        this.causes = causes;
+        this.recovery = recovery;
+        this.context = context;
+        this.name = "CtaError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Code-based mapping: structured errors from @pax8-cta/core
+// ---------------------------------------------------------------------------
+function formatByErrorCode(error) {
+    const ctx = {
+        environmentUrl: error.context?.environmentUrl,
+        tenantName: error.context?.tenantName,
+        solutionName: error.context?.solutionName,
+        clientId: error.context?.clientId,
+    };
+    // --- GDAP / App-user errors ---
+    if (error instanceof GdapError ||
+        error.code === ErrorCode.GDAP_MISSING ||
+        error.code === ErrorCode.GDAP_APP_USER_NOT_REGISTERED ||
+        error.code === ErrorCode.GDAP_SETUP_FAILED ||
+        error.code === ErrorCode.GDAP_ENVIRONMENT_ID_MISSING) {
+        return new CtaError("ERROR_GDAP_MISSING", "Application user not registered in Power Platform environment", [
+            "The application is not configured as a user in the target environment",
+            "The app registration may not have been added to the environment yet",
+            "GDAP (Granular Delegated Admin Privileges) relationship may not be established",
+        ], [
+            "Go to https://admin.powerplatform.microsoft.com",
+            "Select the target environment \u2192 Settings \u2192 Users + permissions \u2192 Application users",
+            'Click "+ New app user" and add your application',
+            ctx.clientId
+                ? `Use Client ID: ${ctx.clientId}`
+                : "Use the Client ID from your partner configuration",
+            'Assign the "System Administrator" security role',
+            "Save and retry the command",
+        ], ctx);
+    }
+    // --- Permission / privilege errors ---
+    if (error.code === ErrorCode.PERMISSION_DENIED ||
+        error.code === ErrorCode.PERMISSION_PRIVILEGE_MISSING ||
+        error.code === ErrorCode.DATAVERSE_FORBIDDEN) {
+        return new CtaError("ERROR_INSUFFICIENT_PERMISSIONS", "Application user lacks required permissions in Power Platform environment", [
+            "The application user exists but doesn't have necessary security roles",
+            "The System Administrator role may not be assigned",
+            "Solution-specific permissions (prvReadSolution, prvWriteSolution, etc.) are missing",
+        ], [
+            "Go to https://admin.powerplatform.microsoft.com",
+            "Select the target environment \u2192 Settings \u2192 Users + permissions \u2192 Application users",
+            ctx.clientId
+                ? `Find your application user (Client ID: ${ctx.clientId})`
+                : "Find your application user",
+            'Click "Manage security roles" or "Edit"',
+            'Ensure "System Administrator" role is assigned',
+            "Verify the role includes solution deployment privileges (prvReadSolution, prvWriteSolution, prvCreateSolution)",
+            "Save and retry the command",
+        ], ctx);
+    }
+    // --- Authentication errors ---
+    if (error instanceof AuthError ||
+        error.code === ErrorCode.DATAVERSE_UNAUTHORIZED ||
+        error.code === ErrorCode.AUTH_FAILED ||
+        error.code === ErrorCode.AUTH_TOKEN_EXPIRED ||
+        error.code === ErrorCode.AUTH_APP_NOT_FOUND ||
+        error.code === ErrorCode.AUTH_INVALID_SECRET ||
+        error.code === ErrorCode.AUTH_ACCOUNT_NOT_FOUND ||
+        error.code === ErrorCode.AUTH_INVALID_CLIENT) {
+        return new CtaError("ERROR_AUTH_FAILED", "Authentication failed - unable to acquire or validate access token", [
+            "The client secret may have expired",
+            "API permissions may not be configured correctly in Azure AD",
+            "Admin consent may not have been granted for the required permissions",
+        ], [
+            "Verify the app registration in Azure Portal:",
+            "  - Go to https://portal.azure.com \u2192 Azure Active Directory \u2192 App registrations",
+            ctx.clientId
+                ? `  - Find your app (Client ID: ${ctx.clientId})`
+                : "  - Locate your application registration",
+            "Check API permissions:",
+            '  - Ensure "Dynamics CRM" or "Common Data Service" API permission is added',
+            '  - Permission should be "user_impersonation" (delegated) or ".default" (application)',
+            '  - Click "Grant admin consent" if not already done',
+            "Verify client secret:",
+            "  - Check if the secret has expired in the app registration",
+            "  - Generate a new secret if needed and update your environment variable (PARTNER_CLIENT_SECRET)",
+            "Retry the command",
+        ], ctx);
+    }
+    // --- Solution not found ---
+    if (error instanceof SolutionError ||
+        error.code === ErrorCode.SOLUTION_NOT_FOUND ||
+        error.code === ErrorCode.SOLUTION_IMPORT_FAILED ||
+        error.code === ErrorCode.SOLUTION_EXPORT_FAILED) {
+        return new CtaError("ERROR_SOLUTION_NOT_FOUND", ctx.solutionName
+            ? `Solution '${ctx.solutionName}' not found in environment`
+            : "Solution not found in environment", [
+            "The solution may not exist in the source environment",
+            "The solution name may be misspelled (names are case-sensitive)",
+            "The solution may have been deleted or renamed",
+        ], [
+            ctx.solutionName
+                ? `Verify the solution name '${ctx.solutionName}' is correct`
+                : "Verify the solution name is correct and matches exactly (case-sensitive)",
+            "List available solutions in the source environment:",
+            "  agents list",
+            "Check that you're connected to the correct source environment",
+            "Ensure the solution is published and visible in the source environment",
+            "Retry with the correct solution name",
+        ], ctx);
+    }
+    // --- Agent resolution errors ---
+    if (error instanceof AgentResolutionError) {
+        return new CtaError("ERROR_SOLUTION_NOT_FOUND", "Could not resolve agent URL to a solution", [
+            "The agent URL may be invalid or the agent no longer exists",
+            "The titleId in the URL may not match any bot in the environment",
+            "The M365 Graph API may be needed to resolve this URL format",
+        ], [
+            "Verify the agent URL is correct and the agent is published",
+            "List available agents in the source environment:",
+            "  agents list",
+            "Try using the solution name directly instead of the agent URL",
+        ], ctx);
+    }
+    // --- Network errors ---
+    if (error instanceof NetworkError ||
+        error.code === ErrorCode.NETWORK_CONNECTION_REFUSED ||
+        error.code === ErrorCode.NETWORK_TIMEOUT ||
+        error.code === ErrorCode.NETWORK_DNS_FAILED ||
+        error.code === ErrorCode.NETWORK_ERROR) {
+        return new CtaError("ERROR_NETWORK", "Network connection failed", [
+            "The target environment URL may be incorrect or unreachable",
+            "Network connectivity issues (firewall, proxy, DNS)",
+            "The Power Platform environment may be temporarily unavailable",
+        ], [
+            "Verify the environment URL is correct:",
+            ctx.environmentUrl
+                ? `  Current: ${ctx.environmentUrl}`
+                : "  Check your configuration file for the correct URL",
+            "Test network connectivity:",
+            ctx.environmentUrl
+                ? `  curl -I ${ctx.environmentUrl}`
+                : "  Use curl or ping to test the environment URL",
+            "Check firewall/proxy settings that may block Power Platform endpoints",
+            "Verify DNS resolution for the environment hostname",
+            "If using a VPN, ensure it's connected and configured properly",
+            "Check Power Platform service status: https://admin.powerplatform.microsoft.com/service-health",
+            "Retry the command after resolving connectivity issues",
+        ], ctx);
+    }
+    // --- Config errors ---
+    if (error instanceof ConfigValidationError ||
+        error.code === ErrorCode.CONFIG_NOT_FOUND ||
+        error.code === ErrorCode.CONFIG_INVALID ||
+        error.code === ErrorCode.CONFIG_READ_FAILED ||
+        error.code === ErrorCode.CONFIG_PARSE_FAILED ||
+        error.code === ErrorCode.CONFIG_SECRET_MISSING) {
+        return new CtaError("ERROR_CONFIG_NOT_FOUND", "Configuration file or required resource not found", [
+            "The configuration file may not exist at the specified path",
+            "The working directory may be incorrect",
+            "Required files may have been deleted or moved",
+        ], [
+            "Verify you're in the correct directory (should contain config/ folder)",
+            "Check if the configuration file exists:",
+            "  ls -la ./config/tenants.yaml",
+            "If the config file doesn't exist, initialize a new configuration:",
+            "  init",
+            "Specify a custom config path with --config flag if needed:",
+            "  deploy --config /path/to/config.yaml ...",
+        ], ctx);
+    }
+    // --- Queue / Redis errors ---
+    if (error.code === ErrorCode.QUEUE_CONNECTION_FAILED) {
+        return new CtaError("ERROR_QUEUE_CONNECTION", LEGACY_QUEUE_ERROR_MESSAGE, LEGACY_QUEUE_ERROR_CAUSES, LEGACY_QUEUE_ERROR_RECOVERY, ctx);
+    }
+    // Unknown code from core - fall through to regex
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Regex-based fallback for untyped errors
+// ---------------------------------------------------------------------------
+function formatByRegex(error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const errorString = errorMessage.toLowerCase();
+    // Extract context from error message
+    const environmentUrlMatch = errorMessage.match(/environment:?\s+(https?:\/\/[^\s]+)/i);
+    const clientIdMatch = errorMessage.match(/client\s+id:?\s+([a-f0-9-]+)/i);
+    const context = {};
+    if (environmentUrlMatch) {
+        context.environmentUrl = environmentUrlMatch[1];
+    }
+    if (clientIdMatch) {
+        context.clientId = clientIdMatch[1];
+    }
+    // GDAP/App user missing
+    if (errorString.includes("not a member of the organization") ||
+        errorString.includes("not a member of") ||
+        errorString.includes("application is not registered")) {
+        return new CtaError("ERROR_GDAP_MISSING", "Application user not registered in Power Platform environment", [
+            "The application is not configured as a user in the target environment",
+            "The app registration may not have been added to the environment yet",
+            "GDAP (Granular Delegated Admin Privileges) relationship may not be established",
+        ], [
+            "Go to https://admin.powerplatform.microsoft.com",
+            "Select the target environment \u2192 Settings \u2192 Users + permissions \u2192 Application users",
+            'Click "+ New app user" and add your application',
+            context.clientId
+                ? `Use Client ID: ${context.clientId}`
+                : "Use the Client ID from your partner configuration",
+            'Assign the "System Administrator" security role',
+            "Save and retry the command",
+        ], context);
+    }
+    // Permission/privilege errors
+    if (errorString.includes("prvread") ||
+        errorString.includes("prvwrite") ||
+        errorString.includes("prvcreate") ||
+        errorString.includes("prvdelete") ||
+        errorString.includes("privilege") ||
+        errorString.includes("insufficient") ||
+        errorString.includes("access") ||
+        errorString.includes("403")) {
+        return new CtaError("ERROR_INSUFFICIENT_PERMISSIONS", "Application user lacks required permissions in Power Platform environment", [
+            "The application user exists but doesn't have necessary security roles",
+            "The System Administrator role may not be assigned",
+            "Solution-specific permissions (prvReadSolution, prvWriteSolution, etc.) are missing",
+        ], [
+            "Go to https://admin.powerplatform.microsoft.com",
+            "Select the target environment \u2192 Settings \u2192 Users + permissions \u2192 Application users",
+            context.clientId
+                ? `Find your application user (Client ID: ${context.clientId})`
+                : "Find your application user",
+            'Click "Manage security roles" or "Edit"',
+            'Ensure "System Administrator" role is assigned',
+            "Verify the role includes solution deployment privileges (prvReadSolution, prvWriteSolution, prvCreateSolution)",
+            "Save and retry the command",
+        ], context);
+    }
+    // Authentication/token errors
+    if (errorString.includes("401") ||
+        errorString.includes("unauthorized") ||
+        errorString.includes("authentication failed") ||
+        errorString.includes("token")) {
+        return new CtaError("ERROR_AUTH_FAILED", "Authentication failed - unable to acquire or validate access token", [
+            "The client secret may have expired",
+            "API permissions may not be configured correctly in Azure AD",
+            "Admin consent may not have been granted for the required permissions",
+        ], [
+            "Verify the app registration in Azure Portal:",
+            "  - Go to https://portal.azure.com \u2192 Azure Active Directory \u2192 App registrations",
+            context.clientId
+                ? `  - Find your app (Client ID: ${context.clientId})`
+                : "  - Locate your application registration",
+            "Check API permissions:",
+            '  - Ensure "Dynamics CRM" or "Common Data Service" API permission is added',
+            '  - Permission should be "user_impersonation" (delegated) or ".default" (application)',
+            '  - Click "Grant admin consent" if not already done',
+            "Verify client secret:",
+            "  - Check if the secret has expired in the app registration",
+            "  - Generate a new secret if needed and update your environment variable (PARTNER_CLIENT_SECRET)",
+            "Retry the command",
+        ], context);
+    }
+    // Solution not found
+    if ((errorString.includes("not found") || errorString.includes("404")) &&
+        (errorString.includes("solution") || errorString.includes("agent"))) {
+        // Try to extract solution name from message
+        const solutionMatch = errorMessage.match(/solution\s+'([^']+)'|solution\s+"([^"]+)"/i);
+        if (solutionMatch) {
+            context.solutionName = solutionMatch[1] || solutionMatch[2];
+        }
+        return new CtaError("ERROR_SOLUTION_NOT_FOUND", context.solutionName
+            ? `Solution '${context.solutionName}' not found in environment`
+            : "Solution not found in environment", [
+            "The solution may not exist in the source environment",
+            "The solution name may be misspelled (names are case-sensitive)",
+            "The solution may have been deleted or renamed",
+        ], [
+            context.solutionName
+                ? `Verify the solution name '${context.solutionName}' is correct`
+                : "Verify the solution name is correct and matches exactly (case-sensitive)",
+            "List available solutions in the source environment:",
+            "  solutions list",
+            "Check that you're connected to the correct source environment",
+            "Ensure the solution is published and visible in the source environment",
+            "Retry with the correct solution name",
+        ], context);
+    }
+    // Network errors
+    if (errorString.includes("econnrefused") ||
+        errorString.includes("etimedout") ||
+        errorString.includes("enotfound") ||
+        errorString.includes("network") ||
+        errorString.includes("fetch failed")) {
+        return new CtaError("ERROR_NETWORK", "Network connection failed", [
+            "The target environment URL may be incorrect or unreachable",
+            "Network connectivity issues (firewall, proxy, DNS)",
+            "The Power Platform environment may be temporarily unavailable",
+        ], [
+            "Verify the environment URL is correct:",
+            context.environmentUrl
+                ? `  Current: ${context.environmentUrl}`
+                : "  Check your configuration file for the correct URL",
+            "Test network connectivity:",
+            context.environmentUrl
+                ? `  curl -I ${context.environmentUrl}`
+                : "  Use curl or ping to test the environment URL",
+            "Check firewall/proxy settings that may block Power Platform endpoints",
+            "Verify DNS resolution for the environment hostname",
+            "If using a VPN, ensure it's connected and configured properly",
+            "Check Power Platform service status: https://admin.powerplatform.microsoft.com/service-health",
+            "Retry the command after resolving connectivity issues",
+        ], context);
+    }
+    // Config/file not found
+    if (errorString.includes("not found") &&
+        (errorString.includes("config") ||
+            errorString.includes("file") ||
+            errorString.includes("enoent"))) {
+        return new CtaError("ERROR_CONFIG_NOT_FOUND", "Configuration file or required resource not found", [
+            "The configuration file may not exist at the specified path",
+            "The working directory may be incorrect",
+            "Required files may have been deleted or moved",
+        ], [
+            "Verify you're in the correct directory (should contain config/ folder)",
+            "Check if the configuration file exists:",
+            "  ls -la ./config/tenants.yaml",
+            "If the config file doesn't exist, initialize a new configuration:",
+            "  init",
+            "Specify a custom config path with --config flag if needed:",
+            "  deploy --config /path/to/config.yaml ...",
+        ], context);
+    }
+    // Redis/queue connection errors
+    if (errorString.includes("redis") ||
+        errorString.includes("queue") ||
+        (errorString.includes("connection") && errorString.includes("refused"))) {
+        return new CtaError("ERROR_QUEUE_CONNECTION", LEGACY_QUEUE_ERROR_MESSAGE, LEGACY_QUEUE_ERROR_CAUSES, LEGACY_QUEUE_ERROR_RECOVERY, context);
+    }
+    // Generic fallback
+    return new CtaError("ERROR_UNKNOWN", errorMessage, [
+        "An unexpected error occurred",
+        "The error details are shown above",
+        "This may be a temporary issue or a bug in Pax8 CTA",
+    ], [
+        "Review the error message above for specific details",
+        "Check the Pax8 CTA documentation for common issues",
+        "Verify your configuration and environment setup",
+        "Try the command again with --verbose flag for more details (if available)",
+        "If the issue persists, please report it on GitHub with the error details",
+        "  https://github.com/pax8labs/pax8-cta/issues",
+    ], context);
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Maps any error to a structured CtaError with recovery guidance.
+ *
+ * 1. If the error is a typed CtaError from @pax8-cta/core, the
+ *    error code is used to select the appropriate guidance (no regex).
+ * 2. Otherwise, falls back to regex matching on the error message.
+ */
+export function formatError(error) {
+    // Fast path: structured error from core with a known code
+    if (isCtaError(error)) {
+        const result = formatByErrorCode(error);
+        if (result) {
+            return result;
+        }
+    }
+    // Slow path: regex fallback for plain Error / string / unknown
+    return formatByRegex(error);
+}
+/**
+ * Prints a formatted error message with recovery guidance
+ */
+export function printError(error) {
+    console.error();
+    console.error(chalk.red.bold(`Error: ${error.message}`), chalk.gray(`(${error.code})`));
+    console.error();
+    // Possible causes
+    console.error(chalk.yellow.bold("Possible causes:"));
+    error.causes.forEach((cause) => {
+        console.error(chalk.yellow(`  \u2022 ${cause}`));
+    });
+    console.error();
+    // Recovery steps
+    console.error(chalk.cyan.bold("To fix:"));
+    error.recovery.forEach((step, index) => {
+        // Check if this is a sub-step (starts with spaces/dash)
+        if (step.startsWith("  ")) {
+            console.error(chalk.cyan(`    ${step.trim()}`));
+        }
+        else {
+            console.error(chalk.cyan(`  ${index + 1}. ${step}`));
+        }
+    });
+    console.error();
+    // Context information
+    if (error.context && Object.keys(error.context).length > 0) {
+        console.error(chalk.gray.bold("Context:"));
+        if (error.context.environmentUrl) {
+            console.error(chalk.gray(`  Environment: ${error.context.environmentUrl}`));
+        }
+        if (error.context.tenantName) {
+            console.error(chalk.gray(`  Tenant: ${error.context.tenantName}`));
+        }
+        if (error.context.solutionName) {
+            console.error(chalk.gray(`  Solution: ${error.context.solutionName}`));
+        }
+        if (error.context.clientId) {
+            console.error(chalk.gray(`  Client ID: ${error.context.clientId}`));
+        }
+        console.error();
+    }
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/lib/error-handler.js.map

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

package/dist/lib/errors.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Copyright 2024 Pax8, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Base CLI error with exit code.
+ * Exit code 1 = runtime error (config not found, network failure, etc.)
+ */
+export declare class CliError extends Error {
+    exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+/**
+ * Usage error — invalid options, missing required args, etc.
+ * Exit code 2.
+ */
+export declare class UsageError extends CliError {
+    constructor(message: string);
+}
+/**
+ * Spinner-like interface for cleanup. Matches the ora spinner API subset we use.
+ */
+interface SpinnerLike {
+    fail: (text?: string) => void;
+    isSpinning?: boolean;
+}
+/**
+ * Detect whether JSON output mode is active.
+ *
+ * Two signals (OR'd):
+ *   1. `--json` is present anywhere in process.argv (simple substring check).
+ *   2. stdout is not a TTY (piped/redirected).
+ *
+ * Exported so that issue #345 (proper Commander-driven --json flag) can replace
+ * this with a single authoritative source of truth once that flag lands.
+ */
+export declare function isJsonOutputMode(): boolean;
+/**
+ * Standard error handler for CLI commands.
+ *
+ * - Stops the spinner with a fail message
+ * - When JSON mode is active (--json flag or piped stdout), emits a single JSON
+ *   object to stderr with structured `code`, `message`, `causes`, and `recovery`
+ *   fields — suitable for LLM-agent consumption.
+ * - Otherwise, uses the human-formatted handler (formatError/printError).
+ * - Exits with the appropriate code (1=runtime, 2=usage).
+ */
+export declare function handleCommandError(error: unknown, spinner?: SpinnerLike | null, failMessage?: string): never;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH;;;GAGG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAGxB,QAAQ,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACR,QAAQ,GAAE,MAAU;CAK9B;AAED;;;GAGG;AACH,qBAAa,UAAW,SAAQ,QAAQ;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,UAAU,WAAW;IACnB,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAsFD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,EAC5B,WAAW,CAAC,EAAE,MAAM,GACnB,KAAK,CA8BP"}