@boxlite-ai/boxlite 0.1.0

package/dist/browserbox.js

@@ -0,0 +1,234 @@
+"use strict";
+/**
+ * BrowserBox - Secure browser with remote debugging.
+ *
+ * Provides a minimal, elegant API for running isolated browsers that can be
+ * controlled from outside using standard tools like Puppeteer or Playwright.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserBox = void 0;
+const simplebox_1 = require("./simplebox");
+const errors_1 = require("./errors");
+const constants = __importStar(require("./constants"));
+/**
+ * Secure browser environment with remote debugging.
+ *
+ * Auto-starts a browser with Chrome DevTools Protocol enabled.
+ * Connect from outside using Puppeteer, Playwright, Selenium, or DevTools.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const browser = new BrowserBox();
+ * try {
+ *   await browser.start();  // Manually start browser
+ *   console.log(`Connect to: ${browser.endpoint()}`);
+ *   // Use Puppeteer/Playwright from your host to connect
+ *   await new Promise(resolve => setTimeout(resolve, 60000));
+ * } finally {
+ *   await browser.stop();
+ * }
+ * ```
+ *
+ * ## Example with custom options
+ *
+ * ```typescript
+ * const browser = new BrowserBox({
+ *   browser: 'firefox',
+ *   memoryMib: 4096,
+ *   cpus: 4
+ * });
+ * try {
+ *   await browser.start();
+ *   const endpoint = browser.endpoint();
+ *   // Connect using Playwright or Puppeteer
+ * } finally {
+ *   await browser.stop();
+ * }
+ * ```
+ */
+class BrowserBox extends simplebox_1.SimpleBox {
+    /**
+     * Create a new BrowserBox.
+     *
+     * @param options - BrowserBox configuration options
+     *
+     * @example
+     * ```typescript
+     * const browser = new BrowserBox({
+     *   browser: 'chromium',
+     *   memoryMib: 2048,
+     *   cpus: 2
+     * });
+     * ```
+     */
+    constructor(options = {}) {
+        const { browser = 'chromium', memoryMib = 2048, cpus = 2, ...restOptions } = options;
+        super({
+            ...restOptions,
+            image: BrowserBox.DEFAULT_IMAGE,
+            memoryMib,
+            cpus,
+        });
+        this._browser = browser;
+        this._port = BrowserBox.PORTS[browser] || 9222;
+    }
+    /**
+     * Start the browser with remote debugging enabled.
+     *
+     * Call this method after creating the BrowserBox to start the browser process.
+     * Waits for the browser to be ready before returning.
+     *
+     * @param timeout - Maximum time to wait for browser to start in seconds (default: 30)
+     * @throws {TimeoutError} If browser doesn't start within timeout
+     *
+     * @example
+     * ```typescript
+     * const browser = new BrowserBox();
+     * try {
+     *   await browser.start();
+     *   console.log(`Connect to: ${browser.endpoint()}`);
+     * } finally {
+     *   await browser.stop();
+     * }
+     * ```
+     */
+    async start(timeout = 30) {
+        let cmd;
+        let processPattern;
+        if (this._browser === 'chromium') {
+            const binary = '/ms-playwright/chromium-*/chrome-linux/chrome';
+            cmd =
+                `${binary} --headless --no-sandbox --disable-dev-shm-usage ` +
+                    `--disable-gpu --remote-debugging-address=0.0.0.0 ` +
+                    `--remote-debugging-port=${this._port} ` +
+                    `> /tmp/browser.log 2>&1 &`;
+            processPattern = 'chrome';
+        }
+        else if (this._browser === 'firefox') {
+            const binary = '/ms-playwright/firefox-*/firefox/firefox';
+            cmd =
+                `${binary} --headless ` +
+                    `--remote-debugging-port=${this._port} ` +
+                    `> /tmp/browser.log 2>&1 &`;
+            processPattern = 'firefox';
+        }
+        else {
+            // webkit
+            cmd =
+                `playwright run-server --browser webkit ` +
+                    `--port ${this._port} > /tmp/browser.log 2>&1 &`;
+            processPattern = 'playwright';
+        }
+        // Start browser in background
+        await this.exec('sh', '-c', `nohup ${cmd}`);
+        // Wait for browser to be ready
+        await this.waitForBrowser(processPattern, timeout);
+    }
+    /**
+     * Wait for the browser process to be running.
+     *
+     * @param processPattern - Pattern to match browser process name
+     * @param timeout - Maximum wait time in seconds
+     * @throws {TimeoutError} If browser doesn't start within timeout
+     */
+    async waitForBrowser(processPattern, timeout) {
+        const startTime = Date.now();
+        const pollInterval = 0.5;
+        while (true) {
+            const elapsed = (Date.now() - startTime) / 1000;
+            if (elapsed > timeout) {
+                throw new errors_1.TimeoutError(`Browser '${this._browser}' did not start within ${timeout} seconds`);
+            }
+            // Check if browser process is running
+            const result = await this.exec('pgrep', '-f', processPattern);
+            if (result.exitCode === 0 && result.stdout.trim()) {
+                // Browser process found, give it a moment to initialize
+                await new Promise(resolve => setTimeout(resolve, 500));
+                return;
+            }
+            // Wait before retrying
+            await new Promise(resolve => setTimeout(resolve, pollInterval * 1000));
+        }
+    }
+    /**
+     * Get the connection endpoint for remote debugging.
+     *
+     * Returns the HTTP endpoint URL for Chrome DevTools Protocol.
+     * Use this with Puppeteer, Playwright, or Selenium to connect to the browser.
+     *
+     * @returns HTTP endpoint URL (e.g., 'http://localhost:9222')
+     *
+     * @example
+     * ```typescript
+     * const browser = new BrowserBox();
+     * try {
+     *   await browser.start();
+     *   const url = browser.endpoint();
+     *
+     *   // Use with Puppeteer:
+     *   // const browserWSEndpoint = await fetch(`${url}/json/version`)
+     *   //   .then(r => r.json())
+     *   //   .then(d => d.webSocketDebuggerUrl);
+     *   // const browser = await puppeteer.connect({ browserWSEndpoint });
+     *
+     *   // Use with Playwright:
+     *   // const browser = await chromium.connectOverCDP(url);
+     * } finally {
+     *   await browser.stop();
+     * }
+     * ```
+     */
+    endpoint() {
+        return `http://localhost:${this._port}`;
+    }
+    /**
+     * Override async disposal to start browser automatically.
+     *
+     * @internal
+     */
+    async [Symbol.asyncDispose]() {
+        await super[Symbol.asyncDispose]();
+    }
+}
+exports.BrowserBox = BrowserBox;
+BrowserBox.DEFAULT_IMAGE = 'mcr.microsoft.com/playwright:v1.47.2-jammy';
+BrowserBox.PORTS = {
+    chromium: constants.BROWSERBOX_PORT_CHROMIUM,
+    firefox: constants.BROWSERBOX_PORT_FIREFOX,
+    webkit: constants.BROWSERBOX_PORT_WEBKIT,
+};
+//# sourceMappingURL=browserbox.js.map

