@office-ai/aioncli-core 0.26.0 → 0.30.0

package/dist/src/utils/schemaValidator.test.js

@@ -109,5 +109,82 @@ describe('SchemaValidator', () => {
         };
         expect(SchemaValidator.validate(schema, params)).not.toBeNull();
     });
+    it('allows schemas with draft-07 $schema property', () => {
+        const schema = {
+            type: 'object',
+            properties: { name: { type: 'string' } },
+            $schema: 'http://json-schema.org/draft-07/schema#',
+        };
+        const params = { name: 'test' };
+        expect(SchemaValidator.validate(schema, params)).toBeNull();
+    });
+    it('allows schemas with unrecognized $schema versions (lenient fallback)', () => {
+        // Future-proof: any unrecognized schema version should skip validation
+        // with a warning rather than failing
+        const schema = {
+            type: 'object',
+            properties: { name: { type: 'string' } },
+            $schema: 'https://json-schema.org/draft/2030-99/schema',
+        };
+        const params = { name: 'test' };
+        expect(SchemaValidator.validate(schema, params)).toBeNull();
+    });
+    describe('JSON Schema draft-2020-12 support', () => {
+        it('validates params against draft-2020-12 schema', () => {
+            const schema = {
+                $schema: 'https://json-schema.org/draft/2020-12/schema',
+                type: 'object',
+                properties: {
+                    message: {
+                        type: 'string',
+                    },
+                },
+                required: ['message'],
+            };
+            // Valid data should pass
+            expect(SchemaValidator.validate(schema, { message: 'hello' })).toBeNull();
+            // Invalid data should fail (proves validation actually works)
+            expect(SchemaValidator.validate(schema, { message: 123 })).not.toBeNull();
+        });
+        it('validates draft-2020-12 schema with prefixItems', () => {
+            // prefixItems is a draft-2020-12 feature (replaces tuple validation)
+            const schema = {
+                $schema: 'https://json-schema.org/draft/2020-12/schema',
+                type: 'object',
+                properties: {
+                    coords: {
+                        type: 'array',
+                        prefixItems: [{ type: 'number' }, { type: 'number' }],
+                        items: false,
+                    },
+                },
+            };
+            // Valid: exactly 2 numbers
+            expect(SchemaValidator.validate(schema, { coords: [1, 2] })).toBeNull();
+            // Invalid: 3 items when items: false
+            expect(SchemaValidator.validate(schema, { coords: [1, 2, 3] })).not.toBeNull();
+        });
+        it('validates draft-2020-12 schema with $defs', () => {
+            // draft-2020-12 uses $defs instead of definitions
+            const schema = {
+                $schema: 'https://json-schema.org/draft/2020-12/schema',
+                type: 'object',
+                $defs: {
+                    ChatRole: {
+                        type: 'string',
+                        enum: ['System', 'User', 'Assistant'],
+                    },
+                },
+                properties: {
+                    role: { $ref: '#/$defs/ChatRole' },
+                },
+                required: ['role'],
+            };
+            // Valid enum value
+            expect(SchemaValidator.validate(schema, { role: 'User' })).toBeNull();
+            // Invalid enum value (proves validation works)
+            expect(SchemaValidator.validate(schema, { role: 'InvalidRole' })).not.toBeNull();
+        });
+    });
 });
 //# sourceMappingURL=schemaValidator.test.js.map

package/dist/src/utils/schemaValidator.test.js.map

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

package/dist/src/utils/security.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export interface SecurityCheckResult {
+    secure: boolean;
+    reason?: string;
+}
+/**
+ * Verifies if a directory is secure (owned by root and not writable by others).
+ *
+ * @param dirPath The path to the directory to check.
+ * @returns A promise that resolves to a SecurityCheckResult.
+ */
+export declare function isDirectorySecure(dirPath: string): Promise<SecurityCheckResult>;

