@justmpm/deps-consult 1.0.0

package/README.md

@@ -0,0 +1,227 @@
+# @justmpm/deps-consult
+
+MCP server que consulta pacotes npm instalados no `node_modules` diretamente. Extrai API surfaces, JSDoc, exemplos de uso e metadados -- zero config, offline, sem API keys.
+
+[![npm version](https://img.shields.io/npm/v/@justmpm/deps-consult.svg)](https://www.npmjs.com/package/@justmpm/deps-consult)
+[![license](https://img.shields.io/npm/l/@justmpm/deps-consult.svg)](https://github.com/Just-mpm/deps-consult/blob/main/LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org/)
+
+## Features
+
+- **API surface completa** -- funcoes, classes, interfaces, tipos, enums e variaveis exportadas com assinaturas TypeScript
+- **JSDoc rico** -- extrai `@param`, `@returns`, `@example`, `@deprecated`, `@since`, `@see`, `@throws`, `@default`
+- **Exemplos de codigo** -- coleta de 4 fontes: JSDoc `@example`, diretorio `/examples`, blocos de codigo do README e `/docs`
+- **Busca inteligente** -- match exato, prefixo (`Button*`), sufixo (`*Button`), contem (`*Button*`) e fuzzy matching com scoring
+- **Zero config** -- funciona com qualquer pacote npm, sem internet, sem API keys, sem arquivos de configuracao
+- **Deduplicacao automatica** -- pacotes com multiplos entry points (como es-toolkit) nao geram resultados duplicados
+- **Cache LRU** -- 50 pacotes em cache com TTL de 30 minutos e invalidacao automatica por hash do package.json
+- **Suporte completo** -- pacotes scoped, workspaces, symlinks, conditional exports e fallbacks legados
+
+## Instalacao
+
+### npx (sem instalar)
+
+```json
+{
+  "mcpServers": {
+    "deps-consult": {
+      "command": "npx",
+      "args": ["-y", "@justmpm/deps-consult"]
+    }
+  }
+}
+```
+
+### Instalacao global
+
+```bash
+npm install -g @justmpm/deps-consult
+```
+
+```json
+{
+  "mcpServers": {
+    "deps-consult": {
+      "command": "deps-consult"
+    }
+  }
+}
+```
+
+### Como projeto local
+
+```bash
+git clone https://github.com/Just-mpm/deps-consult.git
+cd deps-consult
+npm install && npm run build
+```
+
+```json
+{
+  "mcpServers": {
+    "deps-consult": {
+      "command": "node",
+      "args": ["D:/caminho/para/deps-consult/build/index.js"]
+    }
+  }
+}
+```
+
+## Configuracao MCP
+
+O `deps-consult` usa transporte stdio (JSON-RPC). Adicione a configuracao acima no arquivo de configuracao do seu cliente:
+
+| Cliente | Arquivo de configuracao |
+|---------|------------------------|
+| Claude Desktop | `~/.claude/claude_desktop_config.json` |
+| OpenCode | `.opencode/config.json` |
+| Cursor | `.cursor/mcp.json` |
+
+## Referencia das Tools
+
+| Tool | Descricao | Parametros |
+|------|-----------|------------|
+| `deps_info` | Visao geral do pacote: versao, descricao, entry points, dependencias, peer deps, tipos, tamanho | `package`, `projectDir?` |
+| `deps_api` | API surface completa: todas as funcoes, classes, interfaces, tipos, enums e variaveis com assinaturas | `package`, `entrypoint?`, `kind?`, `limit?` |
+| `deps_search` | Busca simbolos por nome com wildcards e fuzzy matching | `package`, `query`, `entrypoint?`, `kind?` |
+| `deps_usage` | Detalhes de uso de um simbolo: assinatura, JSDoc, parametros, return type, exemplos, imports | `package`, `symbol`, `entrypoint?` |
+| `deps_examples` | Exemplos de codigo extraidos de JSDoc, /examples, README e /docs | `package`, `symbol?`, `entrypoint?` |
+
+### Parametros em detalhe
+
+**deps_info**
+- `package` (string, obrigatorio) -- Nome do pacote (ex: `zod`, `@mui/material`)
+- `projectDir` (string, opcional) -- Diretorio do projeto. Default: `process.cwd()`
+
+**deps_api**
+- `package` (string, obrigatorio)
+- `entrypoint` (string, opcional) -- Subpath do entry point (ex: `"hooks"`, `"utils"`)
+- `kind` (enum, opcional) -- `all` | `functions` | `classes` | `interfaces` | `types` | `enums` | `variables`. Default: `all`
+- `limit` (number, opcional) -- Maximo de simbolos por categoria. Range: 1-200. Default: 50
+
+**deps_search**
+- `package` (string, obrigatorio)
+- `query` (string, obrigatorio) -- Suporta wildcards: `Button` (exato), `Button*` (prefixo), `*Button` (sufixo), `*Button*` (contem)
+- `entrypoint` (string, opcional)
+- `kind` (enum, opcional) -- Mesmas opcoes do `deps_api`
+
+**deps_usage**
+- `package` (string, obrigatorio)
+- `symbol` (string, obrigatorio) -- Nome exato do simbolo. Se nao encontrar, faz busca fuzzy com score > 0.5
+- `entrypoint` (string, opcional)
+
+**deps_examples**
+- `package` (string, obrigatorio)
+- `symbol` (string, opcional) -- Filtra exemplos por simbolo
+- `entrypoint` (string, opcional)
+
+## Exemplos de Uso
+
+### Conhecer um pacote novo
+
+```
+deps_info zod
+```
+
+Retorna versao, descricao, entry points, dependencias, se tem tipos e tamanho no disco.
+
+### Ver a API completa
+
+```
+deps_api es-toolkit kind=functions limit=30
+```
+
+Lista as primeiras 30 funcoes exportadas com assinaturas TypeScript.
+
+### Buscar um simbolo
+
+```
+deps_search @mui/material query="Button*"
+```
+
+Encontra todos os simbolos com prefixo "Button" no MUI.
+
+### Entender como usar um simbolo
+
+```
+deps_usage zod symbol="object"
+```
+
+Retorna a assinatura completa, JSDoc (params, returns), exemplos e todos os caminhos de import possiveis.
+
+### Ver exemplos de codigo
+
+```
+deps_examples react-hook-form
+```
+
+Coleta exemplos de todas as fontes: JSDoc, diretorio de exemplos, README e docs.
+
+## Arquitetura
+
+```
+src/
+  index.ts                          MCP server (5 tools registradas)
+  pipeline.ts                       Orquestracao: resolvers -> extractors -> cache
+  types/index.ts                    Tipos compartilhados
+  schemas/package-json.schema.ts    Zod v4 schemas (package.json + inputs)
+  cache/package-cache.ts            LRU cache (50 pacotes, 30min TTL)
+  resolvers/
+    package-resolver.ts             Encontra pacote no node_modules
+    exports-resolver.ts             Resolve conditional exports
+    types-resolver.ts               5 estrategias para achar .d.ts
+  extractors/
+    api-extractor.ts                ts-morph: extrai API surface
+    jsdoc-extractor.ts              Extrai @param, @returns, @example, etc.
+    readme-extractor.ts             Parser manual de markdown
+    examples-extractor.ts           4 fontes de exemplos
+  formatters/
+    markdown-formatter.ts           Output otimizado para contexto de LLM
+```
+
+Fluxo de dados:
+
+```
+Tool call
+  -> Cache (hit? retorna)
+  -> PackageResolver (acha no node_modules)
+  -> ExportsResolver (resolve entry points)
+  -> TypesResolver (acha .d.ts com 5 estrategias)
+  -> ApiExtractor (ts-morph: funcoes, classes, tipos...)
+  -> ReadmeExtractor (parser manual)
+  -> Deduplicacao por nome (Set)
+  -> Salva no cache
+  -> Formatter (markdown para LLM)
+  -> Response
+```
+
+## Desenvolvimento
+
+```bash
+# Instalar dependencias
+npm install
+
+# Build
+npm run build
+
+# Desenvolvimento (watch)
+npm run dev
+
+# Lint
+npm run lint
+
+# Type check
+npm run type-check
+
+# Testes (JSON-RPC real via stdin/stdout)
+node test-mcp.ts
+```
+
+### Requisitos
+
+- Node.js >= 22.0.0
+- npm (ou bun)
+
+## Licenca
+
+[MIT](https://github.com/Just-mpm/deps-consult/blob/main/LICENSE) -- Koda AI Studio

package/build/cache/package-cache.d.ts

@@ -0,0 +1,39 @@
+import type { CachedPackage } from '../types/index.js';
+export declare class PackageCache {
+    private readonly cache;
+    constructor(maxPackages?: number, ttlMs?: number);
+    /**
+     * Gera a cache key: `${projectDir}:${packageName}`
+     */
+    private getKey;
+    /**
+     * Computa hash do package.json para invalidação.
+     */
+    computePackageJsonHash(packageDir: string): Promise<string>;
+    /**
+     * Busca pacote no cache. Retorna null se não existe ou se o hash mudou.
+     */
+    get(projectDir: string, packageName: string): Promise<CachedPackage | null>;
+    /**
+     * Armazena pacote no cache.
+     */
+    set(projectDir: string, packageName: string, data: CachedPackage): Promise<void>;
+    /**
+     * Invalida um pacote específico.
+     */
+    invalidate(projectDir: string, packageName: string): void;
+    /**
+     * Limpa todo o cache.
+     */
+    clear(): void;
+    /**
+     * Estatísticas do cache.
+     */
+    get stats(): {
+        size: number;
+        max: number;
+    };
+}
+/** Singleton compartilhado entre todas as tools */
+export declare const packageCache: PackageCache;
+//# sourceMappingURL=package-cache.d.ts.map

package/build/cache/package-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-cache.d.ts","sourceRoot":"","sources":["../../src/cache/package-cache.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAUvD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;gBAEzC,WAAW,GAAE,MAA6B,EAAE,KAAK,GAAE,MAAuB;IAQtF;;OAEG;IACH,OAAO,CAAC,MAAM;IAId;;OAEG;IACG,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASjE;;OAEG;IACG,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAgBjF;;OAEG;IACG,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAUtF;;OAEG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAIzD;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,KAAK,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAKzC;CACF;AAED,mDAAmD;AACnD,eAAO,MAAM,YAAY,cAAqB,CAAC"}

package/build/cache/package-cache.js

@@ -0,0 +1,90 @@
+/**
+ * Cache LRU para pacotes extraídos.
+ * Evita re-parsear pacotes já consultados na mesma sessão.
+ * Invalidação automática por TTL e por hash do package.json.
+ */
+import { LRUCache } from 'lru-cache';
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const DEFAULT_MAX_PACKAGES = 50;
+const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 minutos
+export class PackageCache {
+    cache;
+    constructor(maxPackages = DEFAULT_MAX_PACKAGES, ttlMs = DEFAULT_TTL_MS) {
+        this.cache = new LRUCache({
+            max: maxPackages,
+            ttl: ttlMs,
+            allowStaleOnFetchAbort: true,
+        });
+    }
+    /**
+     * Gera a cache key: `${projectDir}:${packageName}`
+     */
+    getKey(projectDir, packageName) {
+        return `${projectDir}:${packageName}`;
+    }
+    /**
+     * Computa hash do package.json para invalidação.
+     */
+    async computePackageJsonHash(packageDir) {
+        try {
+            const content = await readFile(join(packageDir, 'package.json'), 'utf-8');
+            return createHash('md5').update(content).digest('hex');
+        }
+        catch {
+            return '';
+        }
+    }
+    /**
+     * Busca pacote no cache. Retorna null se não existe ou se o hash mudou.
+     */
+    async get(projectDir, packageName) {
+        const key = this.getKey(projectDir, packageName);
+        const entry = this.cache.get(key);
+        if (!entry)
+            return null;
+        // Verificar se o package.json mudou desde o cache
+        const currentHash = await this.computePackageJsonHash(entry.data.meta.packageDir);
+        if (currentHash !== entry.packageJsonHash) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry.data;
+    }
+    /**
+     * Armazena pacote no cache.
+     */
+    async set(projectDir, packageName, data) {
+        const key = this.getKey(projectDir, packageName);
+        const packageJsonHash = await this.computePackageJsonHash(data.meta.packageDir);
+        this.cache.set(key, {
+            data,
+            packageJsonHash,
+        });
+    }
+    /**
+     * Invalida um pacote específico.
+     */
+    invalidate(projectDir, packageName) {
+        this.cache.delete(this.getKey(projectDir, packageName));
+    }
+    /**
+     * Limpa todo o cache.
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Estatísticas do cache.
+     */
+    get stats() {
+        return {
+            size: this.cache.size,
+            max: this.cache.max,
+        };
+    }
+}
+/** Singleton compartilhado entre todas as tools */
+export const packageCache = new PackageCache();
+//# sourceMappingURL=package-cache.js.map

package/build/cache/package-cache.js.map

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

package/build/extractors/api-extractor.d.ts

@@ -0,0 +1,6 @@
+import type { ExtractedSymbol } from '../types/index.js';
+/**
+ * Extrai todos os símbolos exportados de uma lista de arquivos de tipos.
+ */
+export declare function extractApiSurface(typeFiles: ReadonlyArray<string>, entrypoint: string | undefined, packageDir: string): ReadonlyArray<ExtractedSymbol>;
+//# sourceMappingURL=api-extractor.d.ts.map

package/build/extractors/api-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-extractor.d.ts","sourceRoot":"","sources":["../../src/extractors/api-extractor.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAc,MAAM,mBAAmB,CAAC;AAOrE;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,EAChC,UAAU,EAAE,MAAM,YAAM,EACxB,UAAU,EAAE,MAAM,GACjB,aAAa,CAAC,eAAe,CAAC,CAoChC"}

package/build/extractors/api-extractor.js

@@ -0,0 +1,191 @@
+/**
+ * Extrai a API surface completa de arquivos .d.ts usando ts-morph.
+ * Resolve re-exports, aliases e segue a cadeia de exports automaticamente.
+ */
+import { Project, SyntaxKind } from 'ts-morph';
+import { relative } from 'node:path';
+import { extractJSDoc } from './jsdoc-extractor.js';
+import { uniqBy } from 'es-toolkit';
+/** Limite de profundidade para seguir re-exports */
+const MAX_REEXPORT_DEPTH = 10;
+/**
+ * Extrai todos os símbolos exportados de uma lista de arquivos de tipos.
+ */
+export function extractApiSurface(typeFiles, entrypoint = '.', packageDir) {
+    const project = new Project({
+        skipAddingFilesFromTsConfig: true,
+        useInMemoryFileSystem: false,
+        compilerOptions: {
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            noEmit: true,
+        },
+    });
+    // Adicionar arquivos de tipos ao projeto
+    const sourceFiles = [];
+    for (const filePath of typeFiles) {
+        try {
+            const sf = project.addSourceFileAtPath(filePath);
+            sourceFiles.push(sf);
+        }
+        catch (error) {
+            console.error(`[deps-consult] Falha ao parsear ${filePath}: ${error}`);
+        }
+    }
+    const symbols = [];
+    for (const sourceFile of sourceFiles) {
+        try {
+            const fileSymbols = extractFromFile(sourceFile, entrypoint, packageDir);
+            symbols.push(...fileSymbols);
+        }
+        catch (error) {
+            console.error(`[deps-consult] Erro ao extrair de ${sourceFile.getFilePath()}: ${error}`);
+        }
+    }
+    // Deduplicar (mesmo símbolo pode vir de múltiplos .d.ts)
+    return uniqBy(symbols, s => `${s.kind}:${s.name}`);
+}
+/**
+ * Extrai símbolos de um único source file.
+ */
+function extractFromFile(sourceFile, entrypoint, packageDir) {
+    const symbols = [];
+    const filePath = sourceFile.getFilePath();
+    // getExportedDeclarations() resolve re-exports automaticamente!
+    const exportedDeclarations = sourceFile.getExportedDeclarations();
+    for (const [exportName, declarations] of exportedDeclarations) {
+        // Pular export * (nome é asterisk-like ou Symbol)
+        if (!exportName || exportName === 'default')
+            continue;
+        for (const decl of declarations) {
+            const symbol = extractSymbol(exportName, decl, entrypoint, packageDir);
+            if (symbol)
+                symbols.push(symbol);
+        }
+    }
+    // Capturar default export
+    const defaultExports = sourceFile.getExportAssignments();
+    for (const defaultExport of defaultExports) {
+        const expression = defaultExport.getExpression();
+        const decl = expression.getSymbol()?.getDeclarations()[0];
+        if (decl) {
+            const symbol = extractSymbol('default', decl, entrypoint, packageDir);
+            if (symbol)
+                symbols.push(symbol);
+        }
+    }
+    return symbols;
+}
+/**
+ * Extrai um único símbolo de uma declaração.
+ */
+function extractSymbol(name, decl, entrypoint, packageDir) {
+    try {
+        const kind = getSymbolKind(decl);
+        if (!kind)
+            return null;
+        const signature = getSignature(decl, name);
+        // getSourceFile() está disponível em nós que têm arquivo
+        const sourceFile = decl.getSourceFile?.();
+        if (!sourceFile)
+            return null;
+        const filePath = sourceFile.getFilePath();
+        const lineNumber = decl.getStartLineNumber?.() ?? 0;
+        const jsdoc = extractJSDoc(decl);
+        return {
+            name,
+            kind,
+            signature,
+            file: relative(packageDir, filePath).replace(/\\/g, '/'),
+            line: lineNumber,
+            entrypoint,
+            jsdoc,
+            isReExport: false,
+            originalModule: undefined,
+        };
+    }
+    catch (error) {
+        console.error(`[deps-consult] Erro ao extrair símbolo '${name}': ${error}`);
+        return null;
+    }
+}
+/**
+ * Determina o tipo do símbolo baseado no SyntaxKind.
+ */
+function getSymbolKind(decl) {
+    const kind = decl.getKind();
+    switch (kind) {
+        case SyntaxKind.FunctionDeclaration:
+        case SyntaxKind.FunctionExpression:
+        case SyntaxKind.ArrowFunction:
+        case SyntaxKind.MethodDeclaration:
+            return 'function';
+        case SyntaxKind.ClassDeclaration:
+            return 'class';
+        case SyntaxKind.InterfaceDeclaration:
+            return 'interface';
+        case SyntaxKind.TypeAliasDeclaration:
+            return 'type';
+        case SyntaxKind.EnumDeclaration:
+            return 'enum';
+        case SyntaxKind.VariableDeclaration:
+        case SyntaxKind.VariableStatement: {
+            try {
+                const parent = decl.getParentIfKind?.(SyntaxKind.VariableDeclarationList);
+                if (parent) {
+                    const flags = parent.getDeclarationFlags?.();
+                    if (flags !== undefined && (flags & 2)) {
+                        return 'constant';
+                    }
+                }
+            }
+            catch {
+                // Fallback
+            }
+            return 'variable';
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Extrai a assinatura completa do símbolo como string.
+ */
+function getSignature(decl, name) {
+    try {
+        const kind = decl.getKind();
+        const text = decl.getText();
+        switch (kind) {
+            case SyntaxKind.FunctionDeclaration: {
+                const bodyIndex = text.indexOf('=> {') !== -1 ? text.indexOf('=> {') : text.indexOf(') {');
+                return bodyIndex > -1 ? text.substring(0, bodyIndex).trim() : `function ${name}()`;
+            }
+            case SyntaxKind.ClassDeclaration: {
+                const className = decl.getName?.() ?? name;
+                return `class ${className}`;
+            }
+            case SyntaxKind.InterfaceDeclaration: {
+                const ifaceName = decl.getName?.() ?? name;
+                return `interface ${ifaceName}`;
+            }
+            case SyntaxKind.TypeAliasDeclaration: {
+                return text.length > 500 ? text.substring(0, 500) + '...' : text;
+            }
+            case SyntaxKind.EnumDeclaration: {
+                const enumName = decl.getName?.() ?? name;
+                return `enum ${enumName}`;
+            }
+            case SyntaxKind.VariableDeclaration: {
+                const typeText = decl.getType?.()?.getText(decl) ?? 'unknown';
+                return `const ${name}: ${typeText}`;
+            }
+            default:
+                return name;
+        }
+    }
+    catch {
+        return name;
+    }
+}
+//# sourceMappingURL=api-extractor.js.map

package/build/extractors/api-extractor.js.map

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

package/build/extractors/examples-extractor.d.ts

@@ -0,0 +1,16 @@
+import type { ExtractedSymbol, ReadmeData } from '../types/index.js';
+export interface CodeExample {
+    /** Código do exemplo */
+    code: string;
+    /** Linguagem (typescript, javascript, etc) */
+    language?: string;
+    /** Contexto (qual símbolo ou seção) */
+    context?: string;
+    /** Origem do exemplo */
+    source: 'jsdoc' | 'examples-dir' | 'readme' | 'docs';
+}
+/**
+ * Coleta exemplos de todas as fontes disponíveis.
+ */
+export declare function extractExamples(packageDir: string, symbols: ReadonlyArray<ExtractedSymbol>, readme: ReadmeData | null, targetSymbol?: string): Promise<ReadonlyArray<CodeExample>>;
+//# sourceMappingURL=examples-extractor.d.ts.map

package/build/extractors/examples-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"examples-extractor.d.ts","sourceRoot":"","sources":["../../src/extractors/examples-extractor.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGrE,MAAM,WAAW,WAAW;IAC1B,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,MAAM,EAAE,OAAO,GAAG,cAAc,GAAG,QAAQ,GAAG,MAAM,CAAC;CACtD;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,aAAa,CAAC,eAAe,CAAC,EACvC,MAAM,EAAE,UAAU,GAAG,IAAI,EACzB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAsBrC"}