@nexus-ai-nexoralabs/cli 0.1.0

package/dist/orchestration/codingRepairService.d.ts

@@ -0,0 +1,34 @@
+/**
+ * NEXUS AI — P6-D: Coding Repair Service
+ *
+ * Generates bounded repair plans when validation checks fail.
+ *
+ * SECURITY INVARIANTS:
+ *  - Non-repairable security errors (PERMISSION_DENIED, PATH_TRAVERSAL_DENIED,
+ *    COMMAND_NOT_ALLOWED, APPROVAL_REJECTED, etc.) IMMEDIATELY halt the repair loop.
+ *  - Infinite loops are prevented by enforcing a strict maxRepairAttempts retry budget.
+ *  - Repair plan proposals MUST pass through PlanValidator before execution.
+ *  - Secrets and raw protected environment variables are NEVER passed to the model.
+ */
+import type { PlanSynthesisService } from './planner.js';
+import type { PlanValidator } from './planner.js';
+import type { ToolGateway } from '../tools/index.js';
+import type { RepairContext, RepairPlanResult } from './codingAgentTypes.js';
+export type { RepairContext, RepairPlanResult };
+import { LogLevel } from '../common/logger.js';
+export declare class CodingRepairService {
+    private planner;
+    private planValidator;
+    private toolGateway;
+    private logger;
+    constructor(planner: PlanSynthesisService, planValidator: PlanValidator, toolGateway: ToolGateway, logLevel?: LogLevel);
+    /**
+     * Determine whether a validation failure can be repaired and synthesize a repair plan proposal.
+     *
+     * @param taskId Agent task ID.
+     * @param context Failure context containing goal, diffs, validation output, retry count.
+     * @returns Deterministic RepairPlanResult.
+     */
+    synthesizeRepairPlan(taskId: string, context: RepairContext): Promise<RepairPlanResult>;
+}
+//# sourceMappingURL=codingRepairService.d.ts.map

package/dist/orchestration/codingRepairService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codingRepairService.d.ts","sourceRoot":"","sources":["../../src/orchestration/codingRepairService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC7E,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,CAAC;AAEhD,OAAO,EAAU,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEvD,qBAAa,mBAAmB;IAI5B,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,aAAa;IACrB,OAAO,CAAC,WAAW;IALrB,OAAO,CAAC,MAAM,CAAS;gBAGb,OAAO,EAAE,oBAAoB,EAC7B,aAAa,EAAE,aAAa,EAC5B,WAAW,EAAE,WAAW,EAChC,QAAQ,GAAE,QAAiB;IAK7B;;;;;;OAMG;IACG,oBAAoB,CACxB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,gBAAgB,CAAC;CAkG7B"}

package/dist/orchestration/codingRepairService.js

