mcp-phase-gate 2.0.1 → 2.2.0

package/build/phases.js

@@ -4,8 +4,37 @@
 import * as fs from "fs";
 import * as path from "path";
 import { promptsLayers } from "./config.js";
+import { log } from "./log.js";
+import { claveDeNombre, validarSegmento } from "./paths.js";
 // Las reglas globales se anteponen a cada fase.
-const GLOBAL_RULES_FILE = "global-rules.md";
+export const GLOBAL_RULES_FILE = "global-rules.md";
+// Comando de cada fase (`/fN`): `comandos/fN.md` dentro de una capa de prompts. Gana la capa más
+// alta que lo tenga, igual que las fases; sin ninguno, la fase usa un texto genérico.
+export const CARPETA_COMANDOS = "comandos";
+export function resolveCommandFile(numero, capas = promptsLayers()) {
+    for (const base of [...capas].reverse()) {
+        const ruta = path.join(base, CARPETA_COMANDOS, `f${numero}.md`);
+        if (tipoDe(ruta) === "archivo")
+            return ruta;
+    }
+    return null;
+}
+// statSync con throwIfNoEntry solo calla el ENOENT: si un tramo de la ruta es un archivo
+// (ENOTDIR) o no hay permiso, lanza igual. Para preguntar "¿es una carpeta?" eso no es un error.
+function tipoDe(ruta) {
+    try {
+        const info = fs.statSync(ruta, { throwIfNoEntry: false });
+        if (!info)
+            return null;
+        return info.isDirectory() ? "carpeta" : info.isFile() ? "archivo" : "otro";
+    }
+    catch {
+        return null;
+    }
+}
+export function esCarpeta(ruta) {
+    return tipoDe(ruta) === "carpeta";
+}
 // Acepta "fase-1-descubrimiento.md" y también "phase-1-discovery.md",
 // para que un juego de prompts en inglés funcione sin tocar el código.
 export const PHASE_FILE_PATTERN = /^(?:fase|phase)-(\d+)[-.]/i;
@@ -14,8 +43,77 @@ export const PHASE_FILE_PATTERN = /^(?:fase|phase)-(\d+)[-.]/i;
 // describe ese documento —no en un archivo de configuración aparte— para que el nombre exista
 // en un solo lugar y se lea en vivo, sin recompilar, igual que el resto del prompt.
 const PHASE_FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+// Los prompts propios, escritos por ejemplo con el Bloc de notas, llegan en CRLF, y a veces con