package/dist/src/utils/security.js

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import * as os from 'node:os';
+import { spawnAsync } from './shell-utils.js';
+/**
+ * Verifies if a directory is secure (owned by root and not writable by others).
+ *
+ * @param dirPath The path to the directory to check.
+ * @returns A promise that resolves to a SecurityCheckResult.
+ */
+export async function isDirectorySecure(dirPath) {
+    try {
+        const stats = await fs.stat(dirPath);
+        if (!stats.isDirectory()) {
+            return { secure: false, reason: 'Not a directory' };
+        }
+        if (os.platform() === 'win32') {
+            try {
+                // Check ACLs using PowerShell to ensure standard users don't have write access
+                const escapedPath = dirPath.replace(/'/g, "''");
+                const script = `
+          $path = '${escapedPath}';
+          $acl = Get-Acl -LiteralPath $path;
+          $rules = $acl.Access | Where-Object { 
+              $_.AccessControlType -eq 'Allow' -and 
+              (($_.FileSystemRights -match 'Write') -or ($_.FileSystemRights -match 'Modify') -or ($_.FileSystemRights -match 'FullControl')) 
+          };
+          $insecureIdentity = $rules | Where-Object { 
+              $_.IdentityReference.Value -match 'Users' -or $_.IdentityReference.Value -eq 'Everyone' 
+          } | Select-Object -ExpandProperty IdentityReference;
+          Write-Output ($insecureIdentity -join ', ');
+        `;
+                const { stdout } = await spawnAsync('powershell', [
+                    '-NoProfile',
+                    '-NonInteractive',
+                    '-Command',
+                    script,
+                ]);
+                const insecureGroups = stdout.trim();
+                if (insecureGroups) {
+                    return {
+                        secure: false,
+                        reason: `Directory '${dirPath}' is insecure. The following user groups have write permissions: ${insecureGroups}. To fix this, remove Write and Modify permissions for these groups from the directory's ACLs.`,
+                    };
+                }
+                return { secure: true };
+            }
+            catch (error) {
+                return {
+                    secure: false,
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+                    reason: `A security check for the system policy directory '${dirPath}' failed and could not be completed. Please file a bug report. Original error: ${error.message}`,
+                };
+            }
+        }
+        // POSIX checks
+        // Check ownership: must be root (uid 0)
+        if (stats.uid !== 0) {
+            return {
+                secure: false,
+                reason: `Directory '${dirPath}' is not owned by root (uid 0). Current uid: ${stats.uid}. To fix this, run: sudo chown root:root "${dirPath}"`,
+            };
+        }
+        // Check permissions: not writable by group (S_IWGRP) or others (S_IWOTH)
+        const mode = stats.mode;
+        if ((mode & (constants.S_IWGRP | constants.S_IWOTH)) !== 0) {
+            return {
+                secure: false,
+                reason: `Directory '${dirPath}' is writable by group or others (mode: ${mode.toString(8)}). To fix this, run: sudo chmod g-w,o-w "${dirPath}"`,
+            };
+        }
+        return { secure: true };
+    }
+    catch (error) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        if (error.code === 'ENOENT') {
+            return { secure: true };
+        }
+        return {
+            secure: false,
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+            reason: `Failed to access directory: ${error.message}`,
+        };
+    }
+}
+//# sourceMappingURL=security.js.map

