crewly 1.0.0

package/dist/backend/backend/src/utils/file-io.utils.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Centralized Atomic File I/O Utilities
+ *
+ * Provides safe, atomic file operations for all JSON persistence in Crewly.
+ * Uses temp-file + fsync + rename to prevent corruption on crash,
+ * and in-process locks to serialize concurrent writes to the same file.
+ *
+ * @module utils/file-io.utils
+ */
+/**
+ * Minimal logger interface accepted by safeReadJson / modifyJsonFile.
+ * Compatible with ComponentLogger from LoggerService.
+ */
+export interface FileIOLogger {
+    warn(message: string, meta?: Record<string, unknown>): void;
+    debug?(message: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Ensures a directory exists, creating it recursively if necessary.
+ *
+ * @param dirPath - Absolute path to the directory
+ */
+export declare function ensureDir(dirPath: string): Promise<void>;
+/**
+ * Serialize concurrent writes to the same file.
+ *
+ * @param lockKey - Unique key for the lock (typically the file path)
+ * @param operation - Async operation to run while holding the lock
+ * @returns The result of the operation
+ */
+export declare function withFileLock<T>(lockKey: string, operation: () => Promise<T>): Promise<T>;
+/**
+ * Serialize read-modify-write cycles on a logical resource.
+ *
+ * Uses a separate lock map from {@link withFileLock} so that callers
+ * can hold an operation lock across a read + write without deadlocking
+ * on the inner file lock.
+ *
+ * @param lockKey - Unique key for the lock
+ * @param operation - Async operation to run while holding the lock
+ * @returns The result of the operation
+ */
+export declare function withOperationLock<T>(lockKey: string, operation: () => Promise<T>): Promise<T>;
+/**
+ * Write a string to a file atomically (temp file → fsync → rename).
+ *
+ * Acquires a per-path file lock so concurrent callers targeting the
+ * same path are serialized.
+ *
+ * **Precondition:** The parent directory must already exist. This function
+ * does not create intermediate directories — use {@link ensureDir} first
+ * if the directory may not exist.
+ *
+ * @param filePath - Destination file path
+ * @param content - String content to write
+ */
+export declare function atomicWriteFile(filePath: string, content: string): Promise<void>;
+/**
+ * Serialize a JavaScript value to JSON and write it atomically.
+ *
+ * @param filePath - Destination file path
+ * @param data - Value to serialize (via `JSON.stringify`)
+ */
+export declare function atomicWriteJson<T>(filePath: string, data: T): Promise<void>;
+/**
+ * Read and parse a JSON file safely.
+ *
+ * - On `ENOENT` → returns `defaultValue` silently.
+ * - On parse error → backs up the corrupt file as `<path>.corrupt.<ts>`
+ *   and returns `defaultValue`.
+ *
+ * @param filePath - Path to the JSON file
+ * @param defaultValue - Value to return when the file is missing or corrupt
+ * @param logger - Optional logger for warnings on corruption
+ * @returns Parsed value or `defaultValue`
+ */
+export declare function safeReadJson<T>(filePath: string, defaultValue: T, logger?: FileIOLogger): Promise<T>;
+/**
+ * Locked read → mutate → atomic write cycle.
+ *
+ * This is the most common persistence pattern: load a JSON file,
+ * apply a mutation, and write it back atomically — all while holding
+ * an operation lock to prevent concurrent read-modify-write races.
+ *
+ * **Important:** If the mutator returns `undefined` (void), the mutated
+ * `data` object is written back. If it returns any other value — including
+ * falsy values like `null`, `0`, or `false` — that value is written instead.
+ * Beware of methods like `Array.push()` which return a number: an accidental
+ * `return records.push(item)` will write the array length to the file.
+ *
+ * @param filePath - Path to the JSON file
+ * @param defaultValue - Value to use if the file is missing or corrupt
+ * @param mutator - Function that receives the current data and mutates it in place (or returns new data)
+ * @param logger - Optional logger
+ * @returns The value returned by `mutator` (or void)
+ */
+export declare function modifyJsonFile<T, R = void>(filePath: string, defaultValue: T, mutator: (data: T) => R | Promise<R>, logger?: FileIOLogger): Promise<R>;
+/**
+ * Reset all lock maps. **Test-only** — never call in production.
+ */
+export declare function _clearAllLocks(): void;
+//# sourceMappingURL=file-io.utils.d.ts.map

package/dist/backend/backend/src/utils/file-io.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-io.utils.d.ts","sourceRoot":"","sources":["../../../../../backend/src/utils/file-io.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC/D;AAaD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9D;AAuCD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAE9F;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEnG;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBtF;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjF;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,CAyB1G;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,EAC9C,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,CAAC,EACf,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EACpC,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,CAAC,CAAC,CAUZ;AAMD;;GAEG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAGrC"}

package/dist/backend/backend/src/utils/file-io.utils.js

@@ -0,0 +1,214 @@
+/**
+ * Centralized Atomic File I/O Utilities
+ *
+ * Provides safe, atomic file operations for all JSON persistence in Crewly.
+ * Uses temp-file + fsync + rename to prevent corruption on crash,
+ * and in-process locks to serialize concurrent writes to the same file.
+ *
+ * @module utils/file-io.utils
+ */
+import * as fs from 'fs/promises';
+// ──────────────────────────────────────────────────────────────────────
+//  Module-level lock maps (singleton per process — no class needed)
+// ──────────────────────────────────────────────────────────────────────
+const fileLocks = new Map();
+const operationLocks = new Map();
+// ──────────────────────────────────────────────────────────────────────
+//  Directory helpers
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * Ensures a directory exists, creating it recursively if necessary.
+ *
+ * @param dirPath - Absolute path to the directory
+ */
+export async function ensureDir(dirPath) {
+    await fs.mkdir(dirPath, { recursive: true });
+}
+// ──────────────────────────────────────────────────────────────────────
+//  Locking
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * Acquire and hold a lock from the given map for the duration of the operation.
+ *
+ * Uses promise-chaining so each caller queues behind the previous one.
+ * This avoids the race condition where multiple awaiters of the same
+ * promise all wake up and proceed past a `while` check simultaneously.
+ */
+async function withLock(lockMap, lockKey, operation) {
+    // Chain behind whatever is currently queued (or resolve immediately)
+    const prevLock = lockMap.get(lockKey) ?? Promise.resolve();
+    let releaseLock;
+    const myLock = new Promise((resolve) => { releaseLock = resolve; });
+    lockMap.set(lockKey, myLock);
+    // Wait for the previous holder to finish
+    await prevLock;
+    try {
+        return await operation();
+    }
+    finally {
+        releaseLock();
+        // Only clean up if we're still the tail of the chain
+        if (lockMap.get(lockKey) === myLock) {
+            lockMap.delete(lockKey);
+        }
+    }
+}
+/**
+ * Serialize concurrent writes to the same file.
+ *
+ * @param lockKey - Unique key for the lock (typically the file path)
+ * @param operation - Async operation to run while holding the lock
+ * @returns The result of the operation
+ */
+export async function withFileLock(lockKey, operation) {
+    return withLock(fileLocks, lockKey, operation);
+}
+/**
+ * Serialize read-modify-write cycles on a logical resource.
+ *
+ * Uses a separate lock map from {@link withFileLock} so that callers
+ * can hold an operation lock across a read + write without deadlocking
+ * on the inner file lock.
+ *
+ * @param lockKey - Unique key for the lock
+ * @param operation - Async operation to run while holding the lock
+ * @returns The result of the operation
+ */
+export async function withOperationLock(lockKey, operation) {
+    return withLock(operationLocks, lockKey, operation);
+}
+// ──────────────────────────────────────────────────────────────────────
+//  Atomic write
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * Write a string to a file atomically (temp file → fsync → rename).
+ *
+ * Acquires a per-path file lock so concurrent callers targeting the
+ * same path are serialized.
+ *
+ * **Precondition:** The parent directory must already exist. This function
+ * does not create intermediate directories — use {@link ensureDir} first
+ * if the directory may not exist.
+ *
+ * @param filePath - Destination file path
+ * @param content - String content to write
+ */
+export async function atomicWriteFile(filePath, content) {
+    await withFileLock(filePath, async () => {
+        const tempPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).substring(2)}`;
+        try {
+            await fs.writeFile(tempPath, content, 'utf8');
+            // Ensure data hits the disk before the atomic rename
+            const handle = await fs.open(tempPath, 'r+');
+            await handle.sync();
+            await handle.close();
+            await fs.rename(tempPath, filePath);
+        }
+        catch (error) {
+            // Clean up temp file on failure
+            try {
+                await fs.unlink(tempPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            throw error;
+        }
+    });
+}
+/**
+ * Serialize a JavaScript value to JSON and write it atomically.
+ *
+ * @param filePath - Destination file path
+ * @param data - Value to serialize (via `JSON.stringify`)
+ */
+export async function atomicWriteJson(filePath, data) {
+    await atomicWriteFile(filePath, JSON.stringify(data, null, 2));
+}
+// ──────────────────────────────────────────────────────────────────────
+//  Safe read
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * Read and parse a JSON file safely.
+ *
+ * - On `ENOENT` → returns `defaultValue` silently.
+ * - On parse error → backs up the corrupt file as `<path>.corrupt.<ts>`
+ *   and returns `defaultValue`.
+ *
+ * @param filePath - Path to the JSON file
+ * @param defaultValue - Value to return when the file is missing or corrupt
+ * @param logger - Optional logger for warnings on corruption
+ * @returns Parsed value or `defaultValue`
+ */
+export async function safeReadJson(filePath, defaultValue, logger) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf-8');
+    }
+    catch (error) {
+        // File does not exist — totally normal, return default
+        if (error.code === 'ENOENT') {
+            return defaultValue;
+        }
+        throw error; // Permission errors etc. should bubble
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        // Corrupt JSON — back up the file so we can debug later
+        const backupPath = `${filePath}.corrupt.${Date.now()}`;
+        try {
+            await fs.copyFile(filePath, backupPath);
+            logger?.warn('Backed up corrupt JSON file', { filePath, backupPath });
+        }
+        catch {
+            logger?.warn('Failed to back up corrupt JSON file', { filePath });
+        }
+        return defaultValue;
+    }
+}
+// ──────────────────────────────────────────────────────────────────────
+//  Read-modify-write helper
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * Locked read → mutate → atomic write cycle.
+ *
+ * This is the most common persistence pattern: load a JSON file,
+ * apply a mutation, and write it back atomically — all while holding
+ * an operation lock to prevent concurrent read-modify-write races.
+ *
+ * **Important:** If the mutator returns `undefined` (void), the mutated
+ * `data` object is written back. If it returns any other value — including
+ * falsy values like `null`, `0`, or `false` — that value is written instead.
+ * Beware of methods like `Array.push()` which return a number: an accidental
+ * `return records.push(item)` will write the array length to the file.
+ *
+ * @param filePath - Path to the JSON file
+ * @param defaultValue - Value to use if the file is missing or corrupt
+ * @param mutator - Function that receives the current data and mutates it in place (or returns new data)
+ * @param logger - Optional logger
+ * @returns The value returned by `mutator` (or void)
+ */
+export async function modifyJsonFile(filePath, defaultValue, mutator, logger) {
+    return withOperationLock(filePath, async () => {
+        const data = await safeReadJson(filePath, defaultValue, logger);
+        const result = await mutator(data);
+        // If mutator returns undefined (void), write the mutated data in place;
+        // otherwise write the returned value (including null, 0, false, etc.)
+        const toWrite = result === undefined ? data : result;
+        await atomicWriteJson(filePath, toWrite);
+        return result;
+    });
+}
+// ──────────────────────────────────────────────────────────────────────
+//  Test helper
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * Reset all lock maps. **Test-only** — never call in production.
+ */
+export function _clearAllLocks() {
+    fileLocks.clear();
+    operationLocks.clear();
+}
+//# sourceMappingURL=file-io.utils.js.map

package/dist/backend/backend/src/utils/file-io.utils.js.map

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

package/dist/backend/backend/src/utils/package-root.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Finds the Crewly package root by walking up from the given directory,
+ * looking for a package.json with `"name": "crewly"`.
+ *
+ * This works correctly in both development mode (where source lives at backend/src/)
+ * and compiled/npm-installed mode (where code lives at dist/backend/backend/src/).
+ * The naive `path.resolve(__dirname, '../..')` approach breaks in compiled mode
+ * because the directory depth differs.
+ *
+ * @param startDir - Directory to start searching from (typically the caller's __dirname).
+ * @returns The absolute path to the package root directory.
+ * @throws Error if no matching package.json is found after reaching the filesystem root.
+ */
+export declare function findPackageRoot(startDir: string): string;
+//# sourceMappingURL=package-root.d.ts.map

package/dist/backend/backend/src/utils/package-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-root.d.ts","sourceRoot":"","sources":["../../../../../backend/src/utils/package-root.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAwBxD"}

package/dist/backend/backend/src/utils/package-root.js

@@ -0,0 +1,38 @@
+import path from 'path';
+import { readFileSync, existsSync } from 'fs';
+/**
+ * Finds the Crewly package root by walking up from the given directory,
+ * looking for a package.json with `"name": "crewly"`.
+ *
+ * This works correctly in both development mode (where source lives at backend/src/)
+ * and compiled/npm-installed mode (where code lives at dist/backend/backend/src/).
+ * The naive `path.resolve(__dirname, '../..')` approach breaks in compiled mode
+ * because the directory depth differs.
+ *
+ * @param startDir - Directory to start searching from (typically the caller's __dirname).
+ * @returns The absolute path to the package root directory.
+ * @throws Error if no matching package.json is found after reaching the filesystem root.
+ */
+export function findPackageRoot(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        const pkgPath = path.join(current, 'package.json');
+        if (existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+                if (pkg.name === 'crewly') {
+                    return current;
+                }
+            }
+            catch {
+                // Malformed package.json — keep searching
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            throw new Error('Could not find Crewly package root (no package.json with name "crewly" found in any parent directory)');
+        }
+        current = parent;
+    }
+}
+//# sourceMappingURL=package-root.js.map

package/dist/backend/backend/src/utils/package-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-root.js","sourceRoot":"","sources":["../../../../../backend/src/utils/package-root.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAE9C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC/C,IAAI,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAErC,OAAO,IAAI,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;QACnD,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC;gBACJ,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;gBACvD,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBAC3B,OAAO,OAAO,CAAC;gBAChB,CAAC;YACF,CAAC;YAAC,MAAM,CAAC;gBACR,0CAA0C;YAC3C,CAAC;QACF,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CACd,uGAAuG,CACvG,CAAC;QACH,CAAC;QACD,OAAO,GAAG,MAAM,CAAC;IAClB,CAAC;AACF,CAAC"}

package/dist/backend/backend/src/utils/process-recovery.d.ts

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { EventEmitter } from 'events';
+/**
+ * ProcessRecovery manages automatic restart and monitoring of the Crewly backend process
+ *
+ * Features:
+ * - Automatic restart on crashes
+ * - Memory usage monitoring
+ * - Port conflict detection and resolution
+ * - Exponential backoff for restart attempts
+ * - Health checks and process monitoring
+ *
+ * @example
+ * ```typescript
+ * const recovery = new ProcessRecovery();
+ * await recovery.start();
+ * ```
+ */
+export declare class ProcessRecovery extends EventEmitter {
+    private childProcess;
+    private restartCount;
+    private maxRestarts;
+    private baseRetryDelay;
+    private maxRetryDelay;
+    private isShuttingDown;
+    private healthCheckInterval;
+    private memoryMonitorInterval;
+    private processStartTime;
+    private minRuntime;
+    constructor();
+    /**
+     * Start the backend process with recovery monitoring
+     *
+     * @returns Promise that resolves when the process recovery system is started
+     */
+    start(): Promise<void>;
+    /**
+     * Start the backend process
+     *
+     * @returns Promise that resolves when the process is started
+     */
+    private startBackendProcess;
+    /**
+     * Handle process exit and determine if restart is needed
+     *
+     * @param code - Exit code of the process
+     * @param signal - Signal that killed the process
+     * @param runtime - How long the process ran
+     */
+    private handleProcessExit;
+    /**
+     * Start health checks for the backend process
+     */
+    private startHealthChecks;
+    /**
+     * Start memory monitoring for early detection of memory leaks
+     */
+    private startMemoryMonitoring;
+    /**
+     * Setup signal handlers for graceful shutdown
+     */
+    private setupSignalHandlers;
+    /**
+     * Gracefully shutdown the recovery system and backend process
+     *
+     * @param signal - Signal that triggered the shutdown
+     */
+    shutdown(signal?: string): Promise<void>;
+    /**
+     * Get current status of the backend process
+     *
+     * @returns Status information about the backend process
+     */
+    getStatus(): {
+        isRunning: boolean;
+        pid: number | undefined;
+        restartCount: number;
+        runtime: number;
+    };
+}
+//# sourceMappingURL=process-recovery.d.ts.map

package/dist/backend/backend/src/utils/process-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-recovery.d.ts","sourceRoot":"","sources":["../../../../../backend/src/utils/process-recovery.ts"],"names":[],"mappings":";AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAGtC;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,eAAgB,SAAQ,YAAY;IAChD,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,aAAa,CAAiB;IACtC,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,mBAAmB,CAA+B;IAC1D,OAAO,CAAC,qBAAqB,CAA+B;IAC5D,OAAO,CAAC,gBAAgB,CAAa;IACrC,OAAO,CAAC,UAAU,CAAiB;;IAOnC;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAU5B;;;;OAIG;YACW,mBAAmB;IA4EjC;;;;;;OAMG;YACW,iBAAiB;IA0C/B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAuBzB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAgB7B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAe3B;;;;OAIG;IACG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwC9C;;;;OAIG;IACH,SAAS,IAAI;QACZ,SAAS,EAAE,OAAO,CAAC;QACnB,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;QACxB,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;KAChB;CAQD"}