trackfw 2.0.0 → 2.1.0

package/src/commands/sync.js

@@ -0,0 +1,362 @@
+'use strict'
+
+const { Command } = require('commander')
+const https = require('https')
+const http = require('http')
+const fs = require('fs')
+const path = require('path')
+
+// ---------------------------------------------------------------------------
+// Config helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Lê um campo de trackfw.yaml (parse linha a linha, sem dependências externas).
+ * @param {string} field
+ * @returns {string}
+ */
+function readConfigField(field) {
+  try {
+    const data = fs.readFileSync('trackfw.yaml', 'utf8')
+    const prefix = field + ':'
+    for (const line of data.split('\n')) {
+      const trimmed = line.trimStart()
+      if (trimmed.startsWith(prefix)) {
+        let value = trimmed.slice(prefix.length).trim()
+        if (value.length >= 2 &&
+          ((value[0] === '"' && value[value.length - 1] === '"') ||
+           (value[0] === "'" && value[value.length - 1] === "'"))) {
+          value = value.slice(1, -1)
+        }
+        return value
+      }
+    }
+  } catch (_) { /* sem arquivo */ }
+  return ''
+}
+
+function getConfig(field, envVar) {
+  return readConfigField(field) || process.env[envVar] || ''
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Faz uma requisição HTTP/HTTPS simples com corpo JSON.
+ * @returns {Promise<{status: number, body: string}>}
+ */
+function request(url, options, bodyStr) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url)
+    const lib = parsed.protocol === 'https:' ? https : http
+    const reqOptions = {
+      hostname: parsed.hostname,
+      port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+      path: parsed.pathname + parsed.search,
+      method: options.method || 'GET',
+      headers: options.headers || {}
+    }
+    const req = lib.request(reqOptions, (res) => {
+      let data = ''
+      res.on('data', (chunk) => { data += chunk })
+      res.on('end', () => resolve({ status: res.statusCode, body: data }))
+    })
+    req.on('error', reject)
+    if (bodyStr) req.write(bodyStr)
+    req.end()
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Linear client
+// ---------------------------------------------------------------------------
+
+/**
+ * Cria issue no Linear via GraphQL.
+ * @param {string} apiKey
+ * @param {string} teamId
+ * @param {string} title
+ * @param {string} description
+ * @returns {Promise<string>} issue identifier (ex: "ENG-123")
+ */
+async function linearCreateIssue(apiKey, teamId, title, description) {
+  const query = `mutation IssueCreate($title: String!, $description: String!, $teamId: String!) {
+    issueCreate(input: {title: $title, description: $description, teamId: $teamId}) {
+      success
+      issue { id identifier }
+    }
+  }`
+  const payload = JSON.stringify({
+    query,
+    variables: { title, description, teamId }
+  })
+
+  const res = await request('https://api.linear.app/graphql', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': apiKey,
+      'Content-Length': Buffer.byteLength(payload)
+    }
+  }, payload)
+
+  if (res.status !== 200) {
+    throw new Error(`Linear: unexpected status ${res.status}: ${res.body}`)
+  }
+
+  const data = JSON.parse(res.body)
+  if (data.errors && data.errors.length > 0) {
+    throw new Error(`Linear API error: ${data.errors[0].message}`)
+  }
+  if (!data.data.issueCreate.success) {
+    throw new Error('Linear: issueCreate returned success=false')
+  }
+  return data.data.issueCreate.issue.identifier
+}
+
+// ---------------------------------------------------------------------------
+// Jira client
+// ---------------------------------------------------------------------------
+
+/**
+ * Cria issue no Jira via REST API v3.
+ * @returns {Promise<string>} issue key (ex: "ENG-456")
+ */
+async function jiraCreateIssue(baseUrl, email, token, project, title, description) {
+  const payload = JSON.stringify({
+    fields: {
+      project: { key: project },
+      summary: title,
+      description: {
+        type: 'doc',
+        version: 1,
+        content: [{
+          type: 'paragraph',
+          content: [{ type: 'text', text: description }]
+        }]
+      },
+      issuetype: { name: 'Story' }
+    }
+  })
+
+  const creds = Buffer.from(`${email}:${token}`).toString('base64')
+  const url = baseUrl.replace(/\/$/, '') + '/rest/api/3/issue'
+
+  const res = await request(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json',
+      'Authorization': `Basic ${creds}`,
+      'Content-Length': Buffer.byteLength(payload)
+    }
+  }, payload)
+
+  if (res.status !== 201) {
+    throw new Error(`Jira: unexpected status ${res.status}: ${res.body}`)
+  }
+
+  const data = JSON.parse(res.body)
+  if (!data.key) {
+    throw new Error('Jira: response missing issue key')
+  }
+  return data.key
+}
+
+// ---------------------------------------------------------------------------
+// REQ file helpers
+// ---------------------------------------------------------------------------
+
+function isStatusOpen(text) {
+  for (const line of text.split('\n')) {
+    if (line.includes('| Status:')) {
+      return line.includes('Status: Open')
+    }
+  }
+  return false
+}
+
+function extractField(text, field) {
+  const prefix = '| ' + field + ':'
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed.startsWith(prefix)) {
+      return trimmed.slice(prefix.length).trim()
+    }
+  }
+  return ''
+}
+
+function extractTitle(text) {
+  for (const line of text.split('\n')) {
+    if (line.startsWith('# REQ: ')) {
+      return line.slice('# REQ: '.length)
+    }
+  }
+  return ''
+}
+
+function extractMotivation(text) {
+  const lines = text.split('\n')
+  let inSection = false
+  const parts = []
+  for (const line of lines) {
+    if (line.startsWith('## Motivation') || line.startsWith('## Motivação')) {
+      inSection = true
+      continue
+    }
+    if (inSection) {
+      if (line.startsWith('## ')) break
+      parts.push(line)
+    }
+  }
+  return parts.join('\n').trim()
+}
+
+function injectField(text, field, value) {
+  const prefix = '| ' + field + ':'
+  const lines = text.split('\n')
+
+  // se campo já existe, substituir
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim().startsWith(prefix)) {
+      lines[i] = `| ${field}: ${value}`
+      return lines.join('\n')
+    }
+  }
+
+  // inserir após a linha com | Status:
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes('| Status:')) {
+      lines.splice(i + 1, 0, `| ${field}: ${value}`)
+      return lines.join('\n')
+    }
+  }
+
+  return text
+}
+
+// ---------------------------------------------------------------------------
+// Core sync logic
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {Function} createFn (title, desc) => Promise<issueId>
+ * @param {string} issueField
+ * @returns {Promise<Array<{reqPath, issueId, skipped, error}>>}
+ */
+async function syncToProvider(createFn, issueField) {
+  const reqDir = 'docs/req'
+  let files = []
+  try {
+    files = fs.readdirSync(reqDir)
+      .filter(f => f.endsWith('.md'))
+      .map(f => path.join(reqDir, f))
+  } catch (_) {
+    return []
+  }
+
+  const results = []
+  for (const f of files) {
+    let text
+    try {
+      text = fs.readFileSync(f, 'utf8')
+    } catch (e) {
+      results.push({ reqPath: f, skipped: false, error: e })
+      continue
+    }
+
+    // pular se não é Open
+    if (!isStatusOpen(text)) {
+      results.push({ reqPath: f, skipped: true })
+      continue
+    }
+
+    // pular se já tem issue vinculado
+    if (extractField(text, issueField) !== '') {
+      results.push({ reqPath: f, skipped: true })
+      continue
+    }
+
+    const title = extractTitle(text)
+    const desc = extractMotivation(text)
+
+    try {
+      const issueId = await createFn(title, desc)
+      const updated = injectField(text, issueField, issueId)
+      fs.writeFileSync(f, updated, 'utf8')
+      results.push({ reqPath: f, issueId, skipped: false })
+    } catch (e) {
+      results.push({ reqPath: f, skipped: false, error: e })
+    }
+  }
+  return results
+}
+
+async function syncToLinear() {
+  const apiKey = getConfig('linear_api_key', 'LINEAR_API_KEY')
+  const teamId = getConfig('linear_team_id', 'LINEAR_TEAM_ID')
+  if (!apiKey) throw new Error('Linear API key not found. Set LINEAR_API_KEY env var or linear_api_key in trackfw.yaml')
+  if (!teamId) throw new Error('Linear Team ID not found. Set LINEAR_TEAM_ID env var or linear_team_id in trackfw.yaml')
+  return syncToProvider((title, desc) => linearCreateIssue(apiKey, teamId, title, desc), 'linear_issue')
+}
+
+async function syncToJira() {
+  const baseUrl = getConfig('jira_base_url', 'JIRA_BASE_URL')
+  const email = getConfig('jira_email', 'JIRA_EMAIL')
+  const token = getConfig('jira_token', 'JIRA_TOKEN')
+  const project = getConfig('jira_project', 'JIRA_PROJECT')
+  if (!baseUrl) throw new Error('Jira base URL not found. Set JIRA_BASE_URL env var or jira_base_url in trackfw.yaml')
+  if (!email) throw new Error('Jira email not found. Set JIRA_EMAIL env var or jira_email in trackfw.yaml')
+  if (!token) throw new Error('Jira API token not found. Set JIRA_TOKEN env var or jira_token in trackfw.yaml')
+  if (!project) throw new Error('Jira project key not found. Set JIRA_PROJECT env var or jira_project in trackfw.yaml')
+  return syncToProvider((title, desc) => jiraCreateIssue(baseUrl, email, token, project, title, desc), 'jira_issue')
+}
+
+// ---------------------------------------------------------------------------
+// Commander command
+// ---------------------------------------------------------------------------
+
+const syncCmd = new Command('sync')
+  .description('Sync Open REQs to a project management tool')
+  .requiredOption('--to <target>', 'Target PM tool: linear or jira')
+  .action(async (options) => {
+    let results
+    try {
+      switch (options.to) {
+        case 'linear':
+          results = await syncToLinear()
+          break
+        case 'jira':
+          results = await syncToJira()
+          break
+        default:
+          console.error(`Unknown target "${options.to}" — use --to=linear or --to=jira`)
+          process.exit(1)
+      }
+    } catch (e) {
+      console.error(e.message)
+      process.exit(1)
+    }
+
+    if (!results || results.length === 0) {
+      console.log('No REQs found in docs/req/')
+      return
+    }
+
+    console.log(`${'REQ'.padEnd(55)} ISSUE`)
+    console.log(`${'-'.repeat(54)} ${'-'.repeat(10)}`)
+    for (const r of results) {
+      if (r.skipped) {
+        console.log(`${r.reqPath.padEnd(55)} (skipped)`)
+      } else if (r.error) {
+        console.log(`${r.reqPath.padEnd(55)} ERROR: ${r.error.message}`)
+      } else {
+        console.log(`${r.reqPath.padEnd(55)} ${r.issueId}`)
+      }
+    }
+  })
+
+module.exports = syncCmd