package/dist/browserbox.js.map

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

package/dist/codebox.d.ts

@@ -0,0 +1,144 @@
+/**
+ * CodeBox - Secure Python code execution container.
+ *
+ * Provides a simple, secure environment for running untrusted Python code.
+ */
+import { SimpleBox, type SimpleBoxOptions } from './simplebox';
+/**
+ * Options for creating a CodeBox.
+ */
+export interface CodeBoxOptions extends Omit<SimpleBoxOptions, 'image'> {
+    /** Container image with Python (default: 'python:slim') */
+    image?: string;
+}
+/**
+ * Secure container for executing Python code.
+ *
+ * CodeBox provides an isolated environment for running untrusted Python code
+ * with built-in safety and result formatting.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const codebox = new CodeBox();
+ * try {
+ *   const result = await codebox.run("print('Hello, World!')");
+ *   console.log(result);  // Hello, World!
+ * } finally {
+ *   await codebox.stop();
+ * }
+ * ```
+ *
+ * Or with async disposal (TypeScript 5.2+):
+ *
+ * ```typescript
+ * await using codebox = new CodeBox();
+ * const result = await codebox.run("print('Hello, World!')");
+ * // Automatically stopped when leaving scope
+ * ```
+ */
+export declare class CodeBox extends SimpleBox {
+    /**
+     * Create a new CodeBox.
+     *
+     * @param options - CodeBox configuration options
+     *
+     * @example
+     * ```typescript
+     * const codebox = new CodeBox({
+     *   image: 'python:slim',
+     *   memoryMib: 512,
+     *   cpus: 2
+     * });
+     * ```
+     */
+    constructor(options?: CodeBoxOptions);
+    /**
+     * Execute Python code in the secure container.
+     *
+     * @param code - Python code to execute
+     *
+     * @returns Promise resolving to stdout output
+     * @throws {ExecError} If Python execution fails (non-zero exit code)
+     *
+     * @example
+     * ```typescript
+     * const codebox = new CodeBox();
+     * try {
+     *   const result = await codebox.run("print('Hello, World!')");
+     *   console.log(result);  // Hello, World!
+     * } finally {
+     *   await codebox.stop();
+     * }
+     * ```
+     *
+     * @remarks
+     * Uses python3 from the container image.
+     * For custom Python paths, use exec() directly:
+     * ```typescript
+     * const result = await codebox.exec('/path/to/python', '-c', code);
+     * ```
+     */
+    run(code: string): Promise<string>;
+    /**
+     * Execute a Python script file in the container.
+     *
+     * @param scriptPath - Path to the Python script on the host
+     *
+     * @returns Promise resolving to execution output
+     *
+     * @example
+     * ```typescript
+     * const codebox = new CodeBox();
+     * try {
+     *   const result = await codebox.runScript('./my_script.py');
+     *   console.log(result);
+     * } finally {
+     *   await codebox.stop();
+     * }
+     * ```
+     */
+    runScript(scriptPath: string): Promise<string>;
+    /**
+     * Install a Python package in the container using pip.
+     *
+     * @param packageName - Package name (e.g., 'requests', 'numpy==1.24.0')
+     *
+     * @returns Promise resolving to installation output
+     * @throws {ExecError} If pip installation fails
+     *
+     * @example
+     * ```typescript
+     * const codebox = new CodeBox();
+     * try {
+     *   await codebox.installPackage('requests');
+     *   const result = await codebox.run('import requests; print(requests.__version__)');
+     *   console.log(result);
+     * } finally {
+     *   await codebox.stop();
+     * }
+     * ```
+     */
+    installPackage(packageName: string): Promise<string>;
+    /**
+     * Install multiple Python packages.
+     *
+     * @param packages - Package names to install
+     *
+     * @returns Promise resolving to installation output
+     * @throws {ExecError} If pip installation fails
+     *
+     * @example
+     * ```typescript
+     * const codebox = new CodeBox();
+     * try {
+     *   await codebox.installPackages('requests', 'numpy', 'pandas');
+     *   const result = await codebox.run('import requests, numpy, pandas');
+     * } finally {
+     *   await codebox.stop();
+     * }
+     * ```
+     */
+    installPackages(...packages: string[]): Promise<string>;
+}
+//# sourceMappingURL=codebox.d.ts.map

