mcp-phase-gate 2.0.1 → 2.2.0

package/build/config.js

@@ -8,40 +8,166 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import { fileURLToPath } from "url";
-import dotenv from "dotenv";
+import { parseEnv } from "util";
 // Carpeta de este módulo. Sirve para localizar el .env y el package.json de la raíz del repo.
 export const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
-// Carga el archivo .env de la raíz del repo (un nivel arriba de build/ o src/).
-// Así cada dispositivo define sus propias rutas sin tocar el mcp.json.
-// quiet: true evita que dotenv v17 imprima su banner en stdout, que es el canal del JSON-RPC.
-dotenv.config({ path: path.join(MODULE_DIR, "..", ".env"), quiet: true });
+// ─── El .env ────────────────────────────────────────────────────────────────
+// El .env de la raíz del paquete (un nivel arriba de build/ o src/) deja que cada dispositivo
+// defina sus rutas sin tocar el mcp.json. Se lee con un lector propio y no con dotenv ni con
+// process.loadEnvFile: loadEnvFile no quita el BOM de UTF-8, y con un .env guardado con BOM la
+// primera clave llegaba como "\uFEFFORQUESTADOR_DOCS_PATH" y la variable desaparecía. Y un .env
+// en UTF-16 —lo que sale de PowerShell con ">"— hoy solo se adivinaba por los acentos rotos.
+//
+// El bloque "env" del cliente sigue ganando: solo se asignan las claves que no estén ya en el
+// entorno, igual que hacía dotenv.
+const clavesCargadas = new Set();
+let errorDeCarga = null;
+export function envPorDefecto() {
+    return path.join(MODULE_DIR, "..", ".env");
+}
+// Claves que vinieron del .env; las demás, del entorno. doctor usa esto para decir la fuente.
+export function clavesDeEnv() {
+    return clavesCargadas;
+}
+// Error guardado de la última carga (por ejemplo, UTF-16), o null.
+export function errorDeEnv() {
+    return errorDeCarga;
+}
+// Solo para tests: borra del entorno las claves que vinieron del .env, vacía clavesDeEnv() y el
+// error guardado. Sin esto, un .env cargado en un test contaminaría al siguiente.
+export function reiniciarEnv() {
+    for (const clave of clavesCargadas)
+        delete process.env[clave];
+    clavesCargadas.clear();
+    errorDeCarga = null;
+}
+// Carga el .env. Sin argumento, el de la raíz del paquete. Se llama una vez al importar este
+// módulo. Volver a llamarla sustituye lo que cargó la vez anterior.
+export function cargarEnv(archivo = envPorDefecto()) {
+    reiniciarEnv();
+    let bytes;
+    try {
+        bytes = fs.readFileSync(archivo);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return; // sin .env, todo sale del entorno
+        errorDeCarga = `No se pudo leer el .env (${archivo}): ${error instanceof Error ? error.message : String(error)}`;
+        return;
+    }
+    // UTF-16 con BOM en cualquiera de sus dos órdenes, o sin BOM pero con bytes NUL: en un .env de
+    // texto en UTF-8 no hay ningún NUL, y en UTF-16 los hay en casi cada carácter.
+    const conBom16 = bytes.length >= 2 && ((bytes[0] === 0xff && bytes[1] === 0xfe) || (bytes[0] === 0xfe && bytes[1] === 0xff));
+    if (conBom16 || bytes.subarray(0, 512).includes(0)) {
+        errorDeCarga = `El .env está en UTF-16 y no se cargó (${archivo}). Guárdalo como UTF-8 (sin BOM).`;
+        return;
+    }
+    const texto = bytes.toString("utf-8").replace(/^\uFEFF/, "");
+    let valores;
+    try {
+        valores = parseEnv(texto);
+    }
+    catch (error) {
+        errorDeCarga = `No se pudo interpretar el .env (${archivo}): ${error instanceof Error ? error.message : String(error)}`;
+        return;
+    }
+    for (const [clave, valor] of Object.entries(valores)) {
+        if (process.env[clave] !== undefined)
+            continue;
+        process.env[clave] = valor;
+        clavesCargadas.add(clave);
+    }
+}
+cargarEnv();
+export const VARIABLES = {
+    DOCS_PATH: { principal: "PHASE_GATE_DOCS_PATH", alias: "ORQUESTADOR_DOCS_PATH", esRuta: true },
+    REPOS_PATH: { principal: "PHASE_GATE_REPOS_PATH", alias: "ORQUESTADOR_REPOS_PATH", esRuta: true },
+    TASKS_SUBDIR: { principal: "PHASE_GATE_TASKS_SUBDIR", alias: "ORQUESTADOR_TASKS_SUBDIR", esRuta: false },
+    PROMPTS_PATH: { principal: "PHASE_GATE_PROMPTS_PATH", alias: "ORQUESTADOR_PROMPTS_PATH", esRuta: true },
+    STATE_PATH: { principal: "PHASE_GATE_STATE_PATH", alias: "ORQUESTADOR_STATE_PATH", esRuta: true },
+    ELICITATION: { principal: "PHASE_GATE_ELICITATION", alias: null, esRuta: false },
+};
+export const NOMBRES_LOGICOS = Object.keys(VARIABLES);
+// Qué nombre gana, en este orden:
+//   1. La fuente: el entorno (el bloque "env" del cliente) gana al .env, también cuando cada
+//      nombre llega por una vía distinta. Si no, un .env con PHASE_GATE_X le ganaría a un bloque
+//      env con ORQUESTADOR_X, y "el cliente gana al .env" dejaría de ser cierto.
+//   2. Dentro de la misma fuente, PHASE_GATE_* gana a ORQUESTADOR_*.
+//
+// "Definida" es que exista, aunque esté vacía: TASKS_SUBDIR vacía a propósito significa que las
+// tareas cuelgan directo del proyecto, y eso tiene que poder decirse también con el nombre nuevo.
+// En las variables de RUTA, en cambio, vacía cuenta como ausente: una ruta vacía no significa
+// nada, y no debe tapar un alias que sí apunta a una carpeta.
+export function leerVariable(logica) {
+    const { principal, alias, esRuta } = VARIABLES[logica];
+    const definida = (nombre) => {
+        const valor = process.env[nombre];
+        return valor !== undefined && (!esRuta || valor.trim() !== "");
+    };
+    const fuenteDe = (nombre) => (clavesCargadas.has(nombre) ? ".env" : "entorno");
+    const candidatos = (alias ? [principal, alias] : [principal]).filter(definida);
+    // sort es estable: con la misma fuente se conserva el orden principal, alias.
+    candidatos.sort((a, b) => Number(fuenteDe(a) === ".env") - Number(fuenteDe(b) === ".env"));
+    const usada = candidatos[0] ?? null;
+    const ignorada = candidatos[1] ?? null;
+    const crudo = usada ? process.env[usada] : undefined;
+    let discrepancia = null;
+    if (usada && ignorada) {
+        const comparable = (valor) => {
+            const recortado = valor.trim();
+            return esRuta && recortado ? path.resolve(recortado) : recortado;
+        };
+        if (comparable(process.env[usada]) !== comparable(process.env[ignorada])) {
+            const motivo = fuenteDe(usada) !== fuenteDe(ignorada) ? " (el entorno del cliente gana al .env)" : "";
+            discrepancia = `${ignorada} difiere de ${usada}; se usa ${usada}${motivo}.`;
+        }
+    }
+    else if (esRuta && alias && usada === alias && process.env[principal] !== undefined) {
+        discrepancia = `${principal} está vacía; se usa ${alias}.`;
+    }
+    return {
+        logica,
+        valor: crudo?.trim(),
+        usada,
+        fuente: usada === null ? "sin definir" : fuenteDe(usada),
+        discrepancia,
+    };
+}
+// Cómo se nombra una variable en un mensaje: la principal, y el alias entre paréntesis.
+export function nombrarVariable(logica) {
+    const { principal, alias } = VARIABLES[logica];
+    return alias ? `${principal} (o su alias ${alias})` : principal;
+}
 export const DOCS = {
-    variable: "ORQUESTADOR_DOCS_PATH",
+    logica: "DOCS_PATH",
     apuntaA: "la carpeta raíz de la Documentación Central",
 };
 export const REPOS = {
-    variable: "ORQUESTADOR_REPOS_PATH",
+    logica: "REPOS_PATH",
     apuntaA: "la carpeta que contiene tus repositorios de código",
 };
 // Se resuelve y valida en cada llamada, no una vez al arrancar. Así el servidor se queda en
 // pie aunque falte configuración, las tools que no dependen de estas rutas siguen sirviendo,
 // y el error llega al chat —donde está el usuario— en vez de quedarse enterrado en un log.
