trackfw 1.1.0 → 2.1.0

package/src/generators/roadmap.js

@@ -1,40 +1,80 @@
 'use strict'
 const fs = require('fs')
 const path = require('path')
+const config = require('../config')
 
-const VALID_STATES = {
-  backlog:   'docs/roadmaps/backlog',
-  wip:       'docs/roadmaps/wip',
-  blocked:   'docs/roadmaps/blocked',
-  done:      'docs/roadmaps/done',
-  abandoned: 'docs/roadmaps/abandoned',
+const STATE_ORDER = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
+
+// stateDir retorna o caminho do diretório para um estado válido no modo flat, ou null se inválido.
+function stateDir(state) {
+  const cfg = config.load()
+  const valid = ['backlog', 'wip', 'blocked', 'done', 'abandoned']
+  if (!valid.includes(state)) return null
+  return cfg.roadmapDir + '/' + state
 }
 
-const STATE_ORDER = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
+// agentStateDir retorna o diretório para um agente+estado em modo by_agent.
+// agent=null usa o primeiro agente configurado (ou "default" se lista vazia).
+function agentStateDir(agent, state) {
+  const cfg = config.load()
+  const valid = ['backlog', 'wip', 'blocked', 'done', 'abandoned']
+  if (!valid.includes(state)) return null
+  if (!agent) {
+    agent = cfg.agents && cfg.agents.length > 0 ? cfg.agents[0] : 'default'
+  }
+  return cfg.roadmapDir + '/' + agent + '/' + state
+}
 
-const TRANSITION_LOG_PATH = 'docs/roadmaps/.trackfw-log'
+// logPath retorna o caminho do arquivo de log de transições.
+function logPath() {
+  return config.load().roadmapDir + '/.trackfw-log'
+}
 
 /**
- * listRoadmaps — lista roadmaps agrupados por estado (wip, backlog, blocked, done, abandoned).
+ * listRoadmaps — lista roadmaps agrupados por estado (e por agente em modo by_agent).
  * Se nenhum encontrado imprime mensagem orientando o usuário.
  */
 function listRoadmaps() {
+  const cfg = config.load()
   let found = false
 
-  for (const state of STATE_ORDER) {
-    const dir = VALID_STATES[state]
-    let files = []
-    try {
-      files = fs.readdirSync(dir).filter(f => !fs.statSync(path.join(dir, f)).isDirectory() && f.endsWith('.md'))
-    } catch (_) {
-      continue
+  if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
+    let agents = cfg.agents || []
+    if (agents.length === 0) {
+      try {
+        agents = fs.readdirSync(cfg.roadmapDir).filter(f => {
+          try { return fs.statSync(path.join(cfg.roadmapDir, f)).isDirectory() } catch (_) { return false }
+        })
+      } catch (_) { agents = [] }
     }
-    if (files.length === 0) continue
-
-    found = true
-    console.log(`[${state}]`)
-    for (const f of files) {
-      console.log(`  ${f}`)
+    for (const agent of agents) {
+      for (const state of STATE_ORDER) {
+        const dir = cfg.roadmapDir + '/' + agent + '/' + state
+        let files = []
+        try {
+          files = fs.readdirSync(dir).filter(f => {
+            try { return !fs.statSync(path.join(dir, f)).isDirectory() && f.endsWith('.md') } catch (_) { return false }
+          })
+        } catch (_) { continue }
+        if (files.length === 0) continue
+        found = true
+        console.log(`[${agent}/${state}]`)
+        for (const f of files) console.log(`  ${f}`)
+      }
+    }
+  } else {
+    for (const state of STATE_ORDER) {
+      const dir = cfg.roadmapDir + '/' + state
+      let files = []
+      try {
+        files = fs.readdirSync(dir).filter(f => {
+          try { return !fs.statSync(path.join(dir, f)).isDirectory() && f.endsWith('.md') } catch (_) { return false }
+        })
+      } catch (_) { continue }
+      if (files.length === 0) continue
+      found = true
+      console.log(`[${state}]`)
+      for (const f of files) console.log(`  ${f}`)
     }
   }
 
@@ -44,8 +84,8 @@ function listRoadmaps() {
 }
 
 /**
- * showRoadmap — busca docs/roadmaps/ESTADO/NOME*.md (partial match), imprime cabeçalho + conteúdo.
- * 0 matches: erro. múltiplos: lista + erro. 1 match: imprime cabeçalho e conteúdo.
+ * showRoadmap — busca <roadmapDir>/ESTADO/NOME*.md (partial match, flat) ou
+ * <roadmapDir>/AGENTE/ESTADO/NOME*.md (by_agent), imprime cabeçalho + conteúdo.
  */
 function showRoadmap(name) {
   const matches = findRoadmapMatches(name)
@@ -58,9 +98,7 @@ function showRoadmap(name) {
 
   if (matches.length > 1) {
     console.log('Multiple roadmaps found — be more specific:')
-    for (const m of matches) {
-      console.log(`  ${m}`)
-    }
+    for (const m of matches) console.log(`  ${m}`)
     console.error(`ambiguous match for "${name}"`)
     process.exitCode = 1
     return
@@ -78,12 +116,12 @@ function showRoadmap(name) {
 
 /**
  * moveRoadmap — move arquivo para diretório do estado alvo.
- * Valida estado, procura arquivo em qualquer estado (case-insensitive partial match),
- * move com fs.renameSync, chama appendTransitionLog, imprime confirmação.
+ * Em modo by_agent, mantém o agente na hierarquia.
  */
 function moveRoadmap(name, state) {
-  const targetDir = VALID_STATES[state]
-  if (!targetDir) {
+  const cfg = config.load()
+  const valid = ['backlog', 'wip', 'blocked', 'done', 'abandoned']
+  if (!valid.includes(state)) {
     console.error(`invalid state "${state}" — valid states: backlog, wip, blocked, done, abandoned`)
     process.exitCode = 1
     return
@@ -97,9 +135,7 @@ function moveRoadmap(name, state) {
   }
   if (matches.length > 1) {
     console.log('Multiple roadmaps found — be more specific:')
-    for (const m of matches) {
-      console.log(`  ${m}`)
-    }
+    for (const m of matches) console.log(`  ${m}`)
     console.error(`ambiguous match for "${name}"`)
     process.exitCode = 1
     return
@@ -107,22 +143,41 @@ function moveRoadmap(name, state) {
 
   const src = matches[0]
   const basename = path.basename(src)
-  const fromState = path.basename(path.dirname(src))
+  let targetDir, fromState, logBasename
+
+  if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
+    const agentDir = path.dirname(path.dirname(src))
+    const agent = path.basename(agentDir)
+    fromState = path.basename(path.dirname(src))
+    targetDir = agentStateDir(agent, state)
+    if (!targetDir) {
+      console.error(`invalid state "${state}"`)
+      process.exitCode = 1
+      return
+    }
+    logBasename = agent + '/' + basename
+  } else {
+    fromState = path.basename(path.dirname(src))
+    targetDir = stateDir(state)
+    if (!targetDir) {
+      console.error(`invalid state "${state}"`)
+      process.exitCode = 1
+      return
+    }
+    logBasename = basename
+  }
 
-  try {
-    fs.mkdirSync(targetDir, { recursive: true })
-  } catch (_) {}
+  try { fs.mkdirSync(targetDir, { recursive: true }) } catch (_) {}
 
   const dst = path.join(targetDir, basename)
   fs.renameSync(src, dst)
 
-  appendTransitionLog(basename, fromState, state)
+  appendTransitionLog(logBasename, fromState, state)
   console.log(`✓ moved ${basename} → ${targetDir}`)
 }
 
 /**
- * appendTransitionLog — append em docs/roadmaps/.trackfw-log.
- * Formato: `YYYY-MM-DD HH:mm  <basename padded to 50>  <fromState> → <toState>\n`
+ * appendTransitionLog — append em <roadmapDir>/.trackfw-log.
  */
 function appendTransitionLog(basename, fromState, toState) {
   const now = new Date()
@@ -135,26 +190,48 @@ function appendTransitionLog(basename, fromState, toState) {
   const line = `${timestamp}  ${basename.padEnd(50)}  ${fromState} → ${toState}\n`
 
   try {
-    fs.mkdirSync(path.dirname(TRANSITION_LOG_PATH), { recursive: true })
-    fs.appendFileSync(TRANSITION_LOG_PATH, line, 'utf8')
+    const lp = logPath()
+    fs.mkdirSync(path.dirname(lp), { recursive: true })
+    fs.appendFileSync(lp, line, 'utf8')
   } catch (_) {}
 }
 
 /**
- * newRoadmap — cria roadmap em docs/roadmaps/backlog/ROADMAP-YYYY-MM-DD-<slug>.md.
+ * newRoadmap — cria roadmap em <roadmapDir>/backlog/ROADMAP-YYYY-MM-DD-<slug>.md.
+ * Em modo by_agent, usa o primeiro agente configurado.
  */
 function newRoadmap(title, reqPath) {
+  const cfg = config.load()
   const now = new Date()
   const yyyy = now.getFullYear()
   const mm = String(now.getMonth() + 1).padStart(2, '0')
   const dd = String(now.getDate()).padStart(2, '0')
   const date = `${yyyy}-${mm}-${dd}`
   const slug = toSlug(title)
-  const filename = `docs/roadmaps/backlog/ROADMAP-${date}-${slug}.md`
 
-  fs.mkdirSync('docs/roadmaps/backlog', { recursive: true })
+  let backlogDir
+  if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
+    backlogDir = agentStateDir(null, 'backlog')
+    if (!backlogDir) {
+      console.error('cannot resolve backlog dir in by_agent mode')
+      process.exitCode = 1
+      return
+    }
+  } else {
+    backlogDir = cfg.roadmapDir + '/backlog'
+  }
+
+  const filename = `${backlogDir}/ROADMAP-${date}-${slug}.md`
+  fs.mkdirSync(backlogDir, { recursive: true })
 
-  const body = `# Roadmap: ${title}
+  const body = `---
+status: backlog
+date: ${date}
+req: ""
+squad: ""
+---
+
+# Roadmap: ${title}
 
 > Created: ${date} | Status: backlog
 
@@ -179,25 +256,180 @@ REQ: ${reqPath || ''}
   console.log(`✓ created ${filename}`)
 }
 
+/**
+ * newRoadmapFromReq — lê uma REQ e gera roadmap pré-preenchido com MLs extraídos
+ * dos critérios de aceite.
+ */
+function newRoadmapFromReq(reqPath) {
+  let data
+  try {
+    data = fs.readFileSync(reqPath, 'utf8')
+  } catch (err) {
+    console.error(`reading REQ: ${err.message}`)
+    process.exitCode = 1
+    return
+  }
+
+  const { title: parsedTitle, criteria, linkedADR } = parseReqForRoadmap(data)
+  const basename = path.basename(reqPath)
+  const title = parsedTitle || basename.replace(/\.md$/, '').replace(/^REQ-/, '')
+
+  const cfg = config.load()
+  const now = new Date()
+  const yyyy = now.getFullYear()
+  const mm = String(now.getMonth() + 1).padStart(2, '0')
+  const dd = String(now.getDate()).padStart(2, '0')
+  const date = `${yyyy}-${mm}-${dd}`
+  const slug = toSlug(title)
+
+  let backlogDir
+  if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
+    backlogDir = agentStateDir(null, 'backlog')
+    if (!backlogDir) {
+      console.error('cannot resolve backlog dir in by_agent mode')
+      process.exitCode = 1
+      return
+    }
+  } else {
+    backlogDir = cfg.roadmapDir + '/backlog'
+  }
+
+  const filename = `${backlogDir}/ROADMAP-${date}-${slug}.md`
+  try { fs.mkdirSync(backlogDir, { recursive: true }) } catch (_) {}
+
+  // Gerar seção de MLs a partir dos critérios de aceite
+  const mlLines = ['## Wave 1 — Implementation (derived from REQ criteria)', '> Dependencies: none']
+  for (let i = 0; i < criteria.length; i++) {
+    const mlLabel = `ML-1${String.fromCharCode(65 + i)}`
+    const crit = criteria[i]
+    mlLines.push(`\n### ${mlLabel} — ${crit}`)
+    mlLines.push('**Status:** pending')
+    mlLines.push('**Files affected:**')
+    mlLines.push('**Actions:**')
+    mlLines.push('**Acceptance criteria:**')
+    mlLines.push(`- [ ] ${crit}`)
+    mlLines.push('- [ ] build passes')
+    mlLines.push('- [ ] tests green')
+  }
+  const mlSection = mlLines.join('\n')
+
+  const adrRef = linkedADR ? `\nADR: ${linkedADR}` : ''
+
+  const body = `---
+status: backlog
+date: ${date}
+req: "${basename}"
+squad: ""
+---
+
+# Roadmap: ${title}
+
+> Created: ${date} | Status: backlog
+
+## Context
+<!-- Derived from REQ: ${basename} -->
+REQ: ${reqPath}${adrRef}
+
+${mlSection}
+`
+
+  fs.writeFileSync(filename, body, 'utf8')
+  console.log(`✓ created ${filename}`)
+}
+
+/**
+ * parseReqForRoadmap — extrai título, critérios de aceite e ADR linkada de conteúdo REQ.
+ */
+function parseReqForRoadmap(content) {
+  const lines = content.split('\n')
+  let title = ''
+  let linkedADR = ''
+  const criteria = []
+  let inCriteria = false
+
+  for (const line of lines) {
+    if (line.startsWith('# REQ: ')) {
+      title = line.replace('# REQ: ', '').trim()
+      continue
+    }
+    if (line.startsWith('# REQ — ')) {
+      title = line.replace('# REQ — ', '').trim()
+      continue
+    }
+    if (line.startsWith('# REQ - ')) {
+      title = line.replace('# REQ - ', '').trim()
+      continue
+    }
+    if (line.startsWith('**ADR:**')) {
+      linkedADR = line.replace('**ADR:**', '').trim()
+      continue
+    }
+
+    const lower = line.trim().toLowerCase()
+    if (lower === '## critérios de aceite' || lower === '## acceptance criteria') {
+      inCriteria = true
+      continue
+    }
+    if (inCriteria && line.startsWith('## ')) {
+      inCriteria = false
+      continue
+    }
+    if (inCriteria) {
+      const trimmed = line.trim()
+      const checkboxPrefixes = ['- [ ]', '- [x]', '- [X]']
+      for (const prefix of checkboxPrefixes) {
+        if (trimmed.startsWith(prefix)) {
+          const item = trimmed.slice(prefix.length).trim().replace(/`/g, '')
+          if (item) criteria.push(item)
+          break
+        }
+      }
+    }
+  }
+  return { title, criteria, linkedADR }
+}
+
 // --- helpers ---
 
 /**
  * findRoadmapMatches — retorna array de paths que contêm `name` (case-insensitive) em qualquer estado.
+ * Suporta modo flat (1 nível) e by_agent (2 níveis).
  */
 function findRoadmapMatches(name) {
+  const cfg = config.load()
   const matches = []
   const nameLower = name.toLowerCase()
-  for (const state of STATE_ORDER) {
-    const dir = VALID_STATES[state]
-    let files = []
-    try {
-      files = fs.readdirSync(dir)
-    } catch (_) {
-      continue
+
+  if (cfg.roadmapNamespacing === config.NAMESPACING_BY_AGENT) {
+    let agents = cfg.agents || []
+    if (agents.length === 0) {
+      try {
+        agents = fs.readdirSync(cfg.roadmapDir).filter(f => {
+          try { return fs.statSync(path.join(cfg.roadmapDir, f)).isDirectory() } catch (_) { return false }
+        })
+      } catch (_) { agents = ['default'] }
+    }
+    for (const agent of agents) {
+      for (const state of STATE_ORDER) {
+        const dir = cfg.roadmapDir + '/' + agent + '/' + state
+        let files = []
+        try { files = fs.readdirSync(dir) } catch (_) { continue }
+        for (const f of files) {
+          if (f.toLowerCase().includes(nameLower) && f.endsWith('.md')) {
+            matches.push(path.join(dir, f))
+          }
+        }
+      }
     }
-    for (const f of files) {
-      if (f.toLowerCase().includes(nameLower) && f.endsWith('.md')) {
-        matches.push(path.join(dir, f))
+  } else {
+    for (const state of STATE_ORDER) {
+      const dir = cfg.roadmapDir + '/' + state
+      let files = []
+      try { files = fs.readdirSync(dir) } catch (_) { continue }
+      for (const f of files) {
+        if (f.toLowerCase().includes(nameLower) && f.endsWith('.md')) {
+          matches.push(path.join(dir, f))
+        }
       }
     }
   }
@@ -215,10 +447,12 @@ function toSlug(s) {
 }
 
 module.exports = {
-  VALID_STATES,
   listRoadmaps,
   showRoadmap,
   moveRoadmap,
   appendTransitionLog,
   newRoadmap,
+  newRoadmapFromReq,
+  stateDir,
+  agentStateDir,
 }

package/src/i18n/locales/en-US.json

@@ -11,6 +11,7 @@
       "gitHooks": "Git hooks?",
       "ci": "CI system?",
       "aiTools": "Which AI assistants do you use?",
+      "require_req_in_commit": "Require REQ reference in commit messages for feat/fix branches?",
       "projectType_fullstack": "Full-stack (frontend + backend)",
       "projectType_frontend": "Frontend only",
       "projectType_backend": "Backend only",
@@ -87,7 +88,8 @@
     "description": "Validate governance rules (use as CI gate)",
     "ok": "✓ No violations found.",
     "violations": "✗ Violations ({{count}}):",
-    "warnings": "⚠ Warnings ({{count}}):"
+    "warnings": "⚠ Warnings ({{count}}):",
+    "lenient_mode": "Governance violations treated as warnings until {{date}}"
   },
   "status": {
     "description": "Show project governance status"
@@ -114,6 +116,12 @@
       "success": "Plugin \"{{name}}\" removed."
     }
   },
+  "metrics": {
+    "description": "Show delivery metrics",
+    "no_data": "No transitions recorded yet.",
+    "since": "Filter by period (e.g. 7d, 30d, 90d)",
+    "export": "Export metrics to CSV file"
+  },
   "errors": {
     "notFound": "Not found: {{path}}",
     "downloadFailed": "download failed: HTTP {{status}} for {{url}}",

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

@@ -11,6 +11,7 @@
       "gitHooks": "¿Git hooks?",
       "ci": "¿Sistema de CI?",
       "aiTools": "¿Qué asistentes de IA usas?",
+      "require_req_in_commit": "¿Requerir referencia REQ en mensajes de commit de ramas feat/fix?",
       "projectType_fullstack": "Full-stack (frontend + backend)",
       "projectType_frontend": "Solo frontend",
       "projectType_backend": "Solo backend",
@@ -87,7 +88,8 @@
     "description": "Validar reglas de gobernanza (úsalo como gate de CI)",
     "ok": "✓ No se encontraron violaciones.",
     "violations": "✗ Violaciones ({{count}}):",
-    "warnings": "⚠ Avisos ({{count}}):"
+    "warnings": "⚠ Avisos ({{count}}):",
+    "lenient_mode": "Las violaciones de gobernanza se tratan como avisos hasta {{date}}"
   },
   "status": {
     "description": "Mostrar el estado actual de gobernanza del proyecto"
@@ -114,6 +116,12 @@
       "success": "Plugin \"{{name}}\" eliminado."
     }
   },
+  "metrics": {
+    "description": "Muestra métricas de entrega",
+    "no_data": "No hay transiciones registradas aún.",
+    "since": "Filtrar por período (ej: 7d, 30d, 90d)",
+    "export": "Exportar métricas a archivo CSV"
+  },
   "errors": {
     "notFound": "No encontrado: {{path}}",
     "downloadFailed": "fallo en la descarga: HTTP {{status}} para {{url}}",

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

@@ -11,6 +11,7 @@
       "gitHooks": "Git hooks?",
       "ci": "Sistema de CI?",
       "aiTools": "Quais assistentes de IA você usa?",
+      "require_req_in_commit": "Exigir referência REQ nas mensagens de commit de branches feat/fix?",
       "projectType_fullstack": "Full-stack (frontend + backend)",
       "projectType_frontend": "Somente frontend",
       "projectType_backend": "Somente backend",
@@ -87,7 +88,8 @@
     "description": "Validar regras de governança (use como gate de CI)",
     "ok": "✓ Nenhuma violação encontrada.",
     "violations": "✗ Violações ({{count}}):",
-    "warnings": "⚠ Avisos ({{count}}):"
+    "warnings": "⚠ Avisos ({{count}}):",
+    "lenient_mode": "Violações de governança tratadas como avisos até {{date}}"
   },
   "status": {
     "description": "Exibir o estado atual de governança do projeto"
@@ -114,6 +116,12 @@
       "success": "Plugin \"{{name}}\" removido."
     }
   },
+  "metrics": {
+    "description": "Exibe métricas de delivery",
+    "no_data": "Nenhuma transição registrada ainda.",
+    "since": "Filtrar por período (ex: 7d, 30d, 90d)",
+    "export": "Exportar métricas para arquivo CSV"
+  },
   "errors": {
     "notFound": "Não encontrado: {{path}}",
     "downloadFailed": "falha no download: HTTP {{status}} para {{url}}",