+// BOM al principio. Se normalizan al leer: lo que se entrega al modelo y lo que se compara en los
+// tests va siempre en LF y sin BOM. Con el BOM delante, el frontmatter no se reconocía y la fase
+// se quedaba sin documento.
+function aLF(texto) {
+    return texto.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
+}
+// Quita los marcadores de ranura y conserva su contenido. El modelo nunca los ve.
+// Una ranura marca el contenido de una sección que un preset podrá sustituir en la Etapa 3:
+//   <!-- ranura: verificacion -->
+//   contenido por defecto
+//   <!-- /ranura -->
+// Solo cuenta un marcador que ocupa su propia línea, y la línea se quita entera. Un marcador con
+// texto detrás, o dos en la misma línea, no se toca: lo avisa loadPhasePrompt.
+export const MARCADOR_RANURA = /^[ \t]*<!--[ \t]*\/?ranura(?:[ \t]*:[ \t]*[\w-]+)?[ \t]*-->[ \t]*\r?$\n?/gm;
+export function quitarMarcadores(texto) {
+    return texto.replace(MARCADOR_RANURA, "");
+}
+// Lo que parece un marcador de ranura y sobrevivió a quitarMarcadores: mal escrito (con acento,
+// en mayúsculas, con texto detrás). Llegaría tal cual al modelo, así que queda en el log.
+const RESTO_DE_MARCADOR = /<!--[^\n]*?ranura/i;
+function entregable(texto, archivo) {
+    const limpio = quitarMarcadores(texto);
+    if (RESTO_DE_MARCADOR.test(limpio)) {
+        log("warning", `${archivo} tiene un marcador de ranura que no se reconoce: llega tal cual al modelo.`);
+    }
+    return limpio.trim();
+}
+// La subcarpeta de recibos acaba dentro de un file_name, así que tiene que ser un solo segmento
+// portable, y visible: write_central_doc no escribe en segmentos que empiezan por punto. Un valor
+// inválido no tumba la fase: se ignora y queda en el log.
+function leerRecibos(valor, archivo) {
+    if (!valor)
+        return undefined;
+    try {
+        const segmento = validarSegmento(valor, "recibos");
+        if (segmento.startsWith("."))
+            throw new Error("no puede empezar por punto.");
+        return segmento;
+    }
+    catch (error) {
+        log("warning", `Se ignora el frontmatter recibos de ${archivo}: ${error.message}`);
+        return undefined;
+    }
+}
+// Una subcarpeta de recibos con el nombre de un documento rompe el flujo: si se llama como el
+// documento de la fase, la carpeta hace que la fase cuente como cerrada al primer recibo. Se
+// comprueba al final, con las fases de todas las capas ya resueltas.
+function descartarRecibosQueChocan(phases) {
+    const documentos = new Set();
+    for (const datos of phases.values()) {
+        for (const nombre of [datos.documento, datos.documentoInicial]) {
+            if (nombre)
+                documentos.add(claveDeNombre(nombre));
+        }
+    }
+    for (const datos of phases.values()) {
+        if (datos.recibos && documentos.has(claveDeNombre(datos.recibos))) {
+            log("warning", `Se ignora el frontmatter recibos de ${datos.file}: ` +
+                `"${datos.recibos}" es el nombre de un documento de fase.`);
+            datos.recibos = undefined;
+        }
+    }
+}
 export function parsePhaseFile(fullPath) {
-    const crudo = fs.readFileSync(fullPath, "utf-8");
+    return separarFrontmatter(fs.readFileSync(fullPath, "utf-8"));
+}
+// La cabecera "clave: valor" de un texto ya leído, y el resto. Sirve igual para un prompt que
+// para un recibo de lote, que usan el mismo formato.
+export function separarFrontmatter(texto) {
+    const crudo = aLF(texto);
     const encontrada = crudo.match(PHASE_FRONTMATTER);
     if (!encontrada)
         return { meta: {}, cuerpo: crudo };
@@ -44,7 +142,9 @@ export function parsePhaseFile(fullPath) {
 export function discoverPhases(capas = promptsLayers()) {
     const phases = new Map();
     for (const base of capas) {
-        if (!fs.existsSync(base))
+        // Una capa que no existe o que no es una carpeta (PHASE_GATE_PROMPTS_PATH apuntando a un
+        // archivo) se salta: doctor la avisa, y las fases de las demás capas siguen sirviendo.
+        if (!esCarpeta(base))
             continue;
         // Se resuelve capa por capa: dentro de una, gana el primero por orden alfabético; entre
         // capas, gana la de más arriba. Sin este mapa intermedio la regla alfabética de la capa
@@ -71,11 +171,13 @@ export function discoverPhases(capas = promptsLayers()) {
                 title: readPhaseTitle(cuerpo, file),
                 documento: meta.documento || undefined,
                 documentoInicial: meta.documento_inicial || undefined,
+                recibos: leerRecibos(meta.recibos, fullPath),
             });
         }
         for (const [numero, datos] of deEstaCapa)
             phases.set(numero, datos);
     }
+    descartarRecibosQueChocan(phases);
     return phases;
 }
 // El título es el primer encabezado "# ..." del cuerpo; si no lo hay, se deriva del nombre