-export function requireBasePath({ variable, apuntaA }) {
-    const valor = process.env[variable]?.trim();
-    if (!valor) {
-        throw new Error(`Falta la variable ${variable}, que debe apuntar a ${apuntaA}. Defínela en el archivo ` +
-            `.env de la raíz del repo, o en el bloque "env" del mcp.json de tu cliente.`);
+export function requireBasePath({ logica, apuntaA }) {
+    const { valor, usada } = leerVariable(logica);
+    if (!valor || !usada) {
+        // Si el .env no se pudo cargar, esa es casi seguro la causa: se dice antes que nada.
+        const delEnv = errorDeCarga ? ` ${errorDeCarga}` : "";
+        throw new Error(`Falta ${nombrarVariable(logica)}, que debe apuntar a ${apuntaA}. Defínela en el archivo ` +
+            `.env de la raíz del repo, o en el bloque "env" del mcp.json de tu cliente.${delEnv}`);
     }
     const ruta = path.resolve(valor);
     // Una variable definida pero incorrecta falla igual de tarde que una ausente, así que la
-    // existencia se comprueba aquí. El caso del encoding ya mordió una vez y no es adivinable.
+    // existencia se comprueba aquí. El BOM y el UTF-16 ya los resuelve cargarEnv; un .env guardado
+    // en ANSI todavía rompe los acentos sin que se pueda detectar con certeza.
     if (!fs.existsSync(ruta)) {
-        throw new Error(`${variable} apunta a "${ruta}", que no existe en este equipo. Corrige la ruta en el .env. ` +
-            `Si lleva acentos, revisa que el .env esté guardado en UTF-8 sin BOM: en UTF-16 los ` +
+        throw new Error(`${usada} apunta a "${ruta}", que no existe en este equipo. Corrige la ruta en el .env. ` +
+            `Si lleva acentos, revisa que el .env esté guardado en UTF-8: en otra codificación los ` +
             `acentos llegan rotos y la carpeta parece no existir.`);
     }
     if (!fs.statSync(ruta).isDirectory()) {
-        throw new Error(`${variable} apunta a "${ruta}", que es un archivo y no una carpeta.`);
+        throw new Error(`${usada} apunta a "${ruta}", que es un archivo y no una carpeta.`);
     }
     return ruta;
 }
@@ -49,8 +175,9 @@ export function requireBasePath({ variable, apuntaA }) {
 // Es una convención de organización, no una ruta de dispositivo, pero vive en el entorno
 // para no tener que introducir un archivo de configuración por una sola cadena.
 // Vacía a propósito significa que las tareas cuelgan directo del proyecto.
+export const TASKS_SUBDIR_POR_DEFECTO = "Proyectos";
 export function tasksSubdir() {
-    return process.env.ORQUESTADOR_TASKS_SUBDIR?.trim() ?? "Proyectos";
+    return leerVariable("TASKS_SUBDIR").valor ?? TASKS_SUBDIR_POR_DEFECTO;
 }
 // ─── Prompts, en capas ──────────────────────────────────────────────────────
 // Los prompts de las fases viven en archivos .md sueltos. Vivir fuera del código permite
@@ -60,7 +187,7 @@ export function tasksSubdir() {
 // Se cargan en CAPAS, no por reemplazo: primero los del paquete y encima, si existe, la
 // carpeta que declare el usuario. La última capa que declare una fase es la que queda.
 //
-// Antes `ORQUESTADOR_PROMPTS_PATH` sustituía la carpeta entera, y eso solo funcionaba con un
+// Antes `PROMPTS_PATH` sustituía la carpeta entera, y eso solo funcionaba con un
 // clon del repo alrededor, donde editar `prompts/` es lo natural. Instalado desde npm los de
 // fábrica caen dentro de node_modules, donde editarlos no sirve porque la siguiente
 // instalación se los lleva. Reemplazar obligaba entonces a copiar las cinco fases para
@@ -72,7 +199,7 @@ export function defaultPromptsPath() {
 // De menor a mayor prioridad. La del usuario va al final: gana.
 export function promptsLayers() {
     const capas = [defaultPromptsPath()];
-    const propia = process.env.ORQUESTADOR_PROMPTS_PATH?.trim();
+    const propia = leerVariable("PROMPTS_PATH").valor;
     if (propia)
         capas.push(path.resolve(propia));
     return capas;
@@ -88,10 +215,12 @@ export function promptsLayers() {
 // No se migran: el puntero se recalcula solo con un `switch_task`, y arrastrar código de
 // migración para un dato que cuesta un comando en recuperarse es más caro que el problema.
 export const APP_DIR_NAME = "mcp-phase-gate";
+// La variable se recorta y se resuelve, como las demás rutas: antes se usaba tal cual, y un
+// espacio pegado al final del valor creaba otra carpeta de estado.
 export function stateDir() {
-    if (process.env.ORQUESTADOR_STATE_PATH) {
-        return process.env.ORQUESTADOR_STATE_PATH;
-    }
+    const propia = leerVariable("STATE_PATH").valor;
+    if (propia)
+        return path.resolve(propia);
     const home = os.homedir();
     if (process.platform === "win32") {
         const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");

package/build/confirmacion.d.ts

@@ -0,0 +1,15 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import type { ServerNotification, ServerRequest } from "@modelcontextprotocol/sdk/types.js";
+export type Confirmacion = "confirmada" | "rechazada" | "no-disponible";
+export type ResultadoConfirmacion = {
+    estado: Confirmacion;
+    nota?: string;
+};
+export declare const ESPERA_POR_DEFECTO_MS = 180000;
+export declare function fijarEsperaDeConfirmacion(ms: number | null): void;
+export declare function pedirConfirmacion(mcp: McpServer, extra: RequestHandlerExtra<ServerRequest, ServerNotification>, pregunta: {
+    mensaje: string;
+    etiqueta: string;
+}): Promise<ResultadoConfirmacion>;
+//# sourceMappingURL=confirmacion.d.ts.map

package/build/confirmacion.js

@@ -0,0 +1,100 @@
+// Confirmaciones pedidas directamente a la persona, por elicitation de MCP.
+//
+// Hasta ahora, reescribir un documento protegido o estrenar un proyecto dependía de una bandera
+// (`force`, `crear_proyecto`) que pone el modelo cuando "el usuario lo confirmó en el chat". Es
+// justo lo que se quiere evitar: la bandera la escribe quien no debe decidir. Con elicitation, el
+// servidor le pregunta a la persona en un formulario de su cliente, y la respuesta no pasa por el
+// modelo.
+//
+// Si el cliente no lo soporta, o lo anuncia pero no lo muestra, se vuelve al comportamiento
+// anterior: deciden las banderas. Una persona que dice que no, o que cierra el formulario, nunca
+// se convierte en un sí.
+import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { leerVariable } from "./config.js";
+import { log } from "./log.js";
+// El SDK espera un minuto por defecto a que el cliente responda; para que una persona lea y
+// decida es poco. Los tests lo acortan.
+export const ESPERA_POR_DEFECTO_MS = 180_000;
+let esperaMs = ESPERA_POR_DEFECTO_MS;
+export function fijarEsperaDeConfirmacion(ms) {
+    esperaMs = ms ?? ESPERA_POR_DEFECTO_MS;
+}
+const sesiones = new WeakMap();
+function sesionDe(mcp) {
+    let sesion = sesiones.get(mcp);
+    if (!sesion) {
+        sesion = { noDisponible: false, vencimientosSeguidos: 0 };
+        sesiones.set(mcp, sesion);
+    }
+    return sesion;
+}
+const NOTA_OFF = "Si tu cliente no te mostró la confirmación, regístralo con PHASE_GATE_ELICITATION=off y la confirmación " +
+    "volverá a pedirse en el chat.";
+const NOTA_SIN_RESPUESTA = "Tu cliente no respondió a dos confirmaciones seguidas, así que esta vez tampoco se escribe nada; durante el " +
+    "resto de la sesión la confirmación vuelve a pedirse en el chat (con force).";
+const NOTA_CANCELADA = "El cliente canceló la llamada antes de que el usuario respondiera.";
+// Valores de PHASE_GATE_ELICITATION que apagan las confirmaciones directas.
+const APAGADO = new Set(["off", "false", "0", "no"]);
+const NOTA_NO_IMPLEMENTA = "Tu cliente anuncia confirmaciones directas pero no las implementa: durante el resto de la sesión la " +
+    "confirmación vuelve a pedirse en el chat (con force).";
+export async function pedirConfirmacion(mcp, extra, pregunta) {
+    // La escotilla para un cliente cuya implementación falle.
+    if (APAGADO.has(leerVariable("ELICITATION").valor?.toLowerCase() ?? ""))
+        return { estado: "no-disponible" };
+    if (!mcp.server.getClientCapabilities()?.elicitation?.form)
+        return { estado: "no-disponible" };
+    const sesion = sesionDe(mcp);
+    if (sesion.noDisponible)
+        return { estado: "no-disponible" };
+    try {
+        const respuesta = await mcp.server.elicitInput({
+            mode: "form",
+            message: pregunta.mensaje,
+            requestedSchema: {
+                type: "object",
+                properties: {
+                    confirmar: {
+                        type: "boolean",
+                        title: pregunta.etiqueta,
+                        description: "Marca la casilla y acepta para confirmar.",
+                        default: false,
+                    },
+                },
+                required: ["confirmar"],
+            },
+        }, 
+        // Con la señal de la llamada: si el cliente cancela la tool (por su propio plazo, o porque la
+        // persona la detuvo), la pregunta se cancela también y no se escribe nada a sus espaldas.
+        { timeout: esperaMs, relatedRequestId: extra.requestId, signal: extra.signal });
+        sesion.vencimientosSeguidos = 0;
+        return { estado: respuesta.action === "accept" && respuesta.content?.confirmar === true ? "confirmada" : "rechazada" };
+    }
+    catch (error) {
+        const mensaje = error instanceof Error ? error.message : String(error);
+        // Una cancelación del cliente no dice nada de si muestra o no el formulario: no cuenta como
+        // vencimiento ni cambia la sesión.
+        if (extra.signal.aborted)
+            return { estado: "rechazada", nota: NOTA_CANCELADA };
+        if (error instanceof McpError && error.code === ErrorCode.RequestTimeout) {
+            sesion.vencimientosSeguidos++;
+            if (sesion.vencimientosSeguidos >= 2) {
+                // Desde la siguiente llamada decide force; ESTA falla cerrada. Si no, una persona ausente
+                // dos veces más un force puesto por el modelo acabarían escribiendo sin que nadie confirmara.
+                sesion.noDisponible = true;
+                log("warning", "El cliente dejó vencer dos confirmaciones seguidas; se desactivan para el resto de la sesión.");
+                return { estado: "rechazada", nota: NOTA_SIN_RESPUESTA };
+            }
+            return { estado: "rechazada", nota: NOTA_OFF };
+        }
+        sesion.vencimientosSeguidos = 0;
+        if ((error instanceof McpError && error.code === ErrorCode.MethodNotFound) || /does not support/i.test(mensaje)) {
+            sesion.noDisponible = true;
+            log("warning", `El cliente anuncia elicitation pero no la implementa (${mensaje}); se desactiva para la sesión.`);
+            return { estado: "no-disponible", nota: NOTA_NO_IMPLEMENTA };
+        }
+        // Ante lo desconocido se falla cerrado: no se escribe nada y la persona puede repetirlo.
+        log("warning", `La confirmación falló y se trata como un no: ${mensaje}`);
+        return { estado: "rechazada" };
+    }
+}
+//# sourceMappingURL=confirmacion.js.map

package/build/diagnostico.d.ts

@@ -0,0 +1,83 @@
+import type { LecturaVariable } from "./config.js";
+import type { PhaseFile } from "./phases.js";
+export type Severidad = "error" | "aviso" | "info";
+export type Hallazgo = {
+    severidad: Severidad;
+    codigo: string;
+    texto: string;
+};
+export type EstadoRuta = {
+    ruta?: string;
+    existe: boolean;
+    error?: string;
+};
+export type EtiquetaCapa = "fábrica" | "propia";
+export type Via = "npx" | "global" | "dependencia" | "clon";
+export type Diagnostico = {
+    paquete: {
+        version: string;
+        ruta: string;
+        via: Via;
+    };
+    node: {
+        version: string;
+        plataforma: NodeJS.Platform;
+    };
+    variables: LecturaVariable[];
+    rutas: {
+        docs: EstadoRuta;
+        repos: EstadoRuta;
+    };
+    estado: {
+        archivo: string;
+        existe: boolean;
+        punteros: number;
+    };
+    capas: {
+        ruta: string;
+        etiqueta: EtiquetaCapa;
+        existe: boolean;
+    }[];
+    reglasGlobales: {
+        archivo: string | null;
+        capa: string | null;
+        faltan: string[];
+    };
+    fases: {
+        numero: number;
+        titulo: string;
+        archivo: string;
+        capa: string;
+        documento?: string;
+        recibos?: string;
+        comando: string | null;
+    }[];
+    proyectos: {
+        nombre: string;
+        tareas: number;
+        activa: {
+            tarea: string;
+            origen: "puntero" | "deducida";
+            fase: string;
+        } | null;
+    }[];
+    cliente?: {
+        nombre: string;
+        version: string;
+        capacidades: {
+            elicitation: boolean;
+            roots: boolean;
+        };
+    };
+    hallazgos: Hallazgo[];
+};
+export declare const SECCIONES_GLOBALES: string[];
+export declare function deducirVia(ruta: string, entorno?: NodeJS.ProcessEnv): Via;
+export declare function capasDePrompts(): Diagnostico["capas"];
+export declare function capaDeArchivo(archivo: string, capas: Diagnostico["capas"]): EtiquetaCapa | null;
+export declare function fasesConCapa(capas?: Diagnostico["capas"], phases?: Map<number, PhaseFile>): Diagnostico["fases"];
+export declare function diagnosticar(opciones?: {
+    cliente?: Diagnostico["cliente"];
+}): Diagnostico;
+export declare function formatearDiagnostico(d: Diagnostico, formato: "texto" | "markdown"): string;
+//# sourceMappingURL=diagnostico.d.ts.map