@panguard-ai/manager 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Panguard AI Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/agent-registry.d.ts

@@ -0,0 +1,88 @@
+/**
+ * AgentRegistry - Manages connected Guard agent registrations
+ * AgentRegistry - 管理已連線的 Guard 代理登錄
+ *
+ * Maintains an internal Map of registered agents, supports heartbeat updates,
+ * and detects stale/offline agents. All returned data is immutable copies.
+ *
+ * @module @panguard-ai/manager/agent-registry
+ */
+import type { AgentRegistration, AgentRegistrationRequest, AgentHeartbeat, AgentStatus } from './types.js';
+/**
+ * Registry that tracks all connected Guard agents.
+ * Uses immutable return patterns - internal state is never exposed directly.
+ */
+export declare class AgentRegistry {
+    private readonly agents;
+    private readonly maxAgents;
+    constructor(maxAgents: number);
+    /**
+     * Register a new Guard agent.
+     * Generates a unique agent ID and returns the registration record.
+     *
+     * @param request - Registration request from the agent
+     * @returns Immutable copy of the registration record
+     * @throws Error if maximum agent limit is reached
+     */
+    registerAgent(request: AgentRegistrationRequest): AgentRegistration;
+    /**
+     * Remove an agent from the registry.
+     *
+     * @param agentId - The agent's unique identifier
+     * @returns true if the agent was found and removed
+     */
+    deregisterAgent(agentId: string): boolean;
+    /**
+     * Update the heartbeat timestamp and metrics for an agent.
+     * Creates a new registration record with updated fields (immutable pattern).
+     *
+     * @param heartbeat - Heartbeat data from the agent
+     * @returns Updated registration or undefined if agent not found
+     */
+    updateHeartbeat(heartbeat: AgentHeartbeat): AgentRegistration | undefined;
+    /**
+     * Get a single agent's registration record.
+     *
+     * @param agentId - The agent's unique identifier
+     * @returns Immutable copy of the registration, or undefined
+     */
+    getAgent(agentId: string): AgentRegistration | undefined;
+    /**
+     * Get all agents currently marked as online.
+     *
+     * @returns Array of immutable registration copies
+     */
+    getActiveAgents(): readonly AgentRegistration[];
+    /**
+     * Get all registered agents regardless of status.
+     *
+     * @returns Array of immutable registration copies
+     */
+    getAllAgents(): readonly AgentRegistration[];
+    /**
+     * Identify agents whose last heartbeat exceeds the timeout threshold.
+     * Marks them as 'stale' in the internal registry.
+     *
+     * @param timeoutMs - Maximum allowed milliseconds since last heartbeat
+     * @returns Array of agents that are now stale
+     */
+    getStaleAgents(timeoutMs: number): readonly AgentRegistration[];
+    /**
+     * Mark an agent as offline.
+     *
+     * @param agentId - The agent's unique identifier
+     * @returns true if the agent was found and marked offline
+     */
+    markOffline(agentId: string): boolean;
+    /**
+     * Get the count of agents by status.
+     *
+     * @returns Object with counts for each status
+     */
+    getStatusCounts(): Record<AgentStatus, number>;
+    /**
+     * Get the total number of registered agents.
+     */
+    get size(): number;
+}
+//# sourceMappingURL=agent-registry.d.ts.map

package/dist/agent-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-registry.d.ts","sourceRoot":"","sources":["../src/agent-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,iBAAiB,EACjB,wBAAwB,EACxB,cAAc,EACd,WAAW,EACZ,MAAM,YAAY,CAAC;AAIpB;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,SAAS,EAAE,MAAM;IAK7B;;;;;;;OAOG;IACH,aAAa,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB;IAmCnE;;;;;OAKG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAezC;;;;;;OAMG;IACH,eAAe,CAAC,SAAS,EAAE,cAAc,GAAG,iBAAiB,GAAG,SAAS;IAkBzE;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAMxD;;;;OAIG;IACH,eAAe,IAAI,SAAS,iBAAiB,EAAE;IAM/C;;;;OAIG;IACH,YAAY,IAAI,SAAS,iBAAiB,EAAE;IAO5C;;;;;;OAMG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,iBAAiB,EAAE;IA8B/D;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAkBrC;;;;OAIG;IACH,eAAe,IAAI,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC;IAc9C;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/agent-registry.js

