trackfw 2.0.0 → 2.1.1

package/package.json

@@ -1,13 +1,20 @@
 {
   "name": "trackfw",
-  "version": "2.0.0",
-  "description": "Governed software delivery framework: ADR → REQ → ROADMAP → kanban",
+  "version": "2.1.1",
+  "description": "CLI de governança para entrega de software: ADR → REQ → ROADMAP → kanban. Suporte nativo a agentes de IA (Claude Code, Gemini CLI, Cursor).",
   "keywords": [
     "cli",
     "adr",
+    "architecture-decision-records",
     "roadmap",
     "governance",
-    "delivery"
+    "software-delivery",
+    "devops",
+    "ai-agents",
+    "developer-tools",
+    "kanban",
+    "req",
+    "trackfw"
   ],
   "homepage": "https://github.com/kgsaran/trackfw",
   "repository": {

package/src/commands/context.js

@@ -0,0 +1,189 @@
+'use strict'
+
+const { Command } = require('commander')
+const fs = require('fs')
+const path = require('path')
+const config = require('../config')
+const { validate } = require('../validator')
+
+/**
+ * extractFrontmatterField — extrai valor de campo YAML dentro de bloco --- ... ---.
+ * Retorna string vazia se não encontrado ou valor '""'.
+ * @param {string} content
+ * @param {string} field
+ * @returns {string}
+ */
+function extractFrontmatterField(content, field) {
+  const lines = content.split('\n')
+  let started = false
+  let inFrontmatter = false
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (trimmed === '---') {
+      if (!started) {
+        started = true
+        inFrontmatter = true
+        continue
+      }
+      break // segundo --- fecha o bloco
+    }
+    if (!inFrontmatter) break
+    const key = field + ':'
+    if (trimmed.startsWith(key)) {
+      let val = trimmed.slice(key.length).trim()
+      val = val.replace(/^["']|["']$/g, '') // remover aspas
+      return val
+    }
+  }
+  return ''
+}
+
+/**
+ * extractInlineStatus — extrai status da linha "| Status: ..." do markdown.
+ * @param {string} content
+ * @returns {string}
+ */
+function extractInlineStatus(content) {
+  for (const line of content.split('\n')) {
+    const idx = line.indexOf('| Status: ')
+    if (idx >= 0) {
+      let rest = line.slice(idx + '| Status: '.length)
+      const pipeIdx = rest.indexOf(' |')
+      if (pipeIdx >= 0) rest = rest.slice(0, pipeIdx)
+      rest = rest.replace(/[\s>|]+$/, '').trim()
+      return rest || 'unknown'
+    }
+  }
+  return 'unknown'
+}
+
+/**
+ * collectEntries — lê diretório e retorna lista de entradas com type, file, status, state.
+ * @param {string} dir
+ * @param {string} type - 'ADR' | 'REQ' | 'ROADMAP'
+ * @param {string} [state] - estado kanban (somente ROADMAP)
+ * @returns {Array<{type: string, file: string, status: string, state?: string}>}
+ */
+function collectEntries(dir, type, state) {
+  const entries = []
+  let files = []
+  try {
+    files = fs.readdirSync(dir).filter(f => f.endsWith('.md') && !fs.statSync(path.join(dir, f)).isDirectory())
+  } catch (_) {
+    return entries
+  }
+  for (const file of files) {
+    let content = ''
+    try { content = fs.readFileSync(path.join(dir, file), 'utf8') } catch (_) {}
+    let status = extractFrontmatterField(content, 'status')
+    if (!status) status = extractInlineStatus(content)
+    if (!status) status = state || 'unknown'
+    const entry = { type, file, status }
+    if (state) entry.state = state
+    entries.push(entry)
+  }
+  return entries
+}
+
+/**
+ * getContext — coleta governança e imprime em md ou json.
+ * @param {string} format - 'md' | 'json'
+ */
+function getContext(format) {
+  const cfg = config.load()
+
+  // ADRs
+  const adrs = []
+  for (const adrDir of (cfg.adrDirs || ['docs/adr'])) {
+    adrs.push(...collectEntries(adrDir, 'ADR'))
+  }
+
+  // REQs
+  const reqs = collectEntries(cfg.reqDir || 'docs/req', 'REQ')
+
+  // Roadmaps
+  const roadmaps = []
+  const states = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
+  if (cfg.roadmapNamespacing === '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 = [] }
+    }
+    for (const agent of agents) {
+      for (const state of states) {
+        const dir = path.join(cfg.roadmapDir, agent, state)
+        roadmaps.push(...collectEntries(dir, 'ROADMAP', state))
+      }
+    }
+  } else {
+    for (const state of states) {
+      const dir = path.join(cfg.roadmapDir, state)
+      roadmaps.push(...collectEntries(dir, 'ROADMAP', state))
+    }
+  }
+
+  // Validate
+  const { violations, warnings } = validate()
+
+  // Score
+  let score = 0
+  if (adrs.length > 0) score += 20
+  if (reqs.length > 0) score += 20
+  if (roadmaps.length > 0) score += 20
+  if (violations.length === 0) score += 40
+
+  if (format === 'json') {
+    console.log(JSON.stringify({ score, violations, warnings, adrs, reqs, roadmaps }, null, 2))
+    return
+  }
+
+  // Markdown
+  console.log('# trackfw governance context\n')
+  console.log(`**Governance score:** ${score}/100\n`)
+
+  console.log(`## ADRs (${adrs.length})`)
+  if (adrs.length === 0) {
+    console.log('- (none)')
+  } else {
+    for (const a of adrs) console.log(`- ${a.file} [${a.status}]`)
+  }
+
+  console.log(`\n## REQs (${reqs.length})`)
+  if (reqs.length === 0) {
+    console.log('- (none)')
+  } else {
+    for (const r of reqs) console.log(`- ${r.file} [${r.status}]`)
+  }
+
+  console.log(`\n## Roadmaps (${roadmaps.length})`)
+  if (roadmaps.length === 0) {
+    console.log('- (none)')
+  } else {
+    for (const r of roadmaps) console.log(`- ${r.file} [${r.state}]`)
+  }
+
+  if (violations.length > 0) {
+    console.log(`\n## Violations (${violations.length})`)
+    for (const v of violations) console.log(`- ${v}`)
+  }
+
+  if (warnings.length > 0) {
+    console.log(`\n## Warnings (${warnings.length})`)
+    for (const w of warnings) console.log(`- ${w}`)
+  }
+}
+
+module.exports = (function () {
+  const cmd = new Command('context')
+  cmd
+    .description('Print governance context for LLM consumption')
+    .option('--format <fmt>', 'Output format: md or json', 'md')
+    .action((opts) => {
+      getContext(opts.format)
+    })
+  return cmd
+})()

package/src/commands/index.js

@@ -19,6 +19,9 @@ function createProgram() {
   program.addCommand(require('./log'))
   program.addCommand(require('./plugins'))
   program.addCommand(require('./discover'))
+  program.addCommand(require('./metrics'))
+  program.addCommand(require('./sync'))
+  program.addCommand(require('./context'))
 
   // plugin dispatch — comandos desconhecidos tentam executar plugin
   program.hook('preSubcommand', () => {})

package/src/commands/init.js

@@ -26,7 +26,7 @@ cmd.action(async () => {
 
   const { input, select, checkbox } = require('@inquirer/prompts')
 
-  let projectName, projectType, frontend, pkgManager, backend, backendFramework, hooks, ci, aiTools
+  let projectName, projectType, frontend, pkgManager, backend, backendFramework, hooks, ci, aiTools, requireReqInCommit
 
   try {
     projectName = await input({
@@ -127,6 +127,15 @@ cmd.action(async () => {
       ],
     })
 
+    requireReqInCommit = false
+    if (hooks !== 'none') {
+      const { confirm: confirmPrompt } = require('@inquirer/prompts')
+      requireReqInCommit = await confirmPrompt({
+        message: t('init.prompt.require_req_in_commit'),
+        default: false,
+      })
+    }
+
     aiTools = await checkbox({
       message: t('init.prompt.aiTools'),
       choices: [
@@ -154,7 +163,7 @@ cmd.action(async () => {
     return
   }
 
-  const cfg = { projectName, projectType, frontend, backend, backendFramework, pkgManager, hooks, ci }
+  const cfg = { projectName, projectType, frontend, backend, backendFramework, pkgManager, hooks, ci, requireReqInCommit }
   await generators.scaffold(cfg)
 
   for (const tool of (aiTools || [])) {

package/src/commands/metrics.js

@@ -0,0 +1,235 @@
+'use strict'
+
+const { Command } = require('commander')
+const fs = require('fs')
+const path = require('path')
+const { t } = require('../i18n')
+
+// lineRe: faz match do formato do .trackfw-log
+// 2026-06-12 14:30  ROADMAP-2026-06-12-auth.md                  backlog → wip
+const LINE_RE = /^(\d{4}-\d{2}-\d{2} \d{2}:\d{2})\s{2,}(\S+)\s{2,}(\S+)\s+→\s+(\S+)/
+
+/**
+ * parseLog lê o arquivo .trackfw-log e retorna array de transições.
+ * Retorna [] se o arquivo não existe.
+ * @param {string} filePath
+ * @returns {{ timestamp: Date, basename: string, from: string, to: string }[]}
+ */
+function parseLog(filePath) {
+  if (!fs.existsSync(filePath)) return []
+  const content = fs.readFileSync(filePath, 'utf8')
+  const lines = content.split('\n')
+  const transitions = []
+  for (const line of lines) {
+    if (!line.trim()) continue
+    const m = LINE_RE.exec(line)
+    if (!m) continue
+    const [, tsStr, basename, from, to] = m
+    const timestamp = new Date(tsStr.replace(' ', 'T') + ':00')
+    if (isNaN(timestamp.getTime())) continue
+    transitions.push({ timestamp, basename: basename.trim(), from: from.trim(), to: to.trim() })
+  }
+  return transitions
+}
+
+/**
+ * filter retorna transições com timestamp >= sinceMs.
+ * @param {Array} transitions
+ * @param {number} sinceMs - timestamp em milissegundos
+ * @returns {Array}
+ */
+function filter(transitions, sinceMs) {
+  return transitions.filter(t => t.timestamp.getTime() >= sinceMs)
+}
+
+/**
+ * calculate computa cycle time médio, throughput e WIP age.
+ * @param {Array} transitions
+ * @returns {{ cycleTimeMeanMs: number, throughput: number, wipEntries: Array }}
+ */
+function calculate(transitions) {
+  // Agrupar por basename
+  const byName = new Map()
+  for (const tr of transitions) {
+    if (!byName.has(tr.basename)) byName.set(tr.basename, [])
+    byName.get(tr.basename).push(tr)
+  }
+
+  // Cycle time: da entrada em backlog ou wip até done
+  const cycleTimes = []
+  for (const [, entries] of byName) {
+    let startTs = null
+    let doneTs = null
+    for (const e of entries) {
+      if ((e.to === 'backlog' || e.to === 'wip') && startTs === null) {
+        startTs = e.timestamp.getTime()
+      }
+      if (e.to === 'done') {
+        doneTs = e.timestamp.getTime()
+      }
+    }
+    if (startTs !== null && doneTs !== null) {
+      cycleTimes.push(doneTs - startTs)
+    }
+  }
+
+  let cycleTimeMeanMs = 0
+  if (cycleTimes.length > 0) {
+    cycleTimeMeanMs = cycleTimes.reduce((a, b) => a + b, 0) / cycleTimes.length
+  }
+
+  // Throughput: roadmaps done por semana
+  let doneCount = 0
+  let minTs = Infinity
+  let maxTs = -Infinity
+  for (const tr of transitions) {
+    const ms = tr.timestamp.getTime()
+    if (tr.to === 'done') doneCount++
+    if (ms < minTs) minTs = ms
+    if (ms > maxTs) maxTs = ms
+  }
+
+  let throughput = 0
+  if (doneCount > 0) {
+    const msPerWeek = 7 * 24 * 60 * 60 * 1000
+    let weeks = (maxTs - minTs) / msPerWeek
+    if (weeks < 1) weeks = 1
+    throughput = doneCount / weeks
+  }
+
+  // WIP age: basenames em wip sem done ou abandoned posterior
+  const wipEntries = []
+  const now = Date.now()
+  for (const [basename, entries] of byName) {
+    let wipTs = null
+    let concluded = false
+    for (const e of entries) {
+      if (e.to === 'wip') wipTs = e.timestamp.getTime()
+      if (e.to === 'done' || e.to === 'abandoned') concluded = true
+    }
+    if (wipTs !== null && !concluded) {
+      wipEntries.push({ basename, ageMs: now - wipTs })
+    }
+  }
+
+  return { cycleTimeMeanMs, throughput, wipEntries }
+}
+
+/**
+ * exportCSV grava transições e métricas em um arquivo CSV.
+ * @param {{ cycleTimeMeanMs: number, throughput: number, wipEntries: Array }} metrics
+ * @param {Array} transitions
+ * @param {string} filePath
+ */
+function exportCSV(metrics, transitions, filePath) {
+  const rows = []
+  rows.push('basename,from,to,timestamp')
+  for (const tr of transitions) {
+    const ts = tr.timestamp.toISOString().slice(0, 16).replace('T', ' ')
+    rows.push(`${tr.basename},${tr.from},${tr.to},${ts}`)
+  }
+  rows.push('')
+  rows.push('metric,value')
+  const cycleHours = (metrics.cycleTimeMeanMs / (1000 * 3600)).toFixed(2)
+  rows.push(`cycle_time_mean_hours,${cycleHours}`)
+  rows.push(`throughput_per_week,${metrics.throughput.toFixed(2)}`)
+  rows.push(`wip_count,${metrics.wipEntries.length}`)
+  fs.writeFileSync(filePath, rows.join('\n') + '\n', 'utf8')
+}
+
+/**
+ * parseSinceDuration converte "7d", "30d", "90d" em milissegundos.
+ * @param {string} s
+ * @returns {number}
+ */
+function parseSinceDuration(s) {
+  if (!s || s.length < 2) throw new Error(`formato inválido: "${s}"`)
+  const unit = s[s.length - 1]
+  if (unit !== 'd') throw new Error(`unidade não suportada "${unit}" (use 'd' para dias)`)
+  const n = parseInt(s.slice(0, -1), 10)
+  if (isNaN(n) || n <= 0) throw new Error(`número inválido em "${s}"`)
+  return n * 24 * 60 * 60 * 1000
+}
+
+/**
+ * formatDuration formata milissegundos em string legível.
+ * @param {number} ms
+ * @returns {string}
+ */
+function formatDuration(ms) {
+  const totalHours = Math.floor(ms / (1000 * 3600))
+  const days = Math.floor(totalHours / 24)
+  const hours = totalHours % 24
+  if (days > 0) return `${days} days ${hours} hours`
+  return `${hours} hours`
+}
+
+/**
+ * printMetrics imprime as métricas em formato tabela ASCII.
+ * @param {{ cycleTimeMeanMs: number, throughput: number, wipEntries: Array }} metrics
+ */
+function printMetrics(metrics) {
+  console.log('── trackfw metrics ──────────────────────')
+
+  if (metrics.cycleTimeMeanMs > 0) {
+    console.log(`  Cycle Time Mean   : ${formatDuration(metrics.cycleTimeMeanMs)}`)
+  } else {
+    console.log('  Cycle Time Mean   : n/a (no completed cycles)')
+  }
+
+  if (metrics.throughput > 0) {
+    console.log(`  Throughput        : ${metrics.throughput.toFixed(2)} roadmaps/week`)
+  } else {
+    console.log('  Throughput        : n/a (no completed roadmaps)')
+  }
+
+  if (metrics.wipEntries.length === 0) {
+    console.log('  WIP Age           : no items in progress')
+  } else {
+    console.log(`  WIP Age (${metrics.wipEntries.length} items) :`)
+    for (const w of metrics.wipEntries) {
+      console.log(`    - ${w.basename}: ${formatDuration(w.ageMs)}`)
+    }
+  }
+
+  console.log('─────────────────────────────────────────')
+}
+
+const cmd = new Command('metrics')
+cmd.description(t('metrics.description'))
+cmd.option('--since <period>', t('metrics.since'))
+cmd.option('--export <file>', t('metrics.export'))
+cmd.action((opts) => {
+  const logPath = path.join('docs', 'roadmaps', '.trackfw-log')
+  let transitions = parseLog(logPath)
+
+  if (transitions.length === 0) {
+    console.log(t('metrics.no_data'))
+    return
+  }
+
+  if (opts.since) {
+    let sinceMs
+    try {
+      sinceMs = parseSinceDuration(opts.since)
+    } catch (err) {
+      console.error(`invalid --since format (use: 7d, 30d, 90d): ${err.message}`)
+      process.exit(1)
+    }
+    transitions = filter(transitions, Date.now() - sinceMs)
+    if (transitions.length === 0) {
+      console.log(t('metrics.no_data'))
+      return
+    }
+  }
+
+  const m = calculate(transitions)
+  printMetrics(m)
+
+  if (opts.export) {
+    exportCSV(m, transitions, opts.export)
+    console.log(`exported to ${opts.export}`)
+  }
+})
+
+module.exports = cmd

package/src/commands/plugins.js

@@ -3,8 +3,59 @@ const { Command } = require('commander')
 const os = require('os')
 const path = require('path')
 const fs = require('fs')
+const https = require('https')
 const { t } = require('../i18n')
 
+const REGISTRY_URL = 'https://raw.githubusercontent.com/kgsaran/trackfw-plugins/main/registry.yaml'
+
+function fetchRegistry() {
+  return new Promise((resolve, reject) => {
+    https.get(REGISTRY_URL, (res) => {
+      let data = ''
+      res.on('data', chunk => { data += chunk })
+      res.on('end', () => resolve(data))
+    }).on('error', reject)
+  })
+}
+
+function parseRegistryYAML(text) {
+  const entries = []
+  let current = null
+  const lines = text.split('\n')
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed === 'plugins:') continue
+    if (trimmed.startsWith('- name:')) {
+      if (current) entries.push(current)
+      current = { name: trimmed.slice('- name:'.length).trim(), repo: '', description: '', tags: [] }
+      continue
+    }
+    if (!current) continue
+    if (trimmed.startsWith('repo:')) {
+      current.repo = trimmed.slice('repo:'.length).trim()
+    } else if (trimmed.startsWith('description:')) {
+      let desc = trimmed.slice('description:'.length).trim()
+      desc = desc.replace(/^"|"$/g, '')
+      current.description = desc
+    } else if (trimmed.startsWith('tags:')) {
+      const raw = trimmed.slice('tags:'.length).trim().replace(/^\[|\]$/g, '')
+      current.tags = raw.split(',').map(s => s.trim()).filter(Boolean)
+    }
+  }
+  if (current) entries.push(current)
+  return entries
+}
+
+function matchesKeyword(entry, kw) {
+  const lkw = kw.toLowerCase()
+  if (entry.name.toLowerCase().includes(lkw)) return true
+  if (entry.description.toLowerCase().includes(lkw)) return true
+  for (const tag of entry.tags) {
+    if (tag.toLowerCase().includes(lkw)) return true
+  }
+  return false
+}
+
 function pluginsDir() {
   return path.join(os.homedir(), '.trackfw', 'plugins')
 }
@@ -94,4 +145,26 @@ cmd.command('remove <name>')
     }
   })
 
+cmd.command('search <keyword>')
+  .description('Search the plugin registry')
+  .action(async (keyword) => {
+    let entries
+    try {
+      const body = await fetchRegistry()
+      entries = parseRegistryYAML(body).filter(e => matchesKeyword(e, keyword))
+    } catch (err) {
+      console.log(`Registry unavailable: ${err.message}`)
+      return
+    }
+    if (entries.length === 0) {
+      console.log(`No plugins found for "${keyword}"`)
+      return
+    }
+    console.log(String('NAME').padEnd(30) + String('REPO').padEnd(30) + 'DESCRIPTION')
+    console.log('-'.repeat(90))
+    for (const e of entries) {
+      console.log(e.name.padEnd(30) + e.repo.padEnd(30) + e.description)
+    }
+  })
+
 module.exports = cmd

package/src/commands/roadmap.js

@@ -1,6 +1,6 @@
 'use strict'
 const { Command } = require('commander')
-const { listRoadmaps, showRoadmap, moveRoadmap, newRoadmap } = require('../generators/roadmap')
+const { listRoadmaps, showRoadmap, moveRoadmap, newRoadmap, newRoadmapFromReq } = require('../generators/roadmap')
 const { t } = require('../i18n')
 
 const cmd = new Command('roadmap')
@@ -10,7 +10,12 @@ cmd.command('new')
   .description(t('roadmap.new.description'))
   .option('-t, --title <title>', 'Roadmap title')
   .option('-r, --req <path>', 'Path to the linked REQ')
+  .option('--from-req <path>', 'Generate roadmap with ML stubs from REQ acceptance criteria')
   .action(async (opts) => {
+    if (opts.fromReq) {
+      newRoadmapFromReq(opts.fromReq)
+      return
+    }
     const title = opts.title || 'New Roadmap'
     const reqPath = opts.req || ''
     newRoadmap(title, reqPath)