@cleocode/cleo 2026.3.56 → 2026.3.58

package/dist/mcp/lib/background-jobs.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Background Job Manager for Long-Running Operations
+ *
+ * Per MCP-SERVER-SPECIFICATION.md Section 10, operations that may take >30s
+ * should support async execution. This module provides a job manager that
+ * tracks background operations with status, progress, and auto-cleanup.
+ *
+ * @task T3080
+ */
+/**
+ * Background job status
+ */
+export type JobStatus = 'running' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Background job representation
+ */
+export interface BackgroundJob {
+    id: string;
+    operation: string;
+    status: JobStatus;
+    startedAt: string;
+    completedAt?: string;
+    result?: unknown;
+    error?: string;
+    progress?: number;
+}
+/**
+ * Configuration for BackgroundJobManager
+ */
+export interface BackgroundJobManagerConfig {
+    maxJobs?: number;
+    retentionMs?: number;
+}
+/**
+ * Manages background jobs for long-running operations
+ */
+export declare class BackgroundJobManager {
+    private jobs;
+    private abortControllers;
+    private maxJobs;
+    private retentionMs;
+    private cleanupTimer;
+    constructor(config?: BackgroundJobManagerConfig);
+    /**
+     * Start a new background job
+     *
+     * @param operation - The operation identifier (e.g. "validate.test.run")
+     * @param executor - Async function to execute in the background
+     * @returns The job ID
+     * @throws Error if max concurrent jobs reached
+     */
+    startJob(operation: string, executor: () => Promise<unknown>): Promise<string>;
+    /**
+     * Get a specific job by ID
+     */
+    getJob(jobId: string): BackgroundJob | undefined;
+    /**
+     * List all jobs, optionally filtered by status
+     */
+    listJobs(status?: string): BackgroundJob[];
+    /**
+     * Cancel a running job
+     *
+     * @returns true if the job was cancelled, false if not found or not running
+     */
+    cancelJob(jobId: string): boolean;
+    /**
+     * Update job progress (0-100)
+     */
+    updateProgress(jobId: string, progress: number): boolean;
+    /**
+     * Cleanup old completed/failed/cancelled jobs past retention period
+     *
+     * @returns Number of jobs cleaned up
+     */
+    cleanup(): number;
+    /**
+     * Destroy the manager: cancel all running jobs and clear state
+     */
+    destroy(): void;
+    /**
+     * Execute a job's executor function and update status on completion/failure
+     */
+    private executeJob;
+}
+//# sourceMappingURL=background-jobs.d.ts.map

package/dist/mcp/lib/background-jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-jobs.d.ts","sourceRoot":"","sources":["../../../src/mcp/lib/background-jobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,IAAI,CAA6B;IACzC,OAAO,CAAC,gBAAgB,CAA+B;IACvD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAAwC;gBAEhD,MAAM,CAAC,EAAE,0BAA0B;IAe/C;;;;;;;OAOG;IACG,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BpF;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIhD;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE;IAQ1C;;;;OAIG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAkBjC;;OAEG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IASxD;;;;OAIG;IACH,OAAO,IAAI,MAAM;IAqBjB;;OAEG;IACH,OAAO,IAAI,IAAI;IAoBf;;OAEG;YACW,UAAU;CAmCzB"}

package/dist/mcp/lib/background-jobs.js