@@ -0,0 +1,120 @@
+/**
+ * NEXUS AI — P6-D: Coding Repair Service
+ *
+ * Generates bounded repair plans when validation checks fail.
+ *
+ * SECURITY INVARIANTS:
+ *  - Non-repairable security errors (PERMISSION_DENIED, PATH_TRAVERSAL_DENIED,
+ *    COMMAND_NOT_ALLOWED, APPROVAL_REJECTED, etc.) IMMEDIATELY halt the repair loop.
+ *  - Infinite loops are prevented by enforcing a strict maxRepairAttempts retry budget.
+ *  - Repair plan proposals MUST pass through PlanValidator before execution.
+ *  - Secrets and raw protected environment variables are NEVER passed to the model.
+ */
+import { NON_REPAIRABLE_SECURITY_ERRORS } from './codingAgentTypes.js';
+import { Logger } from '../common/logger.js';
+export class CodingRepairService {
+    planner;
+    planValidator;
+    toolGateway;
+    logger;
+    constructor(planner, planValidator, toolGateway, logLevel = 'info') {
+        this.planner = planner;
+        this.planValidator = planValidator;
+        this.toolGateway = toolGateway;
+        this.logger = new Logger('CodingRepairService', logLevel);
+    }
+    /**
+     * Determine whether a validation failure can be repaired and synthesize a repair plan proposal.
+     *
+     * @param taskId Agent task ID.
+     * @param context Failure context containing goal, diffs, validation output, retry count.
+     * @returns Deterministic RepairPlanResult.
+     */
+    async synthesizeRepairPlan(taskId, context) {
+        const { repairAttempt, maxRepairAttempts, errorCategory, failedValidationCommand, exitCode, stdout, stderr } = context;
+        this.logger.info(`Evaluating repair attempt ${repairAttempt}/${maxRepairAttempts}`, {
+            taskId,
+            errorCategory,
+            failedCommand: failedValidationCommand,
+            exitCode,
+        });
+        // 1. Non-repairable security/structural failure check — STOP IMMEDIATELY!
+        if (errorCategory && NON_REPAIRABLE_SECURITY_ERRORS.has(errorCategory)) {
+            this.logger.warn(`Repair loop halted: non-repairable security/structural failure category '${errorCategory}'`, {
+                taskId,
+                errorCategory,
+            });
+            return {
+                repairable: false,
+                reason: `Non-repairable security failure '${errorCategory}'. Repair loop halted for safety.`,
+                errorCategory,
+            };
+        }
+        // 2. Retry budget check
+        if (repairAttempt > maxRepairAttempts) {
+            this.logger.warn(`Repair loop halted: repair attempt budget (${maxRepairAttempts}) exhausted`, {
+                taskId,
+                repairAttempt,
+                maxRepairAttempts,
+            });
+            return {
+                repairable: false,
+                reason: `Repair budget exhausted after ${maxRepairAttempts} attempt(s).`,
+                errorCategory: 'REPAIR_BUDGET_EXHAUSTED',
+            };
+        }
+        // 3. Construct clean, secret-safe repair prompt
+        const sanitizeText = (txt) => txt.slice(-2000).replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, '');
+        const repairPrompt = [
+            `TASK GOAL: ${context.taskGoal}`,
+            `REPAIR ATTEMPT: ${repairAttempt} of ${maxRepairAttempts}`,
+            `FAILED COMMAND: ${failedValidationCommand} (exit code: ${exitCode})`,
+            `ERROR CATEGORY: ${errorCategory || 'VALIDATION_FAILURE'}`,
+            `CHANGED FILES: ${context.changedFiles.join(', ') || 'none'}`,
+            `STDERR OUTPUT:\n${sanitizeText(stderr)}`,
+            `STDOUT OUTPUT:\n${sanitizeText(stdout)}`,
+            `INSTRUCTION: Propose a plan with filesystem_edit or filesystem_write steps to fix the error.`,
+        ].join('\n\n');
+        // 4. Synthesize plan proposal via PlanSynthesisService
+        const synthResult = await this.planner.synthesize(taskId, {
+            taskGoal: repairPrompt,
+            temperature: 0.2,
+            maxSteps: 5,
+        });
+        if (!synthResult.success || !synthResult.plan) {
+            this.logger.warn(`Repair plan synthesis failed`, {
+                taskId,
+                errorCategory: synthResult.errorCategory,
+                errorMessage: synthResult.errorMessage,
+            });
+            return {
+                repairable: false,
+                reason: `Repair plan synthesis failed: ${synthResult.errorMessage || 'Unable to generate repair plan.'}`,
+                errorCategory: synthResult.errorCategory || 'PLAN_SYNTHESIS_FAILED',
+            };
+        }
+        // 5. Validate repair plan via PlanValidator
+        const valResult = this.planValidator.validate(synthResult.plan, taskId, 5);
+        if (!valResult.valid) {
+            this.logger.warn(`Repair plan validation failed`, {
+                taskId,
+                errors: valResult.errors,
+            });
+            return {
+                repairable: false,
+                reason: `Repair plan failed validation: ${valResult.errors.map((e) => e.message).join('; ')}`,
+                errorCategory: 'PLAN_VALIDATION_FAILED',
+            };
+        }
+        this.logger.info(`Repair plan successfully synthesized and validated`, {
+            taskId,
+            repairStepCount: synthResult.plan.steps.length,
+        });
+        return {
+            repairable: true,
+            reason: `Repair plan generated for attempt ${repairAttempt}.`,
+            repairPlan: synthResult.plan,
+        };
+    }
+}
+//# sourceMappingURL=codingRepairService.js.map

