@skillsmith/core 0.5.4 → 0.5.6

package/dist/services/SubagentGenerator.d.ts

@@ -0,0 +1,77 @@
+/**
+ * SMI-1788: SubagentGenerator - Generate companion subagent definitions
+ *
+ * Creates subagent definitions for skills that benefit from parallel
+ * execution with context isolation. Subagents enable:
+ * - 37-97% token savings through context isolation
+ * - Parallel execution of heavy operations
+ * - Specialized tool access per agent
+ *
+ * Part of the Skillsmith Optimization Layer for transforming
+ * community skills into more performant versions.
+ */
+import type { SkillAnalysis } from './SkillAnalyzer.js';
+/**
+ * SMI-1795: Claude model constants for type safety and consistency
+ */
+export declare const CLAUDE_MODELS: {
+    readonly HAIKU: "haiku";
+    readonly SONNET: "sonnet";
+    readonly OPUS: "opus";
+};
+export type ClaudeModel = (typeof CLAUDE_MODELS)[keyof typeof CLAUDE_MODELS];
+/**
+ * Generated subagent definition
+ */
+export interface SubagentDefinition {
+    /** Subagent name (e.g., "jest-helper-specialist") */
+    name: string;
+    /** Description for the Task tool */
+    description: string;
+    /** Trigger phrases that should invoke this subagent */
+    triggerPhrases: string[];
+    /** Tools the subagent needs access to */
+    tools: string[];
+    /** Recommended model */
+    model: ClaudeModel;
+    /** The full markdown content for ~/.claude/agents/ */
+    content: string;
+}
+/**
+ * Result of subagent generation
+ */
+export interface SubagentGenerationResult {
+    /** Whether a subagent was generated */
+    generated: boolean;
+    /** The subagent definition (if generated) */
+    subagent?: SubagentDefinition;
+    /** Reason if not generated */
+    reason?: string;
+    /** CLAUDE.md integration snippet */
+    claudeMdSnippet?: string;
+}
+/**
+ * Generate a companion subagent for a skill
+ *
+ * @param skillName - The name of the skill
+ * @param description - The skill's description
+ * @param content - The full SKILL.md content
+ * @param analysis - Analysis from SkillAnalyzer
+ * @returns Subagent generation result
+ */
+export declare function generateSubagent(skillName: string, description: string, content: string, analysis: SkillAnalysis): SubagentGenerationResult;
+/**
+ * Generate a minimal subagent for skills that don't need full analysis
+ *
+ * @param skillName - The name of the skill
+ * @param description - The skill's description
+ * @param content - The full SKILL.md content
+ * @returns Subagent generation result
+ */
+export declare function generateMinimalSubagent(skillName: string, description: string, content: string): SubagentGenerationResult;
+declare const _default: {
+    generateSubagent: typeof generateSubagent;
+    generateMinimalSubagent: typeof generateMinimalSubagent;
+};
+export default _default;
+//# sourceMappingURL=SubagentGenerator.d.ts.map

package/dist/services/SubagentGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubagentGenerator.d.ts","sourceRoot":"","sources":["../../src/services/SubagentGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAqB,MAAM,oBAAoB,CAAA;AAE1E;;GAEG;AACH,eAAO,MAAM,aAAa;;;;CAIhB,CAAA;AAEV,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAA;AAE5E;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAA;IAEZ,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAA;IAEnB,uDAAuD;IACvD,cAAc,EAAE,MAAM,EAAE,CAAA;IAExB,yCAAyC;IACzC,KAAK,EAAE,MAAM,EAAE,CAAA;IAEf,wBAAwB;IACxB,KAAK,EAAE,WAAW,CAAA;IAElB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,uCAAuC;IACvC,SAAS,EAAE,OAAO,CAAA;IAElB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAE7B,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,oCAAoC;IACpC,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAoRD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,aAAa,GACtB,wBAAwB,CAmE1B;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,wBAAwB,CAkD1B;;;;;AAED,wBAA4D"}

package/dist/services/SubagentGenerator.js

