mcp-phase-gate 2.0.0 → 2.0.1

package/build/index.js

@@ -11,9 +11,10 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import * as fs from "fs";
 import * as path from "path";
 import { DOCS, REPOS, SERVER_NAME, SERVER_VERSION, requireBasePath, stateFile } from "./config.js";
-import { describeProjects, discoverProjects, estaDentro, findProjectFolder, requireProjectFolder, resolveDocPath, taskFolderPath, } from "./paths.js";
+import { describeProjects, discoverProjects, estaDentroReal, findProjectFolder, leerTextoAcotado, requireProjectFolder, resolveDocPath, resolveRepoPath, taskFolderPath, validarSegmento, } from "./paths.js";
 import { describePhases, discoverPhases, loadPhasePrompt, nombreContextoInicial, } from "./phases.js";
 import { avisoDeCompuerta, describeEstado, guardarPuntero, limpiarEstadoViejo, listarTareas, tareaActiva, } from "./tasks.js";
+import { validarLlamada } from "./schemas.js";
 const server = new Server({
     name: SERVER_NAME,
     version: SERVER_VERSION,
@@ -139,25 +140,34 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
-        if (name === "start_task") {
-            const proj = String(args?.project).trim();
-            const taskName = String(args?.task_name);
-            const context = String(args?.initial_context);
+        // Todo argumento se valida aquí, antes de que ninguna tool lo use. Un campo ausente o de
+        // otro tipo devuelve un error que lo nombra, en vez de convertirse en "undefined".
+        const llamada = validarLlamada(name, args);
+        if (llamada.tool === "start_task") {
+            const proj = llamada.args.project; // el schema ya le quitó los espacios
+            const taskName = llamada.args.task_name;
+            const context = llamada.args.initial_context;
             // Estrenar proyecto tiene que ser deliberado: sin esta puerta, un nombre mal escrito
             // creaba una carpeta suelta en la Documentación y nadie se enteraba hasta buscarla.
             let carpetaProyecto = findProjectFolder(proj);
             let estrenado = false;
             if (!carpetaProyecto) {
-                if (args?.crear_proyecto !== true) {
+                if (llamada.args.crear_proyecto !== true) {
                     throw new Error(`No existe el proyecto "${proj}". Los proyectos disponibles son: ${describeProjects()}. ` +
                         `Si el usuario te confirmó que quiere estrenar el proyecto "${proj.toUpperCase()}", ` +
                         `vuelve a llamar a start_task con crear_proyecto: true.`);
                 }
+                // El nombre se vuelve carpeta tal cual: "../evil" la creaba fuera de la Documentación.
+                validarSegmento(proj, "project");
                 carpetaProyecto = proj.toUpperCase();
                 estrenado = true;
             }
             const carpetaTarea = taskFolderPath(carpetaProyecto, taskName);
             const contextoInicial = path.join(carpetaTarea, nombreContextoInicial());
+            const docsBase = requireBasePath(DOCS);
+            if (!estaDentroReal(docsBase, carpetaTarea)) {
+                throw new Error(`Acceso denegado: la carpeta de la tarea queda fuera de ${docsBase}.`);
+            }
             // start_task escribe el contexto inicial sin preguntar, así que llamarlo sobre una tarea
             // que ya existe borraba el requerimiento original — el único documento que no se puede
             // regenerar leyendo el código. Retomar una tarea es switch_task, que no toca archivos.
@@ -178,19 +188,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 content: [{ type: "text", text: `Tarea '${taskName}' inicializada correctamente. Archivo guardado en: ${contextoInicial}\nTarea activa de ${carpetaProyecto}: ${taskName}.${aviso}` }],
             };
         }
-        if (name === "get_phase_prompt") {
-            const phase = Number(args?.phase);
-            if (!Number.isInteger(phase)) {
-                throw new Error(`Debes indicar un número de fase. Disponibles: ${PHASES_DESCRIPTION}.`);
-            }
+        if (llamada.tool === "get_phase_prompt") {
+            // Que sea un entero ya lo garantiza el schema; si la fase no existe, lo dice loadPhasePrompt.
+            const { phase, project, task_name } = llamada.args;
             const prompt = loadPhasePrompt(phase);
             // La compuerta avisa, no bloquea: el prompt se entrega siempre. Si comprobarla fallara
             // por lo que sea, entregarlo igual es mejor que dejar al usuario sin fase por un aviso.
             let aviso = null;
             try {
                 aviso = avisoDeCompuerta(phase, discoverPhases(), {
-                    ...(args?.project ? { project: String(args.project) } : {}),
-                    ...(args?.task_name ? { taskName: String(args.task_name) } : {}),
+                    ...(project ? { project } : {}),
+                    ...(task_name ? { taskName: task_name } : {}),
                 });
             }
             catch (error) {
@@ -200,9 +208,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 content: [{ type: "text", text: aviso ? `${aviso}\n\n${prompt}` : prompt }],
             };
         }
-        if (name === "get_active_task") {
+        if (llamada.tool === "get_active_task") {
             const phases = discoverPhases();
-            const pedido = args?.project ? String(args.project) : "";
+            const pedido = llamada.args.project ?? "";
             // Con proyecto: la suya. Sin proyecto: la de cada uno. Antes había un único puntero
             // global y responder "la activa" a secas obligaba a adivinar cuál de dos ventanas
             // preguntaba; listar todas es la respuesta honesta cuando no se sabe.
@@ -230,9 +238,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 content: [{ type: "text", text: `${bloques.join("\n\n")}\n\nPunteros guardados en: ${stateFile()}` }],
             };
         }
-        if (name === "list_tasks") {
+        if (llamada.tool === "list_tasks") {
             const phases = discoverPhases();
-            const pedido = args?.project ? String(args.project) : "";
+            const pedido = llamada.args.project ?? "";
             const proyectos = pedido
                 ? [requireProjectFolder(pedido)]
                 : [...discoverProjects().values()].sort();
@@ -254,10 +262,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 content: [{ type: "text", text: bloques.join("\n\n") || "No hay proyectos todavía." }],
             };
         }
-        if (name === "switch_task") {
+        if (llamada.tool === "switch_task") {
             const phases = discoverPhases();
-            const carpetaProyecto = requireProjectFolder(String(args?.project));
-            const taskName = String(args?.task_name);
+            const carpetaProyecto = requireProjectFolder(llamada.args.project);
+            const taskName = llamada.args.task_name;
             const tareas = listarTareas(carpetaProyecto, phases);
             const encontrada = tareas.find((tarea) => tarea.taskName === taskName);
             if (!encontrada) {
@@ -272,22 +280,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 content: [{ type: "text", text: `Tarea activa de ${carpetaProyecto}: ${taskName}.\nFase: ${describeEstado(encontrada, phases)}\nCarpeta: ${encontrada.folderPath}` }],
             };
         }
-        if (name === "read_central_doc") {
+        if (llamada.tool === "read_central_doc") {
             const docsBase = requireBasePath(DOCS);
-            const fullPath = resolveDocPath(args);
-            if (!estaDentro(docsBase, fullPath)) {
+            const fullPath = resolveDocPath(llamada.args);
+            if (!estaDentroReal(docsBase, fullPath)) {
                 throw new Error(`Acceso denegado: la ruta queda fuera de ${docsBase}.`);
             }
-            const content = fs.readFileSync(fullPath, "utf-8");
+            const content = leerTextoAcotado(fullPath);
             return {
                 content: [{ type: "text", text: content }],
             };
         }
-        if (name === "write_central_doc") {
-            const content = String(args?.content);
+        if (llamada.tool === "write_central_doc") {
+            const content = llamada.args.content;
             const docsBase = requireBasePath(DOCS);
-            const fullPath = resolveDocPath(args);
-            if (!estaDentro(docsBase, fullPath)) {
+            const fullPath = resolveDocPath(llamada.args);
+            if (!estaDentroReal(docsBase, fullPath)) {
                 throw new Error(`Acceso denegado: la ruta queda fuera de ${docsBase}.`);
             }
             fs.mkdirSync(path.dirname(fullPath), { recursive: true });
@@ -296,15 +304,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 content: [{ type: "text", text: `Archivo escrito exitosamente en ${fullPath}` }],
             };
         }
-        if (name === "read_cross_repo") {
-            const repoName = String(args?.repo_name);
-            const filePath = String(args?.file_path);
-            const reposBase = requireBasePath(REPOS);
-            const fullPath = path.join(reposBase, repoName, filePath);
-            if (!estaDentro(reposBase, fullPath)) {
-                throw new Error(`Acceso denegado: la ruta queda fuera de ${reposBase}.`);
-            }
-            const content = fs.readFileSync(fullPath, "utf-8");
+        if (llamada.tool === "read_cross_repo") {
+            const fullPath = resolveRepoPath(llamada.args.repo_name, llamada.args.file_path);
+            const content = leerTextoAcotado(fullPath);
             return {
                 content: [{ type: "text", text: content }],
             };
@@ -335,36 +337,36 @@ function reportarRutas() {
 // una terminal —que es exactamente lo que hace quien acaba de leer `npx mcp-phase-gate` en el
 // README— se queda esperando entrada, sin señal de vida, y parece roto. Estas dos banderas
 // existen para que ese momento devuelva una explicación en vez de un cursor parpadeando.
-const AYUDA = `${SERVER_NAME} v${SERVER_VERSION}
-
-Servidor MCP que parte cada requerimiento en cinco fases con compuerta y obliga a que cada
-una deje su documento en una documentación central.
-
-Esto NO se ejecuta a mano: lo lanza tu cliente MCP. Ejecutado directamente se queda esperando
-mensajes JSON-RPC por stdin, que es lo que parece que se colgó.
-
-Regístralo en tu cliente (Cursor, VS Code, Claude Code) así:
-
-  {
-    "mcpServers": {
-      "${SERVER_NAME}": {
-        "command": "npx",
-        "args": ["-y", "mcp-phase-gate"],
-        "env": {
-          "ORQUESTADOR_DOCS_PATH": "<tu carpeta de documentación>",
-          "ORQUESTADOR_REPOS_PATH": "<tu carpeta de repositorios>"
-        }
-      }
-    }
-  }
-
-Variables de entorno:
-  ORQUESTADOR_DOCS_PATH      Obligatoria. Raíz de la Documentación Central.
-  ORQUESTADOR_REPOS_PATH     Obligatoria. Carpeta con tus repositorios de código.
-  ORQUESTADOR_TASKS_SUBDIR   Subcarpeta de tareas dentro de cada proyecto. Por defecto "Proyectos".
-  ORQUESTADOR_PROMPTS_PATH   Carpeta de prompts propios, que se superponen a los del paquete.
-  ORQUESTADOR_STATE_PATH     Dónde guardar los punteros de tarea activa.
-
+const AYUDA = `${SERVER_NAME} v${SERVER_VERSION}
+
+Servidor MCP que parte cada requerimiento en cinco fases con compuerta y obliga a que cada
+una deje su documento en una documentación central.
+
+Esto NO se ejecuta a mano: lo lanza tu cliente MCP. Ejecutado directamente se queda esperando
+mensajes JSON-RPC por stdin, que es lo que parece que se colgó.
+
+Regístralo en tu cliente (Cursor, VS Code, Claude Code) así:
+
+  {
+    "mcpServers": {
+      "${SERVER_NAME}": {
+        "command": "npx",
+        "args": ["-y", "mcp-phase-gate"],
+        "env": {
+          "ORQUESTADOR_DOCS_PATH": "<tu carpeta de documentación>",
+          "ORQUESTADOR_REPOS_PATH": "<tu carpeta de repositorios>"
+        }
+      }
+    }
+  }
+
+Variables de entorno:
+  ORQUESTADOR_DOCS_PATH      Obligatoria. Raíz de la Documentación Central.
+  ORQUESTADOR_REPOS_PATH     Obligatoria. Carpeta con tus repositorios de código.
+  ORQUESTADOR_TASKS_SUBDIR   Subcarpeta de tareas dentro de cada proyecto. Por defecto "Proyectos".
+  ORQUESTADOR_PROMPTS_PATH   Carpeta de prompts propios, que se superponen a los del paquete.
+  ORQUESTADOR_STATE_PATH     Dónde guardar los punteros de tarea activa.
+
 Documentación: https://github.com/Montse2308/mcp-phase-gate`;
 async function main() {
     const bandera = process.argv[2];

package/build/paths.d.ts

@@ -1,4 +1,7 @@
 export declare function estaDentro(base: string, ruta: string): boolean;
+export declare function rutaReal(ruta: string): string;
+export declare function estaDentroReal(base: string, ruta: string): boolean;
+export declare function validarSegmento(valor: string, campo: string): string;
 export declare function discoverProjects(): Map<string, string>;
 export declare function describeProjects(): string;
 export declare function findProjectFolder(project: string): string | null;
@@ -6,5 +9,14 @@ export declare function requireProjectFolder(project: string): string;
 export declare function taskFolderPath(carpetaProyecto: string, taskName: string): string;
 export declare function resolveTaskFolder(project: string, taskName: string): string;
 export declare function tasksRootPath(carpetaProyecto: string): string;
-export declare function resolveDocPath(args: any): string;
+export type ArgumentosDeDocumento = {
+    project?: string | undefined;
+    task_name?: string | undefined;
+    file_name?: string | undefined;
+    file_path?: string | undefined;
+};
+export declare function resolveDocPath(args: ArgumentosDeDocumento): string;
+export declare function resolveRepoPath(repoName: string, filePath: string): string;
+export declare const LIMITE_LECTURA_BYTES = 1048576;
+export declare function leerTextoAcotado(ruta: string): string;
 //# sourceMappingURL=paths.d.ts.map

package/build/paths.js

@@ -6,7 +6,7 @@
 // busca. Por eso además de armarlas hay que comprobar que caigan dentro de la base.
 import * as fs from "fs";
 import * as path from "path";
-import { DOCS, requireBasePath, tasksSubdir } from "./config.js";
+import { DOCS, REPOS, requireBasePath, tasksSubdir } from "./config.js";
 // Comprueba que una ruta quede dentro de otra. No sirve startsWith, y falla en las dos
 // direcciones: con base "C:\PROYECTOS\TRABAJO" deja pasar "C:\PROYECTOS\TRABAJO_VIEJO",
 // que empieza igual sin estar dentro; y rechaza rutas válidas cuando la base viene escrita
@@ -15,6 +15,60 @@ export function estaDentro(base, ruta) {
     const relativa = path.relative(path.resolve(base), path.resolve(ruta));
     return relativa === "" || (!relativa.startsWith("..") && !path.isAbsolute(relativa));
 }
+// Resuelve symlinks y junctions del ancestro existente más cercano y vuelve a unir el resto.
+// Hace falta porque la ruta que se va a escribir casi nunca existe todavía, y realpath solo
+// funciona sobre lo que existe. "Existe" se mira con lstat y no con existsSync: un enlace roto
+// cuenta como existente, realpath falla sobre él y la operación se rechaza. Con existsSync se
+// saltaría, y escribir a través de él crearía su destino, esté donde esté.
+export function rutaReal(ruta) {
+    let existente = path.resolve(ruta);
+    const pendientes = [];
+    while (!fs.lstatSync(existente, { throwIfNoEntry: false })) {
+        const padre = path.dirname(existente);
+        if (padre === existente)
+            break; // ni la raíz existe: que realpath dé el error
+        pendientes.unshift(path.basename(existente));
+        existente = padre;
+    }
+    return path.join(fs.realpathSync.native(existente), ...pendientes);
+}
+// estaDentro sobre rutas reales. Comparar el texto no basta: un symlink dentro de la
+// Documentación que apunta fuera tiene una ruta que "está dentro" y un destino que no.
+// La base también se resuelve: una DOCS que es symlink sigue valiendo.
+export function estaDentroReal(base, ruta) {
+    return estaDentro(rutaReal(base), rutaReal(ruta));
+}
+// Un nombre de proyecto, tarea o repo es UN segmento de ruta, portable entre sistemas:
+// la Documentación viaja entre equipos con Windows, macOS y Linux. Lo que se rechaza es lo
+// que hoy ya era peligroso (separadores, "..") o lo que Windows no puede guardar y rompe la
+// sincronización (caracteres reservados, punto o espacio final, CON, NUL…).
+const CARACTERES_RESERVADOS = /[<>:"|?*]/;
+const CARACTERES_DE_CONTROL = /[\u0000-\u001f\u007f]/;
+// Windows también reserva COM y LPT con los superíndices ¹²³, y las consolas CONIN$ y CONOUT$.
+// Los espacios antes de la extensión no cuentan: "nul .txt" sigue siendo NUL.
+const NOMBRES_RESERVADOS_WINDOWS = /^(con|prn|aux|nul|conin\$|conout\$|com[1-9¹²³]|lpt[1-9¹²³]) *(\..*)?$/i;
+export function validarSegmento(valor, campo) {
+    const incumple = (regla) => {
+        throw new Error(`${campo} ${JSON.stringify(valor)} no es válido: ${regla}. Tiene que ser un solo nombre de ` +
+            `carpeta o archivo, que funcione igual en Windows, macOS y Linux.`);
+    };
+    if (valor.trim() === "")
+        incumple("está vacío");
+    if (valor === "." || valor === "..")
+        incumple(`no puede ser "${valor}"`);
+    if (/[\\/]/.test(valor))
+        incumple("no puede llevar / ni \\");
+    if (CARACTERES_DE_CONTROL.test(valor))
+        incumple("no puede llevar caracteres de control");
+    if (CARACTERES_RESERVADOS.test(valor))
+        incumple('no puede llevar ninguno de < > : " | ? *');
+    if (/[. ]$/.test(valor))
+        incumple("no puede terminar en punto ni en espacio");
+    if (NOMBRES_RESERVADOS_WINDOWS.test(valor)) {
+        incumple("es un nombre reservado de Windows (CON, PRN, AUX, NUL, CONIN$, CONOUT$, COM1–COM9, LPT1–LPT9)");
+    }
+    return valor;
+}
 // ─── Proyectos ──────────────────────────────────────────────────────────────
 // Los proyectos no se declaran en ninguna parte: son las carpetas que existen. Antes había
 // una tabla fija con los proyectos de quien escribió el código, que no restringía nada
@@ -62,6 +116,7 @@ export function requireProjectFolder(project) {
 // La ruta de una tarea SIEMPRE se arma aquí, en un solo lugar.
 // Estructura: <ORQUESTADOR_DOCS_PATH>/<PROYECTO>/<subcarpeta de tareas>/<tarea>
 export function taskFolderPath(carpetaProyecto, taskName) {
+    validarSegmento(taskName, "task_name");
     return path.join(requireBasePath(DOCS), carpetaProyecto, tasksSubdir(), taskName);
 }
 export function resolveTaskFolder(project, taskName) {
@@ -74,16 +129,113 @@ export function tasksRootPath(carpetaProyecto) {
 }
 // Resuelve la ruta absoluta para read/write. Prioriza project+task_name+file_name;
 // si no, cae al modo legacy con file_path relativo a la Documentación Central.
+//
+// Una ruta relativa hecha de segmentos portables. Cada segmento se valida por separado para que
+// una subcarpeta legítima como "04 - Ejecución/L01 - x.md" siga valiendo.
+function validarRutaRelativa(valor, campo, relativaA) {
+    if (path.isAbsolute(valor)) {
+        throw new Error(`${campo} no puede ser una ruta absoluta ("${valor}"): es relativo a ${relativaA}.`);
+    }
+    for (const segmento of valor.split(/[\\/]/))
+        validarSegmento(segmento, campo);
+}
+// Con file_name la ruta tiene que quedar dentro de la carpeta de la tarea, no solo dentro de
+// la base: antes "../otra-tarea/x.md" escribía en otra tarea y la comprobación de la tool,
+// que solo miraba la base, lo dejaba pasar.
+//
+// Con file_path basta con no salir de la base (la restricción a carpetas de tarea llega en la
+// Etapa 1), pero sus segmentos también tienen que ser portables: antes creaba dentro de la
+// Documentación un "CON", un "nul.md" o un flujo alterno "nota.md:secreto", que el Explorador
+// y OneDrive no saben manejar.
 export function resolveDocPath(args) {
-    const project = args?.project ? String(args.project) : "";
-    const taskName = args?.task_name ? String(args.task_name) : "";
-    const fileName = args?.file_name ? String(args.file_name) : "";
+    const { project = "", task_name: taskName = "", file_name: fileName = "", file_path: filePath = "" } = args;
     if (project && taskName && fileName) {
-        return path.join(resolveTaskFolder(project, taskName), fileName);
+        const carpetaTarea = resolveTaskFolder(project, taskName);
+        validarRutaRelativa(fileName, "file_name", "la carpeta de la tarea");
+        const ruta = path.join(carpetaTarea, fileName);
+        if (!estaDentroReal(carpetaTarea, ruta)) {
+            throw new Error(`Acceso denegado: file_name "${fileName}" queda fuera de la carpeta de la tarea ${carpetaTarea}.`);
+        }
+        return ruta;
     }
-    if (args?.file_path) {
-        return path.join(requireBasePath(DOCS), String(args.file_path));
+    if (filePath) {
+        const docsBase = requireBasePath(DOCS);
+        validarRutaRelativa(filePath, "file_path", "la Documentación Central");
+        const ruta = path.join(docsBase, filePath);
+        if (!estaDentroReal(docsBase, ruta)) {
+            throw new Error(`Acceso denegado: file_path queda fuera de ${docsBase}.`);
+        }
+        return ruta;
     }
     throw new Error("Debes proporcionar (project + task_name + file_name) o bien file_path.");
 }
+// ─── Repos ──────────────────────────────────────────────────────────────────
+// Ruta de un archivo dentro de UN repo. Antes la comprobación miraba la carpeta de repos
+// entera, y desde repoA "../repoB/.env" pasaba: estaba dentro de la carpeta de repos. El repo
+// se resuelve a su ruta real para que un repo que es un enlace a otra unidad siga valiendo.
+export function resolveRepoPath(repoName, filePath) {
+    validarSegmento(repoName, "repo_name");
+    const repo = path.join(requireBasePath(REPOS), repoName);
+    const repoReal = rutaReal(repo);
+    const ruta = path.join(repo, filePath);
+    if (!estaDentroReal(repoReal, ruta)) {
+        throw new Error(`Acceso denegado: file_path "${filePath}" queda fuera del repositorio ${repoName}.`);
+    }
+    return ruta;
+}
+// ─── Lectura acotada ────────────────────────────────────────────────────────
+// Lo que leen las tools va entero al contexto del modelo. Un volcado de varios megas o un
+// binario no le sirven de nada y se comen la conversación, así que se cortan antes de leer.
+export const LIMITE_LECTURA_BYTES = 1_048_576;
+// La misma heurística que usa git para decidir si un archivo es binario.
+const BYTES_PARA_DETECTAR_BINARIO = 8000;
+// Se lee del descriptor y no de la ruta: tipo, tamaño y contenido salen del mismo archivo
+// abierto. Con statSync seguido de readFileSync, un archivo que crecía entre las dos llamadas
+// se leía entero, sin tope. Y nunca se piden más de LIMITE + 1 bytes, que es lo justo para
+// saber si se pasa. O_NONBLOCK, que no existe en Windows, evita que abrir un FIFO se quede
+// esperando a que alguien escriba en él.
+//
+// Riesgo aceptado: la contención se comprueba sobre la ruta real y aquí se abre la ruta tal
+// cual, así que cambiar un enlace justo entre las dos cosas abriría otro destino. Cerrarlo
+// exige abrir sin seguir enlaces componente a componente, que Node no ofrece de forma portable.
+export function leerTextoAcotado(ruta) {
+    let descriptor;
+    try {
+        descriptor = fs.openSync(ruta, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+    }
+    catch (error) {
+        if (error?.code === "EISDIR")
+            throw new Error(`${ruta} no es un archivo: es una carpeta.`);
+        throw error;
+    }
+    try {
+        const info = fs.fstatSync(descriptor);
+        if (!info.isFile()) {
+            throw new Error(`${ruta} no es un archivo normal: es una carpeta, un dispositivo o una tubería.`);
+        }
+        if (info.size > LIMITE_LECTURA_BYTES) {
+            throw new Error(`${ruta} pesa ${info.size} bytes y el límite de lectura es 1 MB (${LIMITE_LECTURA_BYTES} bytes).`);
+        }
+        const buffer = Buffer.alloc(LIMITE_LECTURA_BYTES + 1);
+        let leidos = 0;
+        while (leidos < buffer.length) {
+            const bytes = fs.readSync(descriptor, buffer, leidos, buffer.length - leidos, null);
+            if (bytes === 0)
+                break;
+            leidos += bytes;
+        }
+        if (leidos > LIMITE_LECTURA_BYTES) {
+            throw new Error(`${ruta} creció mientras se leía y pasa del límite de lectura de 1 MB (${LIMITE_LECTURA_BYTES} bytes).`);
+        }
+        const contenido = buffer.subarray(0, leidos);
+        if (contenido.subarray(0, BYTES_PARA_DETECTAR_BINARIO).includes(0)) {
+            throw new Error(`${ruta} parece binario: tiene un byte NUL en sus primeros ${BYTES_PARA_DETECTAR_BINARIO} bytes. ` +
+                `Estas tools solo leen texto.`);
+        }
+        return contenido.toString("utf-8");
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
 //# sourceMappingURL=paths.js.map

package/build/schemas.d.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+export declare const startTaskShape: {
+    project: z.ZodString;
+    task_name: z.ZodString;
+    initial_context: z.ZodString;
+    crear_proyecto: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+};
+export declare const getPhasePromptShape: {
+    phase: z.ZodNumber;
+    project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    task_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+};
+export declare const getActiveTaskShape: {
+    project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+};
+export declare const listTasksShape: {
+    project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+};
+export declare const switchTaskShape: {
+    project: z.ZodString;
+    task_name: z.ZodString;
+};
+export declare const readCentralDocShape: {
+    project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    task_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    file_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    file_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+};
+export declare const writeCentralDocShape: {
+    content: z.ZodString;
+    project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    task_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    file_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    file_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+};
+export declare const readCrossRepoShape: {
+    repo_name: z.ZodString;
+    file_path: z.ZodString;
+};
+declare const SHAPES: {
+    start_task: {
+        project: z.ZodString;
+        task_name: z.ZodString;
+        initial_context: z.ZodString;
+        crear_proyecto: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    };
+    get_phase_prompt: {
+        phase: z.ZodNumber;
+        project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        task_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    };
+    get_active_task: {
+        project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    };
+    list_tasks: {
+        project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    };
+    switch_task: {
+        project: z.ZodString;
+        task_name: z.ZodString;
+    };
+    read_central_doc: {
+        project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        task_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        file_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        file_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    };
+    write_central_doc: {
+        content: z.ZodString;
+        project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        task_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        file_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        file_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    };
+    read_cross_repo: {
+        repo_name: z.ZodString;
+        file_path: z.ZodString;
+    };
+};
+type NombreTool = keyof typeof SHAPES;
+type SinNulos<T> = {
+    [K in keyof T]: Exclude<T[K], null>;
+};
+export type LlamadaValidada = {
+    [K in NombreTool]: {
+        tool: K;
+        args: SinNulos<z.output<z.ZodObject<(typeof SHAPES)[K]>>>;
+    };
+}[NombreTool];
+export declare function validarLlamada(tool: string, args: unknown): LlamadaValidada;
+export {};
+//# sourceMappingURL=schemas.d.ts.map

package/build/schemas.js

@@ -0,0 +1,105 @@
+// Los argumentos de cada tool, declarados una sola vez con zod.
+//
+// Antes cada tool leía sus argumentos con String(args?.x), que no valida nada: sin task_name,
+// String(undefined) creaba la tarea "undefined/" y la dejaba activa. Ahora todo pasa por aquí
+// antes de usarse, y el error nombra el campo.
+//
+// Se exportan shapes (los campos sueltos) y no z.object(...): es lo que recibe registerTool
+// del SDK, al que se pasarán tal cual en la migración a McpServer (Etapa 2).
+//
+// Los opcionales son .nullish() y null cuenta como ausente: algunos clientes con modelos en
+// modo estricto mandan null en todo campo opcional. Un número en texto (phase: "3") no se
+// convierte: se rechaza con un mensaje que dice qué se espera. Es raro, el modelo lo corrige
+// al primer intento, y convertirlo complicaría el JSON Schema que se generará desde aquí.
+import { z } from "zod";
+export const startTaskShape = {
+    project: z.string().trim().min(1, "Falta `project`."),
+    task_name: z.string().min(1, "Falta `task_name`."),
+    initial_context: z.string().min(1, "Falta `initial_context`."),
+    crear_proyecto: z.boolean().nullish(),
+};
+export const getPhasePromptShape = {
+    phase: z.number().int(),
+    project: z.string().nullish(),
+    task_name: z.string().nullish(),
+};
+export const getActiveTaskShape = {
+    project: z.string().nullish(),
+};
+export const listTasksShape = {
+    project: z.string().nullish(),
+};
+export const switchTaskShape = {
+    project: z.string().trim().min(1, "Falta `project`."),
+    task_name: z.string().min(1, "Falta `task_name`."),
+};
+// Los cuatro son opcionales por separado: qué combinación vale lo decide resolveDocPath.
+export const readCentralDocShape = {
+    project: z.string().nullish(),
+    task_name: z.string().nullish(),
+    file_name: z.string().nullish(),
+    file_path: z.string().nullish(),
+};
+export const writeCentralDocShape = {
+    ...readCentralDocShape,
+    content: z.string(),
+};
+export const readCrossRepoShape = {
+    repo_name: z.string().min(1, "Falta `repo_name`."),
+    file_path: z.string().min(1, "Falta `file_path`."),
+};
+const SHAPES = {
+    start_task: startTaskShape,
+    get_phase_prompt: getPhasePromptShape,
+    get_active_task: getActiveTaskShape,
+    list_tasks: listTasksShape,
+    switch_task: switchTaskShape,
+    read_central_doc: readCentralDocShape,
+    write_central_doc: writeCentralDocShape,
+    read_cross_repo: readCrossRepoShape,
+};
+// Lo que se espera de cada tipo, dicho como se le diría al modelo para que corrija la llamada.
+// El único número es `phase`, de ahí el ejemplo.
+const TIPOS = {
+    string: "un texto",
+    number: "un número, por ejemplo 3",
+    int: "un número entero, por ejemplo 3",
+    boolean: "true o false",
+    object: "un objeto",
+};
+function describirProblema(issue, recibidos) {
+    const campo = issue.path.map(String).join(".");
+    if (!campo)
+        return "los argumentos tienen que ser un objeto.";
+    const nombre = `\`${campo}\``;
+    // null también es "falta": en un opcional se tolera, en un obligatorio es lo mismo que no venir.
+    if (issue.code === "invalid_type") {
+        return recibidos[campo] == null
+            ? `Falta ${nombre}.`
+            : `${nombre} debe ser ${TIPOS[issue.expected] ?? issue.expected}.`;
+    }
+    // Los mínimos llevan su mensaje en español en el propio shape ("Falta `task_name`.").
+    if (issue.code === "too_small")
+        return issue.message;
+    // Los máximos no: el único que puede saltar es el del entero seguro de `phase`.
+    if (issue.code === "too_big")
+        return `${nombre} es demasiado grande.`;
+    return `${nombre}: ${issue.message}.`;
+}
+export function validarLlamada(tool, args) {
+    if (!Object.hasOwn(SHAPES, tool)) {
+        throw new Error(`Unknown tool: ${tool}`);
+    }
+    const resultado = z.object(SHAPES[tool]).safeParse(args ?? {});
+    if (!resultado.success) {
+        const recibidos = (args && typeof args === "object" ? args : {});
+        const problemas = resultado.error.issues.map((issue) => describirProblema(issue, recibidos));
+        throw new Error(`Argumentos no válidos. ${problemas.join(" ")}`);
+    }
+    // null cuenta como ausente: se quita aquí, una vez, para que ninguna tool tenga que
+    // distinguir entre un campo que no vino y uno que vino vacío.
+    const sinNulos = Object.fromEntries(Object.entries(resultado.data).filter(([, valor]) => valor !== null));
+    // El cast es seguro: los datos los acaba de producir el shape de esta misma tool.
+    return { tool, args: sinNulos };
+}
+//# sourceMappingURL=schemas.js.map