package/dist/orchestration/codingRepairService.js.map

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

package/dist/orchestration/goalCompletionVerifier.d.ts

@@ -0,0 +1,36 @@
+/**
+ * NEXUS AI - P7-F.1: Production-Grade Goal Completion Verifier
+ *
+ * Prevents false positive task completions.
+ *
+ * Distinguishes:
+ *   1. PLAN EXECUTION SUCCESS (all steps in a plan succeeded)
+ *   2. GOAL COMPLETION (the user's requested goal was actually achieved)
+ *
+ * Security & Sandbox Invariants:
+ *  - Enforces workspace root sandbox boundaries on all path checks.
+ *  - Performs zero arbitrary shell execution or state mutations.
+ *  - Deterministic and pure observation layer over the workspace filesystem.
+ */
+import type { AgentPlanStep } from './types.js';
+import { LogLevel } from '../common/logger.js';
+export interface GoalVerificationResult {
+    verified: boolean;
+    errorCategory?: string;
+    errorMessage?: string;
+    artifactsChecked?: string[];
+}
+export declare class GoalCompletionVerifier {
+    private logger;
+    constructor(logLevel?: LogLevel);
+    /**
+     * Verifies whether an executed task has truly satisfied its goal before
+     * allowing the task state to transition to COMPLETED.
+     *
+     * @param taskGoal - The natural language task goal.
+     * @param steps - The execution plan steps that were run.
+     * @param workspaceRoot - The canonical workspace sandbox root path.
+     */
+    verifyGoal(taskGoal: string, steps: AgentPlanStep[], workspaceRoot: string): GoalVerificationResult;
+}
+//# sourceMappingURL=goalCompletionVerifier.d.ts.map

package/dist/orchestration/goalCompletionVerifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"goalCompletionVerifier.d.ts","sourceRoot":"","sources":["../../src/orchestration/goalCompletionVerifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,EAAU,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,qBAAa,sBAAsB;IACjC,OAAO,CAAC,MAAM,CAAS;gBAEX,QAAQ,GAAE,QAAiB;IAIvC;;;;;;;OAOG;IACH,UAAU,CACR,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,aAAa,EAAE,EACtB,aAAa,EAAE,MAAM,GACpB,sBAAsB;CA6J1B"}

package/dist/orchestration/goalCompletionVerifier.js

