agents-reverse-engineer 0.3.6 → 0.4.0

package/dist/ai/registry.js

@@ -0,0 +1,192 @@
+/**
+ * Backend registry, factory, and auto-detection.
+ *
+ * Manages the set of registered AI CLI backends, selects the appropriate
+ * backend at runtime via auto-detection or explicit request, and provides
+ * actionable error messages when no CLI is found.
+ *
+ * @module
+ */
+import { AIServiceError } from './types.js';
+import { ClaudeBackend } from './backends/claude.js';
+import { GeminiBackend } from './backends/gemini.js';
+import { OpenCodeBackend } from './backends/opencode.js';
+// ---------------------------------------------------------------------------
+// Backend registry
+// ---------------------------------------------------------------------------
+/**
+ * Registry of available AI CLI backends.
+ *
+ * Stores backends in insertion order, which determines the priority for
+ * auto-detection. Use {@link createBackendRegistry} to get a pre-populated
+ * registry with all supported backends.
+ *
+ * @example
+ * ```typescript
+ * const registry = createBackendRegistry();
+ * const claude = registry.get('claude');
+ * const all = registry.getAll(); // [ClaudeBackend, GeminiBackend, OpenCodeBackend]
+ * ```
+ */
+export class BackendRegistry {
+    backends = new Map();
+    /**
+     * Register a backend adapter.
+     *
+     * @param backend - The backend to register (keyed by its `name` property)
+     */
+    register(backend) {
+        this.backends.set(backend.name, backend);
+    }
+    /**
+     * Get a specific backend by name.
+     *
+     * @param name - The backend name (e.g., "claude", "gemini", "opencode")
+     * @returns The backend, or `undefined` if not registered
+     */
+    get(name) {
+        return this.backends.get(name);
+    }
+    /**
+     * Get all registered backends in priority order.
+     *
+     * @returns Array of all registered backends
+     */
+    getAll() {
+        return Array.from(this.backends.values());
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a new backend registry pre-populated with all supported backends.
+ *
+ * Registration order determines auto-detection priority:
+ * 1. Claude (recommended, fully implemented)
+ * 2. Gemini (experimental, stub)
+ * 3. OpenCode (experimental, stub)
+ *
+ * @returns A populated {@link BackendRegistry}
+ *
+ * @example
+ * ```typescript
+ * const registry = createBackendRegistry();
+ * const backend = await detectBackend(registry);
+ * ```
+ */
+export function createBackendRegistry() {
+    const registry = new BackendRegistry();
+    registry.register(new ClaudeBackend());
+    registry.register(new GeminiBackend());
+    registry.register(new OpenCodeBackend());
+    return registry;
+}
+// ---------------------------------------------------------------------------
+// Auto-detection
+// ---------------------------------------------------------------------------
+/**
+ * Detect the first available backend on PATH in priority order.
+ *
+ * Iterates all registered backends and calls `isAvailable()` on each.
+ * Returns the first backend whose CLI is found, or `null` if none are
+ * available.
+ *
+ * Priority order is determined by registration order in
+ * {@link createBackendRegistry}: Claude > Gemini > OpenCode.
+ *
+ * @param registry - The backend registry to search
+ * @returns The first available backend, or `null` if none found
+ *
+ * @example
+ * ```typescript
+ * const registry = createBackendRegistry();
+ * const backend = await detectBackend(registry);
+ * if (backend) {
+ *   console.log(`Using ${backend.name} backend`);
+ * }
+ * ```
+ */
+export async function detectBackend(registry) {
+    for (const backend of registry.getAll()) {
+        if (await backend.isAvailable()) {
+            return backend;
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Install instructions
+// ---------------------------------------------------------------------------
+/**
+ * Get formatted install instructions for all registered backends.
+ *
+ * Returns a multi-line string suitable for error messages when no CLI
+ * is found. Matches the error message template from RESEARCH.md.
+ *
+ * @param registry - The backend registry
+ * @returns Formatted install instructions string
+ *
+ * @example
+ * ```typescript
+ * const instructions = getInstallInstructions(registry);
+ * console.error(`No AI CLI found.\n\nInstall one of the following:\n\n${instructions}`);
+ * ```
+ */
+export function getInstallInstructions(registry) {
+    return registry
+        .getAll()
+        .map((backend) => backend.getInstallInstructions())
+        .join('\n\n');
+}
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a backend by name or auto-detect the best available one.
+ *
+ * - If `requested` is `'auto'`: runs {@link detectBackend} and throws with
+ *   install instructions if nothing is found.
+ * - If `requested` is a specific name: looks it up in the registry, checks
+ *   availability, and throws if not found or not available.
+ *
+ * @param registry - The backend registry
+ * @param requested - Backend name or `'auto'` for auto-detection
+ * @returns The resolved backend adapter
+ * @throws {AIServiceError} With code `CLI_NOT_FOUND` if no backend is available
+ *
+ * @example
+ * ```typescript
+ * const registry = createBackendRegistry();
+ *
+ * // Auto-detect
+ * const backend = await resolveBackend(registry, 'auto');
+ *
+ * // Explicit selection
+ * const claude = await resolveBackend(registry, 'claude');
+ * ```
+ */
+export async function resolveBackend(registry, requested) {
+    if (requested === 'auto') {
+        const detected = await detectBackend(registry);
+        if (detected) {
+            return detected;
+        }
+        const instructions = getInstallInstructions(registry);
+        throw new AIServiceError('CLI_NOT_FOUND', `No AI CLI found on your system.\n\nInstall one of the following:\n\n${instructions}\n\nThen run this command again.`);
+    }
+    // Explicit backend requested
+    const backend = registry.get(requested);
+    if (!backend) {
+        const known = registry
+            .getAll()
+            .map((b) => b.name)
+            .join(', ');
+        throw new AIServiceError('CLI_NOT_FOUND', `Unknown backend "${requested}". Available backends: ${known}`);
+    }
+    if (!(await backend.isAvailable())) {
+        throw new AIServiceError('CLI_NOT_FOUND', `Backend "${requested}" is not available. The "${backend.cliCommand}" CLI was not found on PATH.\n\n${backend.getInstallInstructions()}`);
+    }
+    return backend;
+}
+//# sourceMappingURL=registry.js.map

package/dist/ai/registry.js.map

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

package/dist/ai/retry.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Retry utility with exponential backoff for transient AI service failures.
+ *
+ * Wraps any async operation with configurable retry logic. Uses exponential
+ * delays with jitter to prevent thundering herd when multiple callers hit
+ * the same rate limit.
+ *
+ * @module
+ */
+import type { RetryOptions } from './types.js';
+/**
+ * Default retry configuration values.
+ *
+ * Does NOT include `isRetryable` or `onRetry` since those are
+ * caller-specific. Spread these defaults and provide your own predicates:
+ *
+ * @example
+ * ```typescript
+ * import { withRetry, DEFAULT_RETRY_OPTIONS } from './retry.js';
+ * import { AIServiceError } from './types.js';
+ *
+ * const result = await withRetry(() => callAI(prompt), {
+ *   ...DEFAULT_RETRY_OPTIONS,
+ *   isRetryable: (err) => err instanceof AIServiceError && err.code === 'RATE_LIMIT',
+ *   onRetry: (attempt, err) => console.warn(`Retry ${attempt}:`, err),
+ * });
+ * ```
+ */
+export declare const DEFAULT_RETRY_OPTIONS: {
+    /** Maximum number of retries (3 retries = 4 total attempts) */
+    readonly maxRetries: 3;
+    /** Base delay before first retry: 1 second */
+    readonly baseDelayMs: 1000;
+    /** Maximum delay cap: 8 seconds */
+    readonly maxDelayMs: 8000;
+    /** Exponential multiplier: delay doubles each attempt */
+    readonly multiplier: 2;
+};
+/**
+ * Execute an async function with exponential backoff retry on failure.
+ *
+ * - On success: returns the result immediately.
+ * - On transient failure (isRetryable returns true): waits with exponential
+ *   backoff + jitter, then retries up to `maxRetries` times.
+ * - On permanent failure (isRetryable returns false): throws immediately
+ *   without retrying.
+ * - After exhausting all retries: throws the last error.
+ *
+ * Delay formula: `min(baseDelayMs * multiplier^attempt, maxDelayMs) + jitter`
+ * where jitter is a random value in [0, 500ms].
+ *
+ * @typeParam T - The return type of the wrapped function
+ * @param fn - Async function to execute (and potentially retry)
+ * @param options - Retry configuration including backoff timing and predicates
+ * @returns The result of a successful `fn()` invocation
+ * @throws The last error if all retry attempts are exhausted or if the error is not retryable
+ *
+ * @example
+ * ```typescript
+ * import { withRetry } from './retry.js';
+ *
+ * // Retry up to 3 times on rate limit errors
+ * const response = await withRetry(
+ *   () => runAICall(prompt),
+ *   {
+ *     maxRetries: 3,
+ *     baseDelayMs: 1000,
+ *     maxDelayMs: 8000,
+ *     multiplier: 2,
+ *     isRetryable: (err) => isRateLimitError(err),
+ *     onRetry: (attempt, err) => logger.warn(`Attempt ${attempt} failed, retrying...`),
+ *   },
+ * );
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/ai/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/ai/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB;IAChC,+DAA+D;;IAE/D,8CAA8C;;IAE9C,mCAAmC;;IAEnC,yDAAyD;;CAEO,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,CAAC,CAAC,CA4BZ"}

package/dist/ai/retry.js

@@ -0,0 +1,100 @@
+/**
+ * Retry utility with exponential backoff for transient AI service failures.
+ *
+ * Wraps any async operation with configurable retry logic. Uses exponential
+ * delays with jitter to prevent thundering herd when multiple callers hit
+ * the same rate limit.
+ *
+ * @module
+ */
+/**
+ * Default retry configuration values.
+ *
+ * Does NOT include `isRetryable` or `onRetry` since those are
+ * caller-specific. Spread these defaults and provide your own predicates:
+ *
+ * @example
+ * ```typescript
+ * import { withRetry, DEFAULT_RETRY_OPTIONS } from './retry.js';
+ * import { AIServiceError } from './types.js';
+ *
+ * const result = await withRetry(() => callAI(prompt), {
+ *   ...DEFAULT_RETRY_OPTIONS,
+ *   isRetryable: (err) => err instanceof AIServiceError && err.code === 'RATE_LIMIT',
+ *   onRetry: (attempt, err) => console.warn(`Retry ${attempt}:`, err),
+ * });
+ * ```
+ */
+export const DEFAULT_RETRY_OPTIONS = {
+    /** Maximum number of retries (3 retries = 4 total attempts) */
+    maxRetries: 3,
+    /** Base delay before first retry: 1 second */
+    baseDelayMs: 1_000,
+    /** Maximum delay cap: 8 seconds */
+    maxDelayMs: 8_000,
+    /** Exponential multiplier: delay doubles each attempt */
+    multiplier: 2,
+};
+/**
+ * Execute an async function with exponential backoff retry on failure.
+ *
+ * - On success: returns the result immediately.
+ * - On transient failure (isRetryable returns true): waits with exponential
+ *   backoff + jitter, then retries up to `maxRetries` times.
+ * - On permanent failure (isRetryable returns false): throws immediately
+ *   without retrying.
+ * - After exhausting all retries: throws the last error.
+ *
+ * Delay formula: `min(baseDelayMs * multiplier^attempt, maxDelayMs) + jitter`
+ * where jitter is a random value in [0, 500ms].
+ *
+ * @typeParam T - The return type of the wrapped function
+ * @param fn - Async function to execute (and potentially retry)
+ * @param options - Retry configuration including backoff timing and predicates
+ * @returns The result of a successful `fn()` invocation
+ * @throws The last error if all retry attempts are exhausted or if the error is not retryable
+ *
+ * @example
+ * ```typescript
+ * import { withRetry } from './retry.js';
+ *
+ * // Retry up to 3 times on rate limit errors
+ * const response = await withRetry(
+ *   () => runAICall(prompt),
+ *   {
+ *     maxRetries: 3,
+ *     baseDelayMs: 1000,
+ *     maxDelayMs: 8000,
+ *     multiplier: 2,
+ *     isRetryable: (err) => isRateLimitError(err),
+ *     onRetry: (attempt, err) => logger.warn(`Attempt ${attempt} failed, retrying...`),
+ *   },
+ * );
+ * ```
+ */
+export async function withRetry(fn, options) {
+    for (let attempt = 0; attempt <= options.maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            // If we've exhausted retries or the error is permanent, throw immediately.
+            if (attempt === options.maxRetries || !options.isRetryable(error)) {
+                throw error;
+            }
+            // Compute exponential delay with cap.
+            const exponentialDelay = options.baseDelayMs * Math.pow(options.multiplier, attempt);
+            const cappedDelay = Math.min(exponentialDelay, options.maxDelayMs);
+            // Add jitter (0-500ms) to prevent thundering herd.
+            const jitter = Math.random() * 500;
+            const delay = cappedDelay + jitter;
+            // Notify caller before waiting.
+            options.onRetry?.(attempt + 1, error);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+    // This is unreachable -- the loop either returns or throws.
+    // TypeScript needs it for exhaustiveness.
+    throw new Error('withRetry: unreachable');
+}
+//# sourceMappingURL=retry.js.map

package/dist/ai/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/ai/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,+DAA+D;IAC/D,UAAU,EAAE,CAAC;IACb,8CAA8C;IAC9C,WAAW,EAAE,KAAK;IAClB,mCAAmC;IACnC,UAAU,EAAE,KAAK;IACjB,yDAAyD;IACzD,UAAU,EAAE,CAAC;CACmD,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAoB,EACpB,OAAqB;IAErB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,OAAO,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QAC/D,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,2EAA2E;YAC3E,IAAI,OAAO,KAAK,OAAO,CAAC,UAAU,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;gBAClE,MAAM,KAAK,CAAC;YACd,CAAC;YAED,sCAAsC;YACtC,MAAM,gBAAgB,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;YACrF,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;YAEnE,mDAAmD;YACnD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC;YACnC,MAAM,KAAK,GAAG,WAAW,GAAG,MAAM,CAAC;YAEnC,gCAAgC;YAChC,OAAO,CAAC,OAAO,EAAE,CAAC,OAAO,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;YAEtC,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IAED,4DAA4D;IAC5D,0CAA0C;IAC1C,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;AAC5C,CAAC"}

package/dist/ai/service.d.ts

@@ -0,0 +1,124 @@
+/**
+ * AI service orchestrator.
+ *
+ * The {@link AIService} class is the main entry point for making AI calls.
+ * It ties together the subprocess wrapper, retry logic, backend selection,
+ * and telemetry logging into a clean `call()` method.
+ *
+ * @module
+ */
+import type { AIBackend, AICallOptions, AIResponse, RunLog, FileRead } from './types.js';
+import type { ModelPricing } from './pricing.js';
+/**
+ * Configuration options for the {@link AIService}.
+ *
+ * These are typically sourced from the config schema's `ai` section.
+ */
+export interface AIServiceOptions {
+    /** Default subprocess timeout in milliseconds */
+    timeoutMs: number;
+    /** Maximum number of retries for transient errors */
+    maxRetries: number;
+    /** Telemetry settings */
+    telemetry: {
+        /** Number of most recent run logs to keep on disk */
+        keepRuns: number;
+        /** Optional cost threshold in USD. Warn when exceeded. */
+        costThresholdUsd?: number;
+    };
+    /** Custom pricing overrides from config */
+    pricingOverrides?: Record<string, ModelPricing>;
+}
+/**
+ * Orchestrates AI CLI calls with retry, timeout, and telemetry.
+ *
+ * Create one instance per CLI run. Call {@link call} for each AI invocation.
+ * Call {@link finalize} at the end to write the run log and clean up old files.
+ *
+ * @example
+ * ```typescript
+ * import { AIService } from './service.js';
+ * import { resolveBackend, createBackendRegistry } from './registry.js';
+ *
+ * const registry = createBackendRegistry();
+ * const backend = await resolveBackend(registry, 'auto');
+ * const service = new AIService(backend, {
+ *   timeoutMs: 120_000,
+ *   maxRetries: 3,
+ *   telemetry: { keepRuns: 10 },
+ * });
+ *
+ * const response = await service.call({ prompt: 'Summarize this codebase' });
+ * console.log(response.text);
+ *
+ * const { logPath, summary } = await service.finalize('/path/to/project');
+ * console.log(`Log written to ${logPath}, cost: $${summary.totalCostUsd}`);
+ * ```
+ */
+export declare class AIService {
+    /** The backend adapter used for CLI invocations */
+    private readonly backend;
+    /** Service configuration */
+    private readonly options;
+    /** In-memory telemetry logger for this run */
+    private readonly logger;
+    /** Running count of calls made (used for entry tracking) */
+    private callCount;
+    /** Set of model IDs for which an unknown-pricing warning has already been emitted */
+    private readonly warnedModels;
+    /**
+     * Create a new AI service instance.
+     *
+     * @param backend - The resolved backend adapter
+     * @param options - Service configuration (timeout, retries, telemetry)
+     */
+    constructor(backend: AIBackend, options: AIServiceOptions);
+    /**
+     * Make an AI call with retry logic and telemetry recording.
+     *
+     * The call flow:
+     * 1. Build CLI args via the backend adapter
+     * 2. Wrap the subprocess invocation in retry logic
+     * 3. On success: parse response via backend, record telemetry entry
+     * 4. On failure: record error telemetry entry, throw the error
+     *
+     * Retries are attempted for `RATE_LIMIT` and `TIMEOUT` errors only.
+     * All other errors are treated as permanent failures.
+     *
+     * @param options - The call options (prompt, model, timeout, etc.)
+     * @returns The normalized AI response
+     * @throws {AIServiceError} On timeout, rate limit exhaustion, parse error, or subprocess failure
+     */
+    call(options: AICallOptions): Promise<AIResponse>;
+    /**
+     * Finalize the run: write the run log to disk and clean up old files.
+     *
+     * Call this once at the end of a CLI invocation, after all `call()`
+     * invocations have completed (or failed).
+     *
+     * @param projectRoot - Absolute path to the project root directory
+     * @returns The log file path and the run summary
+     */
+    finalize(projectRoot: string): Promise<{
+        logPath: string;
+        summary: RunLog['summary'];
+    }>;
+    /**
+     * Attach file-read metadata to the most recent telemetry entry.
+     *
+     * Called by the command runner after an AI call completes, to record
+     * which source files were sent as context for that call.
+     *
+     * @param filesRead - Array of file-read records (path + size)
+     */
+    addFilesReadToLastEntry(filesRead: FileRead[]): void;
+    /**
+     * Get the current run summary without finalizing.
+     *
+     * Useful for displaying progress during a run.
+     *
+     * @returns Current summary statistics
+     */
+    getSummary(): RunLog['summary'];
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/ai/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/ai/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAkB,MAAM,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAQzG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AA6BjD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,SAAS,EAAE;QACT,qDAAqD;QACrD,QAAQ,EAAE,MAAM,CAAC;QACjB,0DAA0D;QAC1D,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,2CAA2C;IAC3C,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACjD;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,SAAS;IACpB,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IAEpC,4BAA4B;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAE3C,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC,4DAA4D;IAC5D,OAAO,CAAC,SAAS,CAAa;IAE9B,qFAAqF;IACrF,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAElD;;;;;OAKG;gBACS,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB;IAMzD;;;;;;;;;;;;;;;OAeG;IACG,IAAI,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC;IAgIvD;;;;;;;;OAQG;IACG,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC,CAAA;KAAE,CAAC;IAO7F;;;;;;;OAOG;IACH,uBAAuB,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,IAAI;IAIpD;;;;;;OAMG;IACH,UAAU,IAAI,MAAM,CAAC,SAAS,CAAC;CAGhC"}