trackfw 1.1.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "1.1.0",
+  "version": "2.1.0",
   "description": "Governed software delivery framework: ADR → REQ → ROADMAP → kanban",
   "keywords": [
     "cli",

package/src/commands/adr.js

@@ -25,7 +25,7 @@ cmd.command('new <title>')
 cmd.command('list')
   .description(t('adr.list.description'))
   .action(async () => {
-    await generators.listADRs('docs/adr')
+    await generators.listADRs(require('../config').load().adrDirs[0])
   })
 
 module.exports = cmd

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/discover.js

@@ -0,0 +1,359 @@
+'use strict';
+
+const { Command } = require('commander');
+const fs = require('fs');
+const path = require('path');
+
+function scan(rootDir) {
+  const r = {
+    adrDirs: [],
+    reqDir: '',
+    roadmapDir: '',
+    roadmapNamespacing: 'flat',
+    agents: [],
+    adrCount: 0,
+    reqCount: 0,
+    roadmapCount: 0,
+    hasTrackfwYAML: false,
+    hasTrackfwLog: false,
+    governanceScore: 0,
+    hookFramework: 'none',
+    ciSystem: 'none',
+  };
+
+  // trackfw.yaml
+  r.hasTrackfwYAML = fs.existsSync(path.join(rootDir, 'trackfw.yaml'));
+
+  // REQ dir
+  for (const candidate of ['docs/req', 'docs/requisições', 'docs/requirements', 'docs/reqs']) {
+    const full = path.join(rootDir, candidate);
+    if (isDir(full)) {
+      r.reqDir = candidate;
+      r.reqCount = countMD(full);
+      break;
+    }
+  }
+
+  // ADR dirs
+  const adrRoot = path.join(rootDir, 'docs', 'adr');
+  if (isDir(adrRoot)) {
+    const subDirs = listSubDirs(adrRoot);
+    if (subDirs.length > 0) {
+      for (const sub of subDirs) {
+        const rel = 'docs/adr/' + sub;
+        r.adrDirs.push(rel);
+        r.adrCount += countMD(path.join(rootDir, rel));
+      }
+    } else {
+      r.adrDirs = ['docs/adr'];
+      r.adrCount = countMD(adrRoot);
+    }
+  }
+
+  // Roadmap dir e namespacing
+  const roadmapRoot = path.join(rootDir, 'docs', 'roadmaps');
+  if (isDir(roadmapRoot)) {
+    r.roadmapDir = 'docs/roadmaps';
+    const agentDirs = listSubDirs(roadmapRoot);
+    let byAgent = false;
+    const agents = [];
+    for (const sub of agentDirs) {
+      const wipDir = path.join(roadmapRoot, sub, 'wip');
+      const backlogDir = path.join(roadmapRoot, sub, 'backlog');
+      const doneDir = path.join(roadmapRoot, sub, 'done');
+      const abandonedDir = path.join(roadmapRoot, sub, 'abandoned');
+      const blockedDir = path.join(roadmapRoot, sub, 'blocked');
+      if (isDir(wipDir) || isDir(backlogDir) || isDir(doneDir) || isDir(abandonedDir) || isDir(blockedDir)) {
+        byAgent = true;
+        agents.push(sub);
+      }
+    }
+    if (byAgent) {
+      r.roadmapNamespacing = 'by_agent';
+      r.agents = agents;
+      for (const agent of agents) {
+        for (const state of ['backlog', 'wip', 'blocked', 'done', 'abandoned']) {
+          r.roadmapCount += countMD(path.join(roadmapRoot, agent, state));
+        }
+      }
+    } else {
+      r.roadmapNamespacing = 'flat';
+      for (const state of ['backlog', 'wip', 'blocked', 'done', 'abandoned']) {
+        r.roadmapCount += countMD(path.join(roadmapRoot, state));
+      }
+    }
+
+    r.hasTrackfwLog = fs.existsSync(path.join(roadmapRoot, '.trackfw-log'));
+  }
+
+  // Hook framework
+  if (isFile(path.join(rootDir, 'lefthook.yml')) || isFile(path.join(rootDir, '.lefthook.yml'))) {
+    r.hookFramework = 'lefthook';
+  } else if (isDir(path.join(rootDir, '.husky'))) {
+    r.hookFramework = 'husky';
+  } else if (isFile(path.join(rootDir, '.pre-commit-config.yaml'))) {
+    r.hookFramework = 'pre-commit';
+  } else {
+    r.hookFramework = 'none';
+  }
+
+  // CI
+  if (isDir(path.join(rootDir, '.github', 'workflows'))) {
+    r.ciSystem = 'github-actions';
+  } else if (isFile(path.join(rootDir, '.gitlab-ci.yml'))) {
+    r.ciSystem = 'gitlab';
+  } else {
+    r.ciSystem = 'none';
+  }
+
+  r.governanceScore = calcScore(r);
+  return r;
+}
+
+function calcScore(r) {
+  let score = 0;
+  if (r.adrCount > 0) score += 20;
+  if (r.reqCount > 0) score += 20;
+  if (r.roadmapCount > 0) score += 20;
+  if (r.hasTrackfwYAML) score += 20;
+  if (r.hasTrackfwLog) score += 20;
+  return score;
+}
+
+function generateYAML(r) {
+  let out = '# trackfw configuration — gerado por trackfw discover\n';
+  out += '# governance_mode: lenient permite validação não-bloqueante durante onboarding\n\n';
+  out += 'governance_mode: lenient\n\n';
+
+  if (r.adrDirs.length > 0) {
+    out += 'adr_dirs:\n';
+    r.adrDirs.forEach(d => { out += `  - ${d}\n`; });
+  } else {
+    out += 'adr_dirs:\n  - docs/adr\n';
+  }
+
+  out += `req_dir: ${r.reqDir || 'docs/req'}\n`;
+  out += `roadmap_dir: ${r.roadmapDir || 'docs/roadmaps'}\n`;
+  out += `roadmap_namespacing: ${r.roadmapNamespacing}\n`;
+
+  if (r.agents.length > 0) {
+    out += 'agents:\n';
+    r.agents.forEach(a => { out += `  - ${a}\n`; });
+  }
+
+  out += `hooks: ${r.hookFramework}\n`;
+  out += `ci: ${r.ciSystem}\n`;
+
+  return out;
+}
+
+function generateBootstrapLog(r, rootDir) {
+  let out = '';
+  const roadmapRoot = path.join(rootDir, r.roadmapDir);
+
+  const appendEntries = (dir, agent) => {
+    if (!isDir(dir)) return;
+    for (const entry of fs.readdirSync(dir)) {
+      if (!entry.endsWith('.md')) continue;
+      const filePath = path.join(dir, entry);
+      const stat = fs.statSync(filePath);
+      const ts = stat.mtime.toISOString().slice(0, 16).replace('T', ' ');
+      const basename = agent ? agent + '/' + entry : entry;
+      out += `${ts}  ${basename.padEnd(50)}  backlog → done\n`;
+    }
+  };
+
+  if (r.roadmapNamespacing === 'by_agent') {
+    for (const agent of r.agents) {
+      appendEntries(path.join(roadmapRoot, agent, 'done'), agent);
+    }
+  } else {
+    appendEntries(path.join(roadmapRoot, 'done'), '');
+  }
+
+  return out;
+}
+
+// installGates instala artefatos de governança: validate script, hook entry, CI workflow.
+function installGates(r, rootDir) {
+  writeValidateScript(rootDir);
+  installHook(r.hookFramework, rootDir);
+  if (r.ciSystem === 'github-actions') {
+    writeCIWorkflow(rootDir);
+  }
+}
+
+function writeValidateScript(rootDir) {
+  const scriptsDir = path.join(rootDir, 'scripts');
+  if (!isDir(scriptsDir)) fs.mkdirSync(scriptsDir, { recursive: true });
+  const content = '#!/usr/bin/env bash\nset -euo pipefail\ntrackfw validate\n';
+  const dest = path.join(scriptsDir, 'trackfw-validate.sh');
+  fs.writeFileSync(dest, content, { mode: 0o755 });
+}
+
+function installHook(framework, rootDir) {
+  const hookEntry = '\npre-commit:\n  commands:\n    trackfw-validate:\n      run: scripts/trackfw-validate.sh\n';
+  const huskyEntry = '\nscripts/trackfw-validate.sh\n';
+
+  if (framework === 'lefthook') {
+    let cfgPath = path.join(rootDir, 'lefthook.yml');
+    if (!isFile(cfgPath)) cfgPath = path.join(rootDir, '.lefthook.yml');
+    const content = fs.readFileSync(cfgPath, 'utf8');
+    if (content.includes('trackfw')) return; // idempotente
+    fs.appendFileSync(cfgPath, hookEntry, 'utf8');
+  } else if (framework === 'husky') {
+    const huskyHook = path.join(rootDir, '.husky', 'pre-commit');
+    fs.appendFileSync(huskyHook, huskyEntry, 'utf8');
+  } else {
+    console.log('⚠ No hook framework detected — skipping hook installation');
+  }
+}
+
+function writeCIWorkflow(rootDir) {
+  const workflowsDir = path.join(rootDir, '.github', 'workflows');
+  if (!isDir(workflowsDir)) fs.mkdirSync(workflowsDir, { recursive: true });
+  const dest = path.join(workflowsDir, 'trackfw-validate.yml');
+  if (isFile(dest)) return; // idempotente
+  const content = `name: trackfw validate
+on: [push, pull_request]
+jobs:
+  governance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.22"
+      - run: go install github.com/kgsaran/trackfw/cmd/trackfw@latest
+      - run: trackfw validate
+`;
+  fs.writeFileSync(dest, content, 'utf8');
+}
+
+// helpers
+function isDir(p) {
+  try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+
+function isFile(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+function countMD(dir) {
+  let n = 0;
+  function walk(d) {
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.isDirectory()) walk(path.join(d, e.name));
+      else if (e.name.endsWith('.md')) n++;
+    }
+  }
+  walk(dir);
+  return n;
+}
+
+function listSubDirs(dir) {
+  try {
+    return fs.readdirSync(dir).filter(f => {
+      try { return fs.statSync(path.join(dir, f)).isDirectory(); } catch { return false; }
+    });
+  } catch { return []; }
+}
+
+const cmd = new Command('discover');
+cmd.description('Scan the repository and auto-detect the governance structure');
+cmd.option('--init', 'generate trackfw.yaml calibrated for this project');
+cmd.option('--bootstrap-log', 'create retroactive .trackfw-log from done/ files');
+cmd.action((opts) => {
+  const cwd = process.cwd();
+  console.log(`trackfw discover — scanning ${cwd}\n`);
+
+  const r = scan(cwd);
+
+  // ADR dirs
+  if (r.adrCount > 0) {
+    const dirs = r.adrDirs.join(', ');
+    console.log(`✓ ADRs found:      ${String(r.adrCount).padEnd(4)}  (${dirs})`);
+  } else {
+    console.log('⚠ No ADRs found');
+  }
+
+  // REQ dir
+  if (r.reqCount > 0) {
+    console.log(`✓ REQs found:      ${String(r.reqCount).padEnd(4)}  (${r.reqDir})`);
+  } else {
+    console.log('⚠ No REQs found');
+  }
+
+  // Roadmaps
+  if (r.roadmapCount > 0) {
+    const mode = r.roadmapNamespacing === 'by_agent' ? 'by_agent mode' : r.roadmapNamespacing;
+    console.log(`✓ Roadmaps found:  ${String(r.roadmapCount).padEnd(4)}  (${r.roadmapDir} — ${mode})`);
+  } else {
+    console.log('⚠ No roadmaps found');
+  }
+
+  // Agents
+  if (r.agents.length > 0) {
+    console.log(`✓ Agents detected: ${r.agents.join(', ')}`);
+  }
+
+  // trackfw.yaml
+  if (!r.hasTrackfwYAML) {
+    console.log('⚠ No trackfw.yaml — run with --init to generate one');
+  } else {
+    console.log('✓ trackfw.yaml found');
+  }
+
+  // .trackfw-log
+  if (!r.hasTrackfwLog) {
+    console.log('⚠ No .trackfw-log — run with --bootstrap-log to create retroactive history');
+  } else {
+    console.log('✓ .trackfw-log found');
+  }
+
+  // hooks
+  if (r.hookFramework !== 'none') {
+    console.log(`✓ Hooks: ${r.hookFramework}`);
+  } else {
+    console.log('⚠ No hook framework detected');
+  }
+
+  // CI
+  if (r.ciSystem !== 'none') {
+    console.log(`✓ CI: ${r.ciSystem}`);
+  } else {
+    console.log('⚠ No CI system detected');
+  }
+
+  console.log(`\nGovernance Score: ${r.governanceScore}/100`);
+
+  if (opts.init) {
+    const yaml = generateYAML(r);
+    fs.writeFileSync('trackfw.yaml', yaml, 'utf8');
+    console.log('\n✓ trackfw.yaml generated');
+    try {
+      installGates(r, cwd);
+      console.log('✓ governance gates installed');
+    } catch (e) {
+      console.log(`⚠ gates install partial: ${e.message}`);
+    }
+  }
+
+  if (opts.bootstrapLog) {
+    if (!r.roadmapDir) {
+      console.error('⚠ No roadmap dir detected — cannot bootstrap log');
+      return;
+    }
+    const logContent = generateBootstrapLog(r, cwd);
+    const logPath = r.roadmapDir + '/.trackfw-log';
+    fs.appendFileSync(logPath, logContent, 'utf8');
+    console.log(`✓ bootstrap log written to ${logPath}`);
+  }
+});
+
+module.exports = cmd;
+module.exports.scan = scan;
+module.exports.generateYAML = generateYAML;
+module.exports.generateBootstrapLog = generateBootstrapLog;

package/src/commands/index.js

@@ -18,6 +18,10 @@ function createProgram() {
   program.addCommand(require('./status'))
   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 || [])) {