package/dist/codebox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codebox.d.ts","sourceRoot":"","sources":["../lib/codebox.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/D;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACrE,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,OAAQ,SAAQ,SAAS;IACpC;;;;;;;;;;;;;OAaG;gBACS,OAAO,GAAE,cAAmB;IAOxC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQxC;;;;;;;;;;;;;;;;;OAiBG;IACG,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAMpD;;;;;;;;;;;;;;;;;;;OAmBG;IACG,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ1D;;;;;;;;;;;;;;;;;;OAkBG;IACG,eAAe,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;CAO9D"}

package/dist/codebox.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * CodeBox - Secure Python code execution container.
+ *
+ * Provides a simple, secure environment for running untrusted Python code.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CodeBox = void 0;
+const simplebox_1 = require("./simplebox");
+const errors_1 = require("./errors");
+/**
+ * Secure container for executing Python code.
+ *
+ * CodeBox provides an isolated environment for running untrusted Python code
+ * with built-in safety and result formatting.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const codebox = new CodeBox();
+ * try {
+ *   const result = await codebox.run("print('Hello, World!')");
+ *   console.log(result);  // Hello, World!
+ * } finally {
+ *   await codebox.stop();
+ * }
+ * ```
+ *
+ * Or with async disposal (TypeScript 5.2+):
+ *
+ * ```typescript
+ * await using codebox = new CodeBox();
+ * const result = await codebox.run("print('Hello, World!')");
+ * // Automatically stopped when leaving scope
+ * ```
+ */
+class CodeBox extends simplebox_1.SimpleBox {
+    /**
+     * Create a new CodeBox.
+     *
+     * @param options - CodeBox configuration options
+     *
+     * @example
+     * ```typescript
+     * const codebox = new CodeBox({
+     *   image: 'python:slim',
+     *   memoryMib: 512,
+     *   cpus: 2
+     * });
+     * ```
+     */
+    constructor(options = {}) {
+        super({
+            ...options,
+            image: options.image ?? 'python:slim',
+        });
+    }
+    /**
+     * Execute Python code in the secure container.
+     *
+     * @param code - Python code to execute
+     *
+     * @returns Promise resolving to stdout output
+     * @throws {ExecError} If Python execution fails (non-zero exit code)
+     *
+     * @example
+     * ```typescript
+     * const codebox = new CodeBox();
+     * try {
+     *   const result = await codebox.run("print('Hello, World!')");
+     *   console.log(result);  // Hello, World!
+     * } finally {
+     *   await codebox.stop();
+     * }
+     * ```
+     *
+     * @remarks
+     * Uses python3 from the container image.
+     * For custom Python paths, use exec() directly:
+     * ```typescript
+     * const result = await codebox.exec('/path/to/python', '-c', code);
+     * ```
+     */
+    async run(code) {
+        const result = await this.exec('/usr/local/bin/python', '-c', code);
+        if (result.exitCode !== 0) {
+            throw new errors_1.ExecError('run()', result.exitCode, result.stderr);
+        }
+        return result.stdout;
+    }
+    /**
+     * Execute a Python script file in the container.
+     *
+     * @param scriptPath - Path to the Python script on the host
+     *
+     * @returns Promise resolving to execution output
+     *
+     * @example
+     * ```typescript
+     * const codebox = new CodeBox();
+     * try {
+     *   const result = await codebox.runScript('./my_script.py');
+     *   console.log(result);
+     * } finally {
+     *   await codebox.stop();
+     * }
+     * ```
+     */
+    async runScript(scriptPath) {
+        const fs = await Promise.resolve().then(() => __importStar(require('fs/promises')));
+        const code = await fs.readFile(scriptPath, 'utf-8');
+        return this.run(code);
+    }
+    /**
+     * Install a Python package in the container using pip.
+     *
+     * @param packageName - Package name (e.g., 'requests', 'numpy==1.24.0')
+     *
+     * @returns Promise resolving to installation output
+     * @throws {ExecError} If pip installation fails
+     *
+     * @example
+     * ```typescript
+     * const codebox = new CodeBox();
+     * try {
+     *   await codebox.installPackage('requests');
+     *   const result = await codebox.run('import requests; print(requests.__version__)');
+     *   console.log(result);
+     * } finally {
+     *   await codebox.stop();
+     * }
+     * ```
+     */
+    async installPackage(packageName) {
+        const result = await this.exec('pip', 'install', packageName);
+        if (result.exitCode !== 0) {
+            throw new errors_1.ExecError(`installPackage('${packageName}')`, result.exitCode, result.stderr);
+        }
+        return result.stdout;
+    }
+    /**
+     * Install multiple Python packages.
+     *
+     * @param packages - Package names to install
+     *
+     * @returns Promise resolving to installation output
+     * @throws {ExecError} If pip installation fails
+     *
+     * @example
+     * ```typescript
+     * const codebox = new CodeBox();
+     * try {
+     *   await codebox.installPackages('requests', 'numpy', 'pandas');
+     *   const result = await codebox.run('import requests, numpy, pandas');
+     * } finally {
+     *   await codebox.stop();
+     * }
+     * ```
+     */
+    async installPackages(...packages) {
+        const result = await this.exec('pip', 'install', ...packages);
+        if (result.exitCode !== 0) {
+            throw new errors_1.ExecError(`installPackages(${packages.join(', ')})`, result.exitCode, result.stderr);
+        }
+        return result.stdout;
+    }
+}
+exports.CodeBox = CodeBox;
+//# sourceMappingURL=codebox.js.map

