trackfw 1.1.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/config/index.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function defaults() {
+  return {
+    adrDirs: ['docs/adr'],
+    reqDir: 'docs/req',
+    roadmapDir: 'docs/roadmaps',
+    roadmapNamespacing: 'flat',
+    agents: [],
+    governanceMode: '',
+    lenientUntil: '',
+    wipLimit: 1,
+    wipBySquad: false,
+    requireReqInCommit: false,
+  };
+}
+
+let _instance = null;
+
+function load(cwd) {
+  if (_instance) return _instance;
+  _instance = defaults();
+  const yamlPath = path.join(cwd || process.cwd(), 'trackfw.yaml');
+  if (!fs.existsSync(yamlPath)) return _instance;
+  const content = fs.readFileSync(yamlPath, 'utf8');
+  parse(content, _instance);
+  return _instance;
+}
+
+function reset() {
+  _instance = null;
+}
+
+function parse(content, cfg) {
+  const lines = content.split('\n');
+  let inAdrDirs = false;
+  let inAgents = false;
+  let adrDirs = [];
+  let agents = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+
+    if (inAdrDirs) {
+      if (line.startsWith('- ')) {
+        adrDirs.push(line.slice(2).trim());
+        continue;
+      }
+      inAdrDirs = false;
+      if (adrDirs.length) cfg.adrDirs = adrDirs;
+    }
+    if (inAgents) {
+      if (line.startsWith('- ')) {
+        agents.push(line.slice(2).trim());
+        continue;
+      }
+      inAgents = false;
+      if (agents.length) cfg.agents = agents;
+    }
+
+    const colonIdx = line.indexOf(':');
+    if (colonIdx < 0) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const val = line.slice(colonIdx + 1).trim();
+    if (!key) continue;
+
+    switch (key) {
+      case 'adr_dirs': inAdrDirs = true; adrDirs = []; break;
+      case 'req_dir': cfg.reqDir = val; break;
+      case 'roadmap_dir': cfg.roadmapDir = val; break;
+      case 'roadmap_namespacing': cfg.roadmapNamespacing = val; break;
+      case 'agents': inAgents = true; agents = []; break;
+      case 'governance_mode': cfg.governanceMode = val; break;
+      case 'lenient_until': cfg.lenientUntil = val; break;
+      case 'wip_limit': { const n = parseInt(val, 10); if (n > 0) cfg.wipLimit = n; break; }
+      case 'wip_by_squad': cfg.wipBySquad = val === 'true'; break;
+      case 'require_req_in_commit': cfg.requireReqInCommit = val === 'true'; break;
+    }
+  }
+
+  // flush pending lists at EOF
+  if (inAdrDirs && adrDirs.length) cfg.adrDirs = adrDirs;
+  if (inAgents && agents.length) cfg.agents = agents;
+}
+
+const NAMESPACING_FLAT = 'flat'
+const NAMESPACING_BY_AGENT = 'by_agent'
+
+module.exports = { load, reset, defaults, NAMESPACING_FLAT, NAMESPACING_BY_AGENT };

package/src/generators/adr.js

@@ -40,18 +40,25 @@ function today() {
  * @returns {Promise<void>}
  */
 async function newADR(content) {
-  fs.mkdirSync('docs/adr', { recursive: true })
+  const adrDir = require('../config').load().adrDirs[0]
+  fs.mkdirSync(adrDir, { recursive: true })
 
   const slug = toSlug(content.title)
   const date = today()
-  const filename = `docs/adr/ADR-${date}-${slug}.md`
+  const filename = `${adrDir}/ADR-${date}-${slug}.md`
 
   const contextSection = content.context || '<!-- What is the situation that motivates this decision? -->'
   const decisionSection = content.decision || '<!-- What was decided? -->'
   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
 
@@ -129,10 +136,10 @@ function parseADRStatus(filepath) {
  * @returns {Promise<string>} basename do arquivo criado
  */
 async function newADRDraft(slug) {
-  fs.mkdirSync('docs/adr', { recursive: true })
+  const adrDir = require('../config').load().adrDirs[0]
+  fs.mkdirSync(adrDir, { recursive: true })
 
   // Verificar idempotência: buscar arquivo existente com o mesmo slug
-  const adrDir = 'docs/adr'
   const existing = fs.existsSync(adrDir)
     ? fs.readdirSync(adrDir).find((f) => f.match(new RegExp(`^ADR-.*-${slug}\\.md$`)))
     : null
@@ -144,10 +151,16 @@ async function newADRDraft(slug) {
 
   const date = today()
   const filename = `ADR-${date}-${slug}.md`
-  const filepath = path.join('docs/adr', filename)
+  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,7 +49,19 @@ 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:
+  - docs/adr
+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')
 }
@@ -195,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)
 // ---------------------------------------------------------------------------
@@ -691,6 +740,7 @@ module.exports = {
   generateValidateScript,
   generateCIWorkflow,
   generateGitHooks,
+  generateCommitMsgHook,
   generateClaudeMD,
   generateClaudeCommands,
   installAgents,

package/src/generators/req.js

@@ -69,11 +69,12 @@ function toSlug(s) {
  * @returns {Promise<void>}
  */
 async function newREQ(content) {
-  fs.mkdirSync('docs/req', { recursive: true })
+  const reqDir = require('../config').load().reqDir
+  fs.mkdirSync(reqDir, { recursive: true })
 
   const slug = toSlug(content.title)
   const date = new Date().toISOString().slice(0, 10)
-  const filename = `docs/req/REQ-${date}-${slug}.md`
+  const filename = `${reqDir}/REQ-${date}-${slug}.md`
 
   const motivationSection = content.motivation || '<!-- Why is this requirement needed? What problem does it solve? -->'
   const criteriaSection = content.criteria || '- [ ]\n- [ ]'
@@ -100,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}