package/dist/src/utils/security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.js","sourceRoot":"","sources":["../../../src/utils/security.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAO9C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAe;IAEf,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAErC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACzB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;QACtD,CAAC;QAED,IAAI,EAAE,CAAC,QAAQ,EAAE,KAAK,OAAO,EAAE,CAAC;YAC9B,IAAI,CAAC;gBACH,+EAA+E;gBAC/E,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBAChD,MAAM,MAAM,GAAG;qBACF,WAAW;;;;;;;;;;SAUvB,CAAC;gBAEF,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,UAAU,CAAC,YAAY,EAAE;oBAChD,YAAY;oBACZ,iBAAiB;oBACjB,UAAU;oBACV,MAAM;iBACP,CAAC,CAAC;gBAEH,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;gBACrC,IAAI,cAAc,EAAE,CAAC;oBACnB,OAAO;wBACL,MAAM,EAAE,KAAK;wBACb,MAAM,EAAE,cAAc,OAAO,oEAAoE,cAAc,gGAAgG;qBAChN,CAAC;gBACJ,CAAC;gBAED,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;YAC1B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO;oBACL,MAAM,EAAE,KAAK;oBACb,uEAAuE;oBACvE,MAAM,EAAE,qDAAqD,OAAO,kFAAmF,KAAe,CAAC,OAAO,EAAE;iBACjL,CAAC;YACJ,CAAC;QACH,CAAC;QAED,eAAe;QACf,wCAAwC;QACxC,IAAI,KAAK,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC;YACpB,OAAO;gBACL,MAAM,EAAE,KAAK;gBACb,MAAM,EAAE,cAAc,OAAO,gDAAgD,KAAK,CAAC,GAAG,6CAA6C,OAAO,GAAG;aAC9I,CAAC;QACJ,CAAC;QAED,yEAAyE;QACzE,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,CAAC,SAAS,CAAC,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3D,OAAO;gBACL,MAAM,EAAE,KAAK;gBACb,MAAM,EAAE,cAAc,OAAO,2CAA2C,IAAI,CAAC,QAAQ,CACnF,CAAC,CACF,4CAA4C,OAAO,GAAG;aACxD,CAAC;QACJ,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,uEAAuE;QACvE,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;QAC1B,CAAC;QACD,OAAO;YACL,MAAM,EAAE,KAAK;YACb,uEAAuE;YACvE,MAAM,EAAE,+BAAgC,KAAe,CAAC,OAAO,EAAE;SAClE,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/src/utils/security.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/security.test.js