@@ -0,0 +1,202 @@
+/**
+ * AgentRegistry - Manages connected Guard agent registrations
+ * AgentRegistry - 管理已連線的 Guard 代理登錄
+ *
+ * Maintains an internal Map of registered agents, supports heartbeat updates,
+ * and detects stale/offline agents. All returned data is immutable copies.
+ *
+ * @module @panguard-ai/manager/agent-registry
+ */
+import { createLogger } from '@panguard-ai/core';
+import { generateAgentId } from './utils.js';
+const logger = createLogger('panguard-manager:registry');
+/**
+ * Registry that tracks all connected Guard agents.
+ * Uses immutable return patterns - internal state is never exposed directly.
+ */
+export class AgentRegistry {
+    agents;
+    maxAgents;
+    constructor(maxAgents) {
+        this.agents = new Map();
+        this.maxAgents = maxAgents;
+    }
+    /**
+     * Register a new Guard agent.
+     * Generates a unique agent ID and returns the registration record.
+     *
+     * @param request - Registration request from the agent
+     * @returns Immutable copy of the registration record
+     * @throws Error if maximum agent limit is reached
+     */
+    registerAgent(request) {
+        if (this.agents.size >= this.maxAgents) {
+            throw new Error(`Maximum agent limit reached (${this.maxAgents}). ` +
+                'Cannot register additional agents.');
+        }
+        const agentId = generateAgentId();
+        const now = new Date().toISOString();
+        const registration = {
+            agentId,
+            hostname: request.hostname,
+            platform: {
+                os: request.os,
+                arch: request.arch,
+                ip: request.ip,
+            },
+            version: request.version,
+            registeredAt: now,
+            lastHeartbeat: now,
+            status: 'online',
+        };
+        this.agents.set(agentId, registration);
+        logger.info(`Agent registered: ${agentId} (${request.hostname}, ${request.os}) / ` +
+            `代理已登錄: ${agentId} (${request.hostname}, ${request.os})`);
+        return { ...registration, platform: { ...registration.platform } };
+    }
+    /**
+     * Remove an agent from the registry.
+     *
+     * @param agentId - The agent's unique identifier
+     * @returns true if the agent was found and removed
+     */
+    deregisterAgent(agentId) {
+        const agent = this.agents.get(agentId);
+        if (!agent) {
+            logger.warn(`Deregister failed: agent ${agentId} not found`);
+            return false;
+        }
+        this.agents.delete(agentId);
+        logger.info(`Agent deregistered: ${agentId} (${agent.hostname}) / ` +
+            `代理已登出: ${agentId} (${agent.hostname})`);
+        return true;
+    }
+    /**
+     * Update the heartbeat timestamp and metrics for an agent.
+     * Creates a new registration record with updated fields (immutable pattern).
+     *
+     * @param heartbeat - Heartbeat data from the agent
+     * @returns Updated registration or undefined if agent not found
+     */
+    updateHeartbeat(heartbeat) {
+        const existing = this.agents.get(heartbeat.agentId);
+        if (!existing) {
+            logger.warn(`Heartbeat from unknown agent: ${heartbeat.agentId}`);
+            return undefined;
+        }
+        const updated = {
+            ...existing,
+            platform: { ...existing.platform },
+            lastHeartbeat: heartbeat.timestamp,
+            status: 'online',
+        };
+        this.agents.set(heartbeat.agentId, updated);
+        return { ...updated, platform: { ...updated.platform } };
+    }
+    /**
+     * Get a single agent's registration record.
+     *
+     * @param agentId - The agent's unique identifier
+     * @returns Immutable copy of the registration, or undefined
+     */
+    getAgent(agentId) {
+        const agent = this.agents.get(agentId);
+        if (!agent)
+            return undefined;
+        return { ...agent, platform: { ...agent.platform } };
+    }
+    /**
+     * Get all agents currently marked as online.
+     *
+     * @returns Array of immutable registration copies
+     */
+    getActiveAgents() {
+        return Array.from(this.agents.values())
+            .filter((a) => a.status === 'online')
+            .map((a) => ({ ...a, platform: { ...a.platform } }));
+    }
+    /**
+     * Get all registered agents regardless of status.
+     *
+     * @returns Array of immutable registration copies
+     */
+    getAllAgents() {
+        return Array.from(this.agents.values()).map((a) => ({
+            ...a,
+            platform: { ...a.platform },
+        }));
+    }
+    /**
+     * Identify agents whose last heartbeat exceeds the timeout threshold.
+     * Marks them as 'stale' in the internal registry.
+     *
+     * @param timeoutMs - Maximum allowed milliseconds since last heartbeat
+     * @returns Array of agents that are now stale
+     */
+    getStaleAgents(timeoutMs) {
+        const now = Date.now();
+        const staleAgents = [];
+        for (const [agentId, agent] of this.agents.entries()) {
+            if (agent.status === 'offline')
+                continue;
+            const lastBeat = new Date(agent.lastHeartbeat).getTime();
+            const elapsed = now - lastBeat;
+            if (elapsed >= timeoutMs) {
+                const updated = {
+                    ...agent,
+                    platform: { ...agent.platform },
+                    status: 'stale',
+                };
+                this.agents.set(agentId, updated);
+                staleAgents.push({ ...updated, platform: { ...updated.platform } });
+                logger.warn(`Agent ${agentId} (${agent.hostname}) is stale ` +
+                    `(last heartbeat ${Math.round(elapsed / 1000)}s ago) / ` +
+                    `代理 ${agentId} (${agent.hostname}) 已過期`);
+            }
+        }
+        return staleAgents;
+    }
+    /**
+     * Mark an agent as offline.
+     *
+     * @param agentId - The agent's unique identifier
+     * @returns true if the agent was found and marked offline
+     */
+    markOffline(agentId) {
+        const existing = this.agents.get(agentId);
+        if (!existing)
+            return false;
+        const updated = {
+            ...existing,
+            platform: { ...existing.platform },
+            status: 'offline',
+        };
+        this.agents.set(agentId, updated);
+        logger.info(`Agent marked offline: ${agentId} (${existing.hostname}) / ` +
+            `代理已標記為離線: ${agentId}`);
+        return true;
+    }
+    /**
+     * Get the count of agents by status.
+     *
+     * @returns Object with counts for each status
+     */
+    getStatusCounts() {
+        const counts = {
+            online: 0,
+            stale: 0,
+            offline: 0,
+        };
+        for (const agent of this.agents.values()) {
+            counts[agent.status]++;
+        }
+        return counts;
+    }
+    /**
+     * Get the total number of registered agents.
+     */
+    get size() {
+        return this.agents.size;
+    }
+}
+//# sourceMappingURL=agent-registry.js.map