@@ -0,0 +1,183 @@
+/**
+ * Background Job Manager for Long-Running Operations
+ *
+ * Per MCP-SERVER-SPECIFICATION.md Section 10, operations that may take >30s
+ * should support async execution. This module provides a job manager that
+ * tracks background operations with status, progress, and auto-cleanup.
+ *
+ * @task T3080
+ */
+import { randomUUID } from 'crypto';
+/**
+ * Manages background jobs for long-running operations
+ */
+export class BackgroundJobManager {
+    jobs;
+    abortControllers;
+    maxJobs;
+    retentionMs;
+    cleanupTimer;
+    constructor(config) {
+        this.jobs = new Map();
+        this.abortControllers = new Map();
+        this.maxJobs = config?.maxJobs ?? 10;
+        this.retentionMs = config?.retentionMs ?? 3600000; // 1 hour default
+        this.cleanupTimer = null;
+        // Start periodic cleanup every 5 minutes
+        this.cleanupTimer = setInterval(() => this.cleanup(), 300000);
+        // Don't prevent process exit
+        if (this.cleanupTimer.unref) {
+            this.cleanupTimer.unref();
+        }
+    }
+    /**
+     * Start a new background job
+     *
+     * @param operation - The operation identifier (e.g. "validate.test.run")
+     * @param executor - Async function to execute in the background
+     * @returns The job ID
+     * @throws Error if max concurrent jobs reached
+     */
+    async startJob(operation, executor) {
+        // Check concurrent job limit (only count running jobs)
+        const runningCount = this.listJobs('running').length;
+        if (runningCount >= this.maxJobs) {
+            throw new Error(`Maximum concurrent jobs reached (${this.maxJobs}). Cancel or wait for existing jobs to complete.`);
+        }
+        const jobId = randomUUID();
+        const abortController = new AbortController();
+        const job = {
+            id: jobId,
+            operation,
+            status: 'running',
+            startedAt: new Date().toISOString(),
+        };
+        this.jobs.set(jobId, job);
+        this.abortControllers.set(jobId, abortController);
+        // Execute async - don't await
+        this.executeJob(jobId, executor, abortController.signal);
+        return jobId;
+    }
+    /**
+     * Get a specific job by ID
+     */
+    getJob(jobId) {
+        return this.jobs.get(jobId);
+    }
+    /**
+     * List all jobs, optionally filtered by status
+     */
+    listJobs(status) {
+        const all = Array.from(this.jobs.values());
+        if (!status) {
+            return all;
+        }
+        return all.filter((job) => job.status === status);
+    }
+    /**
+     * Cancel a running job
+     *
+     * @returns true if the job was cancelled, false if not found or not running
+     */
+    cancelJob(jobId) {
+        const job = this.jobs.get(jobId);
+        if (!job || job.status !== 'running') {
+            return false;
+        }
+        const controller = this.abortControllers.get(jobId);
+        if (controller) {
+            controller.abort();
+            this.abortControllers.delete(jobId);
+        }
+        job.status = 'cancelled';
+        job.completedAt = new Date().toISOString();
+        return true;
+    }
+    /**
+     * Update job progress (0-100)
+     */
+    updateProgress(jobId, progress) {
+        const job = this.jobs.get(jobId);
+        if (!job || job.status !== 'running') {
+            return false;
+        }
+        job.progress = Math.max(0, Math.min(100, progress));
+        return true;
+    }
+    /**
+     * Cleanup old completed/failed/cancelled jobs past retention period
+     *
+     * @returns Number of jobs cleaned up
+     */
+    cleanup() {
+        const now = Date.now();
+        let cleaned = 0;
+        for (const [id, job] of this.jobs.entries()) {
+            if (job.status === 'running') {
+                continue;
+            }
+            if (job.completedAt) {
+                const completedTime = new Date(job.completedAt).getTime();
+                if (now - completedTime > this.retentionMs) {
+                    this.jobs.delete(id);
+                    this.abortControllers.delete(id);
+                    cleaned++;
+                }
+            }
+        }
+        return cleaned;
+    }
+    /**
+     * Destroy the manager: cancel all running jobs and clear state
+     */
+    destroy() {
+        // Cancel all running jobs
+        for (const [id, job] of this.jobs.entries()) {
+            if (job.status === 'running') {
+                const controller = this.abortControllers.get(id);
+                if (controller) {
+                    controller.abort();
+                }
+            }
+        }
+        this.jobs.clear();
+        this.abortControllers.clear();
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+    }
+    /**
+     * Execute a job's executor function and update status on completion/failure
+     */
+    async executeJob(jobId, executor, signal) {
+        const job = this.jobs.get(jobId);
+        if (!job) {
+            return;
+        }
+        try {
+            const result = await executor();
+            // Check if cancelled during execution
+            if (signal.aborted) {
+                return;
+            }
+            job.status = 'completed';
+            job.completedAt = new Date().toISOString();
+            job.result = result;
+            job.progress = 100;
+        }
+        catch (error) {
+            // Check if this was a cancellation
+            if (signal.aborted) {
+                return;
+            }
+            job.status = 'failed';
+            job.completedAt = new Date().toISOString();
+            job.error = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            this.abortControllers.delete(jobId);
+        }
+    }
+}
+//# sourceMappingURL=background-jobs.js.map