@@ -0,0 +1,121 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { isDirectorySecure } from './security.js';
+import * as fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import * as os from 'node:os';
+import { spawnAsync } from './shell-utils.js';
+vi.mock('node:fs/promises');
+vi.mock('node:fs');
+vi.mock('node:os');
+vi.mock('./shell-utils.js', () => ({
+    spawnAsync: vi.fn(),
+}));
+describe('isDirectorySecure', () => {
+    afterEach(() => {
+        vi.clearAllMocks();
+    });
+    it('returns secure=true on Windows if ACL check passes', async () => {
+        vi.spyOn(os, 'platform').mockReturnValue('win32');
+        vi.mocked(fs.stat).mockResolvedValue({
+            isDirectory: () => true,
+        });
+        vi.mocked(spawnAsync).mockResolvedValue({ stdout: '', stderr: '' });
+        const result = await isDirectorySecure('C:\\Some\\Path');
+        expect(result.secure).toBe(true);
+        expect(spawnAsync).toHaveBeenCalledWith('powershell', expect.arrayContaining(['-Command', expect.stringContaining('Get-Acl')]));
+    });
+    it('returns secure=false on Windows if ACL check fails', async () => {
+        vi.spyOn(os, 'platform').mockReturnValue('win32');
+        vi.mocked(fs.stat).mockResolvedValue({
+            isDirectory: () => true,
+        });
+        vi.mocked(spawnAsync).mockResolvedValue({
+            stdout: 'BUILTIN\\Users',
+            stderr: '',
+        });
+        const result = await isDirectorySecure('C:\\Some\\Path');
+        expect(result.secure).toBe(false);
+        expect(result.reason).toBe("Directory 'C:\\Some\\Path' is insecure. The following user groups have write permissions: BUILTIN\\Users. To fix this, remove Write and Modify permissions for these groups from the directory's ACLs.");
+    });
+    it('returns secure=false on Windows if spawnAsync fails', async () => {
+        vi.spyOn(os, 'platform').mockReturnValue('win32');
+        vi.mocked(fs.stat).mockResolvedValue({
+            isDirectory: () => true,
+        });
+        vi.mocked(spawnAsync).mockRejectedValue(new Error('PowerShell is not installed'));
+        const result = await isDirectorySecure('C:\\Some\\Path');
+        expect(result.secure).toBe(false);
+        expect(result.reason).toBe("A security check for the system policy directory 'C:\\Some\\Path' failed and could not be completed. Please file a bug report. Original error: PowerShell is not installed");
+    });
+    it('returns secure=true if directory does not exist (ENOENT)', async () => {
+        vi.spyOn(os, 'platform').mockReturnValue('linux');
+        const error = new Error('ENOENT');
+        Object.assign(error, { code: 'ENOENT' });
+        vi.mocked(fs.stat).mockRejectedValue(error);
+        const result = await isDirectorySecure('/some/path');
+        expect(result.secure).toBe(true);
+    });
+    it('returns secure=false if path is not a directory', async () => {
+        vi.spyOn(os, 'platform').mockReturnValue('linux');
+        vi.mocked(fs.stat).mockResolvedValue({
+            isDirectory: () => false,
+            uid: 0,
+            mode: 0o700,
+        });
+        const result = await isDirectorySecure('/some/file');
+        expect(result.secure).toBe(false);
+        expect(result.reason).toBe('Not a directory');
+    });
+    it('returns secure=false if not owned by root (uid 0) on POSIX', async () => {
+        vi.spyOn(os, 'platform').mockReturnValue('linux');
+        vi.mocked(fs.stat).mockResolvedValue({
+            isDirectory: () => true,
+            uid: 1000, // Non-root
+            mode: 0o755,
+        });
+        const result = await isDirectorySecure('/some/path');
+        expect(result.secure).toBe(false);
+        expect(result.reason).toBe('Directory \'/some/path\' is not owned by root (uid 0). Current uid: 1000. To fix this, run: sudo chown root:root "/some/path"');
+    });
+    it('returns secure=false if writable by group (020) on POSIX', async () => {
+        vi.spyOn(os, 'platform').mockReturnValue('linux');
+        Object.assign(constants, { S_IWGRP: 0o020, S_IWOTH: 0 });
+        vi.mocked(fs.stat).mockResolvedValue({
+            isDirectory: () => true,
+            uid: 0,
+            mode: 0o775, // rwxrwxr-x (group writable)
+        });
+        const result = await isDirectorySecure('/some/path');
+        expect(result.secure).toBe(false);
+        expect(result.reason).toBe('Directory \'/some/path\' is writable by group or others (mode: 775). To fix this, run: sudo chmod g-w,o-w "/some/path"');
+    });
+    it('returns secure=false if writable by others (002) on POSIX', async () => {
+        vi.spyOn(os, 'platform').mockReturnValue('linux');
+        Object.assign(constants, { S_IWGRP: 0, S_IWOTH: 0o002 });
+        vi.mocked(fs.stat).mockResolvedValue({
+            isDirectory: () => true,
+            uid: 0,
+            mode: 0o757, // rwxr-xrwx (others writable)
+        });
+        const result = await isDirectorySecure('/some/path');
+        expect(result.secure).toBe(false);
+        expect(result.reason).toBe('Directory \'/some/path\' is writable by group or others (mode: 757). To fix this, run: sudo chmod g-w,o-w "/some/path"');
+    });
+    it('returns secure=true if owned by root and secure permissions on POSIX', async () => {
+        vi.spyOn(os, 'platform').mockReturnValue('linux');
+        Object.assign(constants, { S_IWGRP: 0, S_IWOTH: 0 });
+        vi.mocked(fs.stat).mockResolvedValue({
+            isDirectory: () => true,
+            uid: 0,
+            mode: 0o755, // rwxr-xr-x
+        });
+        const result = await isDirectorySecure('/some/path');
+        expect(result.secure).toBe(true);
+    });
+});
+//# sourceMappingURL=security.test.js.map

package/dist/src/utils/security.test.js.map

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

package/dist/src/utils/shell-utils.d.ts

@@ -22,10 +22,12 @@ export interface ShellConfiguration {
     /** An identifier for the shell type. */
     shell: ShellType;
 }