@@ -0,0 +1,352 @@
+/**
+ * SMI-1788: SubagentGenerator - Generate companion subagent definitions
+ *
+ * Creates subagent definitions for skills that benefit from parallel
+ * execution with context isolation. Subagents enable:
+ * - 37-97% token savings through context isolation
+ * - Parallel execution of heavy operations
+ * - Specialized tool access per agent
+ *
+ * Part of the Skillsmith Optimization Layer for transforming
+ * community skills into more performant versions.
+ */
+/**
+ * SMI-1795: Claude model constants for type safety and consistency
+ */
+export const CLAUDE_MODELS = {
+    HAIKU: 'haiku',
+    SONNET: 'sonnet',
+    OPUS: 'opus',
+};
+/**
+ * Tool detection patterns for analyzing skill content
+ */
+const TOOL_PATTERNS = {
+    Read: {
+        patterns: ['read file', 'read the', 'examine', 'view file', 'Read tool', 'check file'],
+        priority: 1,
+    },
+    Write: {
+        patterns: ['write file', 'create file', 'save to', 'output to', 'Write tool', 'generate file'],
+        priority: 2,
+    },
+    Edit: {
+        patterns: [
+            'edit file',
+            'modify',
+            'update file',
+            'patch',
+            'Edit tool',
+            'change file',
+            'refactor',
+        ],
+        priority: 2,
+    },
+    Bash: {
+        patterns: [
+            'bash',
+            'npm',
+            'npx',
+            'git',
+            'docker',
+            'yarn',
+            'pnpm',
+            'terminal',
+            'shell',
+            'command',
+        ],
+        priority: 3,
+    },
+    Grep: {
+        patterns: ['grep', 'search for', 'find text', 'pattern match', 'Grep tool', 'search in'],
+        priority: 1,
+    },
+    Glob: {
+        patterns: ['glob', 'find file', 'file pattern', 'list files', 'Glob tool', 'locate'],
+        priority: 1,
+    },
+    WebFetch: {
+        patterns: ['fetch', 'http', 'api call', 'url', 'WebFetch', 'download', 'request'],
+        priority: 2,
+    },
+    WebSearch: {
+        patterns: ['web search', 'search online', 'lookup online', 'WebSearch', 'search the web'],
+        priority: 2,
+    },
+};
+/**
+ * Minimum tools that most subagents need
+ */
+const BASE_TOOLS = ['Read'];
+/**
+ * SMI-1819: Maximum length for subagent names to prevent overly long identifiers
+ */
+const MAX_SUBAGENT_NAME_LENGTH = 100;
+/**
+ * Generate tool usage guidelines for a subagent
+ */
+function generateToolGuidelines(tools) {
+    const guidelines = [];
+    if (tools.includes('Read')) {
+        guidelines.push('- **Read**: Use to examine files before modifications');
+    }
+    if (tools.includes('Write')) {
+        guidelines.push('- **Write**: Use for creating new files only');
+    }
+    if (tools.includes('Edit')) {
+        guidelines.push('- **Edit**: Use for modifying existing files');
+    }
+    if (tools.includes('Bash')) {
+        guidelines.push('- **Bash**: Use for command execution, prefer non-destructive commands');
+    }
+    if (tools.includes('Grep')) {
+        guidelines.push('- **Grep**: Use for searching file contents');
+    }
+    if (tools.includes('Glob')) {
+        guidelines.push('- **Glob**: Use for finding files by pattern');
+    }
+    if (tools.includes('WebFetch')) {
+        guidelines.push('- **WebFetch**: Use for fetching web content');
+    }
+    if (tools.includes('WebSearch')) {
+        guidelines.push('- **WebSearch**: Use for searching the web');
+    }
+    return guidelines.length > 0 ? guidelines.join('\n') : '- Use tools minimally and efficiently';
+}
+/**
+ * Generate subagent markdown content
+ */
+function generateSubagentContent(name, description, triggerPhrases, tools, model) {
+    const triggerString = triggerPhrases.length > 0
+        ? triggerPhrases.map((p) => `"${p}"`).join(', ')
+        : '[describe trigger conditions]';
+    const toolGuidelines = generateToolGuidelines(tools);
+    return `---
+name: ${name}
+description: ${description} Use when ${triggerString}.
+skills: ${name.replace('-specialist', '')}
+tools: ${tools.join(', ')}
+model: ${model}
+---
+
+## Operating Protocol
+
+1. Execute the ${name.replace('-specialist', '')} skill for the delegated task
+2. Process all intermediate results internally
+3. Return ONLY a structured summary to the orchestrator
+
+## Output Format
+
+- **Task:** [what was requested]
+- **Actions:** [what you did]
+- **Results:** [key outcomes, max 3-5 bullet points]
+- **Artifacts:** [file paths or outputs created]
+
+Keep response under 500 tokens unless explicitly requested otherwise.
+
+## Tool Usage Guidelines
+
+${toolGuidelines}
+
+## Error Handling
+
+If the task cannot be completed:
+- Report specific blocking issue
+- Suggest alternative approaches
+- Do not retry indefinitely
+
+---
+
+*Generated by Skillsmith Optimization Layer*
+`;
+}
+/**
+ * Generate CLAUDE.md integration snippet
+ */
+function generateClaudeMdSnippet(skillName, description, triggerPhrases, tools, model) {
+    const triggerPatterns = triggerPhrases.length > 0
+        ? triggerPhrases.map((p) => `- "${p}"`).join('\n')
+        : '- [add trigger patterns]';
+    const exampleTask = triggerPhrases.length > 0 ? triggerPhrases[0] : `execute ${skillName} task`;
+    return `
+### Subagent Delegation: ${skillName}
+
+When tasks match ${skillName} triggers, delegate to the ${skillName}-specialist
+subagent instead of executing directly. This provides context isolation and
+~37-97% token savings.
+
+**Trigger Patterns:**
+${triggerPatterns}
+
+**Delegation Example:**
+\`\`\`
+Task("${skillName}-specialist", "${exampleTask}", "${skillName}-specialist")
+\`\`\`
+
+**Model:** ${model}
+**Tools:** ${tools.join(', ')}
+`;
+}
+/**
+ * Extract trigger phrases from skill description and content
+ */
+function extractTriggerPhrases(description, content) {
+    const phrases = [];
+    // Common trigger phrase patterns
+    const patterns = [
+        /when\s+(?:you\s+)?(?:need\s+to\s+)?(.+?)(?:[.,]|$)/gi,
+        /use\s+(?:this\s+)?(?:when|for)\s+(.+?)(?:[.,]|$)/gi,
+        /(?:helps?\s+(?:you\s+)?(?:to\s+)?)?(.+?)(?:\s+tasks?|\s+operations?)/gi,
+    ];
+    const textToSearch = description + ' ' + content.slice(0, 2000); // Search first 2000 chars
+    for (const pattern of patterns) {
+        for (const match of textToSearch.matchAll(pattern)) {
+            const phrase = match[1].trim().toLowerCase();
+            if (phrase.length >= 5 && phrase.length <= 50 && !phrases.includes(phrase)) {
+                phrases.push(phrase);
+            }
+        }
+    }
+    // Extract from "trigger" or "invoke" mentions
+    const triggerMatch = content.match(/trigger[s]?\s*[:=]\s*["`']([^"`']+)["`']/gi);
+    if (triggerMatch) {
+        for (const match of triggerMatch) {
+            const phrase = match.replace(/trigger[s]?\s*[:=]\s*["`']/i, '').replace(/["`']$/, '');
+            if (!phrases.includes(phrase.toLowerCase())) {
+                phrases.push(phrase.toLowerCase());
+            }
+        }
+    }
+    return phrases.slice(0, 5); // Limit to 5 phrases
+}
+/**
+ * Determine optimal model for subagent
+ * SMI-1795: Uses CLAUDE_MODELS constants for type safety
+ */
+function determineModel(toolUsage, lineCount) {
+    // Haiku for simple, fast operations
+    if (toolUsage.detectedTools.length <= 2 && lineCount < 200) {
+        return CLAUDE_MODELS.HAIKU;
+    }
+    // Opus for complex, reasoning-heavy tasks
+    if (toolUsage.bashCommandCount > 5 ||
+        (toolUsage.fileReadCount > 3 && toolUsage.fileWriteCount > 3)) {
+        return CLAUDE_MODELS.OPUS;
+    }
+    // Sonnet for balanced workloads (default)
+    return CLAUDE_MODELS.SONNET;
+}
+/**
+ * Detect tools needed from skill content
+ */
+function detectTools(content) {
+    const lowerContent = content.toLowerCase();
+    const detectedTools = new Set(BASE_TOOLS);
+    for (const [tool, config] of Object.entries(TOOL_PATTERNS)) {
+        for (const pattern of config.patterns) {
+            if (lowerContent.includes(pattern.toLowerCase())) {
+                detectedTools.add(tool);
+                break;
+            }
+        }
+    }
+    return Array.from(detectedTools);
+}
+/**
+ * Generate a companion subagent for a skill
+ *
+ * @param skillName - The name of the skill
+ * @param description - The skill's description
+ * @param content - The full SKILL.md content
+ * @param analysis - Analysis from SkillAnalyzer
+ * @returns Subagent generation result
+ */
+export function generateSubagent(skillName, description, content, analysis) {
+    // SMI-1815: Validate skill name is non-empty
+    if (!skillName || skillName.trim() === '') {
+        return {
+            generated: false,
+            reason: 'Skill name is required for subagent generation',
+        };
+    }
+    // Check if subagent is recommended
+    if (!analysis.toolUsage.suggestsSubagent && analysis.lineCount < 300) {
+        return {
+            generated: false,
+            reason: 'Skill does not have heavy tool usage or complexity that would benefit from a subagent',
+        };
+    }
+    // Detect tools from content (supplement analysis)
+    const detectedTools = detectTools(content);
+    const allTools = Array.from(new Set([...analysis.toolUsage.detectedTools, ...detectedTools]));
+    // Extract trigger phrases
+    const triggerPhrases = extractTriggerPhrases(description, content);
+    // Determine model
+    const model = determineModel(analysis.toolUsage, analysis.lineCount);
+    // SMI-1819: Generate subagent name with length limit
+    const suffix = '-specialist';
+    const maxBaseLength = MAX_SUBAGENT_NAME_LENGTH - suffix.length;
+    const baseName = skillName.length > maxBaseLength ? skillName.slice(0, maxBaseLength) : skillName;
+    const subagentName = `${baseName}${suffix}`;
+    // Generate subagent description
+    const subagentDescription = description || `Specialist agent for ${skillName} operations`;
+    // Generate content
+    const subagentContent = generateSubagentContent(subagentName, subagentDescription, triggerPhrases, allTools, model);
+    // Generate CLAUDE.md snippet
+    const claudeMdSnippet = generateClaudeMdSnippet(skillName, subagentDescription, triggerPhrases, allTools, model);
+    return {
+        generated: true,
+        subagent: {
+            name: subagentName,
+            description: subagentDescription,
+            triggerPhrases,
+            tools: allTools,
+            model,
+            content: subagentContent,
+        },
+        claudeMdSnippet,
+    };
+}
+/**
+ * Generate a minimal subagent for skills that don't need full analysis
+ *
+ * @param skillName - The name of the skill
+ * @param description - The skill's description
+ * @param content - The full SKILL.md content
+ * @returns Subagent generation result
+ */
+export function generateMinimalSubagent(skillName, description, content) {
+    // SMI-1815: Validate skill name is non-empty
+    if (!skillName || skillName.trim() === '') {
+        return {
+            generated: false,
+            reason: 'Skill name is required for subagent generation',
+        };
+    }
+    const detectedTools = detectTools(content);
+    const triggerPhrases = extractTriggerPhrases(description, content);
+    // Default to sonnet for minimal subagents
+    const model = CLAUDE_MODELS.SONNET;
+    // SMI-1819: Generate subagent name with length limit
+    const suffix = '-specialist';
+    const maxBaseLength = MAX_SUBAGENT_NAME_LENGTH - suffix.length;
+    const baseName = skillName.length > maxBaseLength ? skillName.slice(0, maxBaseLength) : skillName;
+    const subagentName = `${baseName}${suffix}`;
+    const subagentDescription = description || `Specialist agent for ${skillName} operations`;
+    const subagentContent = generateSubagentContent(subagentName, subagentDescription, triggerPhrases, detectedTools, model);
+    const claudeMdSnippet = generateClaudeMdSnippet(skillName, subagentDescription, triggerPhrases, detectedTools, model);
+    return {
+        generated: true,
+        subagent: {
+            name: subagentName,
+            description: subagentDescription,
+            triggerPhrases,
+            tools: detectedTools,
+            model,
+            content: subagentContent,
+        },
+        claudeMdSnippet,
+    };
+}
+export default { generateSubagent, generateMinimalSubagent };
+//# sourceMappingURL=SubagentGenerator.js.map

package/dist/services/SubagentGenerator.js.map

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

package/dist/services/TaskRunner.d.ts

@@ -0,0 +1,151 @@
+/**
+ * SMI-1662: TaskRunner - Background Task Timeout Management
+ * @see SMI-2741: Types split to TaskRunner.types.ts, process utils to TaskRunner.process.ts
+ *
+ * Provides configurable timeout enforcement for background Task agents.
+ * Addresses orphaned process memory leaks identified in incident 2026-01-22.
+ *
+ * Features:
+ * - Configurable timeout via TASK_TIMEOUT_MS environment variable
+ * - Default timeout: 10 minutes (600000ms)
+ * - Warning at 80% of timeout limit
+ * - Graceful shutdown: SIGTERM -> wait 5s -> SIGKILL
+ * - Task registry for tracking running background tasks
+ *
+ * @example
+ * ```typescript
+ * const runner = new TaskRunner({ timeoutMs: 300000 }) // 5 minute timeout
+ * const taskId = runner.register(childProcess.pid, 'SMI-1660 implementation')
+ *
+ * // When task completes
+ * runner.complete(taskId)
+ *
+ * // Cleanup orphaned tasks
+ * await runner.cleanupOrphaned()
+ * ```
+ */
+import { type TaskRunnerConfig, type TaskStatus, type TrackedTask, type CleanupResult } from './TaskRunner.types.js';
+export type { TaskRunnerConfig, TaskStatus, TrackedTask, CleanupResult, } from './TaskRunner.types.js';
+export { DEFAULT_TASK_TIMEOUT_MS, SIGKILL_GRACE_PERIOD_MS, WARNING_THRESHOLD_RATIO, } from './TaskRunner.types.js';
+export { gracefulShutdown, killProcess, sleep } from './TaskRunner.process.js';
+/**
+ * TaskRunner manages background task lifecycles with timeout enforcement.
+ *
+ * Solves the orphaned process problem by:
+ * 1. Tracking all background tasks in a registry
+ * 2. Enforcing configurable timeouts
+ * 3. Graceful shutdown with SIGTERM -> SIGKILL escalation
+ * 4. Logging all timeout events for debugging
+ */
+export declare class TaskRunner {
+    private readonly config;
+    private readonly logger;
+    private readonly tasks;
+    private readonly timers;
+    private readonly warningTimers;
+    private readonly onTimeout?;
+    private readonly onWarning?;
+    constructor(config?: TaskRunnerConfig);
+    /**
+     * Register a new background task for monitoring
+     *
+     * @param pid - Process ID of the background task
+     * @param description - Human-readable description
+     * @returns Task ID for tracking
+     */
+    register(pid: number, description: string): string;
+    /**
+     * Mark a task as completed successfully
+     *
+     * @param taskId - Task ID to complete
+     */
+    complete(taskId: string): void;
+    /**
+     * Mark a task as failed
+     *
+     * @param taskId - Task ID that failed
+     * @param error - Error message or Error object
+     */
+    fail(taskId: string, error: string | Error): void;
+    /**
+     * Get a tracked task by ID
+     *
+     * @param taskId - Task ID to retrieve
+     * @returns The tracked task or undefined
+     */
+    getTask(taskId: string): TrackedTask | undefined;
+    /**
+     * Get all tasks with a specific status
+     *
+     * @param status - Status to filter by (optional, returns all if not specified)
+     * @returns Array of matching tasks
+     */
+    getTasks(status?: TaskStatus): TrackedTask[];
+    /**
+     * Get statistics about tracked tasks
+     */
+    getStats(): {
+        total: number;
+        running: number;
+        completed: number;
+        failed: number;
+        timeout: number;
+        killed: number;
+    };
+    /**
+     * Clean up completed/failed/timeout tasks older than specified age
+     *
+     * @param maxAgeMs - Maximum age in milliseconds (default: 1 hour)
+     * @returns Number of tasks cleaned up
+     */
+    cleanup(maxAgeMs?: number): number;
+    /**
+     * Clean up all orphaned running tasks that have exceeded timeout
+     * This can be called externally to force cleanup
+     *
+     * @returns Cleanup result with details
+     */
+    cleanupOrphaned(): Promise<CleanupResult>;
+    /**
+     * Dispose of the TaskRunner and clean up all timers
+     */
+    dispose(): void;
+    /**
+     * Get the configured timeout in milliseconds
+     */
+    getTimeoutMs(): number;
+    /**
+     * Issue a warning that task is approaching timeout
+     */
+    private issueWarning;
+    /**
+     * Handle a task timeout
+     */
+    private handleTimeout;
+    /**
+     * Finish a task and clean up timers
+     */
+    private finishTask;
+}
+/**
+ * Create a TaskRunner with environment-based configuration
+ *
+ * Environment variables:
+ * - TASK_TIMEOUT_MS: Timeout in milliseconds (default: 600000)
+ * - DEBUG: Enable debug logging (default: false)
+ */
+export declare function createTaskRunner(config?: TaskRunnerConfig): TaskRunner;
+/**
+ * Get or create the global TaskRunner instance
+ */
+export declare function getGlobalTaskRunner(): TaskRunner;
+/**
+ * Set a custom global TaskRunner instance
+ */
+export declare function setGlobalTaskRunner(runner: TaskRunner): void;
+/**
+ * Dispose of the global TaskRunner instance
+ */
+export declare function disposeGlobalTaskRunner(): void;
+export default TaskRunner;
+//# sourceMappingURL=TaskRunner.d.ts.map

package/dist/services/TaskRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskRunner.d.ts","sourceRoot":"","sources":["../../src/services/TaskRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,aAAa,EACnB,MAAM,uBAAuB,CAAA;AAI9B,YAAY,EACV,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,aAAa,GACd,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAA;AAE9E;;;;;;;;GAQG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwE;IAC/F,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsC;IAC5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAChE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAyC;IACvE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAA6B;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAkD;gBAEjE,MAAM,GAAE,gBAAqB;IAqBzC;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM;IAwClD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI9B;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAQjD;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAIhD;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,WAAW,EAAE;IAK5C;;OAEG;IACH,QAAQ,IAAI;QACV,KAAK,EAAE,MAAM,CAAA;QACb,OAAO,EAAE,MAAM,CAAA;QACf,SAAS,EAAE,MAAM,CAAA;QACjB,MAAM,EAAE,MAAM,CAAA;QACd,OAAO,EAAE,MAAM,CAAA;QACf,MAAM,EAAE,MAAM,CAAA;KACf;IAYD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,GAAE,MAAgB,GAAG,MAAM;IAkB3C;;;;;OAKG;IACG,eAAe,IAAI,OAAO,CAAC,aAAa,CAAC;IAmC/C;;OAEG;IACH,OAAO,IAAI,IAAI;IAiBf;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,OAAO,CAAC,YAAY;IAqBpB;;OAEG;YACW,aAAa;IAgC3B;;OAEG;IACH,OAAO,CAAC,UAAU;CAiCnB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,UAAU,CAEtE;AAOD;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,UAAU,CAKhD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAE5D;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAK9C;AAED,eAAe,UAAU,CAAA"}