@nexus-cortex/executors 4.26.0

package/dist/utils/ChromiumBrowserManager.js

@@ -0,0 +1,243 @@
+/**
+ * ChromiumBrowserManager - Robust browser binary discovery for Playwright
+ * Handles finding Chromium/Chrome binaries across different environments
+ */
+import { existsSync, statSync, readdirSync } from 'fs';
+import { join } from 'path';
+/**
+ * ChromiumBinaryLocator - Robust chromium binary discovery
+ * Searches multiple locations with priority order and validation
+ */
+class ChromiumBinaryLocator {
+    cachedPath = undefined;
+    /**
+     * Find chromium binary with comprehensive search
+     */
+    findBinary() {
+        // 1. Environment variable (highest priority - user override)
+        if (process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH) {
+            if (this.isExecutable(process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH)) {
+                console.log(`[ChromiumManager] Using PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH: ${process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH}`);
+                return process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH;
+            }
+            console.warn(`[ChromiumManager] PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH set but not executable: ${process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH}`);
+        }
+        if (process.env.CHROMIUM_BIN) {
+            if (this.isExecutable(process.env.CHROMIUM_BIN)) {
+                console.log(`[ChromiumManager] Using CHROMIUM_BIN: ${process.env.CHROMIUM_BIN}`);
+                return process.env.CHROMIUM_BIN;
+            }
+            console.warn(`[ChromiumManager] CHROMIUM_BIN set but not executable: ${process.env.CHROMIUM_BIN}`);
+        }
+        // 2. Nix store - search for chromium directories
+        try {
+            const nixStorePath = '/nix/store';
+            if (existsSync(nixStorePath)) {
+                const chromiumPath = this.findChromiumInNixStore(nixStorePath);
+                if (chromiumPath) {
+                    console.log(`[ChromiumManager] Found chromium (nix store): ${chromiumPath}`);
+                    return chromiumPath;
+                }
+            }
+        }
+        catch (error) {
+            console.warn(`[ChromiumManager] Error searching nix store:`, error);
+        }
+        // 3. Nix profile locations (common on Replit, NixOS)
+        const homeDir = process.env.HOME;
+        if (homeDir) {
+            const nixPaths = [
+                join(homeDir, '.nix-profile/bin/chromium'),
+                join(homeDir, '.nix-profile/bin/chromium-browser'),
+                join(homeDir, '.local/state/nix/profiles/profile/bin/chromium'),
+            ];
+            for (const path of nixPaths) {
+                if (this.isExecutable(path)) {
+                    console.log(`[ChromiumManager] Found chromium (nix profile): ${path}`);
+                    return path;
+                }
+            }
+        }
+        // 4. System-wide nix locations
+        const systemNixPaths = [
+            '/nix/var/nix/profiles/default/bin/chromium',
+            '/run/current-system/sw/bin/chromium',
+        ];
+        for (const path of systemNixPaths) {
+            if (this.isExecutable(path)) {
+                console.log(`[ChromiumManager] Found chromium (system nix): ${path}`);
+                return path;
+            }
+        }
+        // 5. Standard Chrome/Chromium system paths
+        const systemPaths = [
+            '/usr/bin/chromium',
+            '/usr/bin/chromium-browser',
+            '/usr/bin/google-chrome',
+            '/usr/bin/google-chrome-stable',
+            '/usr/local/bin/chromium',
+            '/opt/google/chrome/chrome',
+            '/opt/chromium.org/chromium/chromium',
+            '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', // macOS
+            '/Applications/Chromium.app/Contents/MacOS/Chromium', // macOS
+        ];
+        for (const path of systemPaths) {
+            if (this.isExecutable(path)) {
+                console.log(`[ChromiumManager] Found chromium (system): ${path}`);
+                return path;
+            }
+        }
+        // 6. Check Playwright's cache (where browsers get installed)
+        try {
+            const playwrightCachePath = this.findPlaywrightCachedChromium();
+            if (playwrightCachePath) {
+                console.log(`[ChromiumManager] Found chromium (playwright cache): ${playwrightCachePath}`);
+                return playwrightCachePath;
+            }
+        }
+        catch (error) {
+            console.warn(`[ChromiumManager] Error searching playwright cache:`, error);
+        }
+        // 7. Return null if nothing found (don't fallback to 'chromium' - be explicit)
+        console.warn(`[ChromiumManager] No chromium binary found. Set PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH environment variable or install chromium.`);
+        return null;
+    }
+    /**
+     * Search nix store for chromium binaries
+     */
+    findChromiumInNixStore(nixStorePath) {
+        try {
+            const entries = readdirSync(nixStorePath);
+            // Look for chromium directories (sorted by name to get latest version)
+            const chromiumDirs = entries
+                .filter(name => name.startsWith('chromium-') || name.includes('chromium'))
+                .sort()
+                .reverse(); // Get latest version first
+            for (const dir of chromiumDirs) {
+                const chromiumBin = join(nixStorePath, dir, 'bin/chromium');
+                if (this.isExecutable(chromiumBin)) {
+                    return chromiumBin;
+                }
+                // Also check for chrome-sandbox and chrome binaries
+                const chromeBin = join(nixStorePath, dir, 'bin/chrome');
+                if (this.isExecutable(chromeBin)) {
+                    return chromeBin;
+                }
+            }
+        }
+        catch (error) {
+            // Directory read error - not a problem, continue searching
+        }
+        return null;
+    }
+    /**
+     * Find chromium in Playwright's cache directory
+     */
+    findPlaywrightCachedChromium() {
+        const homeDir = process.env.HOME;
+        if (!homeDir)
+            return null;
+        const playwrightPaths = [
+            join(homeDir, '.cache/ms-playwright'),
+            join(homeDir, 'Library/Caches/ms-playwright'), // macOS
+            join(homeDir, 'AppData/Local/ms-playwright'), // Windows
+        ];
+        for (const cachePath of playwrightPaths) {
+            if (!existsSync(cachePath))
+                continue;
+            try {
+                const entries = readdirSync(cachePath);
+                const chromiumDirs = entries
+                    .filter(name => name.startsWith('chromium-'))
+                    .sort()
+                    .reverse();
+                for (const dir of chromiumDirs) {
+                    // Linux/Windows
+                    let chromiumBin = join(cachePath, dir, 'chrome-linux/chrome');
+                    if (this.isExecutable(chromiumBin)) {
+                        return chromiumBin;
+                    }
+                    // macOS
+                    chromiumBin = join(cachePath, dir, 'chrome-mac/Chromium.app/Contents/MacOS/Chromium');
+                    if (this.isExecutable(chromiumBin)) {
+                        return chromiumBin;
+                    }
+                    // Windows
+                    chromiumBin = join(cachePath, dir, 'chrome-win/chrome.exe');
+                    if (this.isExecutable(chromiumBin)) {
+                        return chromiumBin;
+                    }
+                }
+            }
+            catch (error) {
+                // Continue searching
+            }
+        }
+        return null;
+    }
+    /**
+     * Check if path is an executable file
+     */
+    isExecutable(path) {
+        try {
+            if (!existsSync(path))
+                return false;
+            const stats = statSync(path);
+            // Check if file and has execute permission
+            return stats.isFile() && !!(stats.mode & 0o111);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get chromium binary path (cached)
+     */
+    getBinary() {
+        if (this.cachedPath === undefined) {
+            this.cachedPath = this.findBinary();
+        }
+        return this.cachedPath;
+    }
+    /**
+     * Clear cached path (for testing)
+     */
+    clearCache() {
+        this.cachedPath = undefined;
+    }
+    /**
+     * Get browser configuration for Playwright
+     */
+    getPlaywrightConfig() {
+        const binary = this.getBinary();
+        if (!binary) {
+            throw new Error('Chromium binary not found. Please install chromium or set PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH environment variable.');
+        }
+        return { executablePath: binary };
+    }
+}
+// Singleton instance
+const locator = new ChromiumBinaryLocator();
+/**
+ * Get chromium binary path
+ */
+export function getChromiumBinary() {
+    return locator.getBinary();
+}
+/**
+ * Get Playwright browser launch configuration
+ */
+export function getPlaywrightConfig() {
+    return locator.getPlaywrightConfig();
+}
+/**
+ * Clear cached chromium path (for testing)
+ */
+export function clearChromiumCache() {
+    locator.clearCache();
+}
+/**
+ * Export the locator class for advanced usage
+ */
+export { ChromiumBinaryLocator };
+//# sourceMappingURL=ChromiumBrowserManager.js.map

package/dist/utils/ChromiumBrowserManager.js.map

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

package/dist/utils/FileUtils.d.ts

@@ -0,0 +1,81 @@
+/**
+ * File Utilities
+ *
+ * Common file operations and path handling for tool executors
+ */
+import fs from 'fs';
+/**
+ * Check if a path is within a root directory
+ *
+ * @param filePath Path to check
+ * @param rootDir Root directory
+ * @returns true if path is within root, false otherwise
+ */
+export declare function isWithinRoot(filePath: string, rootDir: string): boolean;
+/**
+ * Make a path relative to a directory
+ *
+ * @param filePath Absolute path
+ * @param baseDir Base directory
+ * @returns Relative path
+ */
+export declare function makeRelative(filePath: string, baseDir: string): string;
+/**
+ * Shorten a path for display
+ *
+ * @param filePath Path to shorten
+ * @param maxLength Maximum length (default: 60)
+ * @returns Shortened path
+ */
+export declare function shortenPath(filePath: string, maxLength?: number): string;
+/**
+ * Read file content with line range support
+ *
+ * @param filePath Path to file
+ * @param offset Line offset (0-based)
+ * @param limit Number of lines to read
+ * @returns File content
+ */
+export declare function readFileContent(filePath: string, offset?: number, limit?: number): Promise<string>;
+/**
+ * Get file statistics
+ *
+ * @param filePath Path to file
+ * @returns File stats
+ */
+export declare function getFileStats(filePath: string): Promise<fs.Stats>;
+/**
+ * Check if file exists
+ *
+ * @param filePath Path to file
+ * @returns true if exists, false otherwise
+ */
+export declare function fileExists(filePath: string): boolean;
+/**
+ * Resolve a file path with smart fallback for common model mistakes.
+ *
+ * When a model passes a relative path that doesn't exist after resolution
+ * against the working directory, this tries stripping leading segments that
+ * duplicate the working directory name. For example, if workingDirectory is
+ * `/home/user/my-project` and the model passes `my-project/src/index.ts`,
+ * the naive resolution produces `/home/user/my-project/my-project/src/index.ts`
+ * (doesn't exist). The fallback strips the `my-project/` prefix and retries,
+ * yielding the correct `/home/user/my-project/src/index.ts`.
+ *
+ * Only returns a fallback if it (a) exists on disk and (b) passes the
+ * security check (within workingDirectory). Otherwise returns the original
+ * resolved path so the caller can produce the normal error.
+ *
+ * @param rawPath   The path exactly as the model provided it
+ * @param workingDirectory  The project root / security boundary
+ * @returns The resolved absolute path (fallback-corrected when possible)
+ */
+export declare function resolveFilePath(rawPath: string, workingDirectory: string): string;
+/**
+ * Format file size for display
+ *
+ * @param bytes File size in bytes
+ * @returns Formatted string (e.g., "1.5 KB")
+ */
+export declare function formatFileSize(bytes: number): string;
+//# sourceMappingURL=FileUtils.d.ts.map

package/dist/utils/FileUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileUtils.d.ts","sourceRoot":"","sources":["../../src/utils/FileUtils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,IAAI,CAAC;AAGpB;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAIvE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAAW,GAAG,MAAM,CAY5E;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAgBjB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,CAEtE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAiCjF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKpD"}

package/dist/utils/FileUtils.js

@@ -0,0 +1,148 @@
+/**
+ * File Utilities
+ *
+ * Common file operations and path handling for tool executors
+ */
+import fs from 'fs';
+import path from 'path';
+/**
+ * Check if a path is within a root directory
+ *
+ * @param filePath Path to check
+ * @param rootDir Root directory
+ * @returns true if path is within root, false otherwise
+ */
+export function isWithinRoot(filePath, rootDir) {
+    const resolved = path.resolve(filePath);
+    const root = path.resolve(rootDir);
+    return resolved.startsWith(root);
+}
+/**
+ * Make a path relative to a directory
+ *
+ * @param filePath Absolute path
+ * @param baseDir Base directory
+ * @returns Relative path
+ */
+export function makeRelative(filePath, baseDir) {
+    return path.relative(baseDir, filePath);
+}
+/**
+ * Shorten a path for display
+ *
+ * @param filePath Path to shorten
+ * @param maxLength Maximum length (default: 60)
+ * @returns Shortened path
+ */
+export function shortenPath(filePath, maxLength = 60) {
+    if (filePath.length <= maxLength) {
+        return filePath;
+    }
+    const parts = filePath.split(path.sep);
+    if (parts.length <= 2) {
+        return filePath;
+    }
+    // Keep first and last parts, abbreviate middle
+    return `${parts[0]}${path.sep}...${path.sep}${parts[parts.length - 1]}`;
+}
+/**
+ * Read file content with line range support
+ *
+ * @param filePath Path to file
+ * @param offset Line offset (0-based)
+ * @param limit Number of lines to read
+ * @returns File content
+ */
+export async function readFileContent(filePath, offset, limit) {
+    const content = await fs.promises.readFile(filePath, 'utf-8');
+    // Return full content if no offset/limit
+    if (offset === undefined && limit === undefined) {
+        return content;
+    }
+    // Split into lines
+    const lines = content.split('\n');
+    // Apply offset and limit
+    const startLine = offset || 0;
+    const endLine = limit ? startLine + limit : lines.length;
+    return lines.slice(startLine, endLine).join('\n');
+}
+/**
+ * Get file statistics
+ *
+ * @param filePath Path to file
+ * @returns File stats
+ */
+export async function getFileStats(filePath) {
+    return fs.promises.stat(filePath);
+}
+/**
+ * Check if file exists
+ *
+ * @param filePath Path to file
+ * @returns true if exists, false otherwise
+ */
+export function fileExists(filePath) {
+    return fs.existsSync(filePath);
+}
+/**
+ * Resolve a file path with smart fallback for common model mistakes.
+ *
+ * When a model passes a relative path that doesn't exist after resolution
+ * against the working directory, this tries stripping leading segments that
+ * duplicate the working directory name. For example, if workingDirectory is
+ * `/home/user/my-project` and the model passes `my-project/src/index.ts`,
+ * the naive resolution produces `/home/user/my-project/my-project/src/index.ts`
+ * (doesn't exist). The fallback strips the `my-project/` prefix and retries,
+ * yielding the correct `/home/user/my-project/src/index.ts`.
+ *
+ * Only returns a fallback if it (a) exists on disk and (b) passes the
+ * security check (within workingDirectory). Otherwise returns the original
+ * resolved path so the caller can produce the normal error.
+ *
+ * @param rawPath   The path exactly as the model provided it
+ * @param workingDirectory  The project root / security boundary
+ * @returns The resolved absolute path (fallback-corrected when possible)
+ */
+export function resolveFilePath(rawPath, workingDirectory) {
+    // Normalize double slashes
+    let filePath = rawPath.replace(/\/+/g, '/');
+    // Already absolute — nothing to resolve
+    if (path.isAbsolute(filePath)) {
+        return filePath;
+    }
+    // Standard resolution against working directory
+    const resolved = path.resolve(workingDirectory, filePath);
+    // If it exists, great — use it
+    if (fs.existsSync(resolved)) {
+        return resolved;
+    }
+    // --- Smart fallback: strip leading segments that match the workingDirectory basename ---
+    // Handles: "nexus-cortex/packages/core/..." when workingDirectory already IS nexus-cortex
+    const dirName = path.basename(workingDirectory);
+    const segments = filePath.split('/');
+    if (segments[0] === dirName && segments.length > 1) {
+        const stripped = segments.slice(1).join('/');
+        const fallback = path.resolve(workingDirectory, stripped);
+        if (fs.existsSync(fallback) && isWithinRoot(fallback, workingDirectory)) {
+            return fallback;
+        }
+    }
+    // Return original resolution (caller will produce the appropriate error)
+    return resolved;
+}
+/**
+ * Format file size for display
+ *
+ * @param bytes File size in bytes
+ * @returns Formatted string (e.g., "1.5 KB")
+ */
+export function formatFileSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
+//# sourceMappingURL=FileUtils.js.map

package/dist/utils/FileUtils.js.map

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

package/dist/utils/GitPolicy.d.ts

@@ -0,0 +1,70 @@
+/**
+ * GitPolicy — single source of truth for git/PR access control + safe subprocess wiring.
+ *
+ * Used by PRAgentTool, WorkspaceManagerTool, and the server's /v1/pr/* routes so that
+ * repo/action allow-listing, input validation, and token handling are consistent and
+ * defined in exactly one place.
+ *
+ * Security posture:
+ *  - Validation (repo/branch/prNumber regexes) is ALWAYS enforced — there is no opt-out.
+ *    Combined with execFile (no shell), this closes the shell/argument-injection class.
+ *  - The repo/action allow-list is opt-in defense-in-depth. Unset GIT_ALLOWED_REPOS means
+ *    "allow all" so existing single-user setups keep working after an upgrade;
+ *    multi-tenant/shared deployments set it to restrict. (No startup warning — the
+ *    trade-off is documented in .env.example so the TUI/CLI don't print noise on launch.)
+ *  - The auth token is exposed to gh/git ONLY through the subprocess environment
+ *    (GH_TOKEN / GITHUB_TOKEN). It is never interpolated into argv or a clone URL.
+ *
+ * Env vars (see SettingsSchema.ts / .env.example):
+ *  - GIT_ALLOWED_REPOS    comma list of owner/repo, supports `owner/*` and `*`. Default `*`.
+ *  - GIT_ALLOWED_ACTIONS  comma list of actions. Default: all actions allowed.
+ *  - GIT_AUTH_TOKEN       token for gh/git, injected into the subprocess env only.
+ *  - GIT_HOST             GitHub (Enterprise) host, default `github.com`.
+ */
+export type GitAction = 'review' | 'list' | 'create' | 'post-review' | 'clone' | 'worktree' | 'diff' | 'cleanup' | 'status';
+export declare const ALL_GIT_ACTIONS: GitAction[];
+export interface GitPolicyConfig {
+    /** Raw GIT_ALLOWED_REPOS value (comma list of owner/repo, `owner/*`, or `*`). */
+    allowedRepos?: string;
+    /** Raw GIT_ALLOWED_ACTIONS value (comma list). Unset → all actions allowed. */
+    allowedActions?: string;
+    /** GIT_AUTH_TOKEN — injected into subprocess env as GH_TOKEN/GITHUB_TOKEN. */
+    token?: string;
+    /** GIT_HOST — GitHub Enterprise host. Default `github.com`. */
+    host?: string;
+}
+export declare class GitPolicy {
+    /** Parsed allow-list patterns: `*`, `owner/*`, or exact `owner/repo`. */
+    private readonly repoPatterns;
+    /** Allowed actions, or null when all actions are permitted. */
+    private readonly actions;
+    readonly token?: string;
+    readonly host: string;
+    constructor(cfg?: GitPolicyConfig);
+    /** Build a policy from environment variables (defaults to process.env). */
+    static fromEnv(env?: NodeJS.ProcessEnv): GitPolicy;
+    /**
+     * Validate a repo string: format first (blocks injection), then the allow-list.
+     * Returns an error message, or null when the repo is acceptable.
+     */
+    validateRepo(repo: unknown): string | null;
+    /** True if the (already format-valid) repo matches the allow-list. */
+    isRepoAllowed(repo: string): boolean;
+    /** Validate a branch / ref name. Returns an error message or null. */
+    validateBranch(name: unknown): string | null;
+    /** Validate a PR number (must be a positive integer). Returns an error message or null. */
+    validatePrNumber(n: unknown): string | null;
+    /** Coerce a validated PR number to an integer (call only after validatePrNumber passes). */
+    prNumber(n: unknown): number;
+    isActionAllowed(action: GitAction): boolean;
+    /** Returns an error message if the action is blocked, else null. */
+    assertAction(action: GitAction): string | null;
+    /**
+     * Subprocess environment with the auth token + host injected for gh/git.
+     * The token rides in env only — never on argv or in a URL.
+     */
+    subprocessEnv(base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+    /** HTTPS clone URL for an `owner/repo`, host-aware. No token embedded. */
+    cloneUrl(repo: string): string;
+}
+//# sourceMappingURL=GitPolicy.d.ts.map

package/dist/utils/GitPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitPolicy.d.ts","sourceRoot":"","sources":["../../src/utils/GitPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,aAAa,GACb,OAAO,GACP,UAAU,GACV,MAAM,GACN,SAAS,GACT,QAAQ,CAAC;AAEb,eAAO,MAAM,eAAe,EAAE,SAAS,EAUtC,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAUD,qBAAa,SAAS;IACpB,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAW;IACxC,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,GAAG,GAAE,eAAoB;IA6BrC,2EAA2E;IAC3E,MAAM,CAAC,OAAO,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,SAAS;IAS/D;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;IAc1C,sEAAsE;IACtE,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAapC,sEAAsE;IACtE,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;IAQ5C,2FAA2F;IAC3F,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;IAQ3C,4FAA4F;IAC5F,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM;IAI5B,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO;IAI3C,oEAAoE;IACpE,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI;IAM9C;;;OAGG;IACH,aAAa,CAAC,IAAI,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAAC,UAAU;IAYvE,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAG/B"}