trackfw 1.0.3 → 1.1.0

package/README.md

@@ -79,12 +79,14 @@ brew install kgsaran/tap/trackfw
 go install github.com/kgsaran/trackfw/cmd/trackfw@latest
 ```
 
-### npm
+### npm (pure Node.js — no binary)
 
 ```bash
 npm install -g trackfw
 ```
 
+The npm package is pure Node.js — no compiled binary, no postinstall download. Works everywhere Node.js ≥ 18 is installed, including corporate Windows environments where unsigned `.exe` files are blocked by antivirus.
+
 ### pip
 
 ```bash
@@ -127,18 +129,25 @@ trackfw status
 | `trackfw req new "title"` | Create a REQ with guided ADR discovery |
 | `trackfw req list` | List all REQs with status |
 | `trackfw roadmap new "title"` | Create a roadmap in `backlog/` |
+| `trackfw roadmap show <name>` | Print a roadmap with its current state |
 | `trackfw roadmap move <name> <state>` | Move roadmap between states |
 | `trackfw roadmap list` | List all roadmaps grouped by state |
 | `trackfw validate` | Check governance consistency (use as CI gate) |
 | `trackfw status` | Show wip, blocked, REQs waiting on ADRs |
-| `trackfw agents` | Install Claude Code subagents |
-| `trackfw gemini` | Install Gemini CLI skills and commands |
-| `trackfw cursor` | Install Cursor rules |
-| `trackfw copilot` | Install GitHub Copilot instructions |
-| `trackfw windsurf` | Install Windsurf rules and workflows |
-| `trackfw amazonq` | Install Amazon Q Developer rules |
+| `trackfw log [--tail N]` | Show roadmap state transition history |
+| `trackfw plugins list` | List installed plugins |
+| `trackfw plugins add <user/repo>` | Install a plugin from GitHub Releases |
+| `trackfw plugins remove <name>` | Remove an installed plugin |
+| `trackfw agents` | Install Claude Code subagents *(Go binary only)* |
+| `trackfw gemini` | Install Gemini CLI skills and commands *(Go binary only)* |
+| `trackfw cursor` | Install Cursor rules *(Go binary only)* |
+| `trackfw copilot` | Install GitHub Copilot instructions *(Go binary only)* |
+| `trackfw windsurf` | Install Windsurf rules and workflows *(Go binary only)* |
+| `trackfw amazonq` | Install Amazon Q Developer rules *(Go binary only)* |
 | `trackfw version` | Print version |
 
+> **Go binary only** commands (`agents`, `gemini`, `cursor`, `copilot`, `windsurf`, `amazonq`) are available when installed via brew, `install.sh`, or `go install`. When using the npm package, AI integrations are installed through `trackfw init`.
+
 ---
 
 ## Governance chain
@@ -227,7 +236,7 @@ $ trackfw status
 
 ## AI assistant integration
 
-`trackfw init` asks which AI tools your team uses and installs native governance context for each. Commands can also be run independently.
+`trackfw init` asks which AI tools your team uses and installs native governance context for each. When using the Go binary (brew, `install.sh`, `go install`), each integration can also be run as a standalone command.
 
 | Command | Installs | Format |
 |---|---|---|

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.1.0",
   "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,31 @@
