orquestra-mcp 1.72.0 → 1.74.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orquestra-mcp",
-  "version": "1.72.0",
+  "version": "1.74.0",
   "description": "Servidor MCP de Orquestra -- 161 tools para leer y escribir tareas, ideas, changelog, infraestructura, contenido, QA y más desde un agente de IA",
   "type": "module",
   "bin": {

package/src/api.mjs

@@ -115,9 +115,9 @@ export async function apiDeletePath(config, path, { projectId, ...query }) {
 // es la autorización completa. Plazo más largo (sube bytes); un PUT a la
 // misma key es idempotente, pero igual no se reintenta para no duplicar
 // tiempos largos de subida.
-export async function putToPresignedUrl(uploadUrl, buffer, contentType) {
+export async function putToPresignedUrl(uploadUrl, buffer, contentType, headers) {
   try {
-    await request(uploadUrl, { method: 'PUT', headers: { 'Content-Type': contentType }, body: buffer }, { timeoutMs: 120_000, retries: 0 })
+    await request(uploadUrl, { method: 'PUT', headers: { 'Content-Type': contentType, ...(headers || {}) }, body: buffer }, { timeoutMs: 120_000, retries: 0 })
   } catch (err) {
     throw new Error(`Falló la subida a S3: ${err.status ? `HTTP ${err.status}` : err.message}`)
   }

package/src/server.mjs

@@ -3019,6 +3019,14 @@ export function createServer() {
       blocks: navBlocksSchema.optional(),
       actions: navActionsSchema.optional(),
       states: navStatesSchema.optional(),
+      screenshots: z.array(z.object({
+        key: z.string().describe('Key de S3 (de add_design_screenshot)'),
+        caption: z.string().max(200).optional(),
+        state: z.string().optional().describe('Estado que muestra'),
+        width: z.number().int().positive().optional(),
+        height: z.number().int().positive().optional(),
+        takenAt: z.number().optional().describe('ms epoch'),
+      })).max(12).optional().describe('Capturas (máx. 12); usa add_design_screenshot. PATCH reemplaza la lista'),
       sourceRef: z.string().optional().describe('Dónde vive en el código, ej: archivo y símbolo'),
     }
     if (optional) { f.name = f.name.optional(); f.platform = f.platform.optional(); f.kind = f.kind.optional() }
@@ -3092,7 +3100,7 @@ export function createServer() {
     }
   )
 
-  const { parentId: _navParentId, ...navBulkBase } = navNodeFields(false)
+  const { parentId: _navParentId, screenshots: _navShots, ...navBulkBase } = navNodeFields(false) // capturas: solo con add/remove_design_screenshot
   server.registerTool(
     'upsert_design_nav',
     {
@@ -3115,6 +3123,76 @@ export function createServer() {
     }
   )
 
+  // ═══ CAPTURAS POR PANTALLA (ORQ-573) ═══════════════════════════════════════
+  const SHOT_MIME_BY_EXT = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp' }
+  const SHOT_MAX_BYTES = 5 * 1024 * 1024
+  const SHOT_NOTE = 'Las capturas son INTERNAS del equipo (se guardan en un bucket privado y se ven con URL firmada de 1 h). No uses capturas del workspace real si van a usarse en marketing o videos: arma un usuario demo.'
+  const findNavNode = async (pid, platform, key) => {
+    const list = await apiGet(config, '/v1/design-nav', { projectId: pid, platform })
+    const node = (list.items || []).find(n => n.key === key)
+    if (!node) throw new Error(`No hay un nodo con key "${key}" en ${platform}; revisa list_design_nav o créalo con upsert_design_nav`)
+    return node
+  }
+  server.registerTool(
+    'add_design_screenshot',
+    {
+      description: `Sube una captura de pantalla (imagen local png/jpg/webp, máx. 5 MB) y la agrega al nodo de navegación de diseño (platform + key) para ver cómo se ve esa pantalla en cada plataforma y compararlas lado a lado. Valida extensión y tamaño ANTES de subir, pide la URL firmada, hace el PUT a S3 y guarda la clave en el nodo MEZCLANDO por key (no pisa las otras capturas; máx. 12 por nodo). "state" marca qué estado muestra (empty, loading, error...). ${SHOT_NOTE} Devuelve { key, name, screenshots }.`,
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        platform: z.enum(NAV_PLATFORMS).describe('Plataforma del nodo: web | ios | android'),
+        key: z.string().describe('Key del nodo de navegación (ej: "tasks", "settings.general")'),
+        filePath: z.string().describe('Ruta local a la imagen (png/jpg/jpeg/webp, máx. 5 MB)'),
+        caption: z.string().max(200).optional().describe('Pie de la captura (máx. 200)'),
+        state: z.string().optional().describe('Estado que muestra, ej: empty, loading, error'),
+      },
+    },
+    async ({ projectId, platform, key, filePath, caption, state }) => {
+      try {
+        const pid = resolveProjectId(projectId)
+        const ext = path.extname(filePath).slice(1).toLowerCase()
+        const mime = SHOT_MIME_BY_EXT[ext]
+        if (!mime) throw new Error('Solo imágenes png, jpg/jpeg o webp')
+        const stat = statSync(filePath)
+        if (!stat.isFile()) throw new Error('filePath no es un archivo')
+        if (stat.size > SHOT_MAX_BYTES) throw new Error(`La imagen pesa ${(stat.size / 1048576).toFixed(1)} MB; el máximo es 5 MB`)
+        const node = await findNavNode(pid, platform, key)
+        const name = path.basename(filePath)
+        const { uploadUrl, key: shotKey, headers } = await apiPost(config, '/v1/design-assets/presign', { projectId: pid, nodeId: node.id, filename: name, contentType: mime, size: stat.size })
+        await putToPresignedUrl(uploadUrl, readFileSync(filePath), mime, headers)
+        const shot = { key: shotKey, takenAt: Date.now(), ...(caption ? { caption } : {}), ...(state ? { state } : {}) }
+        const res = await apiPost(config, '/v1/design-nav/bulk', { projectId: pid, compact: false, nodes: [{ platform, kind: node.kind, name: node.name, key, screenshots: [shot] }] })
+        const updated = res.items?.[0]
+        return textResult({ key: shotKey, name, nodeId: node.id, screenshots: updated?.screenshots ?? [shot] })
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+  server.registerTool(
+    'remove_design_screenshot',
+    {
+      description: `Quita una captura de un nodo de navegación de diseño (platform + key del nodo + screenshotKey de la captura, la que devolvió add_design_screenshot o list_design_nav). La API también intenta borrar el archivo de S3. ${SHOT_NOTE}`,
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        platform: z.enum(NAV_PLATFORMS).describe('Plataforma del nodo: web | ios | android'),
+        key: z.string().describe('Key del nodo de navegación'),
+        screenshotKey: z.string().describe('Key de S3 de la captura a quitar'),
+      },
+    },
+    async ({ projectId, platform, key, screenshotKey }) => {
+      try {
+        const pid = resolveProjectId(projectId)
+        const node = await findNavNode(pid, platform, key)
+        const current = node.screenshots || []
+        if (!current.some(s => s.key === screenshotKey)) throw new Error(`El nodo "${key}" no tiene una captura con key "${screenshotKey}"`)
+        const data = await apiPatch(config, '/v1/design-nav', { projectId: pid, id: node.id, screenshots: current.filter(s => s.key !== screenshotKey) })
+        return textResult({ removed: screenshotKey, nodeId: node.id, screenshots: data.screenshots ?? [] })
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
   // ═══ COMPONENTES DE DISEÑO (ORQ-562) ═══════════════════════════════════════
   const COMP_PLATFORMS = ['web', 'ios', 'android']
   const COMP_PURPOSE = 'Cataloga los componentes de UI del proyecto (botones, tarjetas, modales, campos...) con sus variantes, estados y en qué plataformas existen, para comparar paridad entre web, iOS y Android. `tokens` enlaza con los nombres de las tools de design tokens (list_design_tokens) y `usedIn` con las keys de nodos de navegación (list_design_nav).'
@@ -3223,7 +3301,7 @@ export function createServer() {
   server.registerTool(
     'set_design_parity_cell',
     {
-      description: 'Fija a mano una celda de la matriz de paridad de diseño (get_design_parity): el override manual gana sobre el cálculo automático. Úsala para marcar not_applicable (la pantalla no existe en esa plataforma a propósito), corregir un estado, dejar una nota o enlazar la tarea hermana que cierra el hueco (taskId = folio, ej. ORQ-123). Con status:null quita el override y la celda vuelve al cálculo automático.',
+      description: 'Fija a mano una celda de la matriz de paridad de diseño (get_design_parity): el override manual gana sobre el cálculo automático. Úsala para marcar not_applicable (la pantalla no existe en esa plataforma a propósito), corregir un estado, dejar una nota o enlazar la tarea hermana que cierra el hueco (taskId = folio, ej. ORQ-123). Con status:null y SIN note ni taskId quita el override y la celda vuelve al cálculo automático; con status:null y note o taskId conserva la nota y el folio sin fijar estado manual (la celda sigue automática). Regla: fijar status:"not_applicable" EXIGE un `reason` (motivo) no vacío; para los demás estados es opcional. `adr` enlaza la celda a un doc del proyecto (normalmente un ADR que documenta la decisión): pásale el id del doc (obtenlo con search types=["doc"] o listando los docs); "" lo quita. get_design_parity devuelve en la celda reason y decision {docId,title,type}.',
       inputSchema: {
         projectId: z.string().optional().describe(PROJECT_ID_DESC),
         key: z.string().min(1).describe('Key de la fila (ver get_design_parity)'),
@@ -3231,11 +3309,142 @@ export function createServer() {
         status: z.enum(['same', 'different', 'missing', 'not_applicable']).nullable().describe('Estado manual; null = quitar el override'),
         note: z.string().optional().describe('Nota de la celda'),
         taskId: z.string().optional().describe('Folio de la tarea que cierra el hueco, ej: ORQ-123'),
+        reason: z.string().max(500).optional().describe('Motivo de la decisión (máx. 500). Obligatorio al fijar status not_applicable'),
+        adr: z.string().max(60).optional().describe('Id del doc (ADR) que documenta la decisión; se envía como docId. "" lo quita'),
+      },
+    },
+    async ({ projectId, key, platform, status, note, taskId, reason, adr }) => {
+      try {
+        if (status === 'not_applicable' && !(reason && reason.trim())) {
+          return errorResult(new Error('motivo obligatorio al fijar No aplica: pasa reason con el porqué (y opcionalmente adr con el id del doc)'))
+        }
+        return textResult(await apiPut(config, '/v1/design-parity/cell', { projectId: resolveProjectId(projectId), key, platform, status, note, taskId, reason, docId: adr }))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  server.registerTool(
+    'create_parity_tasks',
+    {
+      description: 'Convierte huecos de la paridad de diseño en tareas. Flujo: primero get_design_parity con soloHuecos:true para ver los huecos (gaps); luego create_parity_tasks con las celdas {key, platform} que quieras cerrar. Crea UNA tarea por celda, con scope de esa plataforma y el detalle de la diferencia contra la plataforma de referencia (ref, default web; threshold para el umbral de similitud). No duplica: si la celda ya tiene folio la omite (aparece en skipped con su reason) salvo force:true; el folio nuevo se guarda en la celda. La tarea exige módulo y fecha: si no pasas moduleId/dueDate se resuelven solos (módulo de la plataforma, hoy + 14 días); priority es opcional. Responde { created: [{key,platform,taskId,id}], skipped: [{key,platform,reason}], warnings }. No la uses para cientos de celdas a la vez: máximo 50 por llamada.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        cells: z.array(z.object({
+          key: z.string().min(1).describe('Key de la fila (ver get_design_parity)'),
+          platform: z.enum(PARITY_PLATFORMS).describe('Plataforma de la celda: web | ios | android'),
+        })).min(1).max(50).describe('Celdas a convertir en tarea (1 a 50)'),
+        ref: z.enum(PARITY_PLATFORMS).optional().describe('Plataforma de referencia: web | ios | android (default web)'),
+        threshold: z.number().min(0).max(1).optional().describe('Umbral de similitud de bloques (0..1, default 0.6)'),
+        moduleId: z.string().optional().describe('Módulo de las tareas; si falta se usa el de la plataforma'),
+        dueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Formato YYYY-MM-DD').optional().describe('Fecha límite YYYY-MM-DD; si falta, hoy + 14 días'),
+        priority: z.enum(['high', 'medium', 'low']).optional().describe('Prioridad de las tareas'),
+        force: z.boolean().optional().describe('true = crea la tarea aunque la celda ya tenga folio'),
+      },
+    },
+    async ({ projectId, cells, ref, threshold, moduleId, dueDate, priority, force }) => {
+      try {
+        return textResult(await apiPost(config, '/v1/design-parity/tasks', { projectId: resolveProjectId(projectId), cells, ref, threshold, moduleId, dueDate, priority, force }))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  // ═══ DERIVA DE TOKENS (ORQ-574) ═══════════════════════════════════════════
+  const DRIFT_KINDS = ['color', 'radius', 'spacing', 'typography', 'shadow']
+  const DRIFT_STATUSES = ['open', 'ignored', 'fixed']
+  const DRIFT_FLOW = 'Detector de deriva de tokens: valores de diseño (colores hex, radios, spacings, fuentes, sombras) escritos a mano en el código de una plataforma FUERA de la definición de tokens. FLUJO: 1) list_design_tokens para conocer los tokens de la plataforma; 2) recorre el código de UNA plataforma (web, ios o android) buscando colores hex, radios, spacings y fuentes escritos a mano; 3) compara cada valor con los tokens de esa MISMA plataforma y, si coincide, propón suggestedToken con el name del token; 4) reporta en lote con report_design_drift (hasta 200 por llamada; guarda la hora de inicio de la pasada, Date.now()); 5) al terminar una pasada COMPLETA de esa plataforma, llama a resolve_missing_design_drift en dryRun (platform + reportedBefore = hora de inicio de la pasada) para ver qué hallazgos abiertos ya no aparecen y, si es correcto, repítela con dryRun:false (se marcan fixed). NO es deriva: el archivo donde se DEFINEN los tokens (theme, tokens.css, Colors.swift, Color.kt, variables.css...), tests y fixtures, previews/storybook/SwiftUI previews, código generado, node_modules/build, ni valores dinámicos (calculados por el usuario o datos).'
+  const driftItemSchema = z.object({
+    platform: z.enum(PARITY_PLATFORMS).describe('Plataforma donde está el código: web | ios | android'),
+    file: z.string().min(1).max(300).describe('Ruta RELATIVA al repo de la plataforma, ej: src/pages/Tasks.jsx'),
+    line: z.number().int().min(1).optional().describe('Línea (>= 1); parte de la identidad del hallazgo'),
+    kind: z.enum(DRIFT_KINDS).describe('color | radius | spacing | typography | shadow'),
+    value: z.string().min(1).max(120).describe('Valor escrito a mano tal cual, ej: "#2F7A55", "13dp", "12px"'),
+    context: z.string().max(200).optional().describe('Símbolo o línea de código donde aparece (≤200)'),
+    suggestedToken: z.string().max(80).optional().describe('name de un design token EXISTENTE de esa plataforma que lo reemplazaría (≤80); si no existe la API avisa en warnings'),
+    note: z.string().max(300).optional().describe('Nota (≤300), solo se guarda al crear'),
+    reopen: z.boolean().optional().describe('true = reabre este hallazgo si estaba ignored o fixed (por default un reporte repetido NO los reabre)'),
+  })
+
+  server.registerTool(
+    'report_design_drift',
+    {
+      description: `Reporta en lote (1 a 200) hallazgos de deriva de tokens. ${DRIFT_FLOW} Cada hallazgo se identifica por (platform, file, line, value): reportar de nuevo uno existente solo refresca seenAt, suggestedToken y context y NO reabre los ignorados o corregidos (salvo reopen:true). Responde { created, updated, reopened, items (resumidos por default), warnings } donde warnings avisa de suggestedToken que no existe en los tokens. Valida todo el lote antes de escribir.`,
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        compact: z.boolean().optional().describe('true (default) = items resumidos {id,platform,file,line?,value,status,action}; false = filas completas'),
+        items: z.array(driftItemSchema).min(1).max(200).describe('Hallazgos a reportar (1-200)'),
+      },
+    },
+    async ({ projectId, items, compact }) => {
+      try {
+        return textResult(await apiPost(config, '/v1/design-drift/bulk', { projectId: resolveProjectId(projectId), items, compact: compact ?? true }))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  server.registerTool(
+    'list_design_drift',
+    {
+      description: 'Lista los hallazgos de deriva de tokens (valores de diseño escritos a mano que deberían ser un token), ordenados por archivo y línea, con filtros por plataforma, tipo y estado. Responde { items, summary: { open, ignored, fixed, byPlatform: { web, ios, android } } }; el summary es de todo el proyecto, no depende de los filtros. Úsala para ver qué falta migrar a tokens, antes de reportar de nuevo (no repitas lo ya ignorado) o para armar tareas de limpieza. Se llena con report_design_drift; si viene vacía, nadie ha recorrido el código todavía.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        platform: z.enum(PARITY_PLATFORMS).optional().describe('Filtra por plataforma'),
+        kind: z.enum(DRIFT_KINDS).optional().describe('Filtra por tipo'),
+        status: z.enum(DRIFT_STATUSES).optional().describe('Filtra por estado: open | ignored | fixed'),
+      },
+    },
+    async ({ projectId, platform, kind, status }) => {
+      try {
+        return textResult(await apiGet(config, '/v1/design-drift', { projectId: resolveProjectId(projectId), platform, kind, status }))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  server.registerTool(
+    'update_design_drift',
+    {
+      description: 'Cambia el estado de un hallazgo de deriva (list_design_drift): ignored (es intencional o no aplica: un preview, un valor dinámico; ponle una nota con el motivo), fixed (ya se migró a un token) u open (reabrir). También puede ajustar la nota y el suggestedToken. Un hallazgo ignorado o corregido NO se reabre solo cuando se vuelve a reportar. Para marcar como corregidos los que ya no aparecen tras una pasada completa usa resolve_missing_design_drift, no esta tool en bucle.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        driftId: z.string().describe('ID del hallazgo (ver list_design_drift)'),
+        status: z.enum(DRIFT_STATUSES).optional().describe('open | ignored | fixed'),
+        note: z.string().max(300).optional().describe('Nota (≤300), ej. el motivo de ignorarlo'),
+        suggestedToken: z.string().max(80).optional().describe('name del token que lo reemplazaría (≤80)'),
+      },
+    },
+    async ({ projectId, driftId, status, note, suggestedToken }) => {
+      if (status === undefined && note === undefined && suggestedToken === undefined) {
+        return errorResult(new Error('Nada que actualizar: manda status, note o suggestedToken'))
+      }
+      try {
+        return textResult(await apiPatch(config, '/v1/design-drift', { projectId: resolveProjectId(projectId), id: driftId, status, note, suggestedToken }))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  server.registerTool(
+    'resolve_missing_design_drift',
+    {
+      description: 'Cierre de una pasada COMPLETA de deriva sobre una plataforma: marca como fixed los hallazgos OPEN de esa plataforma que no se vieron desde reportedBefore (porque la pasada ya no los encontró en el código). Úsala solo si recorriste TODA la plataforma; con una pasada parcial marcarías como corregido lo que simplemente no revisaste. reportedBefore = hora de inicio de la pasada en ms epoch (Date.now() guardado ANTES de empezar a reportar). dryRun es true por default: solo informa { dryRun, platform, reportedBefore, count, items } sin escribir; revisa la lista y repite con dryRun:false para aplicar. No toca los ignorados ni los ya corregidos.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        platform: z.enum(PARITY_PLATFORMS).describe('Plataforma de la pasada: web | ios | android'),
+        reportedBefore: z.number().int().positive().describe('ms epoch: se marcan los open con seenAt anterior a este valor'),
+        dryRun: z.boolean().optional().describe('true (default) = solo informa; false = marca fixed'),
       },
     },
-    async ({ projectId, key, platform, status, note, taskId }) => {
+    async ({ projectId, platform, reportedBefore, dryRun }) => {
       try {
-        return textResult(await apiPut(config, '/v1/design-parity/cell', { projectId: resolveProjectId(projectId), key, platform, status, note, taskId }))
+        return textResult(await apiPost(config, '/v1/design-drift/resolve-missing', { projectId: resolveProjectId(projectId), platform, reportedBefore, dryRun: dryRun ?? true }))
       } catch (err) {
         return errorResult(err)
       }