@code-rag/mcp-server 0.1.0

package/dist/tools/explain.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import type { HybridSearch, ContextExpander } from '@code-rag/core';
+export declare const explainInputSchema: z.ZodObject<{
+    file_path: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    detail_level: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        brief: "brief";
+        detailed: "detailed";
+    }>>>;
+}, z.core.$strip>;
+export type ExplainInput = z.infer<typeof explainInputSchema>;
+export declare function handleExplain(args: Record<string, unknown>, hybridSearch: HybridSearch | null, contextExpander: ContextExpander | null): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;

package/dist/tools/explain.js

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+export const explainInputSchema = z.object({
+    file_path: z.string().min(1, 'file_path must not be empty').refine((s) => !s.includes('..'), 'file_path must not contain path traversal').optional(),
+    name: z.string().min(1, 'name must not be empty').optional(),
+    detail_level: z.enum(['brief', 'detailed']).optional().default('detailed'),
+}).refine((data) => data.file_path !== undefined || data.name !== undefined, 'At least one of file_path or name must be provided');
+function formatChunk(result, detailLevel) {
+    const explanation = {
+        file_path: result.chunk?.filePath ?? '',
+        chunk_type: result.metadata?.chunkType ?? 'unknown',
+        name: result.metadata?.name ?? '',
+        nl_summary: result.nlSummary,
+    };
+    if (detailLevel === 'detailed') {
+        explanation.code = result.content;
+    }
+    return explanation;
+}
+export async function handleExplain(args, hybridSearch, contextExpander) {
+    const parsed = explainInputSchema.safeParse(args);
+    if (!parsed.success) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: 'Invalid input',
+                        details: parsed.error.issues,
+                    }),
+                },
+            ],
+        };
+    }
+    if (!hybridSearch) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        explanation: { chunks: [], detail_level: parsed.data.detail_level },
+                        chunks_found: 0,
+                        message: 'Services not initialized. Run indexing first.',
+                    }),
+                },
+            ],
+        };
+    }
+    const { file_path, name, detail_level } = parsed.data;
+    try {
+        let results = [];
+        if (name) {
+            // Search by function/class/method name
+            const searchResult = await hybridSearch.search(name, { topK: 5 });
+            if (searchResult.isErr()) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                error: 'Search failed',
+                                message: searchResult.error.message,
+                            }),
+                        },
+                    ],
+                };
+            }
+            // Filter to chunks whose name matches
+            results = searchResult.value.filter((r) => r.metadata?.name?.toLowerCase().includes(name.toLowerCase()));
+        }
+        else if (file_path) {
+            // Search by file path
+            const searchResult = await hybridSearch.search(file_path, { topK: 20 });
+            if (searchResult.isErr()) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                error: 'Search failed',
+                                message: searchResult.error.message,
+                            }),
+                        },
+                    ],
+                };
+            }
+            // Filter to chunks in the specified file
+            results = searchResult.value.filter((r) => r.chunk?.filePath?.includes(file_path));
+        }
+        if (results.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            explanation: { chunks: [], detail_level },
+                            chunks_found: 0,
+                            message: name
+                                ? `No chunks found matching name: ${name}`
+                                : `No chunks found for file: ${file_path}`,
+                        }),
+                    },
+                ],
+            };
+        }
+        const chunks = results.map((r) => formatChunk(r, detail_level));
+        const result = {
+            explanation: {
+                chunks,
+                detail_level,
+            },
+            chunks_found: results.length,
+        };
+        // Add related symbols from context expander when in detailed mode
+        if (detail_level === 'detailed' && contextExpander) {
+            const expanded = contextExpander.expand(results);
+            const relatedSymbols = expanded.relatedChunks.map((related) => {
+                return related.chunk.metadata.name ?? related.chunk.chunk?.filePath ?? 'unknown';
+            });
+            if (relatedSymbols.length > 0) {
+                result.explanation.related_symbols = relatedSymbols;
+            }
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result) }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ error: 'Explain failed', message }),
+                },
+            ],
+        };
+    }
+}

package/dist/tools/explain.js.map

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

package/dist/tools/explain.test.d.ts

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

package/dist/tools/explain.test.js