package/dist/agent-registry.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Panguard AI - Manager Package
+ * Panguard 安全平台 - Manager 套件
+ *
+ * Central orchestration node for the distributed Guard agent architecture.
+ * Manages agent registration, threat correlation, and policy distribution.
+ *
+ * 分散式 Guard 代理架構的中央協調節點。
+ * 管理代理登錄、威脅關聯和策略分發。
+ *
+ * @module @panguard-ai/manager
+ */
+export { Manager } from './manager.js';
+export { AgentRegistry } from './agent-registry.js';
+export { ThreatAggregator } from './threat-aggregator.js';
+export { PolicyEngine } from './policy-engine.js';
+export { generateAgentId, generateThreatId, generatePolicyId, generateAuthToken, extractSourceIP, extractFileHash, } from './utils.js';
+export type { AgentStatus, AgentPlatformInfo, AgentRegistration, AgentRegistrationRequest, AgentHeartbeat, ThreatEvent, ThreatReport, AggregatedThreat, CorrelationMatch, ThreatSummary, PolicyRule, PolicyUpdate, ManagerConfig, AgentOverview, ManagerOverview, PolicyBroadcastResult, } from './types.js';
+export { DEFAULT_MANAGER_CONFIG } from './types.js';
+/** Manager package version / Manager 套件版本 */
+export declare const MANAGER_VERSION = "0.2.0";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,EACxB,cAAc,EACd,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,YAAY,EACZ,aAAa,EACb,aAAa,EACb,eAAe,EACf,qBAAqB,GACtB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,6CAA6C;AAC7C,eAAO,MAAM,eAAe,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * Panguard AI - Manager Package
+ * Panguard 安全平台 - Manager 套件
+ *
+ * Central orchestration node for the distributed Guard agent architecture.
+ * Manages agent registration, threat correlation, and policy distribution.
+ *
+ * 分散式 Guard 代理架構的中央協調節點。
+ * 管理代理登錄、威脅關聯和策略分發。
+ *
+ * @module @panguard-ai/manager
+ */
+// Main orchestrator / 主協調器
+export { Manager } from './manager.js';
+// Components / 元件
+export { AgentRegistry } from './agent-registry.js';
+export { ThreatAggregator } from './threat-aggregator.js';
+export { PolicyEngine } from './policy-engine.js';
+// Utilities / 工具函式
+export { generateAgentId, generateThreatId, generatePolicyId, generateAuthToken, extractSourceIP, extractFileHash, } from './utils.js';
+// Constants / 常數
+export { DEFAULT_MANAGER_CONFIG } from './types.js';
+/** Manager package version / Manager 套件版本 */
+export const MANAGER_VERSION = '0.2.0';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,2BAA2B;AAC3B,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,kBAAkB;AAClB,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,mBAAmB;AACnB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AAsBpB,iBAAiB;AACjB,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,6CAA6C;AAC7C,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC"}