@@ -0,0 +1,165 @@
+/**
+ * NEXUS AI - P7-F.1: Production-Grade Goal Completion Verifier
+ *
+ * Prevents false positive task completions.
+ *
+ * Distinguishes:
+ *   1. PLAN EXECUTION SUCCESS (all steps in a plan succeeded)
+ *   2. GOAL COMPLETION (the user's requested goal was actually achieved)
+ *
+ * Security & Sandbox Invariants:
+ *  - Enforces workspace root sandbox boundaries on all path checks.
+ *  - Performs zero arbitrary shell execution or state mutations.
+ *  - Deterministic and pure observation layer over the workspace filesystem.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { isAuthoringGoal } from './planner.js';
+import { Logger } from '../common/logger.js';
+export class GoalCompletionVerifier {
+    logger;
+    constructor(logLevel = 'info') {
+        this.logger = new Logger('GoalCompletionVerifier', logLevel);
+    }
+    /**
+     * Verifies whether an executed task has truly satisfied its goal before
+     * allowing the task state to transition to COMPLETED.
+     *
+     * @param taskGoal - The natural language task goal.
+     * @param steps - The execution plan steps that were run.
+     * @param workspaceRoot - The canonical workspace sandbox root path.
+     */
+    verifyGoal(taskGoal, steps, workspaceRoot) {
+        this.logger.info(`Starting goal completion verification`, { taskGoal, workspaceRoot });
+        const isAuthoring = isAuthoringGoal(taskGoal);
+        // ── READ-ONLY / INSPECTION GOALS ──────────────────────────────────────────
+        if (!isAuthoring) {
+            this.logger.info(`Goal verified as read-only / inspection task`);
+            return { verified: true, artifactsChecked: [] };
+        }
+        // ── AUTHORING / CREATION GOALS ────────────────────────────────────────────
+        // Check 1: Ensure mutation / creation steps actually executed and succeeded
+        const mutationSteps = steps.filter((s) => s.status === 'completed' &&
+            (s.toolId === 'filesystem_write' ||
+                s.toolId === 'filesystem_edit' ||
+                s.toolId === 'terminal_execute'));
+        if (mutationSteps.length === 0) {
+            this.logger.warn(`Verification failed: no creation/authoring steps succeeded`, { taskGoal });
+            return {
+                verified: false,
+                errorCategory: 'NO_AUTHORING_STEPS',
+                errorMessage: 'Task goal requested creation/authoring, but no file creation or modification steps were executed.',
+            };
+        }
+        // Check 2: Extract expected target artifact relative paths
+        const expectedPaths = new Set();
+        // 2a. Extract paths from filesystem_write / filesystem_edit step params
+        mutationSteps.forEach((s) => {
+            if (s.params) {
+                const rel = typeof s.params.relativePath === 'string'
+                    ? s.params.relativePath.trim()
+                    : typeof s.params.path === 'string'
+                        ? s.params.path.trim()
+                        : '';
+                if (rel)
+                    expectedPaths.add(rel);
+            }
+        });
+        // 2b. Extract explicitly named files from the task goal (order longer extensions first so .json is not matched as .js)
+        const explicitFileRegex = /([a-zA-Z0-9_\-\/\\]+\.(html|css|json|jsx|tsx|yaml|yml|txt|py|md|sh|ts|js))\b/gi;
+        let match;
+        while ((match = explicitFileRegex.exec(taskGoal)) !== null) {
+            const extracted = match[1].replace(/\\/g, '/');
+            // Ignore generic words like "file.html"
+            if (!extracted.startsWith('http') && !extracted.includes('*')) {
+                expectedPaths.add(extracted);
+            }
+        }
+        // If goal mentions a subdirectory (e.g., "calculator-test"), expand file references
+        const folderMatch = taskGoal.match(/(?:folder|directory|called|named)\s+([a-zA-Z0-9_\-]+)/i);
+        if (folderMatch && folderMatch[1]) {
+            const folderName = folderMatch[1].trim();
+            ['index.html', 'style.css', 'script.js'].forEach((fileName) => {
+                if (taskGoal.toLowerCase().includes(fileName)) {
+                    expectedPaths.add(`${folderName}/${fileName}`);
+                }
+            });
+        }
+        if (expectedPaths.size === 0) {
+            // Fallback: if no specific paths extracted, ensure at least one written step exists
+            this.logger.info(`Authoring steps completed (no explicit filename pattern extracted)`);
+            return { verified: true, artifactsChecked: [] };
+        }
+        let canonicalRoot;
+        try {
+            canonicalRoot = fs.realpathSync(workspaceRoot);
+        }
+        catch {
+            canonicalRoot = path.resolve(workspaceRoot);
+        }
+        const checked = [];
+        // Check 3: Verify each expected artifact exists & is non-empty
+        for (const relPath of expectedPaths) {
+            const absPath = path.resolve(canonicalRoot, relPath);
+            // Sandbox safety check
+            if (!absPath.startsWith(canonicalRoot)) {
+                this.logger.warn(`Path traversal attempt blocked in verification: ${relPath}`);
+                return {
+                    verified: false,
+                    errorCategory: 'PERMISSION_DENIED',
+                    errorMessage: `Verification path '${relPath}' is outside workspace root sandbox.`,
+                };
+            }
+            if (!fs.existsSync(absPath)) {
+                this.logger.warn(`Verification failed: missing expected artifact '${relPath}'`);
+                return {
+                    verified: false,
+                    errorCategory: 'MISSING_ARTIFACT',
+                    errorMessage: `Expected artifact file '${relPath}' does not exist in workspace.`,
+                    artifactsChecked: checked,
+                };
+            }
+            const stat = fs.statSync(absPath);
+            if (stat.isFile() && stat.size === 0) {
+                this.logger.warn(`Verification failed: empty artifact '${relPath}' (0 bytes)`);
+                return {
+                    verified: false,
+                    errorCategory: 'EMPTY_ARTIFACT',
+                    errorMessage: `Expected artifact file '${relPath}' exists but is 0 bytes (empty).`,
+                    artifactsChecked: checked,
+                };
+            }
+            checked.push(relPath);
+        }
+        // Check 4: Cross-reference verification for web authoring (HTML + CSS / JS)
+        const lowerGoal = taskGoal.toLowerCase();
+        const isWebGoal = lowerGoal.includes('html') || lowerGoal.includes('calculator') || lowerGoal.includes('webpage') || lowerGoal.includes('website');
+        if (isWebGoal) {
+            const htmlPathRel = Array.from(checked).find((p) => p.endsWith('.html'));
+            if (htmlPathRel) {
+                const htmlAbs = path.resolve(canonicalRoot, htmlPathRel);
+                if (fs.existsSync(htmlAbs)) {
+                    const htmlContent = fs.readFileSync(htmlAbs, 'utf8').toLowerCase();
+                    const hasCssRef = Array.from(checked).some((p) => p.endsWith('.css'))
+                        ? htmlContent.includes('.css') || htmlContent.includes('<style')
+                        : true;
+                    const hasJsRef = Array.from(checked).some((p) => p.endsWith('.js'))
+                        ? htmlContent.includes('.js') || htmlContent.includes('<script')
+                        : true;
+                    if (!hasCssRef || !hasJsRef) {
+                        this.logger.warn(`Verification failed: HTML artifact '${htmlPathRel}' missing CSS or JS references`);
+                        return {
+                            verified: false,
+                            errorCategory: 'CONTENT_VERIFICATION_FAILED',
+                            errorMessage: `HTML artifact '${htmlPathRel}' does not reference expected CSS/JS files.`,
+                            artifactsChecked: checked,
+                        };
+                    }
+                }
+            }
+        }
+        this.logger.info(`Goal completion verification succeeded`, { checkedCount: checked.length });
+        return { verified: true, artifactsChecked: checked };
+    }
+}
+//# sourceMappingURL=goalCompletionVerifier.js.map