@@ -0,0 +1,244 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { ok, err } from 'neverthrow';
+import { handleExplain, explainInputSchema } from './explain.js';
+import { EmbedError } from '@coderag/core';
+// --- Helpers ---
+function makeSearchResult(overrides = {}) {
+    return {
+        chunkId: 'chunk-1',
+        content: 'function hello() {}',
+        nlSummary: 'A greeting function',
+        score: 0.95,
+        method: 'hybrid',
+        metadata: {
+            chunkType: 'function',
+            name: 'hello',
+            declarations: [],
+            imports: [],
+            exports: [],
+        },
+        chunk: {
+            id: 'chunk-1',
+            content: 'function hello() {}',
+            nlSummary: 'A greeting function',
+            filePath: 'src/utils/hello.ts',
+            startLine: 1,
+            endLine: 3,
+            language: 'typescript',
+            metadata: {
+                chunkType: 'function',
+                name: 'hello',
+                declarations: [],
+                imports: [],
+                exports: [],
+            },
+        },
+        ...overrides,
+    };
+}
+function parseResponse(response) {
+    return JSON.parse(response.content[0].text);
+}
+// --- Input Validation Tests ---
+describe('explainInputSchema', () => {
+    it('should accept valid input with name', () => {
+        const result = explainInputSchema.safeParse({ name: 'hello' });
+        expect(result.success).toBe(true);
+    });
+    it('should accept valid input with file_path', () => {
+        const result = explainInputSchema.safeParse({ file_path: 'src/utils/hello.ts' });
+        expect(result.success).toBe(true);
+    });
+    it('should reject input with neither file_path nor name', () => {
+        const result = explainInputSchema.safeParse({});
+        expect(result.success).toBe(false);
+    });
+    it('should reject file_path with path traversal', () => {
+        const result = explainInputSchema.safeParse({ file_path: '../../etc/passwd' });
+        expect(result.success).toBe(false);
+    });
+    it('should apply default detail_level of detailed', () => {
+        const result = explainInputSchema.parse({ name: 'hello' });
+        expect(result.detail_level).toBe('detailed');
+    });
+    it('should accept brief detail_level', () => {
+        const result = explainInputSchema.parse({ name: 'hello', detail_level: 'brief' });
+        expect(result.detail_level).toBe('brief');
+    });
+    it('should reject invalid detail_level', () => {
+        const result = explainInputSchema.safeParse({ name: 'hello', detail_level: 'verbose' });
+        expect(result.success).toBe(false);
+    });
+    it('should accept both file_path and name together', () => {
+        const result = explainInputSchema.safeParse({ file_path: 'src/hello.ts', name: 'hello' });
+        expect(result.success).toBe(true);
+    });
+});
+// --- Handler Tests ---
+describe('handleExplain', () => {
+    let mockHybridSearch;
+    let mockContextExpander;
+    beforeEach(() => {
+        mockHybridSearch = {
+            search: vi.fn(),
+        };
+        mockContextExpander = {
+            expand: vi.fn(),
+        };
+    });
+    it('should return validation error when both file_path and name are missing', async () => {
+        const response = await handleExplain({}, mockHybridSearch, mockContextExpander);
+        const parsed = parseResponse(response);
+        expect(parsed.error).toBe('Invalid input');
+    });
+    it('should return validation error for file_path with path traversal', async () => {
+        const response = await handleExplain({ file_path: '../../../etc/passwd' }, mockHybridSearch, mockContextExpander);
+        const parsed = parseResponse(response);
+        expect(parsed.error).toBe('Invalid input');
+    });
+    it('should return graceful message when services are null', async () => {
+        const response = await handleExplain({ name: 'hello' }, null, null);
+        const parsed = parseResponse(response);
+        expect(parsed.chunks_found).toBe(0);
+        expect(parsed.explanation.chunks).toEqual([]);
+        expect(parsed.message).toContain('not initialized');
+    });
+    it('should search by name and return matching chunks', async () => {
+        const results = [makeSearchResult()];
+        vi.mocked(mockHybridSearch.search).mockResolvedValue(ok(results));
+        const expandedContext = {
+            primaryResults: results,
+            relatedChunks: [],
+            graphExcerpt: { nodes: [], edges: [] },
+        };
+        vi.mocked(mockContextExpander.expand).mockReturnValue(expandedContext);
+        const response = await handleExplain({ name: 'hello' }, mockHybridSearch, mockContextExpander);
+        const parsed = parseResponse(response);
+        expect(mockHybridSearch.search).toHaveBeenCalledWith('hello', { topK: 5 });
+        expect(parsed.chunks_found).toBe(1);
+        expect(parsed.explanation.chunks[0].name).toBe('hello');
+        expect(parsed.explanation.chunks[0].nl_summary).toBe('A greeting function');
+        expect(parsed.explanation.chunks[0].code).toBe('function hello() {}');
+    });
+    it('should search by file_path and return matching chunks', async () => {
+        const results = [makeSearchResult()];
+        vi.mocked(mockHybridSearch.search).mockResolvedValue(ok(results));
+        const expandedContext = {
+            primaryResults: results,
+            relatedChunks: [],
+            graphExcerpt: { nodes: [], edges: [] },
+        };
+        vi.mocked(mockContextExpander.expand).mockReturnValue(expandedContext);
+        const response = await handleExplain({ file_path: 'src/utils/hello.ts' }, mockHybridSearch, mockContextExpander);
+        const parsed = parseResponse(response);
+        expect(mockHybridSearch.search).toHaveBeenCalledWith('src/utils/hello.ts', { topK: 20 });
+        expect(parsed.chunks_found).toBe(1);
+        expect(parsed.explanation.chunks[0].file_path).toBe('src/utils/hello.ts');
+    });
+    it('should return brief output without code or related_symbols', async () => {
+        const results = [makeSearchResult()];
+        vi.mocked(mockHybridSearch.search).mockResolvedValue(ok(results));
+        const response = await handleExplain({ name: 'hello', detail_level: 'brief' }, mockHybridSearch, mockContextExpander);
+        const parsed = parseResponse(response);
+        expect(parsed.explanation.detail_level).toBe('brief');
+        expect(parsed.explanation.chunks[0].nl_summary).toBe('A greeting function');
+        expect(parsed.explanation.chunks[0].code).toBeUndefined();
+        expect(parsed.explanation.related_symbols).toBeUndefined();
+    });
+    it('should return detailed output with code and related_symbols', async () => {
+        const results = [makeSearchResult()];
+        vi.mocked(mockHybridSearch.search).mockResolvedValue(ok(results));
+        const depResult = makeSearchResult({
+            chunkId: 'dep-1',
+            metadata: {
+                chunkType: 'function',
+                name: 'greet',
+                declarations: [],
+                imports: [],
+                exports: [],
+            },
+            chunk: {
+                id: 'dep-1',
+                content: 'function greet() {}',
+                nlSummary: 'A greet helper',
+                filePath: 'src/utils/greet.ts',
+                startLine: 1,
+                endLine: 2,
+                language: 'typescript',
+                metadata: {
+                    chunkType: 'function',
+                    name: 'greet',
+                    declarations: [],
+                    imports: [],
+                    exports: [],
+                },
+            },
+        });
+        const expandedContext = {
+            primaryResults: results,
+            relatedChunks: [
+                {
+                    chunk: depResult,
+                    relationship: 'imports',
+                    distance: 1,
+                },
+            ],
+            graphExcerpt: { nodes: [], edges: [] },
+        };
+        vi.mocked(mockContextExpander.expand).mockReturnValue(expandedContext);
+        const response = await handleExplain({ name: 'hello', detail_level: 'detailed' }, mockHybridSearch, mockContextExpander);
+        const parsed = parseResponse(response);
+        expect(parsed.explanation.detail_level).toBe('detailed');
+        expect(parsed.explanation.chunks[0].code).toBe('function hello() {}');
+        expect(parsed.explanation.related_symbols).toContain('greet');
+    });
+    it('should handle search API errors gracefully', async () => {
+        vi.mocked(mockHybridSearch.search).mockResolvedValue(err(new EmbedError('Connection refused')));
+        const response = await handleExplain({ name: 'hello' }, mockHybridSearch, mockContextExpander);
+        const parsed = parseResponse(response);
+        expect(parsed.error).toBe('Search failed');
+        expect(parsed.message).toContain('Connection refused');
+    });
+    it('should handle thrown exceptions', async () => {
+        vi.mocked(mockHybridSearch.search).mockRejectedValue(new Error('Unexpected'));
+        const response = await handleExplain({ name: 'hello' }, mockHybridSearch, mockContextExpander);
+        const parsed = parseResponse(response);
+        expect(parsed.error).toBe('Explain failed');
+        expect(parsed.message).toBe('Unexpected');
+    });
+    it('should return empty explanation when no chunks match name', async () => {
+        const results = [makeSearchResult({
+                metadata: {
+                    chunkType: 'function',
+                    name: 'other',
+                    declarations: [],
+                    imports: [],
+                    exports: [],
+                },
+            })];
+        vi.mocked(mockHybridSearch.search).mockResolvedValue(ok(results));
+        const response = await handleExplain({ name: 'hello' }, mockHybridSearch, mockContextExpander);
+        const parsed = parseResponse(response);
+        expect(parsed.chunks_found).toBe(0);
+        expect(parsed.message).toContain('No chunks found matching name: hello');
+    });
+    it('should return empty explanation when no chunks match file_path', async () => {
+        const results = [makeSearchResult()]; // filePath is 'src/utils/hello.ts'
+        vi.mocked(mockHybridSearch.search).mockResolvedValue(ok(results));
+        const response = await handleExplain({ file_path: 'src/other.ts' }, mockHybridSearch, mockContextExpander);
+        const parsed = parseResponse(response);
+        expect(parsed.chunks_found).toBe(0);
+        expect(parsed.message).toContain('No chunks found for file: src/other.ts');
+    });
+    it('should work without context expander in detailed mode', async () => {
+        const results = [makeSearchResult()];
+        vi.mocked(mockHybridSearch.search).mockResolvedValue(ok(results));
+        const response = await handleExplain({ name: 'hello', detail_level: 'detailed' }, mockHybridSearch, null);
+        const parsed = parseResponse(response);
+        expect(parsed.chunks_found).toBe(1);
+        expect(parsed.explanation.chunks[0].code).toBe('function hello() {}');
+        // No related_symbols since context expander is null
+        expect(parsed.explanation.related_symbols).toBeUndefined();
+    });
+});
+//# sourceMappingURL=explain.test.js.map

