trackfw 1.0.3 → 1.1.0

package/src/i18n/locales/es-ES.json

@@ -0,0 +1,122 @@
+{
+  "init": {
+    "description": "Inicializa la gobernanza trackfw en el proyecto actual",
+    "prompt": {
+      "projectName": "¿Nombre del proyecto?",
+      "projectType": "¿Tipo de proyecto?",
+      "frontendStack": "¿Stack de frontend?",
+      "pkgManager": "¿Gestor de paquetes?",
+      "backendLang": "¿Lenguaje de backend?",
+      "backendFramework": "¿Framework de backend?",
+      "gitHooks": "¿Git hooks?",
+      "ci": "¿Sistema de CI?",
+      "aiTools": "¿Qué asistentes de IA usas?",
+      "projectType_fullstack": "Full-stack (frontend + backend)",
+      "projectType_frontend": "Solo frontend",
+      "projectType_backend": "Solo backend",
+      "projectType_governance": "Solo gobernanza (sin stack de build)"
+    },
+    "success": "✓ trackfw inicializado — ejecuta 'trackfw status' para ver el estado de gobernanza."
+  },
+  "adr": {
+    "description": "Gestionar Architecture Decision Records",
+    "new": {
+      "description": "Crear un nuevo Architecture Decision Record",
+      "prompt": {
+        "title": "¿Título del ADR?",
+        "status": "¿Estado inicial?",
+        "context": "¿Contexto (qué motiva esta decisión)?",
+        "decision": "¿Decisión (qué fue decidido)?",
+        "consequences": "¿Consecuencias (positivas y negativas)?",
+        "alternatives": "¿Alternativas consideradas?"
+      },
+      "created": "✓ ADR creado: {{path}}"
+    },
+    "list": {
+      "description": "Listar todos los ADRs con estado",
+      "empty": "No se encontraron ADRs en docs/adr/"
+    }
+  },
+  "req": {
+    "description": "Gestionar Requisitos",
+    "new": {
+      "description": "Crear un nuevo requisito",
+      "prompt": {
+        "title": "Requisito del proyecto",
+        "motivation": "¿Motivación (por qué lo necesitamos)?",
+        "criteria": "Criterios de aceptación (uno por línea)",
+        "domainQuestion_authentication": "¿Cómo se autenticarán los usuarios?",
+        "domainQuestion_ui": "¿Existe un framework de UI o design system ya elegido?",
+        "domainQuestion_persistence": "¿Qué motor de base de datos se usará?",
+        "domainQuestion_api": "¿Qué protocolo de API se usará?",
+        "domainQuestion_deploy": "¿Cuál es el destino de despliegue?",
+        "domainQuestion_events": "¿Qué message broker se usará?"
+      },
+      "detectedDomains": "Dominios detectados: {{domains}}",
+      "created": "✓ REQ creado: {{path}}",
+      "adrDraftsCreated": "ADR borradores creados:",
+      "resolveADRs": "Resuelve estos ADRs (establece Status: Accepted) antes de crear un roadmap.",
+      "adrWarning": "advertencia: no se pudo crear ADR borrador para {{slug}}: {{message}}"
+    },
+    "list": {
+      "description": "Listar todos los REQs con estado",
+      "empty": "No se encontraron REQs en docs/req/"
+    }
+  },
+  "roadmap": {
+    "description": "Gestionar Roadmaps",
+    "list": {
+      "description": "Listar todos los roadmaps agrupados por estado",
+      "empty": "No se encontraron roadmaps."
+    },
+    "show": {
+      "description": "Mostrar roadmap por nombre (coincidencia parcial)",
+      "notFound": "Roadmap no encontrado: {{name}}"
+    },
+    "move": {
+      "description": "Mover un roadmap entre estados (backlog|wip|blocked|done|abandoned)",
+      "success": "✓ Movido {{name}} → {{state}}",
+      "notFound": "Roadmap no encontrado: {{name}}"
+    },
+    "new": {
+      "description": "Crear un nuevo roadmap desde un REQ",
+      "created": "✓ Roadmap creado: {{path}}"
+    }
+  },
+  "validate": {
+    "description": "Validar reglas de gobernanza (úsalo como gate de CI)",
+    "ok": "✓ No se encontraron violaciones.",
+    "violations": "✗ Violaciones ({{count}}):",
+    "warnings": "⚠ Avisos ({{count}}):"
+  },
+  "status": {
+    "description": "Mostrar el estado actual de gobernanza del proyecto"
+  },
+  "log": {
+    "description": "Mostrar historial de transiciones de estado de los roadmaps",
+    "empty": "Aún no hay transiciones registradas.",
+    "tail": "Número de transiciones recientes a mostrar",
+    "header": "── trackfw log ─────────────────────────"
+  },
+  "plugins": {
+    "description": "Gestionar plugins de trackfw",
+    "list": {
+      "description": "Listar plugins instalados",
+      "empty": "No hay plugins instalados. Usa `trackfw plugins add <user/repo>` para instalar uno."
+    },
+    "add": {
+      "description": "Instalar un plugin desde GitHub Releases (user/repo o user/repo@tag)",
+      "installing": "Instalando plugin desde {{repo}}...",
+      "success": "Plugin \"{{name}}\" instalado correctamente."
+    },
+    "remove": {
+      "description": "Eliminar un plugin instalado",
+      "success": "Plugin \"{{name}}\" eliminado."
+    }
+  },
+  "errors": {
+    "notFound": "No encontrado: {{path}}",
+    "downloadFailed": "fallo en la descarga: HTTP {{status}} para {{url}}",
+    "pluginNotFound": "plugin \"{{name}}\" no encontrado"
+  }
+}

