@timetotest/cli 0.2.4 → 0.3.1

package/dist/src/lib/local-tools/code/run-command.js

@@ -0,0 +1,235 @@
+/**
+ * run_command tool - Execute shell commands with safety constraints.
+ * Supports timeout enforcement, working directory validation, and user permission prompts.
+ *
+ * Security (TR-5):
+ * - Working directory constrained to project root
+ * - Timeout enforced (default 30s)
+ * - No shell expansion (uses spawn, not exec)
+ * - User must approve command execution via permission prompt
+ */
+import { spawn } from "child_process";
+import * as path from "path";
+// Default timeout in milliseconds (30 seconds as per design)
+const DEFAULT_TIMEOUT_MS = 30000;
+// Maximum output size to capture (1MB per stream)
+const MAX_OUTPUT_SIZE = 1024 * 1024;
+/**
+ * Validate and resolve a working directory path to prevent directory traversal.
+ * Returns the resolved absolute path if valid, or an error.
+ *
+ * Security (TR-5):
+ * - All paths normalized and validated against project root
+ * - Reject paths containing `..` that escape root
+ * - Use `path.resolve()` and check prefix
+ */
+function validateWorkingDirectory(cwd, workingDirectory) {
+    // Normalize the root working directory to absolute path
+    const rootDir = path.resolve(workingDirectory);
+    // If no cwd specified, use the root directory
+    if (!cwd) {
+        return { valid: true, resolvedPath: rootDir };
+    }
+    // Resolve the requested path relative to working directory
+    const resolvedPath = path.resolve(rootDir, cwd);
+    // Security check: ensure resolved path is within root directory
+    // Use path.sep to ensure we're checking directory boundaries properly
+    const normalizedRoot = rootDir.endsWith(path.sep)
+        ? rootDir
+        : rootDir + path.sep;
+    const normalizedResolved = resolvedPath + path.sep;
+    if (!normalizedResolved.startsWith(normalizedRoot) &&
+        resolvedPath !== rootDir) {
+        return {
+            valid: false,
+            error: "Working directory validation failed: access denied",
+        };
+    }
+    return { valid: true, resolvedPath };
+}
+/**
+ * Truncate output if it exceeds the maximum size.
+ *
+ * @param output - The output string to potentially truncate
+ * @param maxSize - Maximum allowed size in bytes
+ * @returns Truncated output with indicator if truncated
+ */
+function truncateOutput(output, maxSize = MAX_OUTPUT_SIZE) {
+    if (Buffer.byteLength(output, "utf-8") <= maxSize) {
+        return output;
+    }
+    // Truncate to max size and add indicator
+    const truncated = Buffer.from(output, "utf-8")
+        .subarray(0, maxSize)
+        .toString("utf-8");
+    return truncated + "\n... [output truncated]";
+}
+/**
+ * Execute a command with timeout and capture output.
+ *
+ * @param command - The command to execute
+ * @param args - Command arguments
+ * @param cwd - Working directory
+ * @param timeout - Timeout in milliseconds
+ * @param env - Additional environment variables
+ * @returns Promise resolving to command result
+ */
+function executeCommand(command, args, cwd, timeout, env) {
+    return new Promise((resolve) => {
+        const startTime = Date.now();
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let childProcess = null;
+        let timeoutId = null;
+        try {
+            // Spawn the process without shell to prevent shell expansion (TR-5)
+            childProcess = spawn(command, args, {
+                cwd,
+                env: { ...process.env, ...env },
+                // No shell to prevent command injection
+                shell: false,
+                // Detach to allow proper cleanup
+                detached: false,
+                // Set stdio to pipe for capturing output
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            // Set up timeout
+            timeoutId = setTimeout(() => {
+                timedOut = true;
+                if (childProcess && !childProcess.killed) {
+                    // Kill the process and all its children
+                    childProcess.kill("SIGTERM");
+                    // Force kill after 5 seconds if still running
+                    setTimeout(() => {
+                        if (childProcess && !childProcess.killed) {
+                            childProcess.kill("SIGKILL");
+                        }
+                    }, 5000);
+                }
+            }, timeout);
+            // Capture stdout with size limit
+            if (childProcess.stdout) {
+                childProcess.stdout.on("data", (data) => {
+                    const chunk = data.toString("utf-8");
+                    if (Buffer.byteLength(stdout, "utf-8") < MAX_OUTPUT_SIZE) {
+                        stdout += chunk;
+                    }
+                });
+            }
+            // Capture stderr with size limit
+            if (childProcess.stderr) {
+                childProcess.stderr.on("data", (data) => {
+                    const chunk = data.toString("utf-8");
+                    if (Buffer.byteLength(stderr, "utf-8") < MAX_OUTPUT_SIZE) {
+                        stderr += chunk;
+                    }
+                });
+            }
+            // Handle process completion
+            childProcess.on("close", (code) => {
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+                const durationMs = Date.now() - startTime;
+                resolve({
+                    exitCode: code ?? (timedOut ? 124 : 1), // 124 is conventional timeout exit code
+                    stdout: truncateOutput(stdout),
+                    stderr: truncateOutput(stderr),
+                    timedOut,
+                    durationMs,
+                });
+            });
+            // Handle spawn errors
+            childProcess.on("error", (error) => {
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+                const durationMs = Date.now() - startTime;
+                resolve({
+                    exitCode: 1,
+                    stdout: truncateOutput(stdout),
+                    stderr: truncateOutput(stderr + `\nSpawn error: ${error.message}`),
+                    timedOut: false,
+                    durationMs,
+                });
+            });
+        }
+        catch (error) {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+            const durationMs = Date.now() - startTime;
+            const errorMessage = error instanceof Error ? error.message : "Unknown error";
+            resolve({
+                exitCode: 1,
+                stdout: "",
+                stderr: `Failed to spawn process: ${errorMessage}`,
+                timedOut: false,
+                durationMs,
+            });
+        }
+    });
+}
+/**
+ * Run a command with safety constraints.
+ *
+ * Security features (TR-5):
+ * - User must approve command via permission prompt before execution
+ * - Working directory is validated to be within project root
+ * - Timeout is enforced (default 30s)
+ * - No shell expansion (uses spawn, not exec)
+ * - Output is captured with size limits
+ *
+ * @param args - RunCommandArgs containing command, args, cwd, timeout, and env
+ * @param context - CodeContext with working directory
+ * @returns RunCommandResult with execution results
+ */
+export async function runCommand(args, context) {
+    const { command, args: commandArgs = [], cwd, timeout = DEFAULT_TIMEOUT_MS, env, } = args;
+    // Validate working directory (TR-5)
+    const cwdValidation = validateWorkingDirectory(cwd, context.workingDirectory);
+    if (!cwdValidation.valid) {
+        return {
+            success: false,
+            exit_code: 1,
+            stdout: "",
+            stderr: "",
+            duration_ms: 0,
+            timed_out: false,
+            error: cwdValidation.error,
+        };
+    }
+    const resolvedCwd = cwdValidation.resolvedPath;
+    // Validate timeout is reasonable (between 1 second and 10 minutes)
+    const effectiveTimeout = Math.max(1000, Math.min(timeout, 600000));
+    try {
+        // Execute the command
+        const result = await executeCommand(command, commandArgs, resolvedCwd, effectiveTimeout, env);
+        return {
+            success: result.exitCode === 0 && !result.timedOut,
+            exit_code: result.exitCode,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            duration_ms: result.durationMs,
+            timed_out: result.timedOut,
+            error: result.timedOut
+                ? `Command timed out after ${effectiveTimeout}ms`
+                : undefined,
+        };
+    }
+    catch (error) {
+        // Handle unexpected errors
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        return {
+            success: false,
+            exit_code: 1,
+            stdout: "",
+            stderr: "",
+            duration_ms: 0,
+            timed_out: false,
+            error: `Failed to execute command: ${errorMessage}`,
+        };
+    }
+}
+//# sourceMappingURL=run-command.js.map

package/dist/src/lib/local-tools/code/run-command.js.map

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

package/dist/src/lib/local-tools/code/search-files.js

@@ -0,0 +1,297 @@
+/**
+ * search_files tool - Search for files matching a glob pattern.
+ * Supports .gitignore respect, exclude patterns, and result limits.
+ *
+ * Security: Implements path validation to prevent directory traversal (TR-5).
+ * Respects .gitignore by default and skips common ignored directories.
+ */
+import * as fs from "fs/promises";
+import * as path from "path";
+// Default maximum results to return
+const DEFAULT_MAX_RESULTS = 100;
+// Directories to always skip unless explicitly requested (TR-5)
+const DEFAULT_IGNORED_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".tox",
+    ".nox",
+    ".eggs",
+    "*.egg-info",
+    ".venv",
+    "venv",
+    "env",
+    ".env",
+    "dist",
+    "build",
+    ".next",
+    ".nuxt",
+    ".output",
+    ".cache",
+    ".parcel-cache",
+    "coverage",
+    ".nyc_output",
+]);
+/**
+ * Parse a .gitignore file and return an array of patterns.
+ */
+async function parseGitignore(gitignorePath) {
+    try {
+        const content = await fs.readFile(gitignorePath, "utf-8");
+        return content
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line && !line.startsWith("#"));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Convert a glob pattern to a RegExp.
+ * Supports *, **, and ? wildcards.
+ */
+function globToRegex(pattern) {
+    // Escape special regex characters except glob wildcards
+    let regexStr = pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        // Handle ** (matches any path including separators)
+        .replace(/\*\*/g, "{{GLOBSTAR}}")
+        // Handle * (matches anything except path separator)
+        .replace(/\*/g, "[^/]*")
+        // Handle ? (matches single character except path separator)
+        .replace(/\?/g, "[^/]")
+        // Restore globstar
+        .replace(/\{\{GLOBSTAR\}\}/g, ".*");
+    return new RegExp(`^${regexStr}$`, "i");
+}
+/**
+ * Check if a path matches a glob pattern.
+ */
+function matchesGlob(filePath, pattern) {
+    // Normalize path separators
+    const normalizedPath = filePath.replace(/\\/g, "/");
+    const normalizedPattern = pattern.replace(/\\/g, "/");
+    // Handle patterns that start with /
+    const patternToUse = normalizedPattern.startsWith("/")
+        ? normalizedPattern.slice(1)
+        : normalizedPattern;
+    const regex = globToRegex(patternToUse);
+    return regex.test(normalizedPath);
+}
+/**
+ * Check if a path should be ignored based on gitignore patterns.
+ */
+function isIgnoredByPatterns(relativePath, patterns) {
+    const normalizedPath = relativePath.replace(/\\/g, "/");
+    for (const pattern of patterns) {
+        if (!pattern)
+            continue;
+        // Handle negation patterns (!)
+        if (pattern.startsWith("!")) {
+            // Negation - if it matches, it's NOT ignored
+            const negatedPattern = pattern.slice(1);
+            if (matchesGlob(normalizedPath, negatedPattern)) {
+                return false;
+            }
+            continue;
+        }
+        // Handle directory-only patterns (ending with /)
+        const isDirectoryPattern = pattern.endsWith("/");
+        const cleanPattern = isDirectoryPattern ? pattern.slice(0, -1) : pattern;
+        // Check if pattern matches
+        if (matchesGlob(normalizedPath, cleanPattern)) {
+            return true;
+        }
+        // Also check if any path component matches (for patterns like "node_modules")
+        const pathParts = normalizedPath.split("/");
+        for (const part of pathParts) {
+            if (matchesGlob(part, cleanPattern)) {
+                return true;
+            }
+        }
+        // Check with ** prefix for patterns that should match anywhere
+        if (!cleanPattern.includes("/") && !cleanPattern.startsWith("*")) {
+            if (matchesGlob(normalizedPath, `**/${cleanPattern}`)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Check if a directory name is in the default ignored list.
+ */
+function isDefaultIgnoredDir(dirName) {
+    return DEFAULT_IGNORED_DIRS.has(dirName);
+}
+/**
+ * Validate and resolve a path to prevent directory traversal.
+ * Returns the resolved absolute path if valid, or an error.
+ *
+ * Security (TR-5):
+ * - All paths normalized and validated against project root
+ * - Reject paths containing `..` that escape root
+ */
+function validatePath(targetPath, workingDirectory) {
+    const rootDir = path.resolve(workingDirectory);
+    const resolvedPath = path.resolve(rootDir, targetPath);
+    // Security check: ensure resolved path is within root directory
+    const normalizedRoot = rootDir.endsWith(path.sep)
+        ? rootDir
+        : rootDir + path.sep;
+    const normalizedResolved = resolvedPath + path.sep;
+    if (!normalizedResolved.startsWith(normalizedRoot) &&
+        resolvedPath !== rootDir) {
+        return {
+            valid: false,
+            error: "Path validation failed: access denied",
+        };
+    }
+    return { valid: true, resolvedPath };
+}
+/**
+ * Recursively search for files matching a glob pattern.
+ */
+async function searchRecursive(currentDir, rootDir, pattern, options) {
+    // Check if we've reached the max results
+    if (options.results.length >= options.maxResults) {
+        return;
+    }
+    try {
+        const entries = await fs.readdir(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            // Check max results limit
+            if (options.results.length >= options.maxResults) {
+                return;
+            }
+            const fullPath = path.join(currentDir, entry.name);
+            const relativePath = path.relative(rootDir, fullPath);
+            // Skip default ignored directories (TR-5)
+            if (entry.isDirectory() && isDefaultIgnoredDir(entry.name)) {
+                continue;
+            }
+            // Check gitignore patterns if enabled
+            if (options.respectGitignore &&
+                isIgnoredByPatterns(relativePath, options.gitignorePatterns)) {
+                continue;
+            }
+            // Check exclude patterns
+            if (isIgnoredByPatterns(relativePath, options.excludePatterns)) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                // Recurse into subdirectory
+                await searchRecursive(currentDir + path.sep + entry.name, rootDir, pattern, options);
+            }
+            else if (entry.isFile()) {
+                // Check if file matches the search pattern
+                const normalizedRelativePath = relativePath.replace(/\\/g, "/");
+                if (pattern.test(normalizedRelativePath)) {
+                    options.results.push(relativePath);
+                }
+            }
+        }
+    }
+    catch {
+        // Skip directories we can't read (permission issues, etc.)
+    }
+}
+/**
+ * Search for files matching a glob pattern.
+ *
+ * @param args - SearchFilesArgs containing pattern and options
+ * @param context - CodeContext with working directory
+ * @returns SearchFilesResult with matching files
+ */
+export async function searchFiles(args, context) {
+    const { pattern, path: basePath = ".", exclude = [], respect_gitignore = true, max_results = DEFAULT_MAX_RESULTS, } = args;
+    // Validate the base path
+    const pathValidation = validatePath(basePath, context.workingDirectory);
+    if (!pathValidation.valid) {
+        return {
+            success: false,
+            files: [],
+            total_found: 0,
+            truncated: false,
+            error: pathValidation.error,
+        };
+    }
+    const resolvedBasePath = pathValidation.resolvedPath;
+    try {
+        // Check if base path exists and is a directory
+        const stats = await fs.stat(resolvedBasePath);
+        if (!stats.isDirectory()) {
+            return {
+                success: false,
+                files: [],
+                total_found: 0,
+                truncated: false,
+                error: "Base path is not a directory",
+            };
+        }
+        // Parse .gitignore if respect_gitignore is enabled
+        let gitignorePatterns = [];
+        if (respect_gitignore) {
+            const gitignorePath = path.join(context.workingDirectory, ".gitignore");
+            gitignorePatterns = await parseGitignore(gitignorePath);
+        }
+        // Convert the search pattern to a regex
+        const searchRegex = globToRegex(pattern);
+        // Search for matching files
+        const results = [];
+        await searchRecursive(resolvedBasePath, resolvedBasePath, searchRegex, {
+            gitignorePatterns,
+            excludePatterns: exclude,
+            respectGitignore: respect_gitignore,
+            maxResults: max_results + 1, // Get one extra to detect truncation
+            results,
+        });
+        // Check if results were truncated
+        const truncated = results.length > max_results;
+        const finalResults = truncated ? results.slice(0, max_results) : results;
+        // Sort results alphabetically for consistent output
+        finalResults.sort((a, b) => a.localeCompare(b));
+        return {
+            success: true,
+            files: finalResults,
+            total_found: finalResults.length,
+            truncated,
+        };
+    }
+    catch (error) {
+        // Handle specific error types without exposing sensitive info (TR-5)
+        if (error instanceof Error) {
+            const nodeError = error;
+            if (nodeError.code === "ENOENT") {
+                return {
+                    success: false,
+                    files: [],
+                    total_found: 0,
+                    truncated: false,
+                    error: "Base path not found",
+                };
+            }
+            if (nodeError.code === "EACCES") {
+                return {
+                    success: false,
+                    files: [],
+                    total_found: 0,
+                    truncated: false,
+                    error: "Permission denied",
+                };
+            }
+        }
+        // Generic error without exposing details (TR-5)
+        return {
+            success: false,
+            files: [],
+            total_found: 0,
+            truncated: false,
+            error: "Failed to search files",
+        };
+    }
+}
+//# sourceMappingURL=search-files.js.map

package/dist/src/lib/local-tools/code/search-files.js.map

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

package/dist/src/lib/local-tools/code/types.js

@@ -0,0 +1,6 @@
+/**
+ * Shared types for code analysis tools.
+ * These interfaces define the arguments and results for all code tools.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/lib/local-tools/code/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/lib/local-tools/code/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/src/lib/permissions.js

@@ -0,0 +1,94 @@
+/**
+ * Permission Guard - Controls access to sensitive operations
+ * Prompts user for permission before executing file writes or shell commands
+ */
+export class PermissionGuard {
+    sessionGrants;
+    promptFn = null;
+    constructor() {
+        this.sessionGrants = {
+            file_write: false,
+            file_delete: false,
+            run_command: false,
+        };
+    }
+    /**
+     * Set the prompt function that will be called when permission is needed
+     */
+    setPromptFn(fn) {
+        this.promptFn = fn;
+    }
+    /**
+     * Check if an operation is allowed
+     * Returns immediately if session grant exists, otherwise prompts user
+     */
+    async check(request) {
+        // If session grant exists, allow immediately
+        if (this.sessionGrants[request.category]) {
+            return { allowed: true };
+        }
+        // If no prompt function set, deny by default (fail-safe)
+        if (!this.promptFn) {
+            return {
+                allowed: false,
+                feedback: `Permission required for ${request.category}. No permission handler configured.`,
+            };
+        }
+        // Prompt user for permission
+        const response = await this.promptFn(request);
+        switch (response) {
+            case "allow_session":
+                this.grantSession(request.category);
+                return { allowed: true };
+            case "allow_once":
+                return { allowed: true };
+            case "deny":
+            default:
+                return {
+                    allowed: false,
+                    feedback: this.buildDenyFeedback(request),
+                };
+        }
+    }
+    /**
+     * Grant session-wide permission for a category
+     */
+    grantSession(category) {
+        this.sessionGrants[category] = true;
+    }
+    /**
+     * Check if a category has session-wide permission
+     */
+    hasSessionGrant(category) {
+        return this.sessionGrants[category];
+    }
+    /**
+     * Reset all session grants
+     */
+    reset() {
+        this.sessionGrants = {
+            file_write: false,
+            file_delete: false,
+            run_command: false,
+        };
+    }
+    /**
+     * Build feedback message for denied operations
+     */
+    buildDenyFeedback(request) {
+        const { category, details } = request;
+        switch (category) {
+            case "run_command":
+                return `User denied permission to run command: ${details.command}${details.args?.length ? ` ${details.args.join(" ")}` : ""}. Please suggest an alternative approach or ask the user what they'd like to do instead.`;
+            case "file_write":
+                return `User denied permission to write to: ${details.path}. Please suggest an alternative approach or ask the user what they'd like to do instead.`;
+            case "file_delete":
+                return `User denied permission to delete: ${details.path}. Please suggest an alternative approach or ask the user what they'd like to do instead.`;
+            default:
+                return `User denied permission for ${category}. Please suggest an alternative approach.`;
+        }
+    }
+}
+// Singleton instance for use across the application
+export const permissionGuard = new PermissionGuard();
+//# sourceMappingURL=permissions.js.map

package/dist/src/lib/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../../src/lib/permissions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA+BH,MAAM,OAAO,eAAe;IAClB,aAAa,CAAqB;IAClC,QAAQ,GAA8B,IAAI,CAAC;IAEnD;QACE,IAAI,CAAC,aAAa,GAAG;YACnB,UAAU,EAAE,KAAK;YACjB,WAAW,EAAE,KAAK;YAClB,WAAW,EAAE,KAAK;SACnB,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,EAAsB;QAChC,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK,CAAC,OAA0B;QACpC,6CAA6C;QAC7C,IAAI,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzC,OAAO,EAAC,OAAO,EAAE,IAAI,EAAC,CAAC;QACzB,CAAC;QAED,yDAAyD;QACzD,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,QAAQ,EAAE,2BAA2B,OAAO,CAAC,QAAQ,qCAAqC;aAC3F,CAAC;QACJ,CAAC;QAED,6BAA6B;QAC7B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAE9C,QAAQ,QAAQ,EAAE,CAAC;YACjB,KAAK,eAAe;gBAClB,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;gBACpC,OAAO,EAAC,OAAO,EAAE,IAAI,EAAC,CAAC;YAEzB,KAAK,YAAY;gBACf,OAAO,EAAC,OAAO,EAAE,IAAI,EAAC,CAAC;YAEzB,KAAK,MAAM,CAAC;YACZ;gBACE,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,QAAQ,EAAE,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC;iBAC1C,CAAC;QACN,CAAC;IACH,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,QAA4B;QACvC,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IACtC,CAAC;IAED;;OAEG;IACH,eAAe,CAAC,QAA4B;QAC1C,OAAO,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,aAAa,GAAG;YACnB,UAAU,EAAE,KAAK;YACjB,WAAW,EAAE,KAAK;YAClB,WAAW,EAAE,KAAK;SACnB,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,iBAAiB,CAAC,OAA0B;QAClD,MAAM,EAAC,QAAQ,EAAE,OAAO,EAAC,GAAG,OAAO,CAAC;QAEpC,QAAQ,QAAQ,EAAE,CAAC;YACjB,KAAK,aAAa;gBAChB,OAAO,0CAA0C,OAAO,CAAC,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,0FAA0F,CAAC;YAExN,KAAK,YAAY;gBACf,OAAO,uCAAuC,OAAO,CAAC,IAAI,0FAA0F,CAAC;YAEvJ,KAAK,aAAa;gBAChB,OAAO,qCAAqC,OAAO,CAAC,IAAI,0FAA0F,CAAC;YAErJ;gBACE,OAAO,8BAA8B,QAAQ,2CAA2C,CAAC;QAC7F,CAAC;IACH,CAAC;CACF;AAED,oDAAoD;AACpD,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC"}