package/dist/tools/explain.test.js.map

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

package/dist/tools/search.d.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import type { HybridSearch } from '@code-rag/core';
+import type { ReRanker } from '@code-rag/core';
+export declare const searchInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    language: z.ZodOptional<z.ZodString>;
+    file_path: z.ZodOptional<z.ZodString>;
+    chunk_type: z.ZodOptional<z.ZodString>;
+    top_k: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+export type SearchInput = z.infer<typeof searchInputSchema>;
+export interface SearchToolResult {
+    file_path: string;
+    chunk_type: string;
+    name: string;
+    content: string;
+    nl_summary: string;
+    score: number;
+}
+export declare function handleSearch(args: Record<string, unknown>, hybridSearch: HybridSearch | null, reranker?: ReRanker | null): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;

package/dist/tools/search.js

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+export const searchInputSchema = z.object({
+    query: z.string().min(1, 'query must not be empty'),
+    language: z.string().optional(),
+    file_path: z.string().refine((s) => !s.includes('..'), 'file_path must not contain path traversal').optional(),
+    chunk_type: z.string().optional(),
+    top_k: z.number().int().positive().max(100).optional().default(10),
+});
+function formatResult(result) {
+    return {
+        file_path: result.chunk?.filePath ?? '',
+        chunk_type: result.metadata?.chunkType ?? 'unknown',
+        name: result.metadata?.name ?? '',
+        content: result.content,
+        nl_summary: result.nlSummary,
+        score: result.score,
+    };
+}
+export async function handleSearch(args, hybridSearch, reranker = null) {
+    const parsed = searchInputSchema.safeParse(args);
+    if (!parsed.success) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: 'Invalid input',
+                        details: parsed.error.issues,
+                    }),
+                },
+            ],
+        };
+    }
+    if (!hybridSearch) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        results: [],
+                        message: 'Search index not initialized. Run indexing first.',
+                    }),
+                },
+            ],
+        };
+    }
+    const { query, top_k } = parsed.data;
+    try {
+        const searchResult = await hybridSearch.search(query, { topK: top_k });
+        if (searchResult.isErr()) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: 'Search failed',
+                            message: searchResult.error.message,
+                        }),
+                    },
+                ],
+            };
+        }
+        let results = searchResult.value;
+        // Apply optional filters
+        if (parsed.data.language) {
+            const lang = parsed.data.language.toLowerCase();
+            results = results.filter((r) => r.chunk?.language?.toLowerCase() === lang);
+        }
+        if (parsed.data.file_path) {
+            const fp = parsed.data.file_path;
+            results = results.filter((r) => r.chunk?.filePath?.includes(fp));
+        }
+        if (parsed.data.chunk_type) {
+            const ct = parsed.data.chunk_type;
+            results = results.filter((r) => r.metadata?.chunkType === ct);
+        }
+        // Re-rank results if reranker is available
+        if (reranker) {
+            const rerankResult = await reranker.rerank(query, results);
+            if (rerankResult.isOk()) {
+                results = rerankResult.value;
+            }
+            // If reranking fails, fall back to original results (don't fail the search)
+        }
+        const formatted = results.map(formatResult);
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ results: formatted }) }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ error: 'Search failed', message }),
+                },
+            ],
+        };
+    }
+}

