trackfw 1.0.3 → 1.0.4

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