@@ -107,9 +209,9 @@ export function loadPhasePrompt(phase, capas = promptsLayers()) {
     const parts = [];
     const globales = resolveGlobalRules(capas);
     if (globales) {
-        parts.push(fs.readFileSync(globales, "utf-8").trim());
+        parts.push(entregable(aLF(fs.readFileSync(globales, "utf-8")), globales));
     }
-    parts.push(parsePhaseFile(entry.file).cuerpo.trim());
+    parts.push(entregable(parsePhaseFile(entry.file).cuerpo, entry.file));
     const archivos = describePhaseFiles(available, phase);
     if (archivos)
         parts.push(archivos);
@@ -119,7 +221,7 @@ export function loadPhasePrompt(phase, capas = promptsLayers()) {
 // fábrica, no se suman: concatenar dos juegos de reglas hace imposible saber de qué archivo
 // salió la instrucción que estorbó cuando algo sale raro, que es justo el momento en que hay
 // que saberlo. Si quieres las de fábrica y algo más, las copias y añades.
-function resolveGlobalRules(capas) {
+export function resolveGlobalRules(capas = promptsLayers()) {
     for (const base of [...capas].reverse()) {
         const ruta = path.join(base, GLOBAL_RULES_FILE);
         if (fs.existsSync(ruta))
@@ -127,8 +229,14 @@ function resolveGlobalRules(capas) {
     }
     return null;
 }
+// El texto de un prompt propio tal como lo ve el modelo: en LF y sin BOM. Lo usan quienes leen
+// un archivo de prompts fuera de este módulo, como el diagnóstico.
+export function leerPromptNormalizado(ruta) {
+    return aLF(fs.readFileSync(ruta, "utf-8"));
+}
 // Bloque que se añade al final del prompt con los nombres exactos de los documentos: el que
-// produce esta fase y los de las anteriores, que son los que hay que leer. Va aquí y no en el
+// produce esta fase y los de las anteriores, que son los que hay que leer, y la subcarpeta de
+// recibos de la fase que la declare. Va aquí y no en el
 // comando del cliente para que el nombre viva en un solo sitio; así afinar un prompt no obliga
 // a editar además un comando en cada dispositivo.
 export function describePhaseFiles(available, phase) {
@@ -136,7 +244,10 @@ export function describePhaseFiles(available, phase) {
     const previos = [...available.entries()]
         .filter(([numero, datos]) => numero < phase && datos.documento)
         .sort((a, b) => a[0] - b[0])
-        .map(([numero, datos]) => `- Fase ${numero}: \`${datos.documento}\``);
+        .map(([numero, datos]) => {
+        const recibos = datos.recibos ? ` (recibos de lote en \`${datos.recibos}/\`)` : "";
+        return `- Fase ${numero}: \`${datos.documento}\`${recibos}`;
+    });
     if (!propio && previos.length === 0)
         return "";
     const lineas = ["## ARCHIVOS DE ESTA TAREA (nombres exactos)"];
@@ -146,19 +257,16 @@ export function describePhaseFiles(available, phase) {
     if (propio) {
         lineas.push("", `El documento de esta fase se llama exactamente \`${propio}\`. Guárdalo con ` +
             "`write_central_doc` en la carpeta de la tarea activa, con ese nombre y sin cambiarlo.");
+        const recibos = available.get(phase)?.recibos;
+        if (recibos) {
+            lineas.push("", `Los recibos de lote van en la subcarpeta \`${recibos}/\`, uno por lote: ` +
+                `\`${recibos}/L01 - <slug>.md\`. Con un solo lote no hay subcarpeta: el recibo es el ` +
+                "documento de esta fase.");
+        }
     }
     else {
         lineas.push("", "Esta fase no deja documento en la Documentación Central: su salida va en el chat.");
     }
     return lineas.join("\n");
 }
-export function describePhases() {
-    const available = discoverPhases();
-    if (available.size === 0)
-        return "No se encontraron prompts de fase.";
-    return [...available.entries()]
-        .sort((a, b) => a[0] - b[0])
-        .map(([number, { title }]) => `${number}: ${title}`)
-        .join(", ");
-}
 //# sourceMappingURL=phases.js.map

package/build/prompts-mcp.d.ts

@@ -0,0 +1,33 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+export declare function argumentosDeFase(numero: number): {
+    project: z.ZodOptional<z.ZodString>;
+    task_name: z.ZodOptional<z.ZodString>;
+    contexto: z.ZodOptional<z.ZodString>;
+    commits?: never;
+} | {
+    project: z.ZodOptional<z.ZodString>;
+    commits: z.ZodOptional<z.ZodString>;
+    task_name?: never;
+    contexto?: never;
+} | {
+    project: z.ZodOptional<z.ZodString>;
+    task_name?: never;
+    contexto?: never;
+    commits?: never;
+};
+export declare function tituloDePrompt(numero: number, titulo: string): string;
+export declare function descripcionDePrompt(numero: number, titulo: string): string;
+export declare function textoGenerico(numero: number, titulo: string): string;
+type Argumentos = {
+    project?: string | undefined;
+    task_name?: string | undefined;
+    commits?: string | undefined;
+    contexto?: string | undefined;
+};
+export declare function textoDelComando(numero: number, titulo: string, args: Argumentos, capas?: string[]): string;
+export declare function sincronizarPrompts(mcp: McpServer): void;
+export declare function asegurarCapacidadDePrompts(mcp: McpServer): void;
+export declare function vigilarCapas(mcp: McpServer, esperaMs?: number): () => void;
+export {};
+//# sourceMappingURL=prompts-mcp.d.ts.map

package/build/prompts-mcp.js

@@ -0,0 +1,194 @@
+// Los comandos de fase (/f1…/fN) servidos como MCP Prompts. Antes había que copiar cada comando a
+// mano en la carpeta de cada cliente y de cada equipo, y las copias se desincronizaban; ahora el
+// servidor los ofrece a cualquier cliente que muestre prompts, y llegan con cada versión.
+//
+// El texto de cada comando vive en `comandos/fN.md` dentro de una capa de prompts (los de fábrica
+// en prompts/comandos/), y se resuelve por capas como las fases: gana la más alta que lo tenga.
+// Una fase sin comando, como una fase-6 propia, recibe un texto genérico que funciona igual.
+//
+// El prompt NO incluye el prompt de la fase: sigue siendo orquestación ("llama a
+// get_phase_prompt(N)…"). Devolver ya el texto de la fase ahorraría una llamada, pero crearía dos
+// caminos para recibir el mismo prompt, y en uno la compuerta no recibiría el `project`.
+import * as fs from "fs";
+import { z } from "zod";
+import { promptsLayers } from "./config.js";
+import { log } from "./log.js";
+import { discoverPhases, parsePhaseFile, resolveCommandFile } from "./phases.js";
+// Todos los argumentos son opcionales: el texto de cada comando ya pide lo que falte, y así el
+// prompt sirve también en clientes que parten los argumentos por espacios (un contexto largo puede
+// ir pegado después del comando, como texto normal del chat).
+const PROJECT = z.string().optional().describe("Proyecto en el que estás trabajando.");
+export function argumentosDeFase(numero) {
+    if (numero === 1) {
+        return {
+            project: PROJECT,
+            task_name: z.string().optional().describe("Nombre corto de la tarea nueva."),
+            contexto: z.string().optional().describe("El correo, mensaje o requerimiento completo."),
+        };
+    }
+    if (numero === 5) {
+        return {
+            project: PROJECT,
+            commits: z
+                .string()
+                .optional()
+                .describe("Rango de commits a auditar. Si lo omites, se toman de los recibos de la Fase 4."),
+        };
+    }
+    return { project: PROJECT };
+}
+export function tituloDePrompt(numero, titulo) {
+    return `Fase ${numero} · ${titulo}`;
+}
+export function descripcionDePrompt(numero, titulo) {
+    return `Arranca la Fase ${numero} (${titulo}) del flujo de mcp-phase-gate.`;
+}
+export function textoGenerico(numero, titulo) {
+    return [
+        `Vas a iniciar la FASE ${numero} (${titulo}) del flujo del mcp-phase-gate.`,
+        "",
+        "Pasos:",
+        "1. Si no sabes cuál es la tarea activa, llama a `get_active_task` (o pídeme project + task_name).",
+        `2. Llama a \`get_phase_prompt(${numero})\` indicándole también el \`project\` en el que estoy trabajando, y asume ese rol.`,
+        "3. Lee los documentos de las fases anteriores con `read_central_doc`; `get_phase_prompt` te dio sus nombres exactos.",
+        "4. Sigue el prompt de la fase y guarda su documento con `write_central_doc`, con el nombre que te indicó `get_phase_prompt`.",
+    ].join("\n");
+}
+// La sección con lo que vino como argumento. Solo aparecen las líneas de los que vinieron, y sin
+// ninguno la sección no existe: así el texto queda igual que el comando escrito a mano.
+function datosDeInvocacion(args) {
+    const presente = (valor) => typeof valor === "string" && valor.trim() !== "";
+    const lineas = [];
+    // project, task_name y commits son de una línea: los saltos se aplanan, para que un valor no
+    // pueda abrir secciones nuevas dentro del texto. El contexto sí es multilínea por naturaleza, y
+    // va tal cual: lo escribe la persona, igual que si lo pegara en el chat.
+    const enUnaLinea = (valor) => valor.replace(/\s+/g, " ").trim();
+    if (presente(args.project))
+        lineas.push(`- project: ${enUnaLinea(args.project)}`);
+    if (presente(args.task_name))
+        lineas.push(`- task_name: ${enUnaLinea(args.task_name)}`);
+    if (presente(args.commits))
+        lineas.push(`- commits: ${enUnaLinea(args.commits)}`);
+    if (presente(args.contexto))
+        lineas.push("- initial_context:", "", args.contexto.trim());
+    return lineas.length ? ["## Datos de esta invocación", ...lineas].join("\n") : null;
+}
+// El texto se lee en cada llamada, como los prompts de fase: editar un comando no exige reiniciar.
+export function textoDelComando(numero, titulo, args, capas = promptsLayers()) {
+    const archivo = resolveCommandFile(numero, capas);
+    let cuerpo;
+    if (archivo) {
+        try {
+            cuerpo = parsePhaseFile(archivo).cuerpo.trim();
+        }
+        catch (error) {
+            log("warning", `No se pudo leer ${archivo}; se usa el texto genérico: ${error instanceof Error ? error.message : String(error)}`);
+            cuerpo = textoGenerico(numero, titulo);
+        }
+    }
+    else {
+        cuerpo = textoGenerico(numero, titulo);
+    }
+    const datos = datosDeInvocacion(args);
+    return datos ? `${cuerpo}\n\n${datos}` : cuerpo;
+}
+const registros = new WeakMap();
+function registrar(mcp, numero, titulo) {
+    return mcp.registerPrompt(`f${numero}`, {
+        title: tituloDePrompt(numero, titulo),
+        description: descripcionDePrompt(numero, titulo),
+        argsSchema: argumentosDeFase(numero),
+    }, async (args) => {
+        // El título se toma del registro vigente: puede haber cambiado desde que se registró.
+        const vigente = registros.get(mcp)?.get(numero)?.titulo ?? titulo;
+        return {
+            description: descripcionDePrompt(numero, vigente),
+            messages: [{ role: "user", content: { type: "text", text: textoDelComando(numero, vigente, args) } }],
+        };
+    });
+}
+// Nunca lanza: se llama tras cada tool, y un prompt que no se pudo registrar no debe convertir en
+// error la respuesta de una tool que salió bien.
+export function sincronizarPrompts(mcp) {
+    try {
+        const capas = promptsLayers();
+        const fases = discoverPhases(capas);
+        let actuales = registros.get(mcp);
+        if (!actuales) {
+            actuales = new Map();
+            registros.set(mcp, actuales);
+        }
+        for (const [numero, registro] of [...actuales]) {
+            if (!fases.has(numero)) {
+                registro.prompt.remove();
+                actuales.delete(numero);
+            }
+        }
+        for (const [numero, datos] of fases) {
+            const comando = resolveCommandFile(numero, capas);
+            const registro = actuales.get(numero);
+            if (!registro) {
+                actuales.set(numero, { prompt: registrar(mcp, numero, datos.title), titulo: datos.title, comando });
+                continue;
+            }
+            if (registro.titulo !== datos.title || registro.comando !== comando) {
+                registro.titulo = datos.title;
+                registro.comando = comando;
+                registro.prompt.update({
+                    title: tituloDePrompt(numero, datos.title),
+                    description: descripcionDePrompt(numero, datos.title),
+                });
+            }
+        }
+    }
+    catch (error) {
+        log("warning", `No se pudieron sincronizar los prompts /fN: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+// La capacidad `prompts` solo se puede declarar antes de conectar. Si al arrancar no hay ninguna
+// fase (una carpeta de prompts vacía o mal configurada), el primer /fN que apareciera después
+// intentaría declararla con la conexión abierta y el SDK lo rechazaría. Registrar y quitar un
+// prompt de paso deja la capacidad declarada sin que la lista tenga nada.
+export function asegurarCapacidadDePrompts(mcp) {
+    if ((registros.get(mcp)?.size ?? 0) > 0)
+        return;
+    // Un nombre que ninguna fase puede tener: las fases se registran como f<número>.
+    mcp.registerPrompt("phase-gate-provisional", { description: "provisional" }, async () => ({ messages: [] })).remove();
+}
+// ─── Vigilancia de las capas ────────────────────────────────────────────────
+// Mejora oportunista: con fs.watch, un comando o una fase nueva aparece sin esperar a la siguiente
+// llamada a una tool. En OneDrive y en algunas unidades de red fs.watch no avisa, y por eso lo que
+// garantiza el resultado es la sincronización tras cada tool, no esto. Los vigilantes no mantienen
+// vivo el proceso (unref) y se cierran con el servidor.
+export function vigilarCapas(mcp, esperaMs = 300) {
+    const vigilantes = [];
+    let temporizador = null;
+    const programar = () => {
+        if (temporizador)
+            clearTimeout(temporizador);
+        temporizador = setTimeout(() => {
+            temporizador = null;
+            sincronizarPrompts(mcp);
+        }, esperaMs);
+        temporizador.unref();
+    };
+    for (const capa of promptsLayers()) {
+        if (!fs.statSync(capa, { throwIfNoEntry: false })?.isDirectory())
+            continue;
+        try {
+            const vigilante = fs.watch(capa, { recursive: true, persistent: false }, programar);
+            vigilante.on("error", () => vigilante.close());
+            vigilantes.push(vigilante);
+        }
+        catch {
+            // Sin vigilancia en esta capa: la sincronización tras cada tool sigue cubriéndola.
+        }
+    }
+    return () => {
+        if (temporizador)
+            clearTimeout(temporizador);
+        for (const vigilante of vigilantes)
+            vigilante.close();
+    };
+}
+//# sourceMappingURL=prompts-mcp.js.map

package/build/recursos.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const URI_ESTADO = "phase-gate://estado";
+export declare const URI_FASES = "phase-gate://fases";
+export declare function uriDeDocumento(proyecto: string, tarea: string, documento: string): string;
+export declare function uriDeRecibo(proyecto: string, tarea: string, recibo: string): string;
+export declare function tablaDeFases(): string;
+export declare function registrarRecursos(mcp: McpServer): void;
+//# sourceMappingURL=recursos.d.ts.map