+'use strict'
+
+const { Command } = require('commander')
+const { input } = require('@inquirer/prompts')
+const generators = require('../generators/adr')
+const { t } = require('../i18n')
+
+const cmd = new Command('adr')
+cmd.description(t('adr.description'))
+
+cmd.command('new <title>')
+  .description(t('adr.new.description'))
+  .action(async (title) => {
+    const content = { title }
+    // wizard interativo se TTY
+    if (process.stdin.isTTY) {
+      content.context = await input({ message: t('adr.new.prompt.context'), default: '' })
+      content.decision = await input({ message: t('adr.new.prompt.decision'), default: '' })
+      content.consequences = await input({ message: t('adr.new.prompt.consequences'), default: '' })
+      content.alternatives = await input({ message: t('adr.new.prompt.alternatives'), default: '' })
+    }
+    await generators.newADR(content)
+  })
+
+cmd.command('list')
+  .description(t('adr.list.description'))
+  .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,174 @@
+'use strict'
+const { Command } = require('commander')
+const { t } = require('../i18n')
+
+const cmd = new Command('init')
+cmd.description(t('init.description'))
+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${t('init.success')}`)
+    return
+  }
+
+  const { input, select, checkbox } = require('@inquirer/prompts')
+
+  let projectName, projectType, frontend, pkgManager, backend, backendFramework, hooks, ci, aiTools
+
+  try {
+    projectName = await input({
+      message: t('init.prompt.projectName'),
+      default: path.basename(process.cwd()),
+    })
+
+    projectType = await select({
+      message: t('init.prompt.projectType'),
+      choices: [
+        { name: t('init.prompt.projectType_fullstack'), value: 'fullstack' },
+        { name: t('init.prompt.projectType_frontend'), value: 'frontend' },
+        { name: t('init.prompt.projectType_backend'), value: 'backend' },
+        { name: t('init.prompt.projectType_governance'), value: 'governance' },
+      ],
+    })
+
+    frontend = ''
+    pkgManager = ''
+    if (projectType === 'fullstack' || projectType === 'frontend') {
+      frontend = await select({
+        message: t('init.prompt.frontendStack'),
+        choices: [
+          { name: 'React / Next.js', value: 'react' },
+          { name: 'Vue', value: 'vue' },
+          { name: 'Angular', value: 'angular' },
+        ],
+      })
+      pkgManager = await select({
+        message: t('init.prompt.pkgManager'),
+        choices: [
+          { name: 'npm', value: 'npm' },
+          { name: 'pnpm', value: 'pnpm' },
+          { name: 'yarn', value: 'yarn' },
+          { name: 'bun', value: 'bun' },
+        ],
+      })
+    }
+
+    backend = ''
+    let backendFramework = ''
+    if (projectType === 'fullstack' || projectType === 'backend') {
+      backend = await select({
+        message: t('init.prompt.backendLang'),
+        choices: [
+          { name: 'Go', value: 'go' },
+          { name: 'Java', value: 'java' },
+          { name: 'Node.js', value: 'node' },
+          { name: 'Python', value: 'python' },
+        ],
+      })
+
+      const frameworkChoices = {
+        go: [
+          { name: 'Gin', value: 'gin' },
+          { name: 'Echo', value: 'echo' },
+          { name: 'Fiber', value: 'fiber' },
+          { name: 'Standard library (net/http)', value: 'stdlib' },
+        ],
+        java: [
+          { name: 'Spring Boot', value: 'spring-boot' },
+          { name: 'Quarkus', value: 'quarkus' },
+          { name: 'Micronaut', value: 'micronaut' },
+        ],
+        node: [
+          { name: 'Express', value: 'express' },
+          { name: 'Fastify', value: 'fastify' },
+          { name: 'NestJS', value: 'nestjs' },
+          { name: 'Koa', value: 'koa' },
+        ],
+        python: [
+          { name: 'FastAPI', value: 'fastapi' },
+          { name: 'Django', value: 'django' },
+          { name: 'Flask', value: 'flask' },
+        ],
+      }
+      backendFramework = await select({
+        message: t('init.prompt.backendFramework'),
+        choices: frameworkChoices[backend] || [],
+      })
+    }
+
+    hooks = await select({
+      message: t('init.prompt.gitHooks'),
+      choices: [
+        { name: 'husky', value: 'husky' },
+        { name: 'lefthook', value: 'lefthook' },
+        { name: 'None', value: 'none' },
+      ],
+    })
+
+    ci = await select({
+      message: t('init.prompt.ci'),
+      choices: [
+        { name: 'GitHub Actions', value: 'github-actions' },
+        { name: 'GitLab CI', value: 'gitlab-ci' },
+        { name: 'None', value: 'none' },
+      ],
+    })
+
+    aiTools = await checkbox({
+      message: t('init.prompt.aiTools'),
+      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${t('init.success')}`)
+    return
+  }
+
+  const cfg = { projectName, projectType, frontend, backend, backendFramework, 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${t('init.success')}`)
+})
+
+module.exports = cmd

package/src/commands/log.js

@@ -0,0 +1,30 @@
+'use strict'
+const { Command } = require('commander')
+const fs = require('fs')
+const path = require('path')
+const { t } = require('../i18n')
+
+const cmd = new Command('log')
+cmd.description(t('log.description'))
+cmd.option('--tail <n>', t('log.tail'), '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(t('log.empty'))
+    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(t('log.header'))
+  visible.forEach(l => console.log(l))
+})
+
+module.exports = cmd

package/src/commands/plugins.js

@@ -0,0 +1,97 @@
+'use strict'
+const { Command } = require('commander')
+const os = require('os')
+const path = require('path')
+const fs = require('fs')
+const { t } = require('../i18n')
+
+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(t('errors.downloadFailed', { status: res.status, 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(t('errors.pluginNotFound', { name }))
+  fs.unlinkSync(filePath)
+}
+
+const cmd = new Command('plugins')
+cmd.description(t('plugins.description'))
+
+cmd.command('list')
+  .description(t('plugins.list.description'))
+  .action(() => {
+    const plugins = listPlugins()
+    if (plugins.length === 0) {
+      console.log(t('plugins.list.empty'))
+      return
+    }
+    plugins.forEach(p => console.log(p))
+  })
+
+cmd.command('add <repo>')
+  .description(t('plugins.add.description'))
+  .action(async (repo) => {
+    try {
+      console.log(t('plugins.add.installing', { repo }))
+      await installPlugin(repo)
+      const name = repo.split('@')[0].split('/').pop()
+      console.log(t('plugins.add.success', { name }))
+    } catch (err) {
+      console.error(`Error: ${err.message}`)
+      process.exit(1)
+    }
+  })
+
+cmd.command('remove <name>')
+  .description(t('plugins.remove.description'))
+  .action((name) => {
+    try {
+      removePlugin(name)
+      console.log(t('plugins.remove.success', { name }))
+    } catch (err) {
+      console.error(`Error: ${err.message}`)
+      process.exit(1)
+    }
+  })
+
+module.exports = cmd

package/src/commands/req.js

@@ -0,0 +1,70 @@
+'use strict'
+const { Command } = require('commander')
+const { listREQs } = require('../generators/req')
+const { t } = require('../i18n')
+
+const cmd = new Command('req')
+cmd.description(t('req.description'))
+
+cmd.command('new <title>')
+  .description(t('req.new.description'))
+  .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: t('req.new.prompt.title'), default: title })
+      content.motivation = await input({ message: t('req.new.prompt.motivation'), 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: t('req.new.prompt.criteria'), 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(t('req.new.adrWarning', { slug: answer, message: e.message }))
+            }
+          }
+        }
+      }
+
+      content.dependsOnADRs = [...new Set(generatedADRs)]
+    }
+
+    await generators.newREQ(content)
+
+    if (content.dependsOnADRs.length > 0) {
+      console.log(`\n${t('req.new.adrDraftsCreated')}`)
+      content.dependsOnADRs.forEach(adr => console.log(`  -> ${adr}`))
+      console.log(`\n${t('req.new.resolveADRs')}`)
+    }
+  })
+
+cmd.command('list')
+  .description(t('req.list.description'))
+  .action(async () => {
+    listREQs('docs/req')
+  })
+
+module.exports = cmd

package/src/commands/roadmap.js

@@ -0,0 +1,37 @@
+'use strict'
+const { Command } = require('commander')
+const { listRoadmaps, showRoadmap, moveRoadmap, newRoadmap } = require('../generators/roadmap')
+const { t } = require('../i18n')
+
+const cmd = new Command('roadmap')
+cmd.description(t('roadmap.description'))
+
+cmd.command('new')
+  .description(t('roadmap.new.description'))
+  .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(t('roadmap.list.description'))
+  .action(async () => {
+    listRoadmaps()
+  })
+
+cmd.command('show <name>')
+  .description(t('roadmap.show.description'))
+  .action(async (name) => {
+    showRoadmap(name)
+  })
+
+cmd.command('move <name> <state>')
+  .description(t('roadmap.move.description'))
+  .action(async (name, state) => {
+    moveRoadmap(name, state)
+  })
+
+module.exports = cmd

package/src/commands/status.js

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

package/src/commands/validate.js

@@ -0,0 +1,29 @@
+'use strict'
+const { Command } = require('commander')
+const { validate } = require('../validator')
+const { t } = require('../i18n')
+
+const cmd = new Command('validate')
+cmd.description(t('validate.description'))
+cmd.action(async () => {
+  const { violations, warnings } = await validate()
+
+  if (violations.length === 0 && warnings.length === 0) {
+    console.log(t('validate.ok'))
+    return
+  }
+
+  if (violations.length > 0) {
+    console.log(`\n${t('validate.violations', { count: violations.length })}`)
+    violations.forEach(v => console.log(`  • ${v}`))
+  }
+
+  if (warnings.length > 0) {
+    console.log(`\n${t('validate.warnings', { count: warnings.length })}`)
+    warnings.forEach(w => console.log(`  • ${w}`))
+  }
+
+  if (violations.length > 0) process.exit(1)
+})
+
+module.exports = cmd