package/dist/orchestration/goalCompletionVerifier.js.map

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

package/dist/orchestration/humanApprovalService.d.ts

@@ -0,0 +1,89 @@
+/**
+ * NEXUS AI — Human Approval Service
+ *
+ * Orchestrates the human approval lifecycle: request creation, policy evaluation,
+ * task state machine integration (transition to/from awaiting_approval), expiration,
+ * resolution, and privacy-safe audit logging.
+ *
+ * SECURITY INVARIANTS:
+ *  - Terminal approval states (approved, rejected, expired, cancelled) CANNOT be reopened.
+ *  - Approval DOES NOT equal permission — authorization remains mandatory via PermissionEngine.
+ *  - Privacy-safe logging: Secrets, full prompts, model responses, and raw document contents are NEVER logged.
+ */
+import type { AgentTaskService } from './agentTaskService.js';
+import type { AgentTask } from '../storage/repositories/types.js';
+import type { ToolGateway } from '../tools/index.js';
+import type { ApprovalRepository } from '../storage/repositories/approvalRepository.js';
+import type { ApprovalRequest, CreateApprovalRequestDto, ApprovalPolicyConfig, ApprovalDecision } from '../tools/approvalTypes.js';
+import { ApprovalPolicyEngine } from '../tools/approvalPolicyEngine.js';
+import { ApprovalGate } from '../tools/approvalGate.js';
+import { LogLevel } from '../common/logger.js';
+export interface ResolveApprovalResult {
+    success: boolean;
+    approval: ApprovalRequest;
+    task: AgentTask | null;
+    error?: string;
+}
+export declare class HumanApprovalService {
+    private taskService;
+    private toolGateway;
+    private repository?;
+    private policyEngine;
+    private approvalGate;
+    private logger;
+    private memoryStore;
+    constructor(taskService: AgentTaskService, toolGateway: ToolGateway, repository?: ApprovalRepository | undefined, policyConfig?: Partial<ApprovalPolicyConfig>, logLevel?: LogLevel);
+    /**
+     * Create an approval request for a task step based on policy evaluation.
+     */
+    createApprovalRequest(dto: CreateApprovalRequestDto): {
+        approval: ApprovalRequest;
+        decision: ApprovalDecision;
+        task: AgentTask;
+    };
+    /**
+     * Resolve a pending approval request with explicit user decision ('approved' | 'rejected').
+     */
+    resolveApproval(approvalId: string, userDecision: 'approved' | 'rejected', reason?: string): ResolveApprovalResult;
+    /**
+     * Retrieve an approval request by ID, automatically evaluating expiration if pending.
+     */
+    getApproval(approvalId: string): ApprovalRequest | null;
+    /**
+     * Retrieve all approval requests for a task.
+     */
+    getApprovalsForTask(taskId: string): ApprovalRequest[];
+    /**
+     * List all pending approval requests.
+     */
+    listPendingApprovals(): ApprovalRequest[];
+    /**
+     * Respond to an approval request with decision APPROVED or REJECTED.
+     */
+    respondToApproval(approvalId: string, params: {
+        decision: 'APPROVED' | 'REJECTED';
+        reason?: string;
+    }): ApprovalRequest;
+    /**
+     * Evaluate the ApprovalGate for a given task step.
+     */
+    evaluateGateForStep(taskId: string, stepId: string): ReturnType<ApprovalGate['evaluateGate']>;
+    /**
+     * Expire all stale pending approvals.
+     */
+    expireStaleApprovals(): number;
+    /**
+     * Invalidate/cancel all pending approvals for a task (e.g. when task is cancelled).
+     */
+    cancelApprovalsForTask(taskId: string, reason?: string): number;
+    /**
+     * Get policy engine instance.
+     */
+    getPolicyEngine(): ApprovalPolicyEngine;
+    /**
+     * Get approval gate instance.
+     */
+    getGate(): ApprovalGate;
+    private saveApproval;
+}
+//# sourceMappingURL=humanApprovalService.d.ts.map