package/dist/manager.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Manager - Central orchestrator for distributed Guard agent architecture
+ * Manager - 分散式 Guard 代理架構的中央協調器
+ *
+ * Coordinates multiple Guard agents across endpoints:
+ * - Agent registration and lifecycle management
+ * - Heartbeat monitoring with stale agent detection
+ * - Threat ingestion and cross-agent correlation
+ * - Centralized policy creation and distribution
+ *
+ * @module @panguard-ai/manager/manager
+ */
+import type { ManagerConfig, AgentRegistrationRequest, AgentRegistration, AgentHeartbeat, ThreatReport, AggregatedThreat, PolicyUpdate, PolicyRule, ManagerOverview, ThreatSummary, PolicyBroadcastResult } from './types.js';
+/**
+ * Manager is the main orchestrator for the distributed Guard architecture.
+ *
+ * It composes AgentRegistry, ThreatAggregator, and PolicyEngine to provide
+ * a unified API for managing the entire fleet of Guard agents.
+ */
+export declare class Manager {
+    private readonly config;
+    private readonly registry;
+    private readonly aggregator;
+    private readonly policyEngine;
+    private running;
+    private startTime;
+    private staleCheckTimer;
+    private purgeTimer;
+    private readonly broadcastQueue;
+    constructor(config: ManagerConfig);
+    /**
+     * Start the Manager service.
+     * Begins periodic stale agent checking and threat purging.
+     */
+    start(): void;
+    /**
+     * Stop the Manager service.
+     * Clears all periodic timers.
+     */
+    stop(): void;
+    /**
+     * Handle a new agent registration request.
+     *
+     * @param request - Registration data from the Guard agent
+     * @returns Immutable copy of the registration record
+     * @throws Error if max agents exceeded
+     */
+    handleRegistration(request: AgentRegistrationRequest): AgentRegistration;
+    /**
+     * Handle a heartbeat from a Guard agent.
+     * Updates the agent's status and last-seen timestamp.
+     *
+     * @param heartbeat - Heartbeat data from the agent
+     * @returns Updated registration, or undefined if agent unknown
+     */
+    handleHeartbeat(heartbeat: AgentHeartbeat): AgentRegistration | undefined;
+    /**
+     * Handle a threat report from a Guard agent.
+     * Ingests threats into the aggregator and checks for cross-agent correlation.
+     *
+     * @param report - Threat report containing one or more events
+     * @returns Array of aggregated threats, with correlation data if detected
+     */
+    handleThreatReport(report: ThreatReport): readonly AggregatedThreat[];
+    /**
+     * Remove an agent from the fleet.
+     *
+     * @param agentId - The agent's unique identifier
+     * @returns true if the agent was found and removed
+     */
+    handleDeregistration(agentId: string): boolean;
+    /**
+     * Create and optionally broadcast a new security policy.
+     *
+     * @param rules - Policy rules to include
+     * @param broadcast - Whether to queue broadcast to all active agents
+     * @returns The created policy
+     */
+    createPolicy(rules: readonly PolicyRule[], broadcast?: boolean): PolicyUpdate;
+    /**
+     * Queue a policy update for broadcast to all active agents.
+     *
+     * @param policy - The policy to broadcast
+     * @returns Broadcast result with target agent list
+     */
+    broadcastPolicy(policy: PolicyUpdate): PolicyBroadcastResult;
+    /**
+     * Get the active global policy.
+     *
+     * @returns Active policy or null
+     */
+    getActivePolicy(): PolicyUpdate | null;
+    /**
+     * Get the policy applicable to a specific agent.
+     *
+     * @param agentId - The agent's unique identifier
+     * @returns Policy for the agent, or null
+     */
+    getPolicyForAgent(agentId: string): PolicyUpdate | null;
+    /**
+     * Get pending policy broadcast results.
+     *
+     * @returns Immutable array of broadcast results
+     */
+    getPendingBroadcasts(): readonly PolicyBroadcastResult[];
+    /**
+     * Check for and handle stale agents.
+     * Called periodically by the stale check timer.
+     */
+    private checkStaleAgents;
+    /**
+     * Generate a comprehensive overview for the management dashboard.
+     *
+     * @returns Immutable manager overview object
+     */
+    getOverview(): ManagerOverview;
+    /**
+     * Get threat summary from the aggregator.
+     *
+     * @returns Immutable threat summary
+     */
+    getThreatSummary(): ThreatSummary;
+    /**
+     * Get threats reported by a specific agent.
+     *
+     * @param agentId - The agent's unique identifier
+     * @returns Array of aggregated threats
+     */
+    getThreatsByAgent(agentId: string): readonly AggregatedThreat[];
+    /**
+     * Get recent threats across all agents.
+     *
+     * @param since - Date threshold
+     * @returns Array of aggregated threats
+     */
+    getRecentThreats(since: Date): readonly AggregatedThreat[];
+    /**
+     * Get a specific agent's registration.
+     *
+     * @param agentId - The agent's unique identifier
+     * @returns Agent registration or undefined
+     */
+    getAgent(agentId: string): AgentRegistration | undefined;
+    /**
+     * Check if the manager is currently running.
+     */
+    isRunning(): boolean;
+    /**
+     * Get the number of registered agents.
+     */
+    getAgentCount(): number;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EACV,aAAa,EACb,wBAAwB,EACxB,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,eAAe,EAEf,aAAa,EACb,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAIpB;;;;;GAKG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAE5C,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,eAAe,CAAwC;IAC/D,OAAO,CAAC,UAAU,CAAwC;IAG1D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0B;gBAE7C,MAAM,EAAE,aAAa;IAsBjC;;;OAGG;IACH,KAAK,IAAI,IAAI;IA6Bb;;;OAGG;IACH,IAAI,IAAI,IAAI;IAsBZ;;;;;;OAMG;IACH,kBAAkB,CAChB,OAAO,EAAE,wBAAwB,GAChC,iBAAiB;IAWpB;;;;;;OAMG;IACH,eAAe,CACb,SAAS,EAAE,cAAc,GACxB,iBAAiB,GAAG,SAAS;IAIhC;;;;;;OAMG;IACH,kBAAkB,CAChB,MAAM,EAAE,YAAY,GACnB,SAAS,gBAAgB,EAAE;IAoB9B;;;;;OAKG;IACH,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAM9C;;;;;;OAMG;IACH,YAAY,CACV,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,SAAS,UAAO,GACf,YAAY;IAcf;;;;;OAKG;IACH,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,qBAAqB;IAuB5D;;;;OAIG;IACH,eAAe,IAAI,YAAY,GAAG,IAAI;IAItC;;;;;OAKG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAIvD;;;;OAIG;IACH,oBAAoB,IAAI,SAAS,qBAAqB,EAAE;IASxD;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAexB;;;;OAIG;IACH,WAAW,IAAI,eAAe;IA6B9B;;;;OAIG;IACH,gBAAgB,IAAI,aAAa;IAIjC;;;;;OAKG;IACH,iBAAiB,CACf,OAAO,EAAE,MAAM,GACd,SAAS,gBAAgB,EAAE;IAI9B;;;;;OAKG;IACH,gBAAgB,CAAC,KAAK,EAAE,IAAI,GAAG,SAAS,gBAAgB,EAAE;IAI1D;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIxD;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,aAAa,IAAI,MAAM;CAGxB"}