package/dist/tools/search.js.map

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

package/dist/tools/status.d.ts

@@ -0,0 +1,14 @@
+import type { LanceDBStore, CodeRAGConfig } from '@code-rag/core';
+export interface StatusResult {
+    total_chunks: number;
+    last_indexed: string | null;
+    model: string;
+    languages: string[] | 'auto';
+    health: 'ok' | 'degraded' | 'not_initialized';
+}
+export declare function handleStatus(store: LanceDBStore | null, config: CodeRAGConfig | null): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;

package/dist/tools/status.js

@@ -0,0 +1,41 @@
+export async function handleStatus(store, config) {
+    try {
+        let totalChunks = 0;
+        let health = 'not_initialized';
+        if (store) {
+            const countResult = await store.count();
+            if (countResult.isOk()) {
+                totalChunks = countResult.value;
+                health = totalChunks > 0 ? 'ok' : 'degraded';
+            }
+            else {
+                health = 'degraded';
+            }
+        }
+        const status = {
+            total_chunks: totalChunks,
+            last_indexed: null,
+            model: config?.embedding.model ?? 'unknown',
+            languages: config?.project.languages ?? 'auto',
+            health,
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(status) }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: 'Status check failed',
+                        message,
+                        health: 'degraded',
+                    }),
+                },
+            ],
+        };
+    }
+}