package/src/i18n/locales/pt-BR.json

@@ -0,0 +1,122 @@
+{
+  "init": {
+    "description": "Inicializa a governança trackfw no projeto atual",
+    "prompt": {
+      "projectName": "Nome do projeto?",
+      "projectType": "Tipo de projeto?",
+      "frontendStack": "Stack de frontend?",
+      "pkgManager": "Gerenciador de pacotes?",
+      "backendLang": "Linguagem de backend?",
+      "backendFramework": "Framework de backend?",
+      "gitHooks": "Git hooks?",
+      "ci": "Sistema de CI?",
+      "aiTools": "Quais assistentes de IA você usa?",
+      "projectType_fullstack": "Full-stack (frontend + backend)",
+      "projectType_frontend": "Somente frontend",
+      "projectType_backend": "Somente backend",
+      "projectType_governance": "Somente governança (sem stack de build)"
+    },
+    "success": "✓ trackfw inicializado — execute 'trackfw status' para ver o estado de governança."
+  },
+  "adr": {
+    "description": "Gerenciar Architecture Decision Records",
+    "new": {
+      "description": "Criar um novo Architecture Decision Record",
+      "prompt": {
+        "title": "Título do ADR?",
+        "status": "Status inicial?",
+        "context": "Contexto (o que motiva esta decisão)?",
+        "decision": "Decisão (o que foi decidido)?",
+        "consequences": "Consequências (positivas e negativas)?",
+        "alternatives": "Alternativas consideradas?"
+      },
+      "created": "✓ ADR criado: {{path}}"
+    },
+    "list": {
+      "description": "Listar todos os ADRs com status",
+      "empty": "Nenhum ADR encontrado em docs/adr/"
+    }
+  },
+  "req": {
+    "description": "Gerenciar Requisitos",
+    "new": {
+      "description": "Criar um novo requisito",
+      "prompt": {
+        "title": "Requisito do projeto",
+        "motivation": "Motivação (por que isso é necessário)?",
+        "criteria": "Critérios de aceite (um por linha)",
+        "domainQuestion_authentication": "Como os usuários serão autenticados?",
+        "domainQuestion_ui": "Existe um framework de UI ou design system já escolhido?",
+        "domainQuestion_persistence": "Qual engine de banco de dados será usada?",
+        "domainQuestion_api": "Qual protocolo de API será usado?",
+        "domainQuestion_deploy": "Qual é o destino de deploy?",
+        "domainQuestion_events": "Qual message broker será usado?"
+      },
+      "detectedDomains": "Domínios detectados: {{domains}}",
+      "created": "✓ REQ criado: {{path}}",
+      "adrDraftsCreated": "ADR drafts criados:",
+      "resolveADRs": "Resolva estes ADRs (defina Status: Accepted) antes de criar um roadmap.",
+      "adrWarning": "aviso: não foi possível criar ADR draft para {{slug}}: {{message}}"
+    },
+    "list": {
+      "description": "Listar todos os REQs com status",
+      "empty": "Nenhum REQ encontrado em docs/req/"
+    }
+  },
+  "roadmap": {
+    "description": "Gerenciar Roadmaps",
+    "list": {
+      "description": "Listar todos os roadmaps agrupados por estado",
+      "empty": "Nenhum roadmap encontrado."
+    },
+    "show": {
+      "description": "Exibir roadmap pelo nome (correspondência parcial)",
+      "notFound": "Roadmap não encontrado: {{name}}"
+    },
+    "move": {
+      "description": "Mover um roadmap entre estados (backlog|wip|blocked|done|abandoned)",
+      "success": "✓ Movido {{name}} → {{state}}",
+      "notFound": "Roadmap não encontrado: {{name}}"
+    },
+    "new": {
+      "description": "Criar um novo roadmap a partir de uma REQ",
+      "created": "✓ Roadmap criado: {{path}}"
+    }
+  },
+  "validate": {
+    "description": "Validar regras de governança (use como gate de CI)",
+    "ok": "✓ Nenhuma violação encontrada.",
+    "violations": "✗ Violações ({{count}}):",
+    "warnings": "⚠ Avisos ({{count}}):"
+  },
+  "status": {
+    "description": "Exibir o estado atual de governança do projeto"
+  },
+  "log": {
+    "description": "Exibir histórico de transições de estado dos roadmaps",
+    "empty": "Nenhuma transição registrada ainda.",
+    "tail": "Número de transições recentes a exibir",
+    "header": "── trackfw log ─────────────────────────"
+  },
+  "plugins": {
+    "description": "Gerenciar plugins do trackfw",
+    "list": {
+      "description": "Listar plugins instalados",
+      "empty": "Nenhum plugin instalado. Use `trackfw plugins add <user/repo>` para instalar um."
+    },
+    "add": {
+      "description": "Instalar um plugin do GitHub Releases (user/repo ou user/repo@tag)",
+      "installing": "Instalando plugin de {{repo}}...",
+      "success": "Plugin \"{{name}}\" instalado com sucesso."
+    },
+    "remove": {
+      "description": "Remover um plugin instalado",
+      "success": "Plugin \"{{name}}\" removido."
+    }
+  },
+  "errors": {
+    "notFound": "Não encontrado: {{path}}",
+    "downloadFailed": "falha no download: HTTP {{status}} para {{url}}",
+    "pluginNotFound": "plugin \"{{name}}\" não encontrado"
+  }
+}

