trackfw 1.0.4 → 2.0.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,24 +190,39 @@ 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}
 
@@ -183,21 +253,43 @@ REQ: ${reqPath || ''}
 
 /**
  * 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 +307,11 @@ function toSlug(s) {
 }
 
 module.exports = {
-  VALID_STATES,
   listRoadmaps,
   showRoadmap,
   moveRoadmap,
   appendTransitionLog,
   newRoadmap,
+  stateDir,
+  agentStateDir,
 }

package/src/i18n/index.js

@@ -0,0 +1,53 @@
+'use strict'
+const path = require('path')
+const fs = require('fs')
+
+function detectLocale() {
+  const raw = process.env.LANG || process.env.LC_ALL || process.env.LANGUAGE || ''
+  // Mapeia pt_BR.UTF-8 → pt-BR, es_ES.UTF-8 → es-ES, en_US.UTF-8 → en-US
+  const map = { pt: 'pt-BR', es: 'es-ES' }
+  const code = raw.split('.')[0].replace('_', '-')  // pt-BR
+  const lang = code.split('-')[0]                   // pt
+  if (map[lang]) return map[lang]
+  // Fallback para Windows: usar Intl
+  try {
+    const loc = Intl.DateTimeFormat().resolvedOptions().locale
+    const l = loc.split('-')[0]
+    if (map[l]) return map[l]
+  } catch (_) {}
+  return 'en-US'
+}
+
+let _locale = null
+let _messages = null
+
+function load() {
+  if (_messages) return
+  _locale = detectLocale()
+  const filePath = path.join(__dirname, 'locales', `${_locale}.json`)
+  const fallback = path.join(__dirname, 'locales', 'en-US.json')
+  try {
+    _messages = JSON.parse(fs.readFileSync(fs.existsSync(filePath) ? filePath : fallback, 'utf8'))
+  } catch (_) {
+    _messages = {}
+  }
+}
+
+function t(key, vars = {}) {
+  load()
+  const keys = key.split('.')
+  let val = _messages
+  for (const k of keys) {
+    val = val?.[k]
+    if (val === undefined) break
+  }
+  if (typeof val !== 'string') return key
+  return val.replace(/\{\{(\w+)\}\}/g, (_, k) => vars[k] ?? `{{${k}}}`)
+}
+
+function locale() {
+  load()
+  return _locale
+}
+
+module.exports = { t, locale }

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

@@ -0,0 +1,122 @@
+{
+  "init": {
+    "description": "Initialize trackfw governance in the current project",
+    "prompt": {
+      "projectName": "Project name?",
+      "projectType": "Project type?",
+      "frontendStack": "Frontend stack?",
+      "pkgManager": "Package manager?",
+      "backendLang": "Backend language?",
+      "backendFramework": "Backend framework?",
+      "gitHooks": "Git hooks?",
+      "ci": "CI system?",
+      "aiTools": "Which AI assistants do you use?",
+      "projectType_fullstack": "Full-stack (frontend + backend)",
+      "projectType_frontend": "Frontend only",
+      "projectType_backend": "Backend only",
+      "projectType_governance": "Governance only (no build stack)"
+    },
+    "success": "✓ trackfw initialized — run 'trackfw status' to see your governance state."
+  },
+  "adr": {
+    "description": "Manage Architecture Decision Records",
+    "new": {
+      "description": "Create a new Architecture Decision Record",
+      "prompt": {
+        "title": "ADR title?",
+        "status": "Initial status?",
+        "context": "Context (what motivates this decision)?",
+        "decision": "Decision (what was decided)?",
+        "consequences": "Consequences (positive and negative)?",
+        "alternatives": "Alternatives considered?"
+      },
+      "created": "✓ ADR created: {{path}}"
+    },
+    "list": {
+      "description": "List all ADRs with status",
+      "empty": "No ADRs found in docs/adr/"
+    }
+  },
+  "req": {
+    "description": "Manage Requirements",
+    "new": {
+      "description": "Create a new requirement",
+      "prompt": {
+        "title": "Project requirement",
+        "motivation": "Motivation (why is this needed)?",
+        "criteria": "Acceptance Criteria (one per line)",
+        "domainQuestion_authentication": "How will users authenticate?",
+        "domainQuestion_ui": "Is there an existing UI framework or design system?",
+        "domainQuestion_persistence": "Which database engine will be used?",
+        "domainQuestion_api": "Which API protocol will be used?",
+        "domainQuestion_deploy": "What is the deployment target?",
+        "domainQuestion_events": "Which event broker will be used?"
+      },
+      "detectedDomains": "Detected domains: {{domains}}",
+      "created": "✓ REQ created: {{path}}",
+      "adrDraftsCreated": "ADR drafts created:",
+      "resolveADRs": "Resolve these ADRs (set Status: Accepted) before creating a roadmap.",
+      "adrWarning": "warning: could not create ADR draft for {{slug}}: {{message}}"
+    },
+    "list": {
+      "description": "List all REQs with status",
+      "empty": "No REQs found in docs/req/"
+    }
+  },
+  "roadmap": {
+    "description": "Manage Roadmaps",
+    "list": {
+      "description": "List all roadmaps grouped by state",
+      "empty": "No roadmaps found."
+    },
+    "show": {
+      "description": "Show a roadmap by name (partial match)",
+      "notFound": "Roadmap not found: {{name}}"
+    },
+    "move": {
+      "description": "Move a roadmap between states (backlog|wip|blocked|done|abandoned)",
+      "success": "✓ Moved {{name}} → {{state}}",
+      "notFound": "Roadmap not found: {{name}}"
+    },
+    "new": {
+      "description": "Create a new roadmap from a REQ",
+      "created": "✓ Roadmap created: {{path}}"
+    }
+  },
+  "validate": {
+    "description": "Validate governance rules (use as CI gate)",
+    "ok": "✓ No violations found.",
+    "violations": "✗ Violations ({{count}}):",
+    "warnings": "⚠ Warnings ({{count}}):"
+  },
+  "status": {
+    "description": "Show project governance status"
+  },
+  "log": {
+    "description": "Show roadmap state transition history",
+    "empty": "No transitions recorded yet.",
+    "tail": "Number of recent transitions to show",
+    "header": "── trackfw log ─────────────────────────"
+  },
+  "plugins": {
+    "description": "Manage trackfw plugins",
+    "list": {
+      "description": "List installed plugins",
+      "empty": "No plugins installed. Use `trackfw plugins add <user/repo>` to install one."
+    },
+    "add": {
+      "description": "Install a plugin from GitHub Releases (user/repo or user/repo@tag)",
+      "installing": "Installing plugin from {{repo}}...",
+      "success": "Plugin \"{{name}}\" installed successfully."
+    },
+    "remove": {
+      "description": "Remove an installed plugin",
+      "success": "Plugin \"{{name}}\" removed."
+    }
+  },
+  "errors": {
+    "notFound": "Not found: {{path}}",
+    "downloadFailed": "download failed: HTTP {{status}} for {{url}}",
+    "pluginNotFound": "plugin \"{{name}}\" not found"
+  }
+}

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"
+  }
+}