package/dist/mcp/lib/background-jobs.js.map

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

package/dist/mcp/lib/budget.d.ts

@@ -0,0 +1,35 @@
+/**
+ * LAFS token budget enforcement for MCP responses.
+ *
+ * Wraps the LAFS protocol's applyBudgetEnforcement() to limit MCP
+ * response sizes for context-constrained agents.
+ *
+ * @task T4701
+ * @epic T4663
+ */
+import type { BudgetEnforcementResult } from '@cleocode/lafs-protocol';
+/**
+ * Apply budget enforcement to an MCP response envelope.
+ *
+ * Converts the DomainResponse into an LAFSEnvelope shape for budget checking,
+ * then applies truncation if the response exceeds the budget.
+ *
+ * @param response - The MCP domain response object
+ * @param budget - Maximum allowed tokens (defaults to DEFAULT_BUDGET)
+ * @returns The response, potentially truncated, with budget metadata
+ *
+ * @task T4701
+ * @epic T4663
+ */
+export declare function enforceBudget(response: Record<string, unknown>, budget?: number): {
+    response: Record<string, unknown>;
+    enforcement: BudgetEnforcementResult;
+};
+/**
+ * Quick check whether a response exceeds a token budget without modifying it.
+ *
+ * @task T4701
+ * @epic T4663
+ */
+export declare function isWithinBudget(response: Record<string, unknown>, budget?: number): boolean;
+//# sourceMappingURL=budget.d.ts.map

package/dist/mcp/lib/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../../src/mcp/lib/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAgB,MAAM,yBAAyB,CAAC;AAWrF;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,MAAM,CAAC,EAAE,MAAM,GACd;IAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,WAAW,EAAE,uBAAuB,CAAA;CAAE,CA+C7E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAoB1F"}

package/dist/mcp/lib/budget.js

@@ -0,0 +1,102 @@
+/**
+ * LAFS token budget enforcement for MCP responses.
+ *
+ * Wraps the LAFS protocol's applyBudgetEnforcement() to limit MCP
+ * response sizes for context-constrained agents.
+ *
+ * @task T4701
+ * @epic T4663
+ */
+import { applyBudgetEnforcement, checkBudget } from '@cleocode/lafs-protocol';
+/**
+ * Default token budget when no explicit budget is provided.
+ * Standard MVI level allows up to 4000 tokens per response.
+ *
+ * @task T4701
+ */
+const DEFAULT_BUDGET = 4000;
+/**
+ * Apply budget enforcement to an MCP response envelope.
+ *
+ * Converts the DomainResponse into an LAFSEnvelope shape for budget checking,
+ * then applies truncation if the response exceeds the budget.
+ *
+ * @param response - The MCP domain response object
+ * @param budget - Maximum allowed tokens (defaults to DEFAULT_BUDGET)
+ * @returns The response, potentially truncated, with budget metadata
+ *
+ * @task T4701
+ * @epic T4663
+ */
+export function enforceBudget(response, budget) {
+    const effectiveBudget = budget ?? DEFAULT_BUDGET;
+    // Build an LAFSEnvelope-shaped object for the budget checker
+    const envelope = {
+        $schema: 'https://lafs.dev/schemas/v1/envelope.schema.json',
+        _meta: response['_meta'] ?? {
+            specVersion: '1.2.3',
+            schemaVersion: '2026.2.1',
+            timestamp: new Date().toISOString(),
+            operation: 'mcp.response',
+            requestId: 'budget-check',
+            transport: 'sdk',
+            strict: true,
+            mvi: 'standard',
+            contextVersion: 1,
+        },
+        success: response['success'] ?? true,
+        result: response['data'] ?? null,
+        ...(response['error'] ? { error: response['error'] } : {}),
+    };
+    const enforcement = applyBudgetEnforcement(envelope, effectiveBudget, {
+        truncateOnExceed: true,
+    });
+    // Merge budget info back into the response _meta
+    const meta = (response['_meta'] ?? {});
+    meta['_budgetEnforcement'] = {
+        budget: effectiveBudget,
+        estimatedTokens: enforcement.estimatedTokens,
+        withinBudget: enforcement.withinBudget,
+        truncated: enforcement.truncated,
+    };
+    return {
+        response: {
+            ...response,
+            _meta: meta,
+            // Replace data with potentially truncated result
+            ...(enforcement.truncated &&
+                enforcement.envelope.result !== undefined && {
+                data: enforcement.envelope.result,
+            }),
+        },
+        enforcement,
+    };
+}
+/**
+ * Quick check whether a response exceeds a token budget without modifying it.
+ *
+ * @task T4701
+ * @epic T4663
+ */
+export function isWithinBudget(response, budget) {
+    const effectiveBudget = budget ?? DEFAULT_BUDGET;
+    const envelope = {
+        $schema: 'https://lafs.dev/schemas/v1/envelope.schema.json',
+        _meta: response['_meta'] ?? {
+            specVersion: '1.2.3',
+            schemaVersion: '2026.2.1',
+            timestamp: new Date().toISOString(),
+            operation: 'mcp.response',
+            requestId: 'budget-check',
+            transport: 'sdk',
+            strict: true,
+            mvi: 'standard',
+            contextVersion: 1,
+        },
+        success: true,
+        result: response['data'] ?? null,
+    };
+    const { exceeded } = checkBudget(envelope, effectiveBudget);
+    return !exceeded;
+}
+//# sourceMappingURL=budget.js.map