package/src/validator/index.js

@@ -0,0 +1,340 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const STALE_WIP_DAYS = 7
+
+// listDir retorna array de nomes de arquivo (não-diretórios) em dir.
+// Retorna [] se o diretório não existir.
+function listDir(dir) {
+  try {
+    return fs.readdirSync(dir).filter(name => {
+      try {
+        return !fs.statSync(path.join(dir, name)).isDirectory()
+      } catch (_) {
+        return false
+      }
+    })
+  } catch (_) {
+    return []
+  }
+}
+
+// parseBlockedADRs extrai basenames de ADRs da seção "## Blocked by ADRs" de um arquivo REQ.
+function parseBlockedADRs(filePath) {
+  let content
+  try {
+    content = fs.readFileSync(filePath, 'utf8')
+  } catch (_) {
+    return []
+  }
+  const lines = content.split('\n')
+  const adrs = []
+  let inSection = false
+  for (const line of lines) {
+    if (line === '## Blocked by ADRs') {
+      inSection = true
+      continue
+    }
+    if (inSection) {
+      if (line.startsWith('## ')) break
+      if (line.startsWith('- ')) {
+        const item = line.slice(2).trim()
+        const parts = item.split(/\s+/)
+        if (parts.length > 0 && parts[0].endsWith('.md')) {
+          adrs.push(parts[0])
+        }
+      }
+    }
+  }
+  return adrs
+}
+
+// adrIsDraft verifica se docs/adr/<basename> contém "Status: Draft".
+function adrIsDraft(basename) {
+  try {
+    const content = fs.readFileSync(path.join('docs', 'adr', basename), 'utf8')
+    return content.includes('Status: Draft')
+  } catch (_) {
+    return false
+  }
+}
+
+// validateWIPHasREQ — roadmaps em docs/roadmaps/wip/ sem "REQ:" no conteúdo → violation
+function validateWIPHasREQ() {
+  const entries = listDir('docs/roadmaps/wip')
+  const violations = []
+  for (const name of entries) {
+    try {
+      const content = fs.readFileSync(path.join('docs/roadmaps/wip', name), 'utf8')
+      if (!content.includes('REQ:') || content.includes('REQ: \n')) {
+        violations.push(`roadmap "${name}" is in wip but has no linked REQ`)
+      }
+    } catch (_) {
+      // ignorar erro de leitura
+    }
+  }
+  return violations
+}
+
+// validateREQsHaveADR — REQs em docs/req/ sem "ADR:" no conteúdo → violation
+function validateREQsHaveADR() {
+  const entries = listDir('docs/req')
+  const violations = []
+  for (const name of entries) {
+    try {
+      const content = fs.readFileSync(path.join('docs/req', name), 'utf8')
+      if (!content.includes('ADR:') || content.includes('ADR: \n')) {
+        violations.push(`req "${name}" has no linked ADR`)
+      }
+    } catch (_) {
+      // ignorar
+    }
+  }
+  return violations
+}
+
+// validateBlockedHasREQ — roadmaps em docs/roadmaps/blocked/ sem "REQ:" → violation
+function validateBlockedHasREQ() {
+  const entries = listDir('docs/roadmaps/blocked')
+  const violations = []
+  for (const name of entries) {
+    try {
+      const content = fs.readFileSync(path.join('docs/roadmaps/blocked', name), 'utf8')
+      if (!content.includes('REQ:') || content.includes('REQ: \n')) {
+        violations.push(`roadmap "${name}" is in blocked but has no linked REQ`)
+      }
+    } catch (_) {
+      // ignorar
+    }
+  }
+  return violations
+}
+
+// validateREQsHaveRoadmap — REQs sem "Roadmap:" → violation
+function validateREQsHaveRoadmap() {
+  const entries = listDir('docs/req')
+  const violations = []
+  for (const name of entries) {
+    try {
+      const content = fs.readFileSync(path.join('docs/req', name), 'utf8')
+      if (!content.includes('Roadmap:') || content.includes('Roadmap: \n')) {
+        violations.push(`req "${name}" has no linked Roadmap`)
+      }
+    } catch (_) {
+      // ignorar
+    }
+  }
+  return violations
+}
+
+// validateADRsAreReferenced — ADRs em docs/adr/ não referenciados em nenhuma REQ → violation
+function validateADRsAreReferenced() {
+  const adrs = listDir('docs/adr')
+  const reqEntries = listDir('docs/req')
+
+  let combined = ''
+  for (const name of reqEntries) {
+    try {
+      combined += fs.readFileSync(path.join('docs/req', name), 'utf8')
+    } catch (_) {
+      // ignorar
+    }
+  }
+
+  const violations = []
+  for (const adr of adrs) {
+    if (!combined.includes(adr)) {
+      violations.push(`adr "${adr}" is not referenced by any REQ`)
+    }
+  }
+  return violations
+}
+
+// validateWIPHasAcceptanceCriteria — roadmaps wip sem bloco de critérios de aceite → violation
+function validateWIPHasAcceptanceCriteria() {
+  const entries = listDir('docs/roadmaps/wip')
+  const violations = []
+  for (const name of entries) {
+    try {
+      const content = fs.readFileSync(path.join('docs/roadmaps/wip', name), 'utf8')
+      const hasBlock =
+        content.includes('## Acceptance Criteria') ||
+        content.includes('## Critérios de Aceite') ||
+        content.includes('acceptance criteria') ||
+        content.includes('Acceptance Criteria:')
+      if (!hasBlock) {
+        violations.push(`roadmap "${name}" is in wip but has no acceptance criteria block`)
+      }
+    } catch (_) {
+      // ignorar
+    }
+  }
+  return violations
+}
+
+// validateSingleWIP — mais de 1 roadmap em wip → warning
+function validateSingleWIP() {
+  const entries = listDir('docs/roadmaps/wip')
+  if (entries.length > 1) {
+    return [`${entries.length} roadmaps in wip/ (recommended: keep only 1 active at a time)`]
+  }
+  return []
+}
+
+// validateStaleWIP — roadmaps wip com mtime >= 7 dias → warning
+function validateStaleWIP() {
+  let files = []
+  try {
+    files = fs.readdirSync('docs/roadmaps/wip')
+      .filter(f => f.endsWith('.md'))
+      .map(f => path.join('docs/roadmaps/wip', f))
+  } catch (_) {
+    return []
+  }
+
+  const warnings = []
+  const now = Date.now()
+  for (const filePath of files) {
+    try {
+      const stat = fs.statSync(filePath)
+      const ageMs = now - stat.mtimeMs
+      const days = Math.floor(ageMs / (1000 * 60 * 60 * 24))
+      if (days >= STALE_WIP_DAYS) {
+        const lastModified = stat.mtime.toISOString().slice(0, 10)
+        const basename = path.basename(filePath)
+        warnings.push(
+          `roadmap/wip/${basename} has been in WIP for ${days} days (last modified ${lastModified})`
+        )
+      }
+    } catch (_) {
+      // ignorar
+    }
+  }
+  return warnings
+}
+
+// validateREQsNotBlockedByDraftADRs — REQs Open com ADRs Draft na seção "## Blocked by ADRs" → violation
+function validateREQsNotBlockedByDraftADRs() {
+  const entries = listDir('docs/req')
+  const violations = []
+  for (const name of entries) {
+    const filePath = path.join('docs/req', name)
+    let content
+    try {
+      content = fs.readFileSync(filePath, 'utf8')
+    } catch (_) {
+      continue
+    }
+    if (!content.includes('Status: Open')) continue
+
+    const blockedADRs = parseBlockedADRs(filePath)
+    for (const adrBasename of blockedADRs) {
+      if (adrIsDraft(adrBasename)) {
+        violations.push(`REQ ${name} is blocked by Draft ADR: ${adrBasename}`)
+      }
+    }
+  }
+  return violations
+}
+
+// blockedREQs retorna mapa de reqBasename → [adrBasenames Draft] para uso em getStatus()
+function blockedREQs() {
+  const entries = listDir('docs/req')
+  const result = {}
+  for (const name of entries) {
+    const filePath = path.join('docs/req', name)
+    let content
+    try {
+      content = fs.readFileSync(filePath, 'utf8')
+    } catch (_) {
+      continue
+    }
+    if (!content.includes('Status: Open')) continue
+
+    const adrNames = parseBlockedADRs(filePath)
+    const draftADRs = adrNames.filter(a => adrIsDraft(a))
+    if (draftADRs.length > 0) {
+      result[name] = draftADRs
+    }
+  }
+  return result
+}
+
+// validate executa todas as validações e retorna { violations, warnings }
+async function validate() {
+  const violations = [
+    ...validateWIPHasREQ(),
+    ...validateREQsHaveADR(),
+    ...validateBlockedHasREQ(),
+    ...validateREQsHaveRoadmap(),
+    ...validateADRsAreReferenced(),
+    ...validateWIPHasAcceptanceCriteria(),
+    ...validateREQsNotBlockedByDraftADRs(),
+  ]
+  const warnings = [
+    ...validateSingleWIP(),
+    ...validateStaleWIP(),
+  ]
+  return { violations, warnings }
+}
+
+// getStatus retorna string formatada com o status de governança do projeto
+async function getStatus() {
+  const wip = listDir('docs/roadmaps/wip')
+  const blocked = listDir('docs/roadmaps/blocked')
+  const done = listDir('docs/roadmaps/done')
+
+  let out = ''
+  out += '── trackfw status ──────────────────────\n'
+
+  out += `\n🔄 WIP (${wip.length})\n`
+  for (const f of wip) out += `   ${f}\n`
+
+  out += `\n❌ Blocked (${blocked.length})\n`
+  for (const f of blocked) out += `   ${f}\n`
+
+  const staleWIPs = validateStaleWIP()
+  if (staleWIPs.length > 0) {
+    out += `\n⚠  Stale WIP (${staleWIPs.length})\n`
+    for (const w of staleWIPs) out += `   ${w}\n`
+  }
+
+  const blockedByDraft = blockedREQs()
+  const blockedKeys = Object.keys(blockedByDraft)
+  if (blockedKeys.length > 0) {
+    out += `\n⏳ REQs blocked by Draft ADRs (${blockedKeys.length})\n`
+    for (const reqFile of blockedKeys) {
+      out += `   ${reqFile}\n`
+      for (const adr of blockedByDraft[reqFile]) {
+        out += `     → ${adr} (Draft)\n`
+      }
+    }
+  }
+
+  out += `\n✅ Done (last 5)\n`
+  const last5 = done.length > 5 ? done.slice(done.length - 5) : done
+  for (const f of last5) out += `   ${f}\n`
+
+  out += '\n────────────────────────────────────────\n'
+  return out
+}
+
+module.exports = {
+  validate,
+  getStatus,
+  // exportadas para testes unitários
+  validateWIPHasREQ,
+  validateREQsHaveADR,
+  validateBlockedHasREQ,
+  validateREQsHaveRoadmap,
+  validateADRsAreReferenced,
+  validateWIPHasAcceptanceCriteria,
+  validateSingleWIP,
+  validateStaleWIP,
+  validateREQsNotBlockedByDraftADRs,
+  parseBlockedADRs,
+  adrIsDraft,
+  listDir,
+}