trackfw 1.0.3 → 1.0.4

package/bin/trackfw

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict'
+
+require('../src/commands/index').createProgram().parseAsync(process.argv)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Governed software delivery framework: ADR → REQ → ROADMAP → kanban",
   "keywords": [
     "cli",
@@ -18,19 +18,16 @@
   "bin": {
     "trackfw": "./bin/trackfw"
   },
+  "main": "./src/commands/index.js",
   "files": [
-    "bin/"
+    "bin/",
+    "src/"
   ],
-  "engines": {
-    "node": ">=14"
+  "dependencies": {
+    "commander": "^12.0.0",
+    "@inquirer/prompts": "^5.0.0"
   },
-  "os": [
-    "linux",
-    "darwin",
-    "win32"
-  ],
-  "cpu": [
-    "x64",
-    "arm64"
-  ]
+  "engines": {
+    "node": ">=18"
+  }
 }

package/src/commands/adr.js

@@ -0,0 +1,30 @@
+'use strict'
+
+const { Command } = require('commander')
+const { input } = require('@inquirer/prompts')
+const generators = require('../generators/adr')
+
+const cmd = new Command('adr')
+cmd.description('Manage Architecture Decision Records')
+
+cmd.command('new <title>')
+  .description('Create a new ADR')
+  .action(async (title) => {
+    const content = { title }
+    // wizard interativo se TTY
+    if (process.stdin.isTTY) {
+      content.context = await input({ message: 'Context (what motivates this decision)?', default: '' })
+      content.decision = await input({ message: 'Decision (what was decided)?', default: '' })
+      content.consequences = await input({ message: 'Consequences (positive and negative)?', default: '' })
+      content.alternatives = await input({ message: 'Alternatives considered?', default: '' })
+    }
+    await generators.newADR(content)
+  })
+
+cmd.command('list')
+  .description('List all ADRs in docs/adr/')
+  .action(async () => {
+    await generators.listADRs('docs/adr')
+  })
+
+module.exports = cmd

package/src/commands/index.js

@@ -0,0 +1,28 @@
+'use strict'
+
+const { Command } = require('commander')
+const { version } = require('../../package.json')
+
+function createProgram() {
+  const program = new Command()
+  program
+    .name('trackfw')
+    .description('trackfw — governed software delivery framework\nADR → REQ → ROADMAP → kanban')
+    .version(version)
+
+  program.addCommand(require('./init'))
+  program.addCommand(require('./adr'))
+  program.addCommand(require('./req'))
+  program.addCommand(require('./roadmap'))
+  program.addCommand(require('./validate'))
+  program.addCommand(require('./status'))
+  program.addCommand(require('./log'))
+  program.addCommand(require('./plugins'))
+
+  // plugin dispatch — comandos desconhecidos tentam executar plugin
+  program.hook('preSubcommand', () => {})
+
+  return program
+}
+
+module.exports = { createProgram }

package/src/commands/init.js

@@ -0,0 +1,143 @@
+'use strict'
+const { Command } = require('commander')
+
+const cmd = new Command('init')
+cmd.description('Initialize trackfw governance in the current project')
+cmd.action(async () => {
+  const path = require('path')
+  const generators = require('../generators/init')
+
+  // Modo não-TTY: usar defaults e chamar scaffold diretamente
+  if (!process.stdin.isTTY) {
+    const cfg = {
+      projectName: path.basename(process.cwd()),
+      projectType: 'governance',
+      frontend: '',
+      backend: '',
+      pkgManager: 'npm',
+      hooks: 'none',
+      ci: 'none',
+    }
+    await generators.scaffold(cfg)
+    console.log("\n✓ trackfw initialized — run 'trackfw status' to see your governance state.")
+    return
+  }
+
+  const { input, select, checkbox } = require('@inquirer/prompts')
+
+  let projectName, projectType, frontend, pkgManager, backend, hooks, ci, aiTools
+
+  try {
+    projectName = await input({
+      message: 'Project name?',
+      default: path.basename(process.cwd()),
+    })
+
+    projectType = await select({
+      message: 'Project type?',
+      choices: [
+        { name: 'Full-stack (frontend + backend)', value: 'fullstack' },
+        { name: 'Frontend only', value: 'frontend' },
+        { name: 'Backend only', value: 'backend' },
+        { name: 'Governance only (no build stack)', value: 'governance' },
+      ],
+    })
+
+    frontend = ''
+    pkgManager = ''
+    if (projectType === 'fullstack' || projectType === 'frontend') {
+      frontend = await select({
+        message: 'Frontend stack?',
+        choices: [
+          { name: 'React / Next.js', value: 'react' },
+          { name: 'Vue', value: 'vue' },
+          { name: 'Angular', value: 'angular' },
+        ],
+      })
+      pkgManager = await select({
+        message: 'Package manager?',
+        choices: [
+          { name: 'npm', value: 'npm' },
+          { name: 'pnpm', value: 'pnpm' },
+          { name: 'yarn', value: 'yarn' },
+          { name: 'bun', value: 'bun' },
+        ],
+      })
+    }
+
+    backend = ''
+    if (projectType === 'fullstack' || projectType === 'backend') {
+      backend = await select({
+        message: 'Backend stack?',
+        choices: [
+          { name: 'Go', value: 'go' },
+          { name: 'Java / Spring Boot', value: 'java' },
+          { name: 'Node.js', value: 'node' },
+          { name: 'Python', value: 'python' },
+        ],
+      })
+    }
+
+    hooks = await select({
+      message: 'Git hooks?',
+      choices: [
+        { name: 'husky', value: 'husky' },
+        { name: 'lefthook', value: 'lefthook' },
+        { name: 'None', value: 'none' },
+      ],
+    })
+
+    ci = await select({
+      message: 'CI system?',
+      choices: [
+        { name: 'GitHub Actions', value: 'github-actions' },
+        { name: 'GitLab CI', value: 'gitlab-ci' },
+        { name: 'None', value: 'none' },
+      ],
+    })
+
+    aiTools = await checkbox({
+      message: 'Which AI assistants do you use?',
+      choices: [
+        { name: 'Claude Code', value: 'claude' },
+        { name: 'Gemini CLI', value: 'gemini' },
+        { name: 'Cursor', value: 'cursor' },
+        { name: 'GitHub Copilot', value: 'copilot' },
+        { name: 'Windsurf', value: 'windsurf' },
+        { name: 'Amazon Q Developer', value: 'amazonq' },
+      ],
+    })
+  } catch (err) {
+    // Fallback quando stdin fecha inesperadamente (ex: pipe em TTY simulado)
+    const cfg = {
+      projectName: path.basename(process.cwd()),
+      projectType: 'governance',
+      frontend: '',
+      backend: '',
+      pkgManager: 'npm',
+      hooks: 'none',
+      ci: 'none',
+    }
+    await generators.scaffold(cfg)
+    console.log("\n✓ trackfw initialized — run 'trackfw status' to see your governance state.")
+    return
+  }
+
+  const cfg = { projectName, projectType, frontend, backend, pkgManager, hooks, ci }
+  await generators.scaffold(cfg)
+
+  for (const tool of (aiTools || [])) {
+    switch (tool) {
+      case 'claude':   await generators.installAgents();  break
+      case 'gemini':   await generators.installGemini();  break
+      case 'cursor':   await generators.installCursor();  break
+      case 'copilot':  await generators.installCopilot(); break
+      case 'windsurf': await generators.installWindsurf(); break
+      case 'amazonq':  await generators.installAmazonQ(); break
+    }
+  }
+
+  console.log("\n✓ trackfw initialized — run 'trackfw status' to see your governance state.")
+})
+
+module.exports = cmd

package/src/commands/log.js

@@ -0,0 +1,29 @@
+'use strict'
+const { Command } = require('commander')
+const fs = require('fs')
+const path = require('path')
+
+const cmd = new Command('log')
+cmd.description('Show roadmap state transition history')
+cmd.option('--tail <n>', 'Number of recent transitions to show', '20')
+cmd.action(async (opts) => {
+  const tail = parseInt(opts.tail, 10)
+  const logPath = path.join('docs', 'roadmaps', '.trackfw-log')
+
+  if (!fs.existsSync(logPath)) {
+    console.log('No transitions recorded yet.')
+    return
+  }
+
+  const lines = fs.readFileSync(logPath, 'utf8')
+    .split('\n')
+    .filter(l => l.trim() !== '')
+
+  const start = Math.max(0, lines.length - tail)
+  const visible = lines.slice(start)
+
+  console.log('── trackfw log ─────────────────────────')
+  visible.forEach(l => console.log(l))
+})
+
+module.exports = cmd

package/src/commands/plugins.js

@@ -0,0 +1,96 @@
+'use strict'
+const { Command } = require('commander')
+const os = require('os')
+const path = require('path')
+const fs = require('fs')
+
+function pluginsDir() {
+  return path.join(os.homedir(), '.trackfw', 'plugins')
+}
+
+function platformOS() {
+  if (process.platform === 'win32') return 'windows'
+  if (process.platform === 'darwin') return 'darwin'
+  return 'linux'
+}
+
+function platformArch() {
+  if (process.arch === 'x64') return 'amd64'
+  return process.arch
+}
+
+function listPlugins() {
+  const dir = pluginsDir()
+  fs.mkdirSync(dir, { recursive: true })
+  return fs.readdirSync(dir).filter(f => fs.statSync(path.join(dir, f)).isFile())
+}
+
+async function installPlugin(repo) {
+  let base = repo
+  let tag = 'latest'
+  const atIdx = repo.indexOf('@')
+  if (atIdx !== -1) {
+    base = repo.slice(0, atIdx)
+    tag = repo.slice(atIdx + 1)
+  }
+  const pluginName = path.basename(base)
+  const assetName = `trackfw-plugin-${pluginName}-${platformOS()}-${platformArch()}`
+  const url = tag === 'latest'
+    ? `https://github.com/${base}/releases/latest/download/${assetName}`
+    : `https://github.com/${base}/releases/download/${tag}/${assetName}`
+
+  const res = await fetch(url)
+  if (!res.ok) throw new Error(`download failed: HTTP ${res.status} for ${url}`)
+
+  const dir = pluginsDir()
+  fs.mkdirSync(dir, { recursive: true })
+  fs.writeFileSync(path.join(dir, pluginName), Buffer.from(await res.arrayBuffer()), { mode: 0o755 })
+}
+
+function removePlugin(name) {
+  const filePath = path.join(pluginsDir(), name)
+  if (!fs.existsSync(filePath)) throw new Error(`plugin "${name}" not found`)
+  fs.unlinkSync(filePath)
+}
+
+const cmd = new Command('plugins')
+cmd.description('Manage trackfw plugins')
+
+cmd.command('list')
+  .description('List installed plugins')
+  .action(() => {
+    const plugins = listPlugins()
+    if (plugins.length === 0) {
+      console.log('No plugins installed. Use `trackfw plugins add <user/repo>` to install one.')
+      return
+    }
+    plugins.forEach(p => console.log(p))
+  })
+
+cmd.command('add <repo>')
+  .description('Install a plugin from GitHub Releases (user/repo or user/repo@tag)')
+  .action(async (repo) => {
+    try {
+      console.log(`Installing plugin from ${repo}...`)
+      await installPlugin(repo)
+      const name = repo.split('@')[0].split('/').pop()
+      console.log(`Plugin "${name}" installed successfully.`)
+    } catch (err) {
+      console.error(`Error: ${err.message}`)
+      process.exit(1)
+    }
+  })
+
+cmd.command('remove <name>')
+  .description('Remove an installed plugin')
+  .action((name) => {
+    try {
+      removePlugin(name)
+      console.log(`Plugin "${name}" removed.`)
+    } catch (err) {
+      console.error(`Error: ${err.message}`)
+      process.exit(1)
+    }
+  })
+
+module.exports = cmd

package/src/commands/req.js

@@ -0,0 +1,69 @@
+'use strict'
+const { Command } = require('commander')
+const { listREQs } = require('../generators/req')
+
+const cmd = new Command('req')
+cmd.description('Manage Requirements')
+
+cmd.command('new <title>')
+  .description('Create a new REQ')
+  .action(async (title) => {
+    const { input, select } = require('@inquirer/prompts')
+    const generators = require('../generators/req')
+    const adrGenerators = require('../generators/adr')
+
+    const content = { title, motivation: '', criteria: '', dependsOnADRs: [] }
+
+    if (process.stdin.isTTY) {
+      // Form 1 — título + motivação
+      content.title = await input({ message: 'Project requirement', default: title })
+      content.motivation = await input({ message: 'Motivation (why is this needed?)', default: '' })
+
+      // Detectar domínios com base em título + motivação
+      const probes = generators.detectDomains(content.title + ' ' + content.motivation)
+
+      // Form 2 — critérios de aceite
+      content.criteria = await input({ message: 'Acceptance Criteria (one per line)', default: '- [ ]\n- [ ]' })
+
+      // Perguntas dinâmicas por probe
+      const generatedADRs = []
+      for (const probe of probes) {
+        for (const question of probe.questions) {
+          const choices = question.options.map(opt => ({
+            name: opt.label,
+            value: opt.adrSlug || '',
+          }))
+          const answer = await select({
+            message: question.text,
+            choices,
+          })
+          if (answer) {
+            try {
+              const basename = await adrGenerators.newADRDraft(answer)
+              if (basename) generatedADRs.push(basename)
+            } catch (e) {
+              console.warn(`warning: could not create ADR draft for ${answer}: ${e.message}`)
+            }
+          }
+        }
+      }
+
+      content.dependsOnADRs = [...new Set(generatedADRs)]
+    }
+
+    await generators.newREQ(content)
+
+    if (content.dependsOnADRs.length > 0) {
+      console.log('\nADR drafts created:')
+      content.dependsOnADRs.forEach(adr => console.log(`  -> ${adr}`))
+      console.log('\nResolve these ADRs (set Status: Accepted) before creating a roadmap.')
+    }
+  })
+
+cmd.command('list')
+  .description('List all REQs in docs/req/')
+  .action(async () => {
+    listREQs('docs/req')
+  })
+
+module.exports = cmd

package/src/commands/roadmap.js

@@ -0,0 +1,36 @@
+'use strict'
+const { Command } = require('commander')
+const { listRoadmaps, showRoadmap, moveRoadmap, newRoadmap } = require('../generators/roadmap')
+
+const cmd = new Command('roadmap')
+cmd.description('Manage Roadmaps')
+
+cmd.command('new')
+  .description('Create a new roadmap from a REQ')
+  .option('-t, --title <title>', 'Roadmap title')
+  .option('-r, --req <path>', 'Path to the linked REQ')
+  .action(async (opts) => {
+    const title = opts.title || 'New Roadmap'
+    const reqPath = opts.req || ''
+    newRoadmap(title, reqPath)
+  })
+
+cmd.command('list')
+  .description('List all roadmaps grouped by state')
+  .action(async () => {
+    listRoadmaps()
+  })
+
+cmd.command('show <name>')
+  .description('Show a roadmap by name (partial match)')
+  .action(async (name) => {
+    showRoadmap(name)
+  })
+
+cmd.command('move <name> <state>')
+  .description('Move a roadmap between states (backlog|wip|blocked|done|abandoned)')
+  .action(async (name, state) => {
+    moveRoadmap(name, state)
+  })
+
+module.exports = cmd

package/src/commands/status.js

@@ -0,0 +1,11 @@
+'use strict'
+const { Command } = require('commander')
+const { getStatus } = require('../validator')
+
+const cmd = new Command('status')
+cmd.description('Show project governance status')
+cmd.action(async () => {
+  console.log(await getStatus())
+})
+
+module.exports = cmd

package/src/commands/validate.js

@@ -0,0 +1,28 @@
+'use strict'
+const { Command } = require('commander')
+const { validate } = require('../validator')
+
+const cmd = new Command('validate')
+cmd.description('Validate governance rules')
+cmd.action(async () => {
+  const { violations, warnings } = await validate()
+
+  if (violations.length === 0 && warnings.length === 0) {
+    console.log('✓ No violations found.')
+    return
+  }
+
+  if (violations.length > 0) {
+    console.log(`\n✗ Violations (${violations.length}):`)
+    violations.forEach(v => console.log(`  • ${v}`))
+  }
+
+  if (warnings.length > 0) {
+    console.log(`\n⚠ Warnings (${warnings.length}):`)
+    warnings.forEach(w => console.log(`  • ${w}`))
+  }
+
+  if (violations.length > 0) process.exit(1)
+})
+
+module.exports = cmd

package/src/generators/adr.js

@@ -0,0 +1,172 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+/**
+ * Converte uma string em slug: lowercase + espaços → hifens.
+ * @param {string} s
+ * @returns {string}
+ */
+function toSlug(s) {
+  return s.toLowerCase().replace(/ /g, '-')
+}
+
+/**
+ * Converte slug com hifens em Title Case.
+ * Ex: "authentication-strategy" → "Authentication Strategy"
+ * @param {string} slug
+ * @returns {string}
+ */
+function slugToTitle(slug) {
+  return slug
+    .split('-')
+    .map((w) => (w.length > 0 ? w[0].toUpperCase() + w.slice(1) : w))
+    .join(' ')
+}
+
+/**
+ * Retorna a data atual no formato YYYY-MM-DD.
+ * @returns {string}
+ */
+function today() {
+  return new Date().toISOString().slice(0, 10)
+}
+
+/**
+ * Cria um novo ADR em docs/adr/ADR-YYYY-MM-DD-<slug>.md.
+ * Campos vazios recebem placeholder HTML.
+ * @param {{ title: string, context?: string, decision?: string, consequences?: string, alternatives?: string }} content
+ * @returns {Promise<void>}
+ */
+async function newADR(content) {
+  fs.mkdirSync('docs/adr', { recursive: true })
+
+  const slug = toSlug(content.title)
+  const date = today()
+  const filename = `docs/adr/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}
+
+> Date: ${date} | Status: Proposed
+
+## Context
+${contextSection}
+
+## Decision
+${decisionSection}
+
+## Consequences
+${consequencesSection}
+
+## Alternatives Considered
+${alternativesSection}
+`
+
+  fs.writeFileSync(filename, body, 'utf8')
+  console.log(`created ${filename}`)
+}
+
+/**
+ * Lista todos os ADRs (.md) em dir, imprimindo filename e status (coluna 60 chars).
+ * @param {string} dir
+ * @returns {Promise<void>}
+ */
+async function listADRs(dir) {
+  if (!fs.existsSync(dir)) {
+    console.log(`No ADRs found in ${dir}`)
+    return
+  }
+
+  const files = fs.readdirSync(dir).filter((f) => f.endsWith('.md')).sort()
+
+  if (files.length === 0) {
+    console.log(`No ADRs found in ${dir}`)
+    return
+  }
+
+  for (const file of files) {
+    const filepath = path.join(dir, file)
+    const status = parseADRStatus(filepath)
+    const padded = file.padEnd(60)
+    console.log(`${padded} ${status}`)
+  }
+}
+
+/**
+ * Extrai o status de um arquivo ADR markdown.
+ * Procura pela linha "> Date: ... | Status: ..."
+ * @param {string} filepath
+ * @returns {string}
+ */
+function parseADRStatus(filepath) {
+  try {
+    const content = fs.readFileSync(filepath, 'utf8')
+    const lines = content.split('\n')
+    for (const line of lines) {
+      const idx = line.indexOf('| Status: ')
+      if (idx >= 0) {
+        let rest = line.slice(idx + '| Status: '.length)
+        rest = rest.replace(/[ >|]+$/, '').trim()
+        return rest
+      }
+    }
+  } catch (_) {
+    // ignorar erros de leitura
+  }
+  return 'unknown'
+}
+
+/**
+ * Cria um ADR com Status: Draft a partir de um slug.
+ * Idempotente: se já existe ADR-*-<slug>.md, pula e imprime mensagem.
+ * @param {string} slug
+ * @returns {Promise<string>} basename do arquivo criado
+ */
+async function newADRDraft(slug) {
+  fs.mkdirSync('docs/adr', { 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
+
+  if (existing) {
+    console.log(`skipped ${existing} (already exists)`)
+    return existing
+  }
+
+  const date = today()
+  const filename = `ADR-${date}-${slug}.md`
+  const filepath = path.join('docs/adr', filename)
+  const title = slugToTitle(slug)
+
+  const body = `# ADR: ${title}
+
+> Date: ${date} | Status: Draft
+
+## Context
+<!-- What is the situation that motivates this decision? -->
+
+## Decision
+<!-- What was decided? -->
+
+## Consequences
+<!-- What are the positive and negative consequences of this decision? -->
+
+## Alternatives Considered
+<!-- What other options were evaluated and why were they rejected? -->
+`
+
+  fs.writeFileSync(filepath, body, 'utf8')
+  console.log(`created ${filename}`)
+  return filename
+}
+
+module.exports = { newADR, listADRs, newADRDraft, toSlug }