@ssolis-ti/mcp-compra-agil 1.0.3 → 2.3.0

package/dist/tools/verificar-ticket.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Tool: verificar_ticket
+ *
+ * Comprueba que el ticket configurado funciona contra la API real,
+ * SIN revelar su valor. Solo muestra una pista (últimos 4 caracteres).
+ *
+ * Existe para que la primera prueba end-to-end no obligue a nadie a imprimir,
+ * pegar o compartir la credencial.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { CompraAgilClient } from '../api/compra-agil-client.js';
+export declare function registerVerificarTicket(server: McpServer, client: CompraAgilClient): void;
+//# sourceMappingURL=verificar-ticket.d.ts.map

package/dist/tools/verificar-ticket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verificar-ticket.d.ts","sourceRoot":"","sources":["../../src/tools/verificar-ticket.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAUhE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAmEzF"}

package/dist/tools/verificar-ticket.js

@@ -0,0 +1,79 @@
+/**
+ * Tool: verificar_ticket
+ *
+ * Comprueba que el ticket configurado funciona contra la API real,
+ * SIN revelar su valor. Solo muestra una pista (últimos 4 caracteres).
+ *
+ * Existe para que la primera prueba end-to-end no obligue a nadie a imprimir,
+ * pegar o compartir la credencial.
+ */
+import { CompraAgilApiError } from '../utils/error-handler.js';
+import { safeError, pista } from '../utils/redact.js';
+const TOOL_NAME = 'verificar_ticket';
+const TOOL_DESCRIPTION = `Verifica que el ticket de acceso a la API de Mercado Público esté configurado y sea válido, realizando una consulta mínima de prueba.
+NUNCA revela el valor del ticket: solo informa si funciona y muestra los últimos 4 caracteres como referencia.
+Úsala como primer diagnóstico cuando otras herramientas fallen con errores de autenticación.`;
+export function registerVerificarTicket(server, client) {
+    server.registerTool(TOOL_NAME, { description: TOOL_DESCRIPTION }, async () => {
+        const referencia = pista(process.env.COMPRA_AGIL_TICKET);
+        if (!process.env.COMPRA_AGIL_TICKET) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: [
+                            '❌ No hay ticket configurado.',
+                            '',
+                            'Configura la variable de entorno COMPRA_AGIL_TICKET (por ejemplo, en un archivo .env).',
+                            'Obtén tu ticket en https://www.chilecompra.cl/api/ (requiere Clave Única).',
+                            '',
+                            '⚠ No pegues el ticket en el chat ni lo compartas: guárdalo solo en el .env,',
+                            '  que ya está protegido por .gitignore.',
+                        ].join('\n'),
+                    }],
+                isError: true,
+            };
+        }
+        try {
+            // Consulta de humo mínima: ventana de cambios de 1 hora.
+            //
+            // IMPORTANTE: la API NO acepta consultas sin filtros — devuelve HTTP 500
+            // (verificado contra el servicio real). Debe enviarse al menos un filtro.
+            // `ttl_cambio_ms` es el más liviano: responde en ~1s aunque no haya
+            // resultados, y un 200 basta para probar que el ticket es válido.
+            const resp = await client.buscar({ ttl_cambio_ms: 3_600_000, tamano_pagina: 10, numero_pagina: 1 });
+            return {
+                content: [{
+                        type: 'text',
+                        text: [
+                            '✅ Ticket válido y operativo.',
+                            '',
+                            `Ticket configurado: ${referencia}`,
+                            `Consulta de prueba: cambios en la última hora → ${resp.paginacion.total_resultados} resultado(s).`,
+                            `Cuota consumida en esta sesión: ${client.getRateLimitStats().requestsToday} request(s).`,
+                            '',
+                            'Nota: un total de 0 es normal si no hubo movimientos en la última hora;',
+                            'lo relevante es que la API respondió correctamente con este ticket.',
+                        ].join('\n'),
+                    }],
+            };
+        }
+        catch (error) {
+            const detalle = error instanceof CompraAgilApiError
+                ? error.actionableMessage
+                : safeError(error);
+            return {
+                content: [{
+                        type: 'text',
+                        text: [
+                            '❌ El ticket está configurado pero la verificación falló.',
+                            '',
+                            `Ticket configurado: ${referencia}`,
+                            `Motivo: ${detalle}`,
+                        ].join('\n'),
+                    }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=verificar-ticket.js.map

package/dist/tools/verificar-ticket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verificar-ticket.js","sourceRoot":"","sources":["../../src/tools/verificar-ticket.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEtD,MAAM,SAAS,GAAG,kBAAkB,CAAC;AAErC,MAAM,gBAAgB,GAAG;;6FAEoE,CAAC;AAE9F,MAAM,UAAU,uBAAuB,CAAC,MAAiB,EAAE,MAAwB;IACjF,MAAM,CAAC,YAAY,CACjB,SAAS,EACT,EAAE,WAAW,EAAE,gBAAgB,EAAE,EACjC,KAAK,IAAI,EAAE;QACT,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QAEzD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,CAAC;YACpC,OAAO;gBACL,OAAO,EAAE,CAAC;wBACR,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE;4BACJ,8BAA8B;4BAC9B,EAAE;4BACF,wFAAwF;4BACxF,4EAA4E;4BAC5E,EAAE;4BACF,6EAA6E;4BAC7E,yCAAyC;yBAC1C,CAAC,IAAI,CAAC,IAAI,CAAC;qBACb,CAAC;gBACF,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,yDAAyD;YACzD,EAAE;YACF,yEAAyE;YACzE,0EAA0E;YAC1E,oEAAoE;YACpE,kEAAkE;YAClE,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,EAAE,aAAa,EAAE,SAAS,EAAE,aAAa,EAAE,EAAE,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC,CAAC;YACpG,OAAO;gBACL,OAAO,EAAE,CAAC;wBACR,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE;4BACJ,8BAA8B;4BAC9B,EAAE;4BACF,uBAAuB,UAAU,EAAE;4BACnC,mDAAmD,IAAI,CAAC,UAAU,CAAC,gBAAgB,gBAAgB;4BACnG,mCAAmC,MAAM,CAAC,iBAAiB,EAAE,CAAC,aAAa,cAAc;4BACzF,EAAE;4BACF,yEAAyE;4BACzE,qEAAqE;yBACtE,CAAC,IAAI,CAAC,IAAI,CAAC;qBACb,CAAC;aACH,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,KAAK,YAAY,kBAAkB;gBACjD,CAAC,CAAC,KAAK,CAAC,iBAAiB;gBACzB,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACrB,OAAO;gBACL,OAAO,EAAE,CAAC;wBACR,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE;4BACJ,0DAA0D;4BAC1D,EAAE;4BACF,uBAAuB,UAAU,EAAE;4BACnC,WAAW,OAAO,EAAE;yBACrB,CAAC,IAAI,CAAC,IAAI,CAAC;qBACb,CAAC;gBACF,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/utils/cache.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Caché de respuestas de la API, con vencimiento y persistencia en disco.
+ *
+ * ⚠ POR QUÉ EXISTE: la cuota del ticket se agotaba en minutos. Medido en
+ *   auditoría, evaluar UNA oportunidad con el flujo natural (radar → detalle →
+ *   analizar_precios → generar_borrador → auditar_desiertas) costaba ~29
+ *   consultas, porque las tres herramientas de análisis repiten exactamente la
+ *   misma pareja de llamadas —`buscar({q, estado:'desierta'})` y luego
+ *   `detalle()` sobre los primeros resultados— y no existía ninguna caché: el
+ *   mismo histórico se descargaba hasta tres veces en cuestión de minutos.
+ *
+ *   Un proceso ya declarado desierto es inmutable, así que reutilizarlo es
+ *   gratis en exactitud y enorme en cuota.
+ *
+ * 🔒 El ticket NUNCA entra aquí: se excluye al construir la clave (el endpoint
+ *   heredado de Órdenes de Compra lo lleva en el query string) y solo se
+ *   guarda el cuerpo de la respuesta, que es información pública.
+ */
+export interface OpcionesCache {
+    /** Ruta del archivo de persistencia, o `null` para vivir solo en memoria. */
+    rutaEstado?: string | null;
+    /** Máximo de entradas retenidas; al excederlo se descartan las más antiguas. */
+    maxEntradas?: number;
+}
+export declare class ResponseCache {
+    private entradas;
+    private readonly rutaEstado;
+    private readonly maxEntradas;
+    private aciertos;
+    private fallos;
+    constructor(opciones?: OpcionesCache);
+    /**
+     * Clave estable para una consulta: mismo endpoint y mismos parámetros
+     * producen la misma clave sin importar el orden en que se escribieron.
+     */
+    static clave(path: string, params?: Record<string, unknown>): string;
+    /** Devuelve el valor vigente, o `undefined` si no está o ya venció. */
+    obtener<T>(clave: string): T | undefined;
+    guardar(clave: string, valor: unknown, ttlSegundos: number): void;
+    /** Elimina lo vencido y, si aún sobra, lo más antiguo. */
+    private purgar;
+    estadisticas(): {
+        entradas: number;
+        aciertos: number;
+        fallos: number;
+        ahorroPorcentaje: number;
+    };
+    /** Vacía la caché (memoria y disco). */
+    limpiar(): void;
+    private cargar;
+    private persistir;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/utils/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/utils/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAcH,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgB;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,MAAM,CAAK;gBAEP,QAAQ,GAAE,aAAkB;IAMxC;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;IASpE,uEAAuE;IACvE,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAkBxC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAOjE,0DAA0D;IAC1D,OAAO,CAAC,MAAM;IAYd,YAAY,IAAI;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE;IAUhG,wCAAwC;IACxC,OAAO,IAAI,IAAI;IAKf,OAAO,CAAC,MAAM;IAmBd,OAAO,CAAC,SAAS;CAQlB"}

package/dist/utils/cache.js

@@ -0,0 +1,131 @@
+/**
+ * Caché de respuestas de la API, con vencimiento y persistencia en disco.
+ *
+ * ⚠ POR QUÉ EXISTE: la cuota del ticket se agotaba en minutos. Medido en
+ *   auditoría, evaluar UNA oportunidad con el flujo natural (radar → detalle →
+ *   analizar_precios → generar_borrador → auditar_desiertas) costaba ~29
+ *   consultas, porque las tres herramientas de análisis repiten exactamente la
+ *   misma pareja de llamadas —`buscar({q, estado:'desierta'})` y luego
+ *   `detalle()` sobre los primeros resultados— y no existía ninguna caché: el
+ *   mismo histórico se descargaba hasta tres veces en cuestión de minutos.
+ *
+ *   Un proceso ya declarado desierto es inmutable, así que reutilizarlo es
+ *   gratis en exactitud y enorme en cuota.
+ *
+ * 🔒 El ticket NUNCA entra aquí: se excluye al construir la clave (el endpoint
+ *   heredado de Órdenes de Compra lo lleva en el query string) y solo se
+ *   guarda el cuerpo de la respuesta, que es información pública.
+ */
+import fs from 'fs';
+import { logger } from './logger.js';
+/** Parámetros que jamás deben formar parte de la clave ni tocar el disco. */
+const PARAMS_SECRETOS = new Set(['ticket']);
+export class ResponseCache {
+    entradas = new Map();
+    rutaEstado;
+    maxEntradas;
+    aciertos = 0;
+    fallos = 0;
+    constructor(opciones = {}) {
+        this.rutaEstado = opciones.rutaEstado ?? null;
+        this.maxEntradas = opciones.maxEntradas ?? 500;
+        this.cargar();
+    }
+    /**
+     * Clave estable para una consulta: mismo endpoint y mismos parámetros
+     * producen la misma clave sin importar el orden en que se escribieron.
+     */
+    static clave(path, params) {
+        const limpios = Object.entries(params ?? {})
+            .filter(([k, v]) => !PARAMS_SECRETOS.has(k.toLowerCase()) && v !== undefined && v !== null && v !== '')
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => `${k}=${String(v)}`)
+            .join('&');
+        return limpios ? `${path}?${limpios}` : path;
+    }
+    /** Devuelve el valor vigente, o `undefined` si no está o ya venció. */
+    obtener(clave) {
+        const e = this.entradas.get(clave);
+        if (!e) {
+            this.fallos++;
+            return undefined;
+        }
+        if (Date.now() >= e.expira) {
+            this.entradas.delete(clave);
+            this.fallos++;
+            return undefined;
+        }
+        // Renovar posición para que la purga descarte lo realmente frío.
+        this.entradas.delete(clave);
+        this.entradas.set(clave, e);
+        this.aciertos++;
+        return e.valor;
+    }
+    guardar(clave, valor, ttlSegundos) {
+        if (ttlSegundos <= 0)
+            return;
+        this.entradas.set(clave, { expira: Date.now() + ttlSegundos * 1000, valor });
+        this.purgar();
+        this.persistir();
+    }
+    /** Elimina lo vencido y, si aún sobra, lo más antiguo. */
+    purgar() {
+        const ahora = Date.now();
+        for (const [k, e] of this.entradas) {
+            if (ahora >= e.expira)
+                this.entradas.delete(k);
+        }
+        while (this.entradas.size > this.maxEntradas) {
+            const primera = this.entradas.keys().next();
+            if (primera.done)
+                break;
+            this.entradas.delete(primera.value);
+        }
+    }
+    estadisticas() {
+        const total = this.aciertos + this.fallos;
+        return {
+            entradas: this.entradas.size,
+            aciertos: this.aciertos,
+            fallos: this.fallos,
+            ahorroPorcentaje: total === 0 ? 0 : Math.round((this.aciertos / total) * 100),
+        };
+    }
+    /** Vacía la caché (memoria y disco). */
+    limpiar() {
+        this.entradas.clear();
+        this.persistir();
+    }
+    cargar() {
+        if (!this.rutaEstado)
+            return;
+        try {
+            if (!fs.existsSync(this.rutaEstado))
+                return;
+            const crudo = JSON.parse(fs.readFileSync(this.rutaEstado, 'utf8'));
+            const ahora = Date.now();
+            for (const [k, e] of Object.entries(crudo)) {
+                if (e && typeof e.expira === 'number' && ahora < e.expira) {
+                    this.entradas.set(k, e);
+                }
+            }
+            if (this.entradas.size > 0) {
+                logger.debug(`Caché: ${this.entradas.size} respuesta(s) vigente(s) recuperada(s) del disco.`);
+            }
+        }
+        catch {
+            // Una caché ilegible se descarta: es una optimización, no un requisito.
+        }
+    }
+    persistir() {
+        if (!this.rutaEstado)
+            return;
+        try {
+            fs.writeFileSync(this.rutaEstado, JSON.stringify(Object.fromEntries(this.entradas)), 'utf8');
+        }
+        catch {
+            // Si el disco no deja escribir, se sigue con la caché en memoria.
+        }
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/utils/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/utils/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,6EAA6E;AAC7E,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;AAe5C,MAAM,OAAO,aAAa;IAChB,QAAQ,GAAG,IAAI,GAAG,EAAmB,CAAC;IAC7B,UAAU,CAAgB;IAC1B,WAAW,CAAS;IAC7B,QAAQ,GAAG,CAAC,CAAC;IACb,MAAM,GAAG,CAAC,CAAC;IAEnB,YAAY,WAA0B,EAAE;QACtC,IAAI,CAAC,UAAU,GAAG,QAAQ,CAAC,UAAU,IAAI,IAAI,CAAC;QAC9C,IAAI,CAAC,WAAW,GAAG,QAAQ,CAAC,WAAW,IAAI,GAAG,CAAC;QAC/C,IAAI,CAAC,MAAM,EAAE,CAAC;IAChB,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,IAAY,EAAE,MAAgC;QACzD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;aACzC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;aACtG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;aACtC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;aACpC,IAAI,CAAC,GAAG,CAAC,CAAC;QACb,OAAO,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/C,CAAC;IAED,uEAAuE;IACvE,OAAO,CAAI,KAAa;QACtB,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,IAAI,CAAC,MAAM,EAAE,CAAC;YACd,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;YAC3B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC5B,IAAI,CAAC,MAAM,EAAE,CAAC;YACd,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,iEAAiE;QACjE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC5B,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChB,OAAO,CAAC,CAAC,KAAU,CAAC;IACtB,CAAC;IAED,OAAO,CAAC,KAAa,EAAE,KAAc,EAAE,WAAmB;QACxD,IAAI,WAAW,IAAI,CAAC;YAAE,OAAO;QAC7B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,WAAW,GAAG,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAC7E,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,CAAC,SAAS,EAAE,CAAC;IACnB,CAAC;IAED,0DAA0D;IAClD,MAAM;QACZ,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnC,IAAI,KAAK,IAAI,CAAC,CAAC,MAAM;gBAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;YAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,OAAO,CAAC,IAAI;gBAAE,MAAM;YACxB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAED,YAAY;QACV,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1C,OAAO;YACL,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI;YAC5B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,gBAAgB,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC;SAC9E,CAAC;IACJ,CAAC;IAED,wCAAwC;IACxC,OAAO;QACL,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,SAAS,EAAE,CAAC;IACnB,CAAC;IAEO,MAAM;QACZ,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,OAAO;QAC7B,IAAI,CAAC;YACH,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC;gBAAE,OAAO;YAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAA4B,CAAC;YAC9F,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACzB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC3C,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,KAAK,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;oBAC1D,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;gBAC1B,CAAC;YACH,CAAC;YACD,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;gBAC3B,MAAM,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,QAAQ,CAAC,IAAI,mDAAmD,CAAC,CAAC;YAChG,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,wEAAwE;QAC1E,CAAC;IACH,CAAC;IAEO,SAAS;QACf,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,OAAO;QAC7B,IAAI,CAAC;YACH,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QAC/F,CAAC;QAAC,MAAM,CAAC;YACP,kEAAkE;QACpE,CAAC;IACH,CAAC;CACF"}

package/dist/utils/doc-search.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Búsqueda de texto dentro de los documentos locales (manuales, guías, normativa).
+ *
+ * ⚠ POR QUÉ EXISTE ESTE MÓDULO: la primera implementación buscaba la consulta
+ *   completa como subcadena literal (`texto.includes(query)`). Con una palabra
+ *   suelta funcionaba, pero cualquier pregunta en lenguaje natural —que es
+ *   justo lo que envía un LLM— no coincidía nunca. Peor aún, el fallo era
+ *   silencioso y seguro de sí mismo: "no se encontraron coincidencias en
+ *   ninguno de los 10 documentos" ante la pregunta "¿qué multas me pueden
+ *   aplicar?", existiendo un PDF entero dedicado a multas y sanciones. El
+ *   modelo repetía ese "no hay información" al usuario como si fuera cierto.
+ *
+ *   Ahora la consulta se descompone en términos, se ignoran las palabras
+ *   vacías y se puntúa cada línea por cuántos términos distintos contiene.
+ *   Además se normalizan los acentos, porque en documentos en español
+ *   "sanción" y "sancion" deben encontrarse mutuamente.
+ */
+/** Minúsculas y sin acentos, para que "sanción" y "sancion" se encuentren. */
+export declare function normalizar(texto: string): string;
+/**
+ * Descompone la consulta en términos buscables: normalizados, sin palabras
+ * vacías y de al menos 3 caracteres.
+ *
+ * Si al filtrar no queda ningún término (consulta hecha solo de palabras
+ * vacías, ej. "qué es esto"), se devuelven todos los de 3+ caracteres antes
+ * que dejar al usuario sin búsqueda.
+ */
+export declare function tokenizar(query: string): string[];
+export interface Fragmento {
+    /** Línea que coincidió, con su contexto inmediato. */
+    texto: string;
+    /** Términos de la consulta presentes en la línea. */
+    terminos: string[];
+    puntaje: number;
+}
+export interface ResultadoBusqueda {
+    fragmentos: Fragmento[];
+    /** Términos en que se descompuso la consulta. */
+    terminos: string[];
+    /** Términos que no aparecen en ninguna parte del texto. */
+    ausentes: string[];
+}
+/**
+ * Busca los términos de `query` en `texto` y devuelve los fragmentos más
+ * relevantes, ordenados por cuántos términos distintos concentra cada uno.
+ *
+ * Una línea que contiene la consulta completa e íntegra se prioriza sobre
+ * cualquier coincidencia parcial: si el usuario acertó la frase exacta, esa
+ * es la mejor respuesta posible.
+ */
+export declare function buscarEnTexto(texto: string, query: string, maxFragmentos?: number): ResultadoBusqueda;
+//# sourceMappingURL=doc-search.d.ts.map

package/dist/utils/doc-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-search.d.ts","sourceRoot":"","sources":["../../src/utils/doc-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAcH,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKhD;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAQjD;AAED,MAAM,WAAW,SAAS;IACxB,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,aAAa,SAAK,GACjB,iBAAiB,CAwCnB"}

package/dist/utils/doc-search.js

@@ -0,0 +1,97 @@
+/**
+ * Búsqueda de texto dentro de los documentos locales (manuales, guías, normativa).
+ *
+ * ⚠ POR QUÉ EXISTE ESTE MÓDULO: la primera implementación buscaba la consulta
+ *   completa como subcadena literal (`texto.includes(query)`). Con una palabra
+ *   suelta funcionaba, pero cualquier pregunta en lenguaje natural —que es
+ *   justo lo que envía un LLM— no coincidía nunca. Peor aún, el fallo era
+ *   silencioso y seguro de sí mismo: "no se encontraron coincidencias en
+ *   ninguno de los 10 documentos" ante la pregunta "¿qué multas me pueden
+ *   aplicar?", existiendo un PDF entero dedicado a multas y sanciones. El
+ *   modelo repetía ese "no hay información" al usuario como si fuera cierto.
+ *
+ *   Ahora la consulta se descompone en términos, se ignoran las palabras
+ *   vacías y se puntúa cada línea por cuántos términos distintos contiene.
+ *   Además se normalizan los acentos, porque en documentos en español
+ *   "sanción" y "sancion" deben encontrarse mutuamente.
+ */
+/** Palabras sin valor discriminante en una consulta en español. */
+const VACIAS = new Set([
+    'que', 'qué', 'cual', 'cuál', 'cuales', 'cuáles', 'como', 'cómo', 'cuando',
+    'cuándo', 'donde', 'dónde', 'quien', 'quién', 'por', 'para', 'con', 'sin',
+    'los', 'las', 'del', 'unos', 'unas', 'una', 'uno', 'sus', 'sobre', 'entre',
+    'este', 'esta', 'esto', 'estos', 'estas', 'ese', 'esa', 'eso', 'aquel',
+    'son', 'ser', 'está', 'esta', 'estan', 'están', 'hay', 'han', 'hace',
+    'puede', 'pueden', 'debe', 'deben', 'tiene', 'tienen', 'mas', 'más',
+    'pero', 'sus', 'les', 'nos', 'mis', 'tus', 'muy', 'ya', 'les', 'algun',
+    'algún', 'alguna', 'todo', 'toda', 'todos', 'todas', 'otro', 'otra',
+]);
+/** Minúsculas y sin acentos, para que "sanción" y "sancion" se encuentren. */
+export function normalizar(texto) {
+    return texto
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/[̀-ͯ]/g, '');
+}
+/**
+ * Descompone la consulta en términos buscables: normalizados, sin palabras
+ * vacías y de al menos 3 caracteres.
+ *
+ * Si al filtrar no queda ningún término (consulta hecha solo de palabras
+ * vacías, ej. "qué es esto"), se devuelven todos los de 3+ caracteres antes
+ * que dejar al usuario sin búsqueda.
+ */
+export function tokenizar(query) {
+    const crudos = normalizar(query)
+        .split(/[^a-z0-9ñ]+/)
+        .filter((t) => t.length >= 3);
+    const utiles = crudos.filter((t) => !VACIAS.has(t));
+    const elegidos = utiles.length > 0 ? utiles : crudos;
+    return [...new Set(elegidos)];
+}
+/**
+ * Busca los términos de `query` en `texto` y devuelve los fragmentos más
+ * relevantes, ordenados por cuántos términos distintos concentra cada uno.
+ *
+ * Una línea que contiene la consulta completa e íntegra se prioriza sobre
+ * cualquier coincidencia parcial: si el usuario acertó la frase exacta, esa
+ * es la mejor respuesta posible.
+ */
+export function buscarEnTexto(texto, query, maxFragmentos = 12) {
+    const terminos = tokenizar(query);
+    if (terminos.length === 0) {
+        return { fragmentos: [], terminos: [], ausentes: [] };
+    }
+    const frase = normalizar(query).trim();
+    const lineas = texto.split('\n');
+    const normalizadas = lineas.map(normalizar);
+    const ausentes = terminos.filter((t) => !normalizadas.some((l) => l.includes(t)));
+    const candidatos = [];
+    for (let i = 0; i < lineas.length; i++) {
+        const linea = lineas[i]?.trim();
+        if (!linea)
+            continue;
+        const norm = normalizadas[i];
+        const presentes = terminos.filter((t) => norm.includes(t));
+        if (presentes.length === 0)
+            continue;
+        // La frase completa vale más que la suma de sus partes.
+        const bonus = frase.length > 0 && norm.includes(frase) ? terminos.length * 10 : 0;
+        const contexto = [];
+        const anterior = lineas[i - 1]?.trim();
+        const siguiente = lineas[i + 1]?.trim();
+        if (anterior)
+            contexto.push(`[Anterior] ${anterior}`);
+        contexto.push(`[COINCIDENCIA] ${linea}`);
+        if (siguiente)
+            contexto.push(`[Siguiente] ${siguiente}`);
+        candidatos.push({
+            texto: contexto.join('\n'),
+            terminos: presentes,
+            puntaje: presentes.length + bonus,
+        });
+    }
+    candidatos.sort((a, b) => b.puntaje - a.puntaje);
+    return { fragmentos: candidatos.slice(0, maxFragmentos), terminos, ausentes };
+}
+//# sourceMappingURL=doc-search.js.map

package/dist/utils/doc-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-search.js","sourceRoot":"","sources":["../../src/utils/doc-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,mEAAmE;AACnE,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC;IACrB,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ;IAC1E,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;IACzE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO;IAC1E,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO;IACtE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM;IACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK;IACnE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO;IACtE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM;CACpE,CAAC,CAAC;AAEH,8EAA8E;AAC9E,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK;SACT,WAAW,EAAE;SACb,SAAS,CAAC,KAAK,CAAC;SAChB,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC;SAC7B,KAAK,CAAC,aAAa,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC;IAEhC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IACrD,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;AAChC,CAAC;AAkBD;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAa,EACb,KAAa,EACb,aAAa,GAAG,EAAE;IAElB,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IACxD,CAAC;IAED,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;IACvC,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAE5C,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAElF,MAAM,UAAU,GAAgB,EAAE,CAAC;IACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QAChC,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,MAAM,IAAI,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QAE7B,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3D,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAErC,wDAAwD;QACxD,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAElF,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QACvC,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QACxC,IAAI,QAAQ;YAAE,QAAQ,CAAC,IAAI,CAAC,cAAc,QAAQ,EAAE,CAAC,CAAC;QACtD,QAAQ,CAAC,IAAI,CAAC,kBAAkB,KAAK,EAAE,CAAC,CAAC;QACzC,IAAI,SAAS;YAAE,QAAQ,CAAC,IAAI,CAAC,eAAe,SAAS,EAAE,CAAC,CAAC;QAEzD,UAAU,CAAC,IAAI,CAAC;YACd,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;YAC1B,QAAQ,EAAE,SAAS;YACnB,OAAO,EAAE,SAAS,CAAC,MAAM,GAAG,KAAK;SAClC,CAAC,CAAC;IACL,CAAC;IAED,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;IACjD,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAChF,CAAC"}

package/dist/utils/docs-locator.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Localizador compartido de documentos locales (manuales/guías de Compra Ágil).
+ *
+ * Centraliza la lógica antes duplicada e inconsistente entre
+ * `tools/documentos.ts` y `resources/documentacion.ts`:
+ * - Detección recursiva de la carpeta docs/ (empaquetada vs. cwd).
+ * - Filtrado por extensión soportada (.pdf, .txt, .md), excluyendo readme.md.
+ * - Exclusión de subcarpetas internas del proyecto (ver EXCLUDED_DIRS).
+ */
+export declare const SUPPORTED_DOC_EXTENSIONS: readonly [".pdf", ".txt", ".md"];
+/**
+ * Subcarpetas de docs/ que NO son documentación de Compra Ágil y por tanto no
+ * deben ofrecerse al LLM como tal.
+ *
+ * `internals/` contiene documentación de ingeniería del propio servidor
+ * (pendientes, decisiones de arquitectura, hallazgos de la API). Sin esta
+ * exclusión aparecería en `consultar_documentos_locales` y en el recurso
+ * `compra-agil://documentacion/{filename}`, que existen para consultar
+ * normativa y guías del mecanismo — no las notas internas del proyecto.
+ */
+export declare const EXCLUDED_DIRS: readonly ["internals"];
+/**
+ * Obtiene de forma recursiva todas las rutas relativas de archivos dentro de un directorio,
+ * normalizadas con barras diagonales (/).
+ */
+export declare function getRelativeFilesRecursively(dir: string, baseDir?: string): string[];
+/**
+ * True si el archivo es documentación consultable de Compra Ágil.
+ * Excluye READMEs y todo lo que viva en una carpeta interna del proyecto.
+ *
+ * @param file Ruta RELATIVA al directorio docs/, con separadores "/".
+ */
+export declare function isSupportedDoc(file: string): boolean;
+/**
+ * Resuelve el directorio de documentación efectivo: prefiere la carpeta empaquetada
+ * (docs/ junto al build) si contiene documentos soportados; si no, usa docs/ del cwd.
+ */
+export declare function resolveDocsDir(): string;
+/** Lista las rutas relativas de documentos consultables dentro del docs dir resuelto. */
+export declare function listSupportedDocs(docsDir: string): string[];
+//# sourceMappingURL=docs-locator.d.ts.map

package/dist/utils/docs-locator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-locator.d.ts","sourceRoot":"","sources":["../../src/utils/docs-locator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,eAAO,MAAM,wBAAwB,kCAAmC,CAAC;AAEzE;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,wBAAyB,CAAC;AAEpD;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,MAAY,GAAG,MAAM,EAAE,CAexF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAUpD;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAMvC;AAED,yFAAyF;AACzF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAE3D"}

package/dist/utils/docs-locator.js

@@ -0,0 +1,82 @@
+/**
+ * Localizador compartido de documentos locales (manuales/guías de Compra Ágil).
+ *
+ * Centraliza la lógica antes duplicada e inconsistente entre
+ * `tools/documentos.ts` y `resources/documentacion.ts`:
+ * - Detección recursiva de la carpeta docs/ (empaquetada vs. cwd).
+ * - Filtrado por extensión soportada (.pdf, .txt, .md), excluyendo readme.md.
+ * - Exclusión de subcarpetas internas del proyecto (ver EXCLUDED_DIRS).
+ */
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageDocsDir = path.resolve(__dirname, '../../docs');
+const cwdDocsDir = path.resolve(process.cwd(), 'docs');
+export const SUPPORTED_DOC_EXTENSIONS = ['.pdf', '.txt', '.md'];
+/**
+ * Subcarpetas de docs/ que NO son documentación de Compra Ágil y por tanto no
+ * deben ofrecerse al LLM como tal.
+ *
+ * `internals/` contiene documentación de ingeniería del propio servidor
+ * (pendientes, decisiones de arquitectura, hallazgos de la API). Sin esta
+ * exclusión aparecería en `consultar_documentos_locales` y en el recurso
+ * `compra-agil://documentacion/{filename}`, que existen para consultar
+ * normativa y guías del mecanismo — no las notas internas del proyecto.
+ */
+export const EXCLUDED_DIRS = ['internals'];
+/**
+ * Obtiene de forma recursiva todas las rutas relativas de archivos dentro de un directorio,
+ * normalizadas con barras diagonales (/).
+ */
+export function getRelativeFilesRecursively(dir, baseDir = dir) {
+    let results = [];
+    if (!fs.existsSync(dir))
+        return [];
+    const list = fs.readdirSync(dir);
+    for (const file of list) {
+        const filePath = path.join(dir, file);
+        const stat = fs.statSync(filePath);
+        if (stat && stat.isDirectory()) {
+            results = results.concat(getRelativeFilesRecursively(filePath, baseDir));
+        }
+        else {
+            const relativePath = path.relative(baseDir, filePath).replace(/\\/g, '/');
+            results.push(relativePath);
+        }
+    }
+    return results;
+}
+/**
+ * True si el archivo es documentación consultable de Compra Ágil.
+ * Excluye READMEs y todo lo que viva en una carpeta interna del proyecto.
+ *
+ * @param file Ruta RELATIVA al directorio docs/, con separadores "/".
+ */
+export function isSupportedDoc(file) {
+    const normalizado = file.replace(/\\/g, '/');
+    // Cualquier archivo bajo una carpeta interna queda fuera, a cualquier profundidad.
+    const primerSegmento = normalizado.split('/')[0].toLowerCase();
+    if (EXCLUDED_DIRS.includes(primerSegmento))
+        return false;
+    const ext = path.extname(normalizado).toLowerCase();
+    const name = path.basename(normalizado).toLowerCase();
+    return SUPPORTED_DOC_EXTENSIONS.includes(ext) && name !== 'readme.md';
+}
+/**
+ * Resuelve el directorio de documentación efectivo: prefiere la carpeta empaquetada
+ * (docs/ junto al build) si contiene documentos soportados; si no, usa docs/ del cwd.
+ */
+export function resolveDocsDir() {
+    if (fs.existsSync(packageDocsDir)) {
+        const hasLocalDocs = getRelativeFilesRecursively(packageDocsDir).some(isSupportedDoc);
+        if (hasLocalDocs)
+            return packageDocsDir;
+    }
+    return cwdDocsDir;
+}
+/** Lista las rutas relativas de documentos consultables dentro del docs dir resuelto. */
+export function listSupportedDocs(docsDir) {
+    return getRelativeFilesRecursively(docsDir).filter(isSupportedDoc);
+}
+//# sourceMappingURL=docs-locator.js.map

package/dist/utils/docs-locator.js.map

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

package/dist/utils/error-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../src/utils/error-handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,QAAQ,EAAE,CAAC;CACpB;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtC,SAAgB,iBAAiB,EAAE,MAAM,CAAC;gBAE9B,UAAU,EAAE,MAAM,EAAE,SAAS,GAAE,QAAQ,EAAO;CAQ3D;AAqCD;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAoB5E"}
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../src/utils/error-handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,QAAQ,EAAE,CAAC;CACpB;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtC,SAAgB,iBAAiB,EAAE,MAAM,CAAC;gBAE9B,UAAU,EAAE,MAAM,EAAE,SAAS,GAAE,QAAQ,EAAO;CAQ3D;AAoCD;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAoB5E"}

package/dist/utils/error-handler.js

@@ -4,6 +4,7 @@
  * Cada mensaje está redactado para que un agente de IA entienda
  * exactamente qué salió mal y qué acción tomar.
  */
+import { redact } from './redact.js';
 export class CompraAgilApiError extends Error {
     httpStatus;
     apiErrors;
@@ -18,8 +19,10 @@ export class CompraAgilApiError extends Error {
     }
 }
 function getActionableMessage(httpStatus, apiErrors) {
+    // El mensaje viene de la API: no se controla su contenido y podría hacer eco
+    // de la URL solicitada (que en el endpoint legado lleva el ticket en la query).
     const detail = apiErrors.length > 0
-        ? ` Detalle de la API: "${apiErrors[0].mensaje}"`
+        ? ` Detalle de la API: "${redact(apiErrors[0].mensaje ?? '')}"`
         : '';
     switch (httpStatus) {
         case 400:
@@ -41,12 +44,10 @@ function getActionableMessage(httpStatus, apiErrors) {
     }
 }
 function formatRateLimitMessage(detail) {
-    const now = new Date();
-    const tomorrow = new Date(now);
-    tomorrow.setUTCDate(tomorrow.getUTCDate() + 1);
-    tomorrow.setUTCHours(0, 1, 0, 0);
-    const waitHours = Math.ceil((tomorrow.getTime() - now.getTime()) / (1000 * 60 * 60));
-    return `Cuota diaria de la API agotada. El límite se restablece al inicio del próximo día calendario UTC (en aproximadamente ${waitHours} horas). Para reducir el consumo: usa filtros más específicos (estado, región, fechas), evita consultas masivas, y usa 'ttl_cambio_ms' para sincronización incremental en vez de descargas completas. Si necesitas más cuota, contacta a ChileCompra.${detail}`;
+    // La cuota se comporta como un token bucket que se recarga solo (glosario de
+    // la guía oficial): medido en producción, la API volvió a responder ~13 min
+    // después de un 429. Por eso no se aconseja esperar al día siguiente.
+    return `Se agotaron temporalmente los tokens de cuota de la API. No es necesario esperar al día siguiente: la cuota se recarga sola, así que reintenta en unos minutos. Para gastar menos: usa filtros más específicos (estado, región, fechas), baja 'limite_analisis'/'max_paginas' en las herramientas de análisis, y prefiere 'ttl_cambio_ms' o un rango 'cambio_desde'/'cambio_hasta' para sincronización incremental en vez de descargas completas. Si el 429 persiste durante horas, la cuota diaria del ticket sí puede estar agotada: contacta a ChileCompra para uno de mayor límite.${detail}`;
 }
 /**
  * Parsea la respuesta de error de la API y lanza una excepción tipada.