package/src/commands/validate.js

@@ -1,6 +1,6 @@
 'use strict'
 const { Command } = require('commander')
-const { validate } = require('../validator')
+const { validate, isLenient, lenientUntilDate } = require('../validator')
 const { t } = require('../i18n')
 
 const cmd = new Command('validate')
@@ -8,6 +8,14 @@ cmd.description(t('validate.description'))
 cmd.action(async () => {
   const { violations, warnings } = await validate()
 
+  // Informar usuário sobre modo lenient
+  if (isLenient()) {
+    const until = lenientUntilDate()
+    if (until) {
+      console.log(`[LENIENT MODE] ${t('validate.lenient_mode', { date: until })}`)
+    }
+  }
+
   if (violations.length === 0 && warnings.length === 0) {
     console.log(t('validate.ok'))
     return

package/src/generators/adr.js

@@ -52,7 +52,13 @@ async function newADR(content) {
   const consequencesSection = content.consequences || '<!-- What are the positive and negative consequences of this decision? -->'
   const alternativesSection = content.alternatives || '<!-- What other options were evaluated and why were they rejected? -->'
 
-  const body = `# ADR: ${content.title}
+  const body = `---
+status: Proposed
+date: ${date}
+author: ""
+---
+
+# ADR: ${content.title}
 
 > Date: ${date} | Status: Proposed
 
@@ -148,7 +154,13 @@ async function newADRDraft(slug) {
   const filepath = path.join(adrDir, filename)
   const title = slugToTitle(slug)
 
-  const body = `# ADR: ${title}
+  const body = `---
+status: Draft
+date: ${date}
+author: ""
+---
+
+# ADR: ${title}
 
 > Date: ${date} | Status: Draft
 

package/src/generators/init.js

@@ -28,6 +28,7 @@ async function scaffold(cfg) {
   generateValidateScript(cfg)
   generateCIWorkflow(cfg)
   generateGitHooks(cfg)
+  generateCommitMsgHook(cfg)
   generateClaudeMD(cfg)
   if (cfg.backend === 'java') generatePomXml(cfg)
   generateClaudeCommands()
@@ -39,7 +40,7 @@ async function scaffold(cfg) {
 
 function writeTrackfwConfig(cfg) {
   const today = new Date().toISOString().slice(0, 10)
-  const content = `# trackfw configuration
+  let content = `# trackfw configuration
 # generated: ${today}
 
 frontend: ${cfg.frontend || ''}
@@ -48,6 +49,7 @@ backend_framework: ${cfg.backendFramework || ''}
 pkg_manager: ${cfg.pkgManager || ''}
 hooks: ${cfg.hooks || ''}
 ci: ${cfg.ci || ''}
+require_req_in_commit: ${cfg.requireReqInCommit ? 'true' : 'false'}
 
 # governance paths (edit to match your project structure)
 adr_dirs:
@@ -56,6 +58,10 @@ req_dir: docs/req
 roadmap_dir: docs/roadmaps
 roadmap_namespacing: flat
 `
+  if (cfg.brownfieldMode) {
+    const until = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10)
+    content += `governance_mode: lenient\nlenient_until: ${until}\n`
+  }
   fs.writeFileSync('trackfw.yaml', content, 'utf8')
   console.log('  ✓ trackfw.yaml')
 }
@@ -202,6 +208,42 @@ function generateLefthookHook() {
   console.log('  ✓ lefthook.yml')
 }
 
+function generateCommitMsgHook(cfg) {
+  if (!cfg.requireReqInCommit || cfg.hooks === 'none') return
+
+  const script = [
+    '#!/bin/sh',
+    '# trackfw: require REQ reference in feat/* and fix/* branches',
+    'BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")',
+    'case "$BRANCH" in',
+    '  feat/*|fix/*)',
+    '    if ! grep -qE "^(REQ|req): " "$1"; then',
+    '      echo "ERROR: Commits in feat/* and fix/* branches require a REQ reference."',
+    '      echo "  Add to commit body: REQ: REQ-YYYY-MM-DD-your-req-slug"',
+    '      exit 1',
+    '    fi',
+    '    ;;',
+    'esac',
+    '',
+  ].join('\n')
+
+  if (cfg.hooks === 'husky') {
+    fs.mkdirSync('.husky', { recursive: true })
+    fs.writeFileSync('.husky/commit-msg', script, { encoding: 'utf8', mode: 0o755 })
+    console.log('  ✓ .husky/commit-msg')
+  } else if (cfg.hooks === 'lefthook') {
+    const lefthookPath = 'lefthook.yml'
+    const existing = fs.existsSync(lefthookPath) ? fs.readFileSync(lefthookPath, 'utf8') : ''
+    if (!existing.includes('commit-msg:')) {
+      const addition = '\ncommit-msg:\n  scripts:\n    "trackfw-req-check.sh":\n      runner: sh\n'
+      fs.writeFileSync(lefthookPath, existing + addition, 'utf8')
+    }
+    fs.mkdirSync('.lefthook/commit-msg', { recursive: true })
+    fs.writeFileSync('.lefthook/commit-msg/trackfw-req-check.sh', script, { encoding: 'utf8', mode: 0o755 })
+    console.log('  ✓ .lefthook/commit-msg/trackfw-req-check.sh')
+  }
+}
+
 // ---------------------------------------------------------------------------
 // pom.xml (Java / Spring Boot)
 // ---------------------------------------------------------------------------
@@ -698,6 +740,7 @@ module.exports = {
   generateValidateScript,
   generateCIWorkflow,
   generateGitHooks,
+  generateCommitMsgHook,
   generateClaudeMD,
   generateClaudeCommands,
   installAgents,

package/src/generators/req.js

@@ -101,7 +101,15 @@ async function newREQ(content) {
     blockedSection = lines.join('\n')
   }
 
-  const body = `# REQ: ${content.title}
+  const body = `---
+status: Open
+date: ${date}
+author: ""
+adr: ""
+roadmap: ""
+---
+
+# REQ: ${content.title}
 
 ${statusLine}
 

package/src/generators/roadmap.js

@@ -224,7 +224,14 @@ function newRoadmap(title, reqPath) {
   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
 
@@ -249,6 +256,139 @@ 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 ---
 
 /**
@@ -312,6 +452,7 @@ module.exports = {
   moveRoadmap,
   appendTransitionLog,
   newRoadmap,
+  newRoadmapFromReq,
   stateDir,
   agentStateDir,
 }