package/dist/mcp/lib/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../../src/mcp/lib/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,cAAc,GAAG,IAAI,CAAC;AAE5B;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAiC,EACjC,MAAe;IAEf,MAAM,eAAe,GAAG,MAAM,IAAI,cAAc,CAAC;IAEjD,6DAA6D;IAC7D,MAAM,QAAQ,GAAiB;QAC7B,OAAO,EAAE,kDAAkD;QAC3D,KAAK,EAAG,QAAQ,CAAC,OAAO,CAA2B,IAAI;YACrD,WAAW,EAAE,OAAO;YACpB,aAAa,EAAE,UAAU;YACzB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,SAAS,EAAE,cAAc;YACzB,SAAS,EAAE,cAAc;YACzB,SAAS,EAAE,KAAK;YAChB,MAAM,EAAE,IAAI;YACZ,GAAG,EAAE,UAAU;YACf,cAAc,EAAE,CAAC;SAClB;QACD,OAAO,EAAG,QAAQ,CAAC,SAAS,CAAa,IAAI,IAAI;QACjD,MAAM,EAAG,QAAQ,CAAC,MAAM,CAA6B,IAAI,IAAI;QAC7D,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,OAAO,CAA0B,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpF,CAAC;IAEF,MAAM,WAAW,GAAG,sBAAsB,CAAC,QAAQ,EAAE,eAAe,EAAE;QACpE,gBAAgB,EAAE,IAAI;KACvB,CAAC,CAAC;IAEH,iDAAiD;IACjD,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,CAA4B,CAAC;IAClE,IAAI,CAAC,oBAAoB,CAAC,GAAG;QAC3B,MAAM,EAAE,eAAe;QACvB,eAAe,EAAE,WAAW,CAAC,eAAe;QAC5C,YAAY,EAAE,WAAW,CAAC,YAAY;QACtC,SAAS,EAAE,WAAW,CAAC,SAAS;KACjC,CAAC;IAEF,OAAO;QACL,QAAQ,EAAE;YACR,GAAG,QAAQ;YACX,KAAK,EAAE,IAAI;YACX,iDAAiD;YACjD,GAAG,CAAC,WAAW,CAAC,SAAS;gBACvB,WAAW,CAAC,QAAQ,CAAC,MAAM,KAAK,SAAS,IAAI;gBAC3C,IAAI,EAAE,WAAW,CAAC,QAAQ,CAAC,MAAM;aAClC,CAAC;SACL;QACD,WAAW;KACZ,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,QAAiC,EAAE,MAAe;IAC/E,MAAM,eAAe,GAAG,MAAM,IAAI,cAAc,CAAC;IACjD,MAAM,QAAQ,GAAiB;QAC7B,OAAO,EAAE,kDAAkD;QAC3D,KAAK,EAAG,QAAQ,CAAC,OAAO,CAA2B,IAAI;YACrD,WAAW,EAAE,OAAO;YACpB,aAAa,EAAE,UAAU;YACzB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,SAAS,EAAE,cAAc;YACzB,SAAS,EAAE,cAAc;YACzB,SAAS,EAAE,KAAK;YAChB,MAAM,EAAE,IAAI;YACZ,GAAG,EAAE,UAAU;YACf,cAAc,EAAE,CAAC;SAClB;QACD,OAAO,EAAE,IAAI;QACb,MAAM,EAAG,QAAQ,CAAC,MAAM,CAA6B,IAAI,IAAI;KAC9D,CAAC;IACF,MAAM,EAAE,QAAQ,EAAE,GAAG,WAAW,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;IAC5D,OAAO,CAAC,QAAQ,CAAC;AACnB,CAAC"}