package/dist/orchestration/humanApprovalService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"humanApprovalService.d.ts","sourceRoot":"","sources":["../../src/orchestration/humanApprovalService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+CAA+C,CAAC;AACxF,OAAO,KAAK,EACV,eAAe,EAEf,wBAAwB,EACxB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAExD,OAAO,EAAU,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,eAAe,CAAC;IAC1B,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,oBAAoB;IAS7B,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,UAAU,CAAC;IAVrB,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,MAAM,CAAS;IAGvB,OAAO,CAAC,WAAW,CAAsC;gBAG/C,WAAW,EAAE,gBAAgB,EAC7B,WAAW,EAAE,WAAW,EACxB,UAAU,CAAC,EAAE,kBAAkB,YAAA,EACvC,YAAY,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,EAC5C,QAAQ,GAAE,QAAiB;IAO7B;;OAEG;IACH,qBAAqB,CAAC,GAAG,EAAE,wBAAwB,GAAG;QACpD,QAAQ,EAAE,eAAe,CAAC;QAC1B,QAAQ,EAAE,gBAAgB,CAAC;QAC3B,IAAI,EAAE,SAAS,CAAC;KACjB;IAoFD;;OAEG;IACH,eAAe,CACb,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,UAAU,GAAG,UAAU,EACrC,MAAM,CAAC,EAAE,MAAM,GACd,qBAAqB;IAqGxB;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAyBvD;;OAEG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,EAAE;IAOtD;;OAEG;IACH,oBAAoB,IAAI,eAAe,EAAE;IAOzC;;OAEG;IACH,iBAAiB,CACf,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE;QAAE,QAAQ,EAAE,UAAU,GAAG,UAAU,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7D,eAAe;IASlB;;OAEG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC;IAsB7F;;OAEG;IACH,oBAAoB,IAAI,MAAM;IAmB9B;;OAEG;IACH,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAyB,GAAG,MAAM;IAmBjF;;OAEG;IACH,eAAe,IAAI,oBAAoB;IAIvC;;OAEG;IACH,OAAO,IAAI,YAAY;IAIvB,OAAO,CAAC,YAAY;CAiBrB"}