specweave 0.17.16 → 0.17.19

package/dist/src/core/deduplication/command-deduplicator.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Global Command Deduplication System
+ *
+ * Prevents ANY command/tool from being invoked twice within a configurable time window.
+ * Tracks all SlashCommand, Write, Edit, and other tool invocations.
+ *
+ * Architecture:
+ * - File-based cache: `.specweave/state/command-invocations.json`
+ * - Hash-based deduplication: command + args → unique fingerprint
+ * - Time-windowed checks: Configurable window (default: 1000ms)
+ * - Automatic cleanup: Removes old entries to prevent bloat
+ *
+ * Usage:
+ * ```typescript
+ * import { CommandDeduplicator } from './command-deduplicator.js';
+ *
+ * const dedup = new CommandDeduplicator();
+ * const isDuplicate = await dedup.checkDuplicate('/specweave:do', ['0031']);
+ *
+ * if (isDuplicate) {
+ *   console.log('⚠️  Duplicate invocation blocked!');
+ *   return;
+ * }
+ *
+ * await dedup.recordInvocation('/specweave:do', ['0031']);
+ * // ... execute command
+ * ```
+ *
+ * @module core/deduplication
+ */
+/**
+ * Invocation record stored in cache
+ */
+export interface InvocationRecord {
+    /** Unique fingerprint of command + args */
+    fingerprint: string;
+    /** Command name (e.g., '/specweave:do') */
+    command: string;
+    /** Command arguments */
+    args: string[];
+    /** Timestamp when invoked (ms since epoch) */
+    timestamp: number;
+    /** Human-readable timestamp */
+    date: string;
+}
+/**
+ * Cache structure
+ */
+export interface InvocationCache {
+    /** List of invocation records */
+    invocations: InvocationRecord[];
+    /** Last cleanup timestamp */
+    lastCleanup: number;
+    /** Total invocations tracked */
+    totalInvocations: number;
+    /** Total duplicates blocked */
+    totalDuplicatesBlocked: number;
+}
+/**
+ * Configuration for deduplication
+ */
+export interface DeduplicationConfig {
+    /** Time window in milliseconds to check for duplicates (default: 1000ms) */
+    windowMs?: number;
+    /** Path to cache file (default: .specweave/state/command-invocations.json) */
+    cachePath?: string;
+    /** Maximum cache entries before cleanup (default: 1000) */
+    maxCacheSize?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Cleanup interval in milliseconds (default: 60000ms = 1 minute) */
+    cleanupIntervalMs?: number;
+}
+/**
+ * Global command deduplication system
+ */
+export declare class CommandDeduplicator {
+    private projectRoot;
+    private config;
+    private cache;
+    private lastCleanupCheck;
+    /**
+     * Create new deduplicator instance
+     *
+     * @param config - Configuration options
+     * @param projectRoot - Project root directory (default: process.cwd())
+     */
+    constructor(config?: DeduplicationConfig, projectRoot?: string);
+    /**
+     * Check if command invocation is a duplicate
+     *
+     * @param command - Command name (e.g., '/specweave:do')
+     * @param args - Command arguments
+     * @returns true if duplicate detected, false otherwise
+     */
+    checkDuplicate(command: string, args?: string[]): Promise<boolean>;
+    /**
+     * Record command invocation
+     *
+     * @param command - Command name
+     * @param args - Command arguments
+     */
+    recordInvocation(command: string, args?: string[]): Promise<void>;
+    /**
+     * Create unique fingerprint for command + args
+     *
+     * @param command - Command name
+     * @param args - Command arguments
+     * @returns SHA256 hash of command + args
+     */
+    private createFingerprint;
+    /**
+     * Load cache from disk
+     *
+     * @returns Invocation cache
+     */
+    private loadCache;
+    /**
+     * Save cache to disk
+     */
+    private saveCache;
+    /**
+     * Clean up old invocation records
+     *
+     * Removes records older than 10x the deduplication window to prevent cache bloat.
+     */
+    private cleanup;
+    /**
+     * Get statistics about deduplication
+     *
+     * @returns Statistics object
+     */
+    getStats(): {
+        totalInvocations: number;
+        totalDuplicatesBlocked: number;
+        currentCacheSize: number;
+        lastCleanup: string;
+    };
+    /**
+     * Clear all cached invocations (useful for testing)
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Get global deduplicator instance
+ *
+ * @param config - Configuration (only used on first call)
+ * @returns Global deduplicator instance
+ */
+export declare function getGlobalDeduplicator(config?: DeduplicationConfig): CommandDeduplicator;
+/**
+ * Convenience function: Check if command is duplicate
+ *
+ * @param command - Command name
+ * @param args - Command arguments
+ * @returns true if duplicate, false otherwise
+ */
+export declare function isDuplicate(command: string, args?: string[]): Promise<boolean>;
+/**
+ * Convenience function: Record command invocation
+ *
+ * @param command - Command name
+ * @param args - Command arguments
+ */
+export declare function recordCommand(command: string, args?: string[]): Promise<void>;
+//# sourceMappingURL=command-deduplicator.d.ts.map

package/dist/src/core/deduplication/command-deduplicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-deduplicator.d.ts","sourceRoot":"","sources":["../../../../src/core/deduplication/command-deduplicator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IAEpB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAEhB,wBAAwB;IACxB,IAAI,EAAE,MAAM,EAAE,CAAC;IAEf,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAElB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAEhC,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IAEpB,gCAAgC;IAChC,gBAAgB,EAAE,MAAM,CAAC;IAEzB,+BAA+B;IAC/B,sBAAsB,EAAE,MAAM,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAWgB,OAAO,CAAC,WAAW;IAVjE,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,KAAK,CAAkB;IAC/B,OAAO,CAAC,gBAAgB,CAAa;IAErC;;;;;OAKG;gBACS,MAAM,GAAE,mBAAwB,EAAU,WAAW,GAAE,MAAsB;IAYzF;;;;;;OAMG;IACU,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAiCnF;;;;;OAKG;IACU,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BlF;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAKzB;;;;OAIG;IACH,OAAO,CAAC,SAAS;IA0BjB;;OAEG;YACW,SAAS;IAavB;;;;OAIG;YACW,OAAO;IAsBrB;;;;OAIG;IACI,QAAQ,IAAI;QACjB,gBAAgB,EAAE,MAAM,CAAC;QACzB,sBAAsB,EAAE,MAAM,CAAC;QAC/B,gBAAgB,EAAE,MAAM,CAAC;QACzB,WAAW,EAAE,MAAM,CAAC;KACrB;IASD;;OAEG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAapC;AAOD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,mBAAmB,CAKvF;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAExF;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvF"}

package/dist/src/core/deduplication/command-deduplicator.js

@@ -0,0 +1,254 @@
+/**
+ * Global Command Deduplication System
+ *
+ * Prevents ANY command/tool from being invoked twice within a configurable time window.
+ * Tracks all SlashCommand, Write, Edit, and other tool invocations.
+ *
+ * Architecture:
+ * - File-based cache: `.specweave/state/command-invocations.json`
+ * - Hash-based deduplication: command + args → unique fingerprint
+ * - Time-windowed checks: Configurable window (default: 1000ms)
+ * - Automatic cleanup: Removes old entries to prevent bloat
+ *
+ * Usage:
+ * ```typescript
+ * import { CommandDeduplicator } from './command-deduplicator.js';
+ *
+ * const dedup = new CommandDeduplicator();
+ * const isDuplicate = await dedup.checkDuplicate('/specweave:do', ['0031']);
+ *
+ * if (isDuplicate) {
+ *   console.log('⚠️  Duplicate invocation blocked!');
+ *   return;
+ * }
+ *
+ * await dedup.recordInvocation('/specweave:do', ['0031']);
+ * // ... execute command
+ * ```
+ *
+ * @module core/deduplication
+ */
+import * as fs from 'fs-extra';
+import * as path from 'path';
+import * as crypto from 'crypto';
+/**
+ * Global command deduplication system
+ */
+export class CommandDeduplicator {
+    /**
+     * Create new deduplicator instance
+     *
+     * @param config - Configuration options
+     * @param projectRoot - Project root directory (default: process.cwd())
+     */
+    constructor(config = {}, projectRoot = process.cwd()) {
+        this.projectRoot = projectRoot;
+        this.lastCleanupCheck = 0;
+        this.config = {
+            windowMs: config.windowMs ?? 1000,
+            cachePath: config.cachePath ?? path.join(projectRoot, '.specweave', 'state', 'command-invocations.json'),
+            maxCacheSize: config.maxCacheSize ?? 1000,
+            debug: config.debug ?? false,
+            cleanupIntervalMs: config.cleanupIntervalMs ?? 60000
+        };
+        this.cache = this.loadCache();
+    }
+    /**
+     * Check if command invocation is a duplicate
+     *
+     * @param command - Command name (e.g., '/specweave:do')
+     * @param args - Command arguments
+     * @returns true if duplicate detected, false otherwise
+     */
+    async checkDuplicate(command, args = []) {
+        const fingerprint = this.createFingerprint(command, args);
+        const now = Date.now();
+        const windowStart = now - this.config.windowMs;
+        // Check for recent invocations with same fingerprint
+        const recentDuplicates = this.cache.invocations.filter(inv => inv.fingerprint === fingerprint &&
+            inv.timestamp >= windowStart);
+        if (recentDuplicates.length > 0) {
+            const mostRecent = recentDuplicates[recentDuplicates.length - 1];
+            const timeSince = now - mostRecent.timestamp;
+            if (this.config.debug) {
+                console.log(`[CommandDeduplicator] 🚫 DUPLICATE DETECTED!`);
+                console.log(`  Command: ${command}`);
+                console.log(`  Args: ${JSON.stringify(args)}`);
+                console.log(`  Time since last: ${timeSince}ms`);
+                console.log(`  Window: ${this.config.windowMs}ms`);
+            }
+            // Increment duplicate counter
+            this.cache.totalDuplicatesBlocked++;
+            await this.saveCache();
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Record command invocation
+     *
+     * @param command - Command name
+     * @param args - Command arguments
+     */
+    async recordInvocation(command, args = []) {
+        const fingerprint = this.createFingerprint(command, args);
+        const now = Date.now();
+        const record = {
+            fingerprint,
+            command,
+            args,
+            timestamp: now,
+            date: new Date(now).toISOString()
+        };
+        this.cache.invocations.push(record);
+        this.cache.totalInvocations++;
+        if (this.config.debug) {
+            console.log(`[CommandDeduplicator] ✅ Recorded invocation: ${command} ${args.join(' ')}`);
+        }
+        // Trigger cleanup if needed
+        if (now - this.lastCleanupCheck > this.config.cleanupIntervalMs) {
+            await this.cleanup();
+            this.lastCleanupCheck = now;
+        }
+        await this.saveCache();
+    }
+    /**
+     * Create unique fingerprint for command + args
+     *
+     * @param command - Command name
+     * @param args - Command arguments
+     * @returns SHA256 hash of command + args
+     */
+    createFingerprint(command, args) {
+        const data = JSON.stringify({ command, args });
+        return crypto.createHash('sha256').update(data).digest('hex');
+    }
+    /**
+     * Load cache from disk
+     *
+     * @returns Invocation cache
+     */
+    loadCache() {
+        try {
+            if (fs.existsSync(this.config.cachePath)) {
+                const data = fs.readJsonSync(this.config.cachePath);
+                if (this.config.debug) {
+                    console.log(`[CommandDeduplicator] 📂 Loaded cache: ${data.invocations.length} invocations`);
+                }
+                return data;
+            }
+        }
+        catch (error) {
+            if (this.config.debug) {
+                console.log(`[CommandDeduplicator] ⚠️  Failed to load cache: ${error}`);
+            }
+        }
+        // Return empty cache
+        return {
+            invocations: [],
+            lastCleanup: Date.now(),
+            totalInvocations: 0,
+            totalDuplicatesBlocked: 0
+        };
+    }
+    /**
+     * Save cache to disk
+     */
+    async saveCache() {
+        try {
+            await fs.ensureDir(path.dirname(this.config.cachePath));
+            await fs.writeJson(this.config.cachePath, this.cache, { spaces: 2 });
+            if (this.config.debug) {
+                console.log(`[CommandDeduplicator] 💾 Saved cache: ${this.cache.invocations.length} invocations`);
+            }
+        }
+        catch (error) {
+            console.error(`[CommandDeduplicator] ❌ Failed to save cache: ${error}`);
+        }
+    }
+    /**
+     * Clean up old invocation records
+     *
+     * Removes records older than 10x the deduplication window to prevent cache bloat.
+     */
+    async cleanup() {
+        const now = Date.now();
+        const cutoff = now - (this.config.windowMs * 10); // Keep 10x window
+        const before = this.cache.invocations.length;
+        this.cache.invocations = this.cache.invocations.filter(inv => inv.timestamp >= cutoff);
+        const after = this.cache.invocations.length;
+        // Also enforce max cache size
+        if (this.cache.invocations.length > this.config.maxCacheSize) {
+            this.cache.invocations = this.cache.invocations.slice(-this.config.maxCacheSize);
+        }
+        this.cache.lastCleanup = now;
+        if (this.config.debug && before > after) {
+            console.log(`[CommandDeduplicator] 🧹 Cleanup: Removed ${before - after} old records`);
+        }
+        await this.saveCache();
+    }
+    /**
+     * Get statistics about deduplication
+     *
+     * @returns Statistics object
+     */
+    getStats() {
+        return {
+            totalInvocations: this.cache.totalInvocations,
+            totalDuplicatesBlocked: this.cache.totalDuplicatesBlocked,
+            currentCacheSize: this.cache.invocations.length,
+            lastCleanup: new Date(this.cache.lastCleanup).toISOString()
+        };
+    }
+    /**
+     * Clear all cached invocations (useful for testing)
+     */
+    async clear() {
+        this.cache = {
+            invocations: [],
+            lastCleanup: Date.now(),
+            totalInvocations: 0,
+            totalDuplicatesBlocked: 0
+        };
+        await this.saveCache();
+        if (this.config.debug) {
+            console.log(`[CommandDeduplicator] 🗑️  Cache cleared`);
+        }
+    }
+}
+/**
+ * Global singleton instance (convenience)
+ */
+let globalInstance = null;
+/**
+ * Get global deduplicator instance
+ *
+ * @param config - Configuration (only used on first call)
+ * @returns Global deduplicator instance
+ */
+export function getGlobalDeduplicator(config) {
+    if (!globalInstance) {
+        globalInstance = new CommandDeduplicator(config);
+    }
+    return globalInstance;
+}
+/**
+ * Convenience function: Check if command is duplicate
+ *
+ * @param command - Command name
+ * @param args - Command arguments
+ * @returns true if duplicate, false otherwise
+ */
+export async function isDuplicate(command, args = []) {
+    return await getGlobalDeduplicator().checkDuplicate(command, args);
+}
+/**
+ * Convenience function: Record command invocation
+ *
+ * @param command - Command name
+ * @param args - Command arguments
+ */
+export async function recordCommand(command, args = []) {
+    await getGlobalDeduplicator().recordInvocation(command, args);
+}
+//# sourceMappingURL=command-deduplicator.js.map

package/dist/src/core/deduplication/command-deduplicator.js.map

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

package/dist/src/core/living-docs/hierarchy-mapper.d.ts

@@ -0,0 +1,142 @@
+/**
+ * SpecWeave Hierarchy Mapper
+ *
+ * Maps increments to Feature Spec (FS-*) folders following Universal Hierarchy architecture.
+ *
+ * Supports three complexity levels:
+ * 1. Simple: Increment → Issue/Epic/Feature (flat)
+ * 2. Standard: FS-* (Epic) → US-* (User Stories) → T-* (Tasks)
+ * 3. Enterprise: Domain → FS-* (Epic) → US-* → T-*
+ *
+ * @author SpecWeave Team
+ * @version 3.0.0
+ */
+export interface HierarchyConfig {
+    level: 'simple' | 'standard' | 'enterprise' | 'auto';
+    specsBaseDir: string;
+    projectId: string;
+    featureFolderPattern: '{name}';
+    userStoriesSubdir: string;
+    detectFeatureFrom: ('frontmatter' | 'increment-name' | 'config')[];
+    fallbackFeature?: string;
+}
+export interface FeatureMapping {
+    featureId: string;
+    featureFolder: string;
+    featurePath: string;
+    userStoriesPath: string;
+    confidence: number;
+    detectionMethod: 'frontmatter' | 'increment-name' | 'config' | 'fallback';
+}
+export type EpicMapping = FeatureMapping;
+/**
+ * HierarchyMapper - Maps increments to feature folders (named by concept, not increment number)
+ *
+ * NEW ARCHITECTURE (v0.18.0+):
+ * - Features are PERMANENT (named by concept: "release-management", "external-tool-sync")
+ * - Increments are TEMPORARY (named by execution: "0023-release-management-enhancements")
+ * - Multiple increments can contribute to same feature
+ * - No FS-### prefix (features aren't numbered)
+ */
+export declare class HierarchyMapper {
+    private config;
+    private projectRoot;
+    constructor(projectRoot: string, config?: Partial<HierarchyConfig>);
+    /**
+     * Detect which feature folder this increment belongs to
+     *
+     * NEW: Features are named by CONCEPT (release-management), not INCREMENT NUMBER (FS-023)
+     */
+    detectFeatureMapping(incrementId: string): Promise<FeatureMapping>;
+    /**
+     * Legacy alias for backward compatibility
+     */
+    detectEpicMapping(incrementId: string): Promise<EpicMapping>;
+    /**
+     * Detect feature from frontmatter (epic: feature-name)
+     *
+     * FORMAT (v0.18.1+): Accepts simple feature names (external-tool-status-sync)
+     * LEGACY: Also accepts old FS-### format (FS-001) - extracts from increment name instead
+     */
+    private detectFromFrontmatter;
+    /**
+     * Detect feature from increment NAME
+     *
+     * FORMAT (v0.18.1+): Simple descriptive names (no date prefixes)
+     *
+     * Extracts the descriptive part of increment ID and normalizes it to feature name
+     * Examples:
+     *   0023-release-management-enhancements → release-management (new or existing)
+     *   0031-external-tool-status-sync → external-tool-status-sync
+     */
+    private detectFromIncrementName;
+    /**
+     * Detect feature from config mapping (explicit increment → feature mapping)
+     */
+    private detectFromConfig;
+    /**
+     * Create fallback mapping (extract feature name from increment ID)
+     *
+     * FORMAT (v0.18.1+): Simple descriptive names (no prefixes)
+     * - Uses core feature name extracted from increment ID
+     * - No date prefixes (removed to prevent duplicates)
+     * - No FS- prefixes (features are not numbered)
+     *
+     * Example: 0023-release-management-enhancements → release-management
+     */
+    private createFallbackMapping;
+    /**
+     * Get increment creation date in yy-mm-dd format
+     * Tries: metadata.json → spec.md frontmatter → current date
+     */
+    private getIncrementCreationDate;
+    /**
+     * Format date as yy-mm-dd
+     * Input: "2025-11-14" or "2025-11-14T12:00:00Z"
+     * Output: "25-11-14"
+     */
+    private formatDateShort;
+    /**
+     * NEW: Find feature folder by name (exact match or fuzzy match)
+     *
+     * Examples:
+     *   release-management → release-management/
+     *   external-tool-sync → external-tool-status-sync/ (fuzzy match)
+     */
+    private findFeatureFolder;
+    /**
+     * LEGACY: Find FS-* epic folder (for backward compatibility)
+     */
+    private findEpicFolder;
+    /**
+     * Get all feature folders (NEW: no FS- prefix filtering)
+     */
+    getAllFeatureFolders(): Promise<string[]>;
+    /**
+     * LEGACY: Get all epic folders (for backward compatibility)
+     */
+    getAllEpicFolders(): Promise<string[]>;
+    /**
+     * Validate feature folder structure (NEW: checks for FEATURE.md)
+     */
+    validateFeatureFolder(featureFolder: string): Promise<{
+        valid: boolean;
+        missing: string[];
+    }>;
+    /**
+     * LEGACY: Validate epic folder structure (for backward compatibility)
+     */
+    validateEpicFolder(epicFolder: string): Promise<{
+        valid: boolean;
+        missing: string[];
+    }>;
+    /**
+     * Create feature folder structure if missing (NEW: creates FEATURE.md)
+     */
+    createFeatureFolderStructure(featureFolder: string, title: string): Promise<void>;
+    /**
+     * LEGACY: Create epic folder structure (for backward compatibility)
+     */
+    createEpicFolderStructure(epicFolder: string, title: string): Promise<void>;
+}
+//# sourceMappingURL=hierarchy-mapper.d.ts.map

package/dist/src/core/living-docs/hierarchy-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hierarchy-mapper.d.ts","sourceRoot":"","sources":["../../../../src/core/living-docs/hierarchy-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,QAAQ,GAAG,UAAU,GAAG,YAAY,GAAG,MAAM,CAAC;IACrD,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB,EAAE,QAAQ,CAAC;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,CAAC,aAAa,GAAG,gBAAgB,GAAG,QAAQ,CAAC,EAAE,CAAC;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,aAAa,GAAG,gBAAgB,GAAG,QAAQ,GAAG,UAAU,CAAC;CAC3E;AAGD,MAAM,MAAM,WAAW,GAAG,cAAc,CAAC;AAEzC;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,WAAW,CAAS;gBAEhB,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC;IAelE;;;;OAIG;IACG,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAkCxE;;OAEG;IACG,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAIlE;;;;;OAKG;YACW,qBAAqB;IAuCnC;;;;;;;;;OASG;YACW,uBAAuB;IA0CrC;;OAEG;YACW,gBAAgB;IA+B9B;;;;;;;;;OASG;YACW,qBAAqB;IAqCnC;;;OAGG;YACW,wBAAwB;IAoCtC;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAQvB;;;;;;OAMG;YACW,iBAAiB;IA8B/B;;OAEG;YACW,cAAc;IAI5B;;OAEG;IACG,oBAAoB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IA0B/C;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAI5C;;OAEG;IACG,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAiBlG;;OAEG;IACG,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAI5F;;OAEG;IACG,4BAA4B,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqEvF;;OAEG;IACG,yBAAyB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGlF"}