@planu/cli 0.43.1 → 0.45.0

package/dist/engine/hooks/config-loader.js

@@ -0,0 +1,142 @@
+// engine/hooks/config-loader.ts — Load & validate hook config with live reload (SPEC-129)
+import { watch as fsWatch } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Default config (matches hook-defaults.json)
+// ---------------------------------------------------------------------------
+import hookDefaults from '../../config/hook-defaults.json' with { type: 'json' };
+// ---------------------------------------------------------------------------
+// Zod schemas
+// ---------------------------------------------------------------------------
+const hookTypeConfigSchema = z.object({
+    enabled: z.boolean().default(true),
+    include: z.array(z.string()).optional(),
+    exclude: z.array(z.string()).optional(),
+});
+const fileHookConfigSchema = z.object({
+    enabled: z.boolean().default(true),
+    debounceMs: z.number().min(50).max(10_000).default(300),
+    rateLimitPerFileMs: z.number().min(1000).max(60_000).default(5000),
+    hooks: z.record(z.string(), hookTypeConfigSchema).default({}),
+});
+// ---------------------------------------------------------------------------
+// Config file paths
+// ---------------------------------------------------------------------------
+const HOOKS_JSON = '.planu/hooks.json';
+const PLANU_JSON = 'planu.json';
+// ---------------------------------------------------------------------------
+// ConfigLoader
+// ---------------------------------------------------------------------------
+export class ConfigLoader {
+    config;
+    projectRoot;
+    watcher = null;
+    changeCallbacks = [];
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+        this.config = hookDefaults;
+    }
+    /**
+     * Load config from `.planu/hooks.json` or `planu.json`.
+     * Falls back to defaults if file missing or invalid.
+     */
+    async load() {
+        // Try .planu/hooks.json first
+        let raw = await this.readJsonFile(join(this.projectRoot, HOOKS_JSON));
+        // Try planu.json -> hooks key
+        if (!raw) {
+            const planuJson = await this.readJsonFile(join(this.projectRoot, PLANU_JSON));
+            if (planuJson &&
+                typeof planuJson === 'object' &&
+                'hooks' in planuJson) {
+                raw = planuJson.hooks;
+            }
+        }
+        if (raw) {
+            const parsed = fileHookConfigSchema.safeParse(raw);
+            if (parsed.success) {
+                this.config = parsed.data;
+            }
+            else {
+                const messages = parsed.error.issues.map((i) => i.message).join(', ');
+                console.warn(`[hooks] Invalid hook config, using defaults: ${messages}`);
+                this.config = hookDefaults;
+            }
+        }
+        else {
+            this.config = hookDefaults;
+        }
+        return this.config;
+    }
+    /**
+     * Get current config (synchronous, must call load() first).
+     */
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Get config for a specific hook type.
+     */
+    getHookConfig(hookType) {
+        return this.config.hooks[hookType];
+    }
+    /**
+     * Start watching config files for live reload.
+     */
+    startWatching() {
+        const hooksJsonPath = join(this.projectRoot, HOOKS_JSON);
+        try {
+            this.watcher = fsWatch(hooksJsonPath, () => {
+                void this.reloadConfig();
+            });
+            this.watcher.on('error', () => {
+                // Ignore watch errors — config just won't live-reload
+            });
+        }
+        catch {
+            // File doesn't exist yet — that's fine
+        }
+    }
+    /**
+     * Register a callback for config changes.
+     */
+    onChange(callback) {
+        this.changeCallbacks.push(callback);
+    }
+    /**
+     * Stop watching and clean up.
+     */
+    close() {
+        if (this.watcher) {
+            this.watcher.close();
+            this.watcher = null;
+        }
+        this.changeCallbacks = [];
+    }
+    // ---------------------------------------------------------------------------
+    // Private
+    // ---------------------------------------------------------------------------
+    async reloadConfig() {
+        try {
+            await this.load();
+            for (const cb of this.changeCallbacks) {
+                cb(this.config);
+            }
+        }
+        catch {
+            // Ignore reload errors — keep previous config
+        }
+    }
+    async readJsonFile(filePath) {
+        try {
+            const data = await readFile(filePath, 'utf-8');
+            return JSON.parse(data);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=config-loader.js.map

package/dist/engine/hooks/config-loader.js.map

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

package/dist/engine/hooks/debouncer.d.ts

@@ -0,0 +1,30 @@
+import type { WatcherEvent, DebouncerConfig, DebouncedCallback } from '../../types/file-hooks.js';
+export declare class Debouncer {
+    private readonly config;
+    /** Pending debounce timers per file path */
+    private readonly pendingTimers;
+    /** Pending event per file (latest wins) */
+    private readonly pendingEvents;
+    /** Rate limit buckets per file path */
+    private readonly fileBuckets;
+    /** Rate limit buckets per spec ID */
+    private readonly specBuckets;
+    private readonly callback;
+    constructor(callback: DebouncedCallback, config?: Partial<DebouncerConfig>);
+    /**
+     * Feed a raw watcher event. The debouncer will coalesce rapid events
+     * and apply rate limiting before invoking the callback.
+     */
+    push(event: WatcherEvent): void;
+    /**
+     * Check spec-level rate limit for auto-reconcile.
+     * Returns true if allowed, false if rate-limited.
+     */
+    checkSpecRateLimit(specId: string): boolean;
+    /**
+     * Cancel all pending timers and clear state.
+     */
+    dispose(): void;
+    private tryEmit;
+}
+//# sourceMappingURL=debouncer.d.ts.map

package/dist/engine/hooks/debouncer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debouncer.d.ts","sourceRoot":"","sources":["../../../src/engine/hooks/debouncer.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,YAAY,EAEZ,eAAe,EACf,iBAAiB,EAClB,MAAM,2BAA2B,CAAC;AA4CnC,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,4CAA4C;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoD;IAClF,2CAA2C;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmC;IACjE,uCAAuC;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkC;IAC9D,qCAAqC;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkC;IAC9D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;gBAEjC,QAAQ,EAAE,iBAAiB,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC;IAK1E;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAyB/B;;;OAGG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAU3C;;OAEG;IACH,OAAO,IAAI,IAAI;IAcf,OAAO,CAAC,OAAO;CAkBhB"}

package/dist/engine/hooks/debouncer.js

@@ -0,0 +1,124 @@
+// engine/hooks/debouncer.ts — Debounce + rate limit for file events (SPEC-129)
+// 300ms debounce per file, global rate limit per file per 5s,
+// per-spec rate limit per 5 min. Token bucket algorithm.
+// ---------------------------------------------------------------------------
+// Token Bucket helpers
+// ---------------------------------------------------------------------------
+function createBucket(capacity, refillIntervalMs) {
+    return {
+        tokens: capacity,
+        lastRefill: Date.now(),
+        capacity,
+        refillIntervalMs,
+    };
+}
+function tryConsume(bucket, now) {
+    // Refill tokens based on elapsed time
+    const elapsed = now - bucket.lastRefill;
+    const tokensToAdd = Math.floor(elapsed / bucket.refillIntervalMs);
+    if (tokensToAdd > 0) {
+        const updated = {
+            ...bucket,
+            tokens: Math.min(bucket.capacity, bucket.tokens + tokensToAdd),
+            lastRefill: now,
+        };
+        Object.assign(bucket, updated);
+    }
+    if (bucket.tokens > 0) {
+        Object.assign(bucket, { tokens: bucket.tokens - 1 });
+        return true;
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Debouncer
+// ---------------------------------------------------------------------------
+const DEFAULT_CONFIG = {
+    debounceMs: 300,
+    rateLimitPerFileMs: 5000,
+    rateLimitPerSpecMs: 300_000,
+};
+export class Debouncer {
+    config;
+    /** Pending debounce timers per file path */
+    pendingTimers = new Map();
+    /** Pending event per file (latest wins) */
+    pendingEvents = new Map();
+    /** Rate limit buckets per file path */
+    fileBuckets = new Map();
+    /** Rate limit buckets per spec ID */
+    specBuckets = new Map();
+    callback;
+    constructor(callback, config) {
+        this.callback = callback;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Feed a raw watcher event. The debouncer will coalesce rapid events
+     * and apply rate limiting before invoking the callback.
+     */
+    push(event) {
+        const key = event.path;
+        // Store the latest event (coalescing — last wins)
+        this.pendingEvents.set(key, event);
+        // Clear existing timer for this path
+        const existing = this.pendingTimers.get(key);
+        if (existing !== undefined) {
+            clearTimeout(existing);
+        }
+        // Set new debounce timer
+        const timer = setTimeout(() => {
+            this.pendingTimers.delete(key);
+            const latest = this.pendingEvents.get(key);
+            this.pendingEvents.delete(key);
+            if (latest) {
+                this.tryEmit(latest);
+            }
+        }, this.config.debounceMs);
+        this.pendingTimers.set(key, timer);
+    }
+    /**
+     * Check spec-level rate limit for auto-reconcile.
+     * Returns true if allowed, false if rate-limited.
+     */
+    checkSpecRateLimit(specId) {
+        const now = Date.now();
+        let bucket = this.specBuckets.get(specId);
+        if (!bucket) {
+            bucket = createBucket(1, this.config.rateLimitPerSpecMs);
+            this.specBuckets.set(specId, bucket);
+        }
+        return tryConsume(bucket, now);
+    }
+    /**
+     * Cancel all pending timers and clear state.
+     */
+    dispose() {
+        for (const timer of this.pendingTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.pendingTimers.clear();
+        this.pendingEvents.clear();
+        this.fileBuckets.clear();
+        this.specBuckets.clear();
+    }
+    // ---------------------------------------------------------------------------
+    // Private
+    // ---------------------------------------------------------------------------
+    tryEmit(event) {
+        const now = Date.now();
+        const key = event.path;
+        // File-level rate limit
+        let bucket = this.fileBuckets.get(key);
+        if (!bucket) {
+            bucket = createBucket(1, this.config.rateLimitPerFileMs);
+            this.fileBuckets.set(key, bucket);
+        }
+        if (!tryConsume(bucket, now)) {
+            // Rate limited — drop the event
+            return;
+        }
+        this.callback(event);
+    }
+}
+//# sourceMappingURL=debouncer.js.map

package/dist/engine/hooks/debouncer.js.map

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

package/dist/engine/hooks/event-bus.d.ts

@@ -0,0 +1,40 @@
+import { EventEmitter } from 'node:events';
+import type { EventBusEvent } from '../../types/file-hooks.js';
+/**
+ * Typed event bus extending EventEmitter.
+ * Provides typed events with discriminated unions, filtering,
+ * event history (FIFO, last 100), and meta-events.
+ */
+export declare class EventBus extends EventEmitter {
+    private readonly history;
+    private idCounter;
+    constructor();
+    /**
+     * Emit a typed event. Automatically adds to history and fires meta-events.
+     */
+    emitEvent(type: EventBusEvent['type'], data: Record<string, unknown>): EventBusEvent;
+    /**
+     * Subscribe to events of a specific type.
+     */
+    onEvent(type: EventBusEvent['type'] | '*', listener: (event: EventBusEvent) => void): this;
+    /**
+     * Subscribe to events once.
+     */
+    onceEvent(type: EventBusEvent['type'] | '*', listener: (event: EventBusEvent) => void): this;
+    /**
+     * Get filtered event history.
+     */
+    getHistory(filter?: {
+        type?: EventBusEvent['type'];
+        filePattern?: string;
+    }): EventBusEvent[];
+    /**
+     * Get all events in history (readonly).
+     */
+    getFullHistory(): readonly EventBusEvent[];
+    /**
+     * Clear history.
+     */
+    clearHistory(): void;
+}
+//# sourceMappingURL=event-bus.d.ts.map

package/dist/engine/hooks/event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../../src/engine/hooks/event-bus.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAY/D;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,YAAY;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,SAAS,CAAK;;IAOtB;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAoBpF;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,GAAG,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI;IAI1F;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,GAAG,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI;IAI5F;;OAEG;IACH,UAAU,CAAC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,aAAa,EAAE;IAkB5F;;OAEG;IACH,cAAc,IAAI,SAAS,aAAa,EAAE;IAI1C;;OAEG;IACH,YAAY,IAAI,IAAI;CAGrB"}

package/dist/engine/hooks/event-bus.js

@@ -0,0 +1,83 @@
+// engine/hooks/event-bus.ts — Typed event bus with history (SPEC-130)
+import { EventEmitter } from 'node:events';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const MAX_HISTORY = 100;
+// ---------------------------------------------------------------------------
+// EventBus
+// ---------------------------------------------------------------------------
+/**
+ * Typed event bus extending EventEmitter.
+ * Provides typed events with discriminated unions, filtering,
+ * event history (FIFO, last 100), and meta-events.
+ */
+export class EventBus extends EventEmitter {
+    history = [];
+    idCounter = 0;
+    constructor() {
+        super();
+        this.setMaxListeners(50);
+    }
+    /**
+     * Emit a typed event. Automatically adds to history and fires meta-events.
+     */
+    emitEvent(type, data) {
+        const event = {
+            id: `evt-${String(++this.idCounter)}-${Date.now()}`,
+            type,
+            timestamp: Date.now(),
+            data,
+        };
+        // FIFO eviction
+        if (this.history.length >= MAX_HISTORY) {
+            this.history.shift();
+        }
+        this.history.push(event);
+        this.emit(type, event);
+        this.emit('*', event);
+        return event;
+    }
+    /**
+     * Subscribe to events of a specific type.
+     */
+    onEvent(type, listener) {
+        return this.on(type, listener);
+    }
+    /**
+     * Subscribe to events once.
+     */
+    onceEvent(type, listener) {
+        return this.once(type, listener);
+    }
+    /**
+     * Get filtered event history.
+     */
+    getHistory(filter) {
+        let result = [...this.history];
+        if (filter?.type) {
+            result = result.filter((e) => e.type === filter.type);
+        }
+        if (filter?.filePattern) {
+            const regex = new RegExp(filter.filePattern);
+            result = result.filter((e) => {
+                const path = e.data.path;
+                return typeof path === 'string' && regex.test(path);
+            });
+        }
+        return result;
+    }
+    /**
+     * Get all events in history (readonly).
+     */
+    getFullHistory() {
+        return this.history;
+    }
+    /**
+     * Clear history.
+     */
+    clearHistory() {
+        this.history.length = 0;
+    }
+}
+//# sourceMappingURL=event-bus.js.map

package/dist/engine/hooks/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../../src/engine/hooks/event-bus.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,MAAM,WAAW,GAAG,GAAG,CAAC;AAExB,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,OAAO,QAAS,SAAQ,YAAY;IACvB,OAAO,GAAoB,EAAE,CAAC;IACvC,SAAS,GAAG,CAAC,CAAC;IAEtB;QACE,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,IAA2B,EAAE,IAA6B;QAClE,MAAM,KAAK,GAAkB;YAC3B,EAAE,EAAE,OAAO,MAAM,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE;YACnD,IAAI;YACJ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,IAAI;SACL,CAAC;QAEF,gBAAgB;QAChB,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,WAAW,EAAE,CAAC;YACvC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAEzB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAEtB,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,IAAiC,EAAE,QAAwC;QACjF,OAAO,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,IAAiC,EAAE,QAAwC;QACnF,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,MAA+D;QACxE,IAAI,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;QAE/B,IAAI,MAAM,EAAE,IAAI,EAAE,CAAC;YACjB,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC;QACxD,CAAC;QAED,IAAI,MAAM,EAAE,WAAW,EAAE,CAAC;YACxB,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YAC7C,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;gBAC3B,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;gBACzB,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACtD,CAAC,CAAC,CAAC;QACL,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,YAAY;QACV,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IAC1B,CAAC;CACF"}

package/dist/engine/hooks/file-watcher.d.ts

@@ -0,0 +1,48 @@
+import { EventEmitter } from 'node:events';
+import type { FileWatcherOptions } from '../../types/file-hooks.js';
+/**
+ * Convert a glob pattern to a RegExp. Supports:
+ * - `**` matches any path segment (including nested)
+ * - `*` matches any characters except path separator
+ * - `?` matches a single character
+ */
+export declare function globToRegex(pattern: string): RegExp;
+/**
+ * Test whether `filePath` matches a glob pattern.
+ */
+export declare function matchesGlobPattern(filePath: string, pattern: string): boolean;
+/**
+ * Returns true if filePath matches any include pattern
+ * and does not match any exclude pattern.
+ */
+export declare function matchesPatterns(filePath: string, include?: string[], exclude?: string[]): boolean;
+export declare class FileWatcher extends EventEmitter {
+    private watcher;
+    private readonly rootDir;
+    private readonly include;
+    private readonly exclude;
+    /** Track known files to distinguish create vs modify */
+    private readonly knownFiles;
+    private closed;
+    constructor(options: FileWatcherOptions);
+    /**
+     * Start watching. Emits 'change' events with WatcherEvent payloads.
+     * Emits 'error' on watch failure — never throws.
+     */
+    start(): void;
+    /**
+     * Mark a file as known (pre-existing). Call this for initial file scan.
+     */
+    addKnownFile(relPath: string): void;
+    /**
+     * Mark multiple files as known.
+     */
+    addKnownFiles(paths: string[]): void;
+    /**
+     * Graceful shutdown: release all handles.
+     */
+    close(): void;
+    private handleFsEvent;
+    private determineEventType;
+}
+//# sourceMappingURL=file-watcher.d.ts.map

package/dist/engine/hooks/file-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-watcher.d.ts","sourceRoot":"","sources":["../../../src/engine/hooks/file-watcher.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C,OAAO,KAAK,EAAkC,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAMpG;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA6BnD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAG7E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAYjG;AAYD,qBAAa,WAAY,SAAQ,YAAY;IAC3C,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IACnC,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,EAAE,kBAAkB;IAOvC;;;OAGG;IACH,KAAK,IAAI,IAAI;IAqBb;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAInC;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAMpC;;OAEG;IACH,KAAK,IAAI,IAAI;YAaC,aAAa;YA4Bb,kBAAkB;CAoBjC"}