trackfw 1.0.3 → 1.1.0

package/src/generators/req.js

@@ -0,0 +1,239 @@
+'use strict'
+const fs = require('fs')
+const path = require('path')
+
+/**
+ * listREQs — lista arquivos .md em dir, imprimindo filename e status (coluna 60 chars).
+ * Extrai status da linha `> Date: ... | Status: ...`.
+ * Se dir não existe ou vazio: imprime "No REQs found in <dir>".
+ */
+function listREQs(dir) {
+  let files = []
+  try {
+    files = fs.readdirSync(dir).filter(f => f.endsWith('.md'))
+  } catch (_) {
+    // dir não existe
+  }
+
+  if (files.length === 0) {
+    console.log(`No REQs found in ${dir}`)
+    return
+  }
+
+  for (const filename of files) {
+    const filepath = path.join(dir, filename)
+    const status = parseREQStatus(filepath)
+    console.log(`${filename.padEnd(60)} ${status}`)
+  }
+}
+
+/**
+ * parseREQStatus — extrai o status da linha `> Date: ... | Status: ...` de um arquivo REQ.
+ * Status termina no próximo " |" ou fim da linha.
+ */
+function parseREQStatus(filepath) {
+  let content
+  try {
+    content = fs.readFileSync(filepath, 'utf8')
+  } catch (_) {
+    return 'unknown'
+  }
+
+  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>|]+$/, '')
+      return rest.trim() || 'unknown'
+    }
+  }
+  return 'unknown'
+}
+
+/**
+ * toSlug — converte string em slug kebab-case lowercase.
+ * @param {string} s
+ * @returns {string}
+ */
+function toSlug(s) {
+  return s.toLowerCase().replace(/ /g, '-')
+}
+
+/**
+ * newREQ — cria docs/req/REQ-YYYY-MM-DD-<slug>.md.
+ * @param {{ title: string, motivation?: string, criteria?: string, dependsOnADRs?: string[] }} content
+ * @returns {Promise<void>}
+ */
+async function newREQ(content) {
+  fs.mkdirSync('docs/req', { recursive: true })
+
+  const slug = toSlug(content.title)
+  const date = new Date().toISOString().slice(0, 10)
+  const filename = `docs/req/REQ-${date}-${slug}.md`
+
+  const motivationSection = content.motivation || '<!-- Why is this requirement needed? What problem does it solve? -->'
+  const criteriaSection = content.criteria || '- [ ]\n- [ ]'
+  const linkedADRSection = ''
+  const linkedRoadmapSection = ''
+
+  const dependsOnADRs = content.dependsOnADRs || []
+
+  // Linha de status — inclui contador de ADRs bloqueantes quando presente
+  let statusLine = `> Date: ${date} | Status: Open`
+  if (dependsOnADRs.length > 0) {
+    statusLine = `> Date: ${date} | Status: Open | Blocked by ADRs: ${dependsOnADRs.length}`
+  }
+
+  // Seção "Blocked by ADRs"
+  let blockedSection
+  if (dependsOnADRs.length === 0) {
+    blockedSection = '<!-- none -->'
+  } else {
+    const lines = ['<!-- ADRs in Draft status that must be Accepted before a roadmap can be created -->']
+    for (const adr of dependsOnADRs) {
+      lines.push(`- ${adr} (Draft)`)
+    }
+    blockedSection = lines.join('\n')
+  }
+
+  const body = `# REQ: ${content.title}
+
+${statusLine}
+
+## Motivation
+${motivationSection}
+
+## Acceptance Criteria
+${criteriaSection}
+
+## Linked ADR
+<!-- Reference the ADR that governs this requirement -->
+ADR: ${linkedADRSection}
+
+## Blocked by ADRs
+${blockedSection}
+
+## Linked Roadmap
+<!-- Reference the roadmap that implements this requirement -->
+Roadmap: ${linkedRoadmapSection}
+`
+
+  fs.writeFileSync(filename, body, 'utf8')
+  console.log(`created ${filename}`)
+}
+
+/**
+ * PROBES_CATALOG — catálogo de domínios técnicos detectáveis (porte exato do Go).
+ */
+const PROBES_CATALOG = [
+  {
+    domain: 'authentication',
+    keywords: ['login', 'auth', 'senha', 'password', 'sso', 'jwt', 'session', 'token', 'autenticação', 'autenticar'],
+    questions: [
+      {
+        text: 'How will users authenticate?',
+        options: [
+          { label: 'Local login (email + password)', decided: true, adrSlug: '' },
+          { label: 'SSO (Google, Azure AD, Okta...)', decided: false, adrSlug: 'sso-provider' },
+          { label: 'Both (local + SSO)', decided: false, adrSlug: 'authentication-strategy' },
+          { label: 'Not decided yet', decided: false, adrSlug: 'authentication-strategy' },
+        ],
+      },
+      {
+        text: 'How will sessions be managed?',
+        options: [
+          { label: 'JWT (stateless)', decided: true, adrSlug: '' },
+          { label: 'Server-side sessions (cookies)', decided: true, adrSlug: '' },
+          { label: 'Not decided yet', decided: false, adrSlug: 'session-management' },
+        ],
+      },
+    ],
+  },
+  {
+    domain: 'ui',
+    keywords: ['tela', 'screen', 'ui', 'frontend', 'componente', 'component', 'design', 'layout', 'interface'],
+    questions: [
+      {
+        text: 'Is there an existing UI framework or design system?',
+        options: [
+          { label: 'Yes, already chosen', decided: true, adrSlug: '' },
+          { label: 'No, need to choose a UI framework', decided: false, adrSlug: 'ui-framework' },
+          { label: 'Not relevant for this REQ', decided: true, adrSlug: '' },
+        ],
+      },
+    ],
+  },
+  {
+    domain: 'persistence',
+    keywords: ['banco', 'database', 'db', 'tabela', 'table', 'migração', 'migration', 'modelo', 'model', 'persistência', 'persist'],
+    questions: [
+      {
+        text: 'Which database engine will be used?',
+        options: [
+          { label: 'Already decided', decided: true, adrSlug: '' },
+          { label: 'Not decided yet', decided: false, adrSlug: 'database-engine' },
+        ],
+      },
+    ],
+  },
+  {
+    domain: 'api',
+    keywords: ['api', 'endpoint', 'rest', 'grpc', 'graphql', 'rota', 'route', 'http'],
+    questions: [
+      {
+        text: 'Which API protocol will be used?',
+        options: [
+          { label: 'REST (already decided)', decided: true, adrSlug: '' },
+          { label: 'gRPC (already decided)', decided: true, adrSlug: '' },
+          { label: 'GraphQL (already decided)', decided: true, adrSlug: '' },
+          { label: 'Not decided yet', decided: false, adrSlug: 'api-protocol' },
+        ],
+      },
+    ],
+  },
+  {
+    domain: 'deploy',
+    keywords: ['deploy', 'cloud', 'container', 'kubernetes', 'k8s', 'docker', 'infra', 'aws', 'gcp', 'azure'],
+    questions: [
+      {
+        text: 'Is the deployment infrastructure already defined?',
+        options: [
+          { label: 'Yes, fully defined', decided: true, adrSlug: '' },
+          { label: 'Cloud provider not decided', decided: false, adrSlug: 'cloud-provider' },
+          { label: 'Container strategy not decided', decided: false, adrSlug: 'container-strategy' },
+        ],
+      },
+    ],
+  },
+  {
+    domain: 'events',
+    keywords: ['kafka', 'fila', 'queue', 'notificação', 'notification', 'evento', 'event', 'pubsub', 'pub/sub', 'broker', 'sqs', 'redis'],
+    questions: [
+      {
+        text: 'Which event broker will be used?',
+        options: [
+          { label: 'Already decided', decided: true, adrSlug: '' },
+          { label: 'Not decided yet', decided: false, adrSlug: 'event-broker' },
+        ],
+      },
+    ],
+  },
+]
+
+/**
+ * detectDomains — retorna probes cujos keywords aparecem na intention (case-insensitive).
+ * @param {string} intention
+ * @returns {Array}
+ */
+function detectDomains(intention) {
+  const lower = intention.toLowerCase()
+  return PROBES_CATALOG.filter(probe =>
+    probe.keywords.some(kw => lower.includes(kw.toLowerCase()))
+  )
+}
+
+module.exports = { listREQs, parseREQStatus, newREQ, PROBES_CATALOG, detectDomains }

