spindb 0.37.2 → 0.38.0

package/dist/engines/clickhouse/backup.js

@@ -0,0 +1,289 @@
+/**
+ * ClickHouse backup module
+ * Supports SQL-based backups using clickhouse client
+ *
+ * ClickHouse backup formats:
+ * - SQL: DDL + INSERT statements (portable, human-readable)
+ * - Native: ClickHouse native format (faster, compact)
+ */
+import { spawn } from 'child_process';
+import { stat, mkdir, writeFile } from 'fs/promises';
+import { existsSync, createWriteStream } from 'fs';
+import { dirname } from 'path';
+import { logDebug, logWarning } from '../../core/error-handler.js';
+import { requireClickHousePath, validateClickHouseIdentifier, escapeClickHouseIdentifier, } from './cli-utils.js';
+/**
+ * Execute a ClickHouse query and return the result
+ */
+async function execClickHouseQuery(clickhousePath, port, database, query) {
+    return new Promise((resolve, reject) => {
+        const args = [
+            'client',
+            '--host',
+            '127.0.0.1',
+            '--port',
+            String(port),
+            '--database',
+            database,
+            '--query',
+            query,
+        ];
+        const proc = spawn(clickhousePath, args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        proc.stdout.on('data', (data) => {
+            stdout += data.toString();
+        });
+        proc.stderr.on('data', (data) => {
+            stderr += data.toString();
+        });
+        proc.on('error', reject);
+        proc.on('close', (code) => {
+            if (code === 0 || code === null) {
+                resolve(stdout);
+            }
+            else {
+                reject(new Error(stderr || `clickhouse client exited with code ${code}`));
+            }
+        });
+    });
+}
+/**
+ * Get list of tables in a database
+ */
+async function getTables(clickhousePath, port, database) {
+    // Validate database identifier to prevent SQL injection
+    validateClickHouseIdentifier(database, 'database');
+    // Escape single quotes for use in string literal (WHERE clause)
+    const escapedDbLiteral = database.replace(/'/g, "''");
+    const result = await execClickHouseQuery(clickhousePath, port, database, `SELECT name FROM system.tables WHERE database = '${escapedDbLiteral}' ORDER BY name`);
+    return result
+        .trim()
+        .split('\n')
+        .filter((t) => t.trim());
+}
+/**
+ * Get CREATE TABLE statement for a table
+ * Returns portable SQL without database prefix for cross-database restore
+ */
+async function getCreateTableStatement(clickhousePath, port, database, table) {
+    // Validate and escape identifiers to prevent SQL injection
+    validateClickHouseIdentifier(database, 'database');
+    validateClickHouseIdentifier(table, 'table');
+    const escapedDb = escapeClickHouseIdentifier(database);
+    const escapedTable = escapeClickHouseIdentifier(table);
+    // Use TSVRaw format to get unescaped output (newlines as actual newlines, not \n)
+    const result = await execClickHouseQuery(clickhousePath, port, database, `SHOW CREATE TABLE ${escapedDb}.${escapedTable} FORMAT TSVRaw`);
+    // Strip database prefix from CREATE TABLE statement to make it portable
+    // e.g., "CREATE TABLE testdb.test_user" → "CREATE TABLE test_user"
+    // e.g., "CREATE TABLE `testdb`.`test_user`" → "CREATE TABLE `test_user`"
+    // This allows the backup to be restored to any target database
+    const createStmt = result.trim();
+    // Escape regex metacharacters in database name for safe interpolation
+    const escapedDatabase = database.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // Match both quoted and unquoted database names: db.table or `db`.table or `db`.`table`
+    const dbPrefixPattern = new RegExp(`(CREATE TABLE\\s+)\`?${escapedDatabase}\`?\\.`, 'i');
+    return createStmt.replace(dbPrefixPattern, '$1');
+}
+/**
+ * Create a SQL backup (DDL + INSERT statements)
+ */
+async function createSqlBackup(container, outputPath, database) {
+    const { port, version } = container;
+    const clickhousePath = await requireClickHousePath(version);
+    const lines = [];
+    lines.push('-- ClickHouse backup generated by SpinDB');
+    lines.push(`-- Date: ${new Date().toISOString()}`);
+    lines.push(`-- Database: ${database}`);
+    lines.push('');
+    // Get list of tables
+    const tables = await getTables(clickhousePath, port, database);
+    logDebug(`Found ${tables.length} tables to backup`);
+    for (const table of tables) {
+        lines.push(`-- Table: ${table}`);
+        lines.push('');
+        // Get CREATE TABLE statement
+        try {
+            const createStmt = await getCreateTableStatement(clickhousePath, port, database, table);
+            lines.push(createStmt + ';');
+            lines.push('');
+        }
+        catch (error) {
+            logWarning(`Could not get CREATE TABLE for ${table}: ${error}`);
+            continue;
+        }
+        // Export data using INSERT format
+        try {
+            // Validate and escape identifiers for SQL injection protection
+            // Note: table names from getTables are already validated, but escape for query safety
+            validateClickHouseIdentifier(table, 'table');
+            const escapedDb = escapeClickHouseIdentifier(database);
+            const escapedTable = escapeClickHouseIdentifier(table);
+            const data = await execClickHouseQuery(clickhousePath, port, database, `SELECT * FROM ${escapedDb}.${escapedTable} FORMAT SQLInsert`);
+            if (data.trim()) {
+                // SQLInsert format uses literal "table" as placeholder, replace ALL occurrences with actual table name
+                // Use global flag to handle multi-statement output
+                const insertData = data
+                    .trim()
+                    .replace(/INSERT INTO table \(/gi, `INSERT INTO ${escapedTable} (`);
+                lines.push(insertData);
+                lines.push('');
+            }
+        }
+        catch (error) {
+            logWarning(`Could not export data for ${table}: ${error}`);
+        }
+    }
+    // Ensure output directory exists
+    const outputDir = dirname(outputPath);
+    if (!existsSync(outputDir)) {
+        await mkdir(outputDir, { recursive: true });
+    }
+    // Write to file
+    const content = lines.join('\n');
+    await writeFile(outputPath, content, 'utf-8');
+    const stats = await stat(outputPath);
+    return {
+        path: outputPath,
+        format: 'sql',
+        size: stats.size,
+    };
+}
+/**
+ * Create a native format backup (faster, more compact)
+ *
+ * TODO: Enable native backup format when restore support is implemented.
+ * Native format is ~10x faster and more compact than SQL, but requires
+ * parsing the binary format for restore. SQL format is currently preferred
+ * for portability and ease of restore via clickhouse client --multiquery.
+ *
+ * ARCHITECTURAL NOTE: The current implementation mixes text markers
+ * (-- TABLE:, -- CREATE:, -- DATA:) with binary Native format data in
+ * the same stream. Before enabling this feature, refactor to use a
+ * structured container format for deterministic parsing during restore:
+ * - Tar archive with separate files per table (schema.sql + data.native)
+ * - Or length-prefixed binary sections
+ * - Or separate metadata JSON file alongside pure binary data
+ *
+ * To enable: export this function, add 'native' to BACKUP_FORMATS in
+ * config/backup-formats.ts, and implement native restore in restore.ts.
+ *
+ * @internal Kept for future native backup support
+ */
+async function _createNativeBackup(container, outputPath, database) {
+    const { port, version } = container;
+    const clickhousePath = await requireClickHousePath(version);
+    // Ensure output directory exists
+    const outputDir = dirname(outputPath);
+    if (!existsSync(outputDir)) {
+        await mkdir(outputDir, { recursive: true });
+    }
+    // Get list of tables
+    const tables = await getTables(clickhousePath, port, database);
+    logDebug(`Found ${tables.length} tables to backup`);
+    // Create a combined backup with all tables
+    const fileStream = createWriteStream(outputPath);
+    // Write header
+    const header = `-- ClickHouse native backup\n-- Database: ${database}\n-- Date: ${new Date().toISOString()}\n\n`;
+    fileStream.write(header);
+    for (const table of tables) {
+        // Write table marker
+        fileStream.write(`\n-- TABLE: ${table}\n`);
+        // Get CREATE TABLE
+        try {
+            const createStmt = await getCreateTableStatement(clickhousePath, port, database, table);
+            fileStream.write(`-- CREATE:\n${createStmt};\n`);
+        }
+        catch (error) {
+            logWarning(`Could not get CREATE TABLE for ${table}: ${error}`);
+            continue;
+        }
+        // Export data in Native format (binary, fast)
+        fileStream.write(`-- DATA (Native format):\n`);
+        // Validate and escape identifiers for SQL injection protection
+        validateClickHouseIdentifier(table, 'table');
+        const escapedDb = escapeClickHouseIdentifier(database);
+        const escapedTable = escapeClickHouseIdentifier(table);
+        await new Promise((resolve, reject) => {
+            const args = [
+                'client',
+                '--host',
+                '127.0.0.1',
+                '--port',
+                String(port),
+                '--database',
+                database,
+                '--query',
+                `SELECT * FROM ${escapedDb}.${escapedTable} FORMAT Native`,
+            ];
+            const proc = spawn(clickhousePath, args, {
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            let stderr = '';
+            proc.stdout.pipe(fileStream, { end: false });
+            proc.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+            proc.on('error', reject);
+            proc.on('close', (code) => {
+                if (code === 0 || code === null) {
+                    resolve();
+                }
+                else {
+                    reject(new Error(stderr || `clickhouse client exited with code ${code}`));
+                }
+            });
+        });
+        fileStream.write('\n-- END TABLE\n');
+    }
+    // Close file
+    await new Promise((resolve, reject) => {
+        fileStream.end((err) => {
+            if (err)
+                reject(err);
+            else
+                resolve();
+        });
+    });
+    const stats = await stat(outputPath);
+    return {
+        path: outputPath,
+        format: 'native',
+        size: stats.size,
+    };
+}
+/**
+ * Create a backup
+ *
+ * Currently only supports SQL format (DDL + INSERT statements).
+ * Native format support is planned but not yet implemented for restore.
+ * See _createNativeBackup for the future native implementation.
+ *
+ * @param container - Container configuration
+ * @param outputPath - Path to write backup file
+ * @param options - Backup options (BackupOptions type)
+ * @param options.format - Reserved for future use. Currently ignored; all backups
+ *   use SQL format. When native format support is added, 'dump' will use
+ *   _createNativeBackup for faster, more compact backups.
+ */
+export async function createBackup(container, outputPath, options) {
+    const database = options.database || container.database || 'default';
+    // Log when a non-SQL format is requested but not yet supported
+    if (options.format && options.format !== 'sql') {
+        logDebug(`ClickHouse backup: format '${options.format}' requested but not yet supported. ` +
+            `Using SQL format instead. See _createNativeBackup for future native support.`);
+    }
+    // Currently only SQL format is supported
+    // Native format (_createNativeBackup) will be enabled when restore support is added
+    return createSqlBackup(container, outputPath, database);
+}
+/**
+ * Create a backup for cloning purposes
+ * Uses SQL format for reliability
+ */
+export async function createCloneBackup(container, outputPath) {
+    return createSqlBackup(container, outputPath, container.database || 'default');
+}
+//# sourceMappingURL=backup.js.map

package/dist/engines/clickhouse/backup.js.map

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

package/dist/engines/clickhouse/binary-manager.js

@@ -0,0 +1,145 @@
+/**
+ * ClickHouse Binary Manager
+ *
+ * Handles downloading, extracting, and managing ClickHouse binaries from hostdb.
+ * ClickHouse uses a single unified binary that handles server, client, and local modes.
+ *
+ * Extends BaseServerBinaryManager with ClickHouse-specific overrides:
+ * - No Windows support (throws on Windows extraction)
+ * - YY.MM version matching in verify()
+ * - Flat archive handling (moves clickhouse binary to bin/)
+ */
+import { existsSync } from 'fs';
+import { mkdir, readdir } from 'fs/promises';
+import { join } from 'path';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { paths } from '../../config/paths.js';
+import { getBinaryUrl } from './binary-urls.js';
+import { normalizeVersion } from './version-maps.js';
+import { logDebug } from '../../core/error-handler.js';
+import { moveEntry } from '../../core/fs-error-utils.js';
+import { BaseServerBinaryManager, } from '../../core/base-server-binary-manager.js';
+import { Engine, } from '../../types/index.js';
+const execAsync = promisify(exec);
+class ClickHouseBinaryManager extends BaseServerBinaryManager {
+    config = {
+        engine: Engine.ClickHouse,
+        engineName: 'clickhouse',
+        displayName: 'ClickHouse',
+        serverBinaryNames: ['clickhouse'],
+    };
+    getBinaryUrlFromModule(version, platform, arch) {
+        return getBinaryUrl(version, platform, arch);
+    }
+    normalizeVersionFromModule(version) {
+        return normalizeVersion(version);
+    }
+    parseVersionFromOutput(stdout) {
+        // Extract version from output like "ClickHouse client version 25.12.3.21"
+        const match = stdout.match(/(\d+\.\d+\.\d+\.\d+)/);
+        return match?.[1] ?? null;
+    }
+    /**
+     * ClickHouse does not have Windows binaries on hostdb.
+     * Override to throw a clear error.
+     */
+    async extractWindowsBinaries(_zipFile, _binPath, _tempDir, _onProgress) {
+        throw new Error('ClickHouse binaries are not available for Windows. ' +
+            'ClickHouse is only supported on macOS and Linux.');
+    }
+    /**
+     * Override to handle ClickHouse's archive structure.
+     * ClickHouse archives may have a flat structure where the binary is at the root,
+     * not in a bin/ subdirectory. This moves the clickhouse binary to bin/.
+     */
+    async moveExtractedEntries(extractDir, binPath) {
+        const entries = await readdir(extractDir, { withFileTypes: true });
+        // Check for a clickhouse subdirectory
+        const clickhouseDir = entries.find((e) => e.isDirectory() &&
+            (e.name === 'clickhouse' || e.name.startsWith('clickhouse-')));
+        const sourceDir = clickhouseDir
+            ? join(extractDir, clickhouseDir.name)
+            : extractDir;
+        const sourceEntries = clickhouseDir
+            ? await readdir(sourceDir, { withFileTypes: true })
+            : entries;
+        // Check if source has a bin/ subdirectory
+        const hasBinDir = sourceEntries.some((e) => e.isDirectory() && e.name === 'bin');
+        if (hasBinDir) {
+            // Standard structure: move all entries as-is (preserves bin/ subdirectory)
+            for (const entry of sourceEntries) {
+                const sourcePath = join(sourceDir, entry.name);
+                const destPath = join(binPath, entry.name);
+                await moveEntry(sourcePath, destPath);
+            }
+        }
+        else {
+            // Flat structure: create bin/ and move binaries there
+            const destBinDir = join(binPath, 'bin');
+            await mkdir(destBinDir, { recursive: true });
+            for (const entry of sourceEntries) {
+                const sourcePath = join(sourceDir, entry.name);
+                // Check if it's an executable (no extension on Unix, starts with 'clickhouse')
+                const isExecutable = entry.isFile() &&
+                    !entry.name.includes('.') &&
+                    entry.name.startsWith('clickhouse');
+                const destPath = isExecutable
+                    ? join(destBinDir, entry.name)
+                    : join(binPath, entry.name);
+                await moveEntry(sourcePath, destPath);
+            }
+        }
+    }
+    /**
+     * Override verification for ClickHouse's YY.MM version format.
+     * ClickHouse uses `clickhouse client --version` and has 4-part versions (YY.MM.patch.build).
+     */
+    async verify(version, platform, arch) {
+        const fullVersion = this.getFullVersion(version);
+        const binPath = paths.getBinaryPath({
+            engine: this.config.engineName,
+            version: fullVersion,
+            platform,
+            arch,
+        });
+        const clickhousePath = join(binPath, 'bin', 'clickhouse');
+        if (!existsSync(clickhousePath)) {
+            throw new Error(`ClickHouse binary not found at ${binPath}/bin/`);
+        }
+        try {
+            const { stdout, stderr } = await execAsync(`"${clickhousePath}" client --version`);
+            // Log stderr if present (may contain benign warnings about config, etc.)
+            if (stderr && stderr.trim()) {
+                logDebug(`clickhouse client stderr during version check: ${stderr.trim()}`);
+            }
+            const reportedVersion = this.parseVersionFromOutput(stdout);
+            if (!reportedVersion) {
+                throw new Error(`Could not parse version from: ${stdout.trim()}`);
+            }
+            // Check if major versions match (YY.MM format)
+            const expectedMajor = version.split('.').slice(0, 2).join('.');
+            const reportedMajor = reportedVersion.split('.').slice(0, 2).join('.');
+            if (expectedMajor === reportedMajor) {
+                return true;
+            }
+            // Check if full versions match
+            if (reportedVersion === fullVersion) {
+                return true;
+            }
+            throw new Error(`Version mismatch: expected ${version}, got ${reportedVersion}`);
+        }
+        catch (error) {
+            const err = error;
+            // Include stderr and exit code in error message for better debugging
+            const details = [err.message];
+            if (err.stderr)
+                details.push(`stderr: ${err.stderr.trim()}`);
+            if (err.code !== undefined)
+                details.push(`exit code: ${err.code}`);
+            throw new Error(`Failed to verify ClickHouse binaries: ${details.join(', ')}`);
+        }
+    }
+}
+export const clickhouseBinaryManager = new ClickHouseBinaryManager();
+//# sourceMappingURL=binary-manager.js.map

package/dist/engines/clickhouse/binary-manager.js.map

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

package/dist/engines/clickhouse/binary-urls.js

@@ -0,0 +1,100 @@
+import { CLICKHOUSE_VERSION_MAP } from './version-maps.js';
+import { buildHostdbUrl } from '../../core/hostdb-client.js';
+import { logDebug } from '../../core/error-handler.js';
+import { Engine } from '../../types/index.js';
+/**
+ * Supported platform identifiers for hostdb downloads.
+ * Note: ClickHouse on hostdb doesn't support Windows currently.
+ */
+const SUPPORTED_PLATFORMS = new Set([
+    'darwin-arm64',
+    'darwin-x64',
+    'linux-arm64',
+    'linux-x64',
+]);
+/**
+ * Get the hostdb platform identifier
+ *
+ * hostdb uses standard platform naming that matches Node.js identifiers directly.
+ * This function validates the platform/arch combination is supported.
+ *
+ * @param platform - Node.js platform (e.g., 'darwin', 'linux', 'win32')
+ * @param arch - Node.js architecture (e.g., 'arm64', 'x64')
+ * @returns hostdb platform identifier or null if unsupported
+ */
+export function getHostdbPlatform(platform, arch) {
+    const key = `${platform}-${arch}`;
+    return SUPPORTED_PLATFORMS.has(key) ? key : null;
+}
+/**
+ * Build the download URL for ClickHouse binaries from hostdb
+ *
+ * Format: https://registry.layerbase.host/clickhouse-{version}/clickhouse-{version}-{platform}-{arch}.tar.gz
+ *
+ * @param version - ClickHouse version (e.g., '25.12', '25.12.3.21')
+ * @param platform - Platform identifier (e.g., 'darwin', 'linux')
+ * @param arch - Architecture identifier (e.g., 'arm64', 'x64')
+ * @returns Download URL for the binary
+ */
+export function getBinaryUrl(version, platform, arch) {
+    const platformKey = `${platform}-${arch}`;
+    const hostdbPlatform = getHostdbPlatform(platform, arch);
+    if (!hostdbPlatform) {
+        const supported = Array.from(SUPPORTED_PLATFORMS).join(', ');
+        throw new Error(`Unsupported platform: ${platformKey}. Supported platforms: ${supported}`);
+    }
+    // Normalize version (handles major version lookup)
+    const fullVersion = normalizeVersion(version, CLICKHOUSE_VERSION_MAP);
+    // ClickHouse on hostdb uses tar.gz for all platforms (no Windows support)
+    return buildHostdbUrl(Engine.ClickHouse, {
+        version: fullVersion,
+        hostdbPlatform,
+        extension: 'tar.gz',
+    });
+}
+/**
+ * Normalize version string to full version format
+ *
+ * @param version - Version string (e.g., '25.12', '25.12.3', '25.12.3.21')
+ * @param versionMap - Optional version map for version lookup
+ * @returns Normalized version (e.g., '25.12.3.21')
+ */
+function normalizeVersion(version, versionMap = CLICKHOUSE_VERSION_MAP) {
+    // Check if it's an exact key in the map
+    if (versionMap[version]) {
+        return versionMap[version];
+    }
+    const parts = version.split('.');
+    // If it's already a full version (4 parts), return as-is
+    if (parts.length === 4) {
+        return version;
+    }
+    // For partial versions, try to find a match
+    if (parts.length === 3) {
+        // Try YY.MM.X format
+        const threePart = `${parts[0]}.${parts[1]}.${parts[2]}`;
+        if (versionMap[threePart]) {
+            return versionMap[threePart];
+        }
+    }
+    if (parts.length === 2) {
+        // Try YY.MM format
+        const twoPart = `${parts[0]}.${parts[1]}`;
+        if (versionMap[twoPart]) {
+            return versionMap[twoPart];
+        }
+    }
+    // Unknown version format - log and return as-is
+    logDebug(`ClickHouse version '${version}' not in version map, may not be available in hostdb`);
+    return version;
+}
+/**
+ * Get the full version string for a version
+ *
+ * Supports partial version lookups (e.g., '25.12' -> '25.12.3.21')
+ * by delegating to normalizeVersion for consistent behavior.
+ *
+ * @param version - Version (e.g., '25.12', '25.12.3.21')
+ * @returns Full version string (e.g., '25.12.3.21') or null if not in version map
+ */
+//# sourceMappingURL=binary-urls.js.map

package/dist/engines/clickhouse/binary-urls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-urls.js","sourceRoot":"","sources":["../../../engines/clickhouse/binary-urls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACnD,OAAO,EAAE,MAAM,EAA4B,MAAM,aAAa,CAAA;AAE9D;;;GAGG;AACH,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC;IAClC,cAAc;IACd,YAAY;IACZ,aAAa;IACb,WAAW;CACZ,CAAC,CAAA;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAkB,EAClB,IAAU;IAEV,MAAM,GAAG,GAAG,GAAG,QAAQ,IAAI,IAAI,EAAE,CAAA;IACjC,OAAO,mBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAA;AAClD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,OAAe,EACf,QAAkB,EAClB,IAAU;IAEV,MAAM,WAAW,GAAG,GAAG,QAAQ,IAAI,IAAI,EAAE,CAAA;IACzC,MAAM,cAAc,GAAG,iBAAiB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;IACxD,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC5D,MAAM,IAAI,KAAK,CACb,yBAAyB,WAAW,0BAA0B,SAAS,EAAE,CAC1E,CAAA;IACH,CAAC;IAED,mDAAmD;IACnD,MAAM,WAAW,GAAG,gBAAgB,CAAC,OAAO,EAAE,sBAAsB,CAAC,CAAA;IAErE,0EAA0E;IAC1E,OAAO,cAAc,CAAC,MAAM,CAAC,UAAU,EAAE;QACvC,OAAO,EAAE,WAAW;QACpB,cAAc;QACd,SAAS,EAAE,QAAQ;KACpB,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAS,gBAAgB,CACvB,OAAe,EACf,aAAqC,sBAAsB;IAE3D,wCAAwC;IACxC,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACxB,OAAO,UAAU,CAAC,OAAO,CAAC,CAAA;IAC5B,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAEhC,yDAAyD;IACzD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,OAAO,CAAA;IAChB,CAAC;IAED,4CAA4C;IAC5C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,qBAAqB;QACrB,MAAM,SAAS,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAA;QACvD,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC1B,OAAO,UAAU,CAAC,SAAS,CAAC,CAAA;QAC9B,CAAC;IACH,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,mBAAmB;QACnB,MAAM,OAAO,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAA;QACzC,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACxB,OAAO,UAAU,CAAC,OAAO,CAAC,CAAA;QAC5B,CAAC;IACH,CAAC;IAED,gDAAgD;IAChD,QAAQ,CACN,uBAAuB,OAAO,sDAAsD,CACrF,CAAA;IACD,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;;;;;GAQG"}