package/dist/mcp/lib/cache.d.ts

@@ -0,0 +1,78 @@
+/**
+ * In-memory query cache for CLEO MCP Server
+ *
+ * Caches query responses with configurable TTL.
+ * Cache key = domain + operation + hash(params).
+ * Invalidated on any mutate operation for the relevant domain.
+ *
+ * @task T3145
+ */
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    evictions: number;
+    size: number;
+    domains: Record<string, number>;
+}
+/**
+ * Query cache with per-domain invalidation
+ */
+export declare class QueryCache {
+    private store;
+    private domainKeys;
+    private stats;
+    private ttl;
+    private enabled;
+    private cleanupTimer;
+    constructor(ttlMs?: number, enabled?: boolean);
+    /**
+     * Build cache key from domain, operation, and params
+     */
+    buildKey(domain: string, operation: string, params?: Record<string, unknown>): string;
+    /**
+     * Get cached value, or undefined if not found/expired
+     */
+    get<T = unknown>(domain: string, operation: string, params?: Record<string, unknown>): T | undefined;
+    /**
+     * Store a value in the cache
+     */
+    set<T = unknown>(domain: string, operation: string, params: Record<string, unknown> | undefined, value: T): void;
+    /**
+     * Invalidate all cached entries for a domain
+     *
+     * Called on any mutate operation to ensure consistency.
+     */
+    invalidateDomain(domain: string): number;
+    /**
+     * Clear entire cache
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset statistics counters
+     */
+    resetStats(): void;
+    /**
+     * Evict all expired entries
+     */
+    evictExpired(): number;
+    /**
+     * Stop the cleanup timer (call on shutdown)
+     */
+    destroy(): void;
+    /**
+     * Check if cache is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Delete a single key and update domain tracking
+     */
+    private delete;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/mcp/lib/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/mcp/lib/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAsC;IACnD,OAAO,CAAC,UAAU,CAAuC;IACzD,OAAO,CAAC,KAAK,CAMX;IACF,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,YAAY,CAA+C;gBAEvD,KAAK,GAAE,MAAc,EAAE,OAAO,GAAE,OAAc;IAc1D;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;IAUrF;;OAEG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EACb,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,CAAC,GAAG,SAAS;IA0BhB;;OAEG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EACb,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,KAAK,EAAE,CAAC,GACP,IAAI;IAyBP;;;;OAIG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAmBxC;;OAEG;IACH,KAAK,IAAI,IAAI;IASb;;OAEG;IACH,QAAQ,IAAI,UAAU;IAItB;;OAEG;IACH,UAAU,IAAI,IAAI;IAMlB;;OAEG;IACH,YAAY,IAAI,MAAM;IAoBtB;;OAEG;IACH,OAAO,IAAI,IAAI;IAQf;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,OAAO,CAAC,MAAM;CASf"}