package/src/generators/roadmap.js

@@ -0,0 +1,224 @@
+'use strict'
+const fs = require('fs')
+const path = require('path')
+
+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']
+
+const TRANSITION_LOG_PATH = 'docs/roadmaps/.trackfw-log'
+
+/**
+ * listRoadmaps — lista roadmaps agrupados por estado (wip, backlog, blocked, done, abandoned).
+ * Se nenhum encontrado imprime mensagem orientando o usuário.
+ */
+function listRoadmaps() {
+  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 (files.length === 0) continue
+
+    found = true
+    console.log(`[${state}]`)
+    for (const f of files) {
+      console.log(`  ${f}`)
+    }
+  }
+
+  if (!found) {
+    console.log("Nenhum roadmap encontrado. Crie um com 'trackfw roadmap new'.")
+  }
+}
+
+/**
+ * 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.
+ */
+function showRoadmap(name) {
+  const matches = findRoadmapMatches(name)
+
+  if (matches.length === 0) {
+    console.error(`no roadmap found matching "${name}"`)
+    process.exitCode = 1
+    return
+  }
+
+  if (matches.length > 1) {
+    console.log('Multiple roadmaps found — be more specific:')
+    for (const m of matches) {
+      console.log(`  ${m}`)
+    }
+    console.error(`ambiguous match for "${name}"`)
+    process.exitCode = 1
+    return
+  }
+
+  const filepath = matches[0]
+  const basename = path.basename(filepath)
+  const state = path.basename(path.dirname(filepath)).toUpperCase()
+  const content = fs.readFileSync(filepath, 'utf8')
+
+  console.log(`── ${basename} ── [${state}] ──────────────────────\n`)
+  console.log(content)
+  console.log(`Location: ${filepath}`)
+}
+
+/**
+ * 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.
+ */
+function moveRoadmap(name, state) {
+  const targetDir = VALID_STATES[state]
+  if (!targetDir) {
+    console.error(`invalid state "${state}" — valid states: backlog, wip, blocked, done, abandoned`)
+    process.exitCode = 1
+    return
+  }
+
+  const matches = findRoadmapMatches(name)
+  if (matches.length === 0) {
+    console.error(`roadmap "${name}" not found in any state directory`)
+    process.exitCode = 1
+    return
+  }
+  if (matches.length > 1) {
+    console.log('Multiple roadmaps found — be more specific:')
+    for (const m of matches) {
+      console.log(`  ${m}`)
+    }
+    console.error(`ambiguous match for "${name}"`)
+    process.exitCode = 1
+    return
+  }
+
+  const src = matches[0]
+  const basename = path.basename(src)
+  const fromState = path.basename(path.dirname(src))
+
+  try {
+    fs.mkdirSync(targetDir, { recursive: true })
+  } catch (_) {}
+
+  const dst = path.join(targetDir, basename)
+  fs.renameSync(src, dst)
+
+  appendTransitionLog(basename, 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`
+ */
+function appendTransitionLog(basename, fromState, toState) {
+  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 hh = String(now.getHours()).padStart(2, '0')
+  const min = String(now.getMinutes()).padStart(2, '0')
+  const timestamp = `${yyyy}-${mm}-${dd} ${hh}:${min}`
+  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')
+  } catch (_) {}
+}
+
+/**
+ * newRoadmap — cria roadmap em docs/roadmaps/backlog/ROADMAP-YYYY-MM-DD-<slug>.md.
+ */
+function newRoadmap(title, reqPath) {
+  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 })
+
+  const body = `# Roadmap: ${title}
+
+> Created: ${date} | Status: backlog
+
+## Context
+<!-- What problem does this roadmap solve? Link the REQ. -->
+REQ: ${reqPath || ''}
+
+## Wave 1 — <name> (parallel MLs)
+> Dependencies: none
+
+### ML-1A — ${title}
+**Status:** pending
+**Files affected:**
+**Actions:**
+**Acceptance criteria:**
+- [ ] build passes
+- [ ] tests green
+- [ ] validate passes
+`
+
+  fs.writeFileSync(filename, body, 'utf8')
+  console.log(`✓ created ${filename}`)
+}
+
+// --- helpers ---
+
+/**
+ * findRoadmapMatches — retorna array de paths que contêm `name` (case-insensitive) em qualquer estado.
+ */
+function findRoadmapMatches(name) {
+  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
+    }
+    for (const f of files) {
+      if (f.toLowerCase().includes(nameLower) && f.endsWith('.md')) {
+        matches.push(path.join(dir, f))
+      }
+    }
+  }
+  return matches
+}
+
+/**
+ * toSlug — converte string para slug lowercase com hífens.
+ */
+function toSlug(s) {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+module.exports = {
+  VALID_STATES,
+  listRoadmaps,
+  showRoadmap,
+  moveRoadmap,
+  appendTransitionLog,
+  newRoadmap,
+}

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