package/dist/tools/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/tools/status.ts"],"names":[],"mappings":"AAUA,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAA0B,EAC1B,MAA4B;IAE5B,IAAI,CAAC;QACH,IAAI,WAAW,GAAG,CAAC,CAAC;QACpB,IAAI,MAAM,GAA2B,iBAAiB,CAAC;QAEvD,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,WAAW,GAAG,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;YACxC,IAAI,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC;gBACvB,WAAW,GAAG,WAAW,CAAC,KAAK,CAAC;gBAChC,MAAM,GAAG,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC;YAC/C,CAAC;iBAAM,CAAC;gBACN,MAAM,GAAG,UAAU,CAAC;YACtB,CAAC;QACH,CAAC;QAED,MAAM,MAAM,GAAiB;YAC3B,YAAY,EAAE,WAAW;YACzB,YAAY,EAAE,IAAI;YAClB,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,KAAK,IAAI,SAAS;YAC3C,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,SAAS,IAAI,MAAM;YAC9C,MAAM;SACP,CAAC;QAEF,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;SAC1D,CAAC;IACJ,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;QACzE,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;wBACnB,KAAK,EAAE,qBAAqB;wBAC5B,OAAO;wBACP,MAAM,EAAE,UAAU;qBACnB,CAAC;iBACH;aACF;SACF,CAAC;IACJ,CAAC;AACH,CAAC"}