+export declare function resolveExecutable(exe: string): Promise<string | undefined>;
 export declare function initializeShellParsers(): Promise<void>;
 export interface ParsedCommandDetail {
     name: string;
     text: string;
+    startIndex: number;
 }
 interface CommandParseResult {
     details: ParsedCommandDetail[];
@@ -101,4 +103,16 @@ export declare const spawnAsync: (command: string, args: string[], options?: Spa
     stdout: string;
     stderr: string;
 }>;
+/**
+ * Executes a command and yields lines of output as they appear.
+ * Use for large outputs where buffering is not feasible.
+ *
+ * @param command The executable to run
+ * @param args Arguments for the executable
+ * @param options Spawn options (cwd, env, etc.)
+ */
+export declare function execStreaming(command: string, args: string[], options?: SpawnOptionsWithoutStdio & {
+    signal?: AbortSignal;
+    allowedExitCodes?: number[];
+}): AsyncGenerator<string, void, void>;
 export {};

package/dist/src/utils/shell-utils.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/shell-utils.integration.test.js

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect } from 'vitest';
+import { execStreaming } from './shell-utils.js';
+// Integration tests using real child processes
+describe('execStreaming (Integration)', () => {
+    it('should yield lines from stdout', async () => {
+        // Use node to echo for cross-platform support
+        const generator = execStreaming(process.execPath, [
+            '-e',
+            'console.log("line 1\\nline 2")',
+        ]);
+        const lines = [];
+        for await (const line of generator) {
+            lines.push(line);
+        }
+        expect(lines).toEqual(['line 1', 'line 2']);
+    });
+    it('should throw error on non-zero exit code', async () => {
+        // exit 2 via node
+        const generator = execStreaming(process.execPath, [
+            '-e',
+            'process.exit(2)',
+        ]);
+        await expect(async () => {
+            for await (const _ of generator) {
+                // consume
+            }
+        }).rejects.toThrow();
+    });
+    it('should abort cleanly when signal is aborted', async () => {
+        const controller = new AbortController();
+        // sleep for 2s via node
+        const generator = execStreaming(process.execPath, ['-e', 'setTimeout(() => {}, 2000)'], { signal: controller.signal });
+        // Start reading
+        const readPromise = (async () => {
+            const lines = [];
+            try {
+                for await (const line of generator) {
+                    lines.push(line);
+                }
+            }
+            catch (_e) {
+                // ignore
+            }
+            return lines;
+        })();
+        setTimeout(() => {
+            controller.abort();
+        }, 100);
+        const lines = await readPromise;
+        expect(lines).toEqual([]);
+    });
+});
+//# sourceMappingURL=shell-utils.integration.test.js.map

package/dist/src/utils/shell-utils.integration.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-utils.integration.test.js","sourceRoot":"","sources":["../../../src/utils/shell-utils.integration.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,+CAA+C;AAC/C,QAAQ,CAAC,6BAA6B,EAAE,GAAG,EAAE;IAC3C,EAAE,CAAC,gCAAgC,EAAE,KAAK,IAAI,EAAE;QAC9C,8CAA8C;QAC9C,MAAM,SAAS,GAAG,aAAa,CAAC,OAAO,CAAC,QAAQ,EAAE;YAChD,IAAI;YACJ,gCAAgC;SACjC,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,EAAE,CAAC;QACjB,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,KAAK,IAAI,EAAE;QACxD,kBAAkB;QAClB,MAAM,SAAS,GAAG,aAAa,CAAC,OAAO,CAAC,QAAQ,EAAE;YAChD,IAAI;YACJ,iBAAiB;SAClB,CAAC,CAAC;QAEH,MAAM,MAAM,CAAC,KAAK,IAAI,EAAE;YACtB,IAAI,KAAK,EAAE,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;gBAChC,UAAU;YACZ,CAAC;QACH,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6CAA6C,EAAE,KAAK,IAAI,EAAE;QAC3D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,wBAAwB;QACxB,MAAM,SAAS,GAAG,aAAa,CAC7B,OAAO,CAAC,QAAQ,EAChB,CAAC,IAAI,EAAE,4BAA4B,CAAC,EACpC,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAC9B,CAAC;QAEF,gBAAgB;QAChB,MAAM,WAAW,GAAG,CAAC,KAAK,IAAI,EAAE;YAC9B,MAAM,KAAK,GAAG,EAAE,CAAC;YACjB,IAAI,CAAC;gBACH,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;oBACnC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACnB,CAAC;YACH,CAAC;YAAC,OAAO,EAAE,EAAE,CAAC;gBACZ,SAAS;YACX,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC,CAAC,EAAE,CAAC;QAEL,UAAU,CAAC,GAAG,EAAE;YACd,UAAU,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC,EAAE,GAAG,CAAC,CAAC;QAER,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC;QAChC,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}