package/dist/codebox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codebox.js","sourceRoot":"","sources":["../lib/codebox.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,2CAA+D;AAC/D,qCAAqC;AAUrC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAa,OAAQ,SAAQ,qBAAS;IACpC;;;;;;;;;;;;;OAaG;IACH,YAAY,UAA0B,EAAE;QACtC,KAAK,CAAC;YACJ,GAAG,OAAO;YACV,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,aAAa;SACtC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,KAAK,CAAC,GAAG,CAAC,IAAY;QACpB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,uBAAuB,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QACpE,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,kBAAS,CAAC,OAAO,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,MAAM,CAAC,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,SAAS,CAAC,UAAkB;QAChC,MAAM,EAAE,GAAG,wDAAa,aAAa,GAAC,CAAC;QACvC,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACpD,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,cAAc,CAAC,WAAmB;QACtC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;QAC9D,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,kBAAS,CAAC,mBAAmB,WAAW,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAC1F,CAAC;QACD,OAAO,MAAM,CAAC,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,eAAe,CAAC,GAAG,QAAkB;QACzC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,QAAQ,CAAC,CAAC;QAC9D,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,kBAAS,CAAC,mBAAmB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACjG,CAAC;QACD,OAAO,MAAM,CAAC,MAAM,CAAC;IACvB,CAAC;CACF;AAtID,0BAsIC"}