trackfw 3.0.0 → 4.0.0

package/src/commands/init.js

@@ -10,6 +10,7 @@ const cmd = new Command('init')
 cmd.description(t('init.description'))
 cmd.option('--ai-tools <tools>', 'Comma-separated AI tools to configure (claude,codex,gemini,antigravity,cursor,copilot,windsurf,amazonq,kiro)', '')
 cmd.option('--identity-preset <preset>', `Agent identity preset: none, neutral, ${identityStore.presetNames().join(', ')}`, 'none')
+cmd.option('--forge <value>', 'Forge platform: github, gitlab, bitbucket, azure', '')
 cmd.action(async (options, command) => {
   const os = require('os')
   const path = require('path')
@@ -29,6 +30,14 @@ cmd.action(async (options, command) => {
     }
   }
 
+  // --forge: validate unconditionally above the non-TTY early return so that
+  // an invalid value fails loudly in CI instead of silently no-op'ing.
+  const forgeChanged = command.getOptionValueSource('forge') === 'cli'
+  if (forgeChanged && options.forge) {
+    const { validateForge } = require('../forge/resolve')
+    validateForge(options.forge) // throws on invalid value
+  }
+
   // Pula o wizard de identidade inteiramente quando a flag foi passada
   // explicitamente (já tratado acima) ou quando um arquivo de identidade já
   // existe — re-executar init nunca deve sobrescrever silenciosamente uma
@@ -45,6 +54,7 @@ cmd.action(async (options, command) => {
       pkgManager: 'npm',
       hooks: 'none',
       ci: 'none',
+      forge: forgeChanged ? options.forge : '',
     }
     await generators.scaffold(cfg)
     const aiTools = String(options.aiTools || '').split(',').map(tool => tool.trim()).filter(Boolean)
@@ -62,7 +72,17 @@ cmd.action(async (options, command) => {
 
   const { input, select, checkbox } = require('@inquirer/prompts')
 
-  let projectName, projectType, frontend, pkgManager, backend, backendFramework, hooks, ci, aiTools, requireReqInCommit, scope
+  // Detect forge from the current dir to prefill the wizard default.
+  const { resolveFromRepo: resolveForgeFromRepo } = require('../forge/resolve')
+  let detectedForge = ''
+  if (!forgeChanged) {
+    try {
+      const res = resolveForgeFromRepo('', '', process.cwd())
+      if (res.source !== 'none') detectedForge = res.forge
+    } catch (_) {}
+  }
+
+  let projectName, projectType, frontend, pkgManager, backend, backendFramework, hooks, ci, forgeValue, aiTools, requireReqInCommit, scope
 
   try {
     projectName = await input({
@@ -163,6 +183,22 @@ cmd.action(async (options, command) => {
       ],
     })
 
+    if (!forgeChanged) {
+      forgeValue = await select({
+        message: t('init.prompt.forge'),
+        default: detectedForge,
+        choices: [
+          { name: 'Auto-detect (omit key)', value: '' },
+          { name: 'GitHub', value: 'github' },
+          { name: 'GitLab', value: 'gitlab' },
+          { name: 'Bitbucket', value: 'bitbucket' },
+          { name: 'Azure DevOps', value: 'azure' },
+        ],
+      })
+    } else {
+      forgeValue = options.forge
+    }
+
     requireReqInCommit = false
     if (hooks !== 'none') {
       const { confirm: confirmPrompt } = require('@inquirer/prompts')
@@ -202,6 +238,7 @@ cmd.action(async (options, command) => {
       pkgManager: 'npm',
       hooks: 'none',
       ci: 'none',
+      forge: forgeChanged ? options.forge : '',
     }
     await generators.scaffold(cfg)
     console.log(`\n${t('init.success')}`)
@@ -229,6 +266,7 @@ cmd.action(async (options, command) => {
         pkgManager: 'npm',
         hooks: 'none',
         ci: 'none',
+        forge: forgeChanged ? options.forge : '',
       })
       console.log(`\n${t('init.success')}`)
       require('../generators/init').printArchitectNextSteps(process.cwd())
@@ -236,7 +274,7 @@ cmd.action(async (options, command) => {
     }
   }
 
-  const cfg = { projectName, projectType, frontend, backend, backendFramework, pkgManager, hooks, ci, requireReqInCommit }
+  const cfg = { projectName, projectType, frontend, backend, backendFramework, pkgManager, hooks, ci, forge: forgeValue || '', requireReqInCommit }
   await generators.scaffold(cfg)
 
   for (const tool of (aiTools || [])) await generators.installIntegrationTarget(tool, process.cwd(), scope)

package/src/commands/log.js

@@ -3,13 +3,14 @@ const { Command } = require('commander')
 const fs = require('fs')
 const path = require('path')
 const { t } = require('../i18n')
+const config = require('../config')
 
 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')
+  const logPath = path.join(config.load().roadmapDir, '.trackfw-log')
 
   if (!fs.existsSync(logPath)) {
     console.log(t('log.empty'))

package/src/commands/note.js

@@ -0,0 +1,24 @@
+'use strict'
+
+const { Command } = require('commander')
+const { newNote } = require('../generators/note')
+
+function createNoteCommand() {
+  const note = new Command('note').description('Manage vault knowledge notes')
+
+  note
+    .command('new <title>')
+    .description('Create a new knowledge note in vault/notes/')
+    .action((title) => {
+      try {
+        newNote(title)
+      } catch (err) {
+        console.error(`error: ${err.message}`)
+        process.exit(1)
+      }
+    })
+
+  return note
+}
+
+module.exports = createNoteCommand()

package/src/commands/req.js

@@ -1,6 +1,6 @@
 'use strict'
 const { Command } = require('commander')
-const { listREQs } = require('../generators/req')
+const { listREQs, moveREQ } = require('../generators/req')
 const { t } = require('../i18n')
 
 const cmd = new Command('req')
@@ -67,4 +67,10 @@ cmd.command('list')
     listREQs(require('../config').load().reqDir)
   })
 
+cmd.command('move <name> <status>')
+  .description('Update a REQ status in place')
+  .action(async (name, status) => {
+    moveREQ(name, status)
+  })
+
 module.exports = cmd

package/src/commands/roadmap.js

@@ -8,15 +8,16 @@ cmd.description(t('roadmap.description'))
 
 cmd.command('new')
   .description(t('roadmap.new.description'))
-  .option('-t, --title <title>', 'Roadmap title')
+  .argument('[title]', 'Roadmap title')
+  .option('-t, --title <title>', 'Roadmap title (alias)')
   .option('-r, --req <path>', 'Path to the linked REQ')
   .option('--from-req <path>', 'Generate roadmap with ML stubs from REQ acceptance criteria')
-  .action(async (opts) => {
+  .action(async (titleArg, opts) => {
     if (opts.fromReq) {
       newRoadmapFromReq(opts.fromReq)
       return
     }
-    const title = opts.title || 'New Roadmap'
+    const title = titleArg || opts.title || 'New Roadmap'
     const reqPath = opts.req || ''
     newRoadmap(title, reqPath)
   })

package/src/commands/ship.js

@@ -0,0 +1,49 @@
+'use strict'
+
+const { Command } = require('commander')
+const { runShip } = require('../ship/runner')
+const config = require('../config')
+
+function createShipCommand() {
+  const cmd = new Command('ship')
+  cmd
+    .description(
+      'trackfw ship runs a governed delivery sequence:\n\n' +
+      '  1. Validates branch name — must match feat|fix|refactor/<slug>\n' +
+      '  2. Validates governance — REQ + roadmap in wip/ must exist\n' +
+      '     (hard gate: not affected by lenient mode or per-rule severity)\n' +
+      '  3. Detects pending squash-merges in other branches (advisory only)\n' +
+      '  4. Reviews what is staged (git status --short + git diff --cached --stat)\n' +
+      '  5. Commits with Conventional Commits format (-m is required)\n' +
+      '  6. Pushes to origin (adds -u if no upstream is configured yet)\n' +
+      '  7. Opens PR/MR via the resolved forge CLI (or prints URL if CLI is absent)\n\n' +
+      "Stage your files explicitly before running ship.\n" +
+      "This command never executes 'git add .' or 'git add -A'."
+    )
+    .option('-m, --message <msg>', 'Commit message (Conventional Commits format required)')
+    .option('--dry-run', 'Print what would be done without executing write commands', false)
+    .option('--no-pr', 'Skip PR/MR creation after push')
+    .option('--forge <forge>', 'Override forge detection (github, gitlab, bitbucket, azure)', '')
+    .action((options) => {
+      const cfg = config.load()
+      const exitCode = runShip(
+        {
+          message: options.message || '',
+          dryRun: options.dryRun || false,
+          noPR: options.pr === false,
+          forge: options.forge || '',
+        },
+        {
+          configForge: cfg.forge || '',
+          repoDir: '.',
+        }
+      )
+      if (exitCode !== 0) {
+        process.exit(exitCode)
+      }
+    })
+
+  return cmd
+}
+
+module.exports = createShipCommand()

package/src/commands/update-harness.js

@@ -0,0 +1,208 @@
+'use strict'
+
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const identityStore = require('../identity')
+const { catalog, buildPlans, IntegrationManager, globalGroupPath } = require('../integrations')
+const { tildeify, validateTargets, buildDocument, humanReport, silenceConsole } = require('../lib/update-engine')
+
+// `trackfw update harness` is the global counterpart to `trackfw update` —
+// see docs/cli-parity.md, "`trackfw update` vs `trackfw update harness`".
+// It never requires trackfw.yaml or a project cwd, and its only job is to
+// update rules/agents/skills ALREADY INSTALLED under the user's home
+// directory (~/.claude and equivalents). It never installs a target that is
+// not already present unless --install-missing is passed.
+//
+// Target universe (fixed declared order, mirrors internal/commands/
+// update_harness.go and pypi/trackfw/commands/update_harness.py):
+//   1. claude-skill      — ~/.claude/skills/trackfw/SKILL.md (legacy
+//                          governance meta-skill, previously written by the
+//                          removed `update` step "skill global"; this is the
+//                          exact target named in the frozen contract
+//                          example in docs/cli-parity.md).
+//   2..N. <tool>-agents / <tool>-skills — one target per (catalog target,
+//                          kind) pair, in catalog.targets declared order,
+//                          covering the project-independent, home-rooted
+//                          agents/skills catalog (npm/src/integrations).
+//
+// Ambiguity (reported, not resolved unilaterally — see ML-6C handoff
+// report): each <tool>-<kind> target aggregates potentially many catalog
+// items (e.g. claude-agents bundles all 12 agent personas) into a single
+// state. The contract does not specify item-level granularity for harness
+// targets, so this implementation reports the bundle-level outcome:
+//   - every item not-installed             -> missing
+//   - any item unmanaged/modified          -> skipped (never overwritten)
+//   - otherwise, at least one item written -> updated
+//   - otherwise (all current)              -> skipped
+
+// claudeSkillContent — mirrors generators/init.js:installSkillsForce
+// (npm/src/generators/init.js:1242) byte-for-byte. Duplicated here, not
+// imported, because installSkillsForce() bakes os.homedir() internally with
+// an unconditional overwrite and no dry-run mode — it cannot be reused
+// without either mutating on --dry-run or forking its signature. Reported
+// as a follow-up cleanup opportunity in the ML-6C handoff report.
+function claudeSkillContent() {
+  return `---
+name: trackfw
+description: "trackfw — Governed Software Delivery: ADR → REQ → ROADMAP → kanban"
+signature: "📦 trackfw - Governed Delivery"
+---
+
+# trackfw — Modo de Operação
+
+Este projeto usa **trackfw** para governança de entrega de software.
+Cadeia: **ADR → REQ → ROADMAP** · Estados: \`backlog / wip / blocked / done / abandoned\`
+
+## Comandos principais
+
+- \`trackfw context\` — contexto de trabalho atual (sempre execute primeiro)
+- \`trackfw status\` — todos os artefatos e estados
+- \`trackfw validate\` — valida consistência de governança
+- \`trackfw roadmap move <nome> <estado>\` — transição de estado
+- \`trackfw serve\` — board Kanban em http://localhost:4080
+
+## Protocolo de agente
+
+1. Antes de iniciar: \`trackfw context\` + ler \`docs/agents-working-context.md\`
+2. Após concluir: atualizar \`docs/agents-working-context.md\`
+3. Antes de PR: \`trackfw validate\` deve passar com zero violations
+`
+}
+
+function claudeSkillTarget(homeRoot, { dryRun, installMissing }) {
+  const id = 'claude-skill'
+  const filePath = path.join(homeRoot, '.claude', 'skills', 'trackfw', 'SKILL.md')
+  const displayPath = tildeify(homeRoot, filePath)
+  const desired = claudeSkillContent()
+
+  try {
+    const exists = fs.existsSync(filePath)
+    const actual = exists ? fs.readFileSync(filePath, 'utf8') : null
+
+    if (!exists && !installMissing) return { id, state: 'missing', path: displayPath }
+    if (exists && actual === desired) return { id, state: 'skipped', path: displayPath }
+
+    if (dryRun) return { id, state: 'updated', path: displayPath }
+
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, desired, 'utf8')
+    return { id, state: 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
+// catalogBundleTarget — one target per (tool, kind) pair at global scope.
+// Uses IntegrationManager.inspect (read-only) to classify every catalog
+// item under that pair, then only calls manager.update() for the subset
+// that needs a write — and never for --dry-run. displayPath is derived from
+// the catalog itself (globalGroupPath), not from any individual plan's
+// destination, so it never depends on catalog item iteration order (this is
+// what previously caused the claude-skills path to diverge from the Python
+// CLI — see docs/cli-parity.md, "Declared harness targets — pinned list").
+function catalogBundleTarget(toolId, kind, homeRoot, identityConfig, { dryRun, installMissing }) {
+  const id = `${toolId}-${kind}`
+  let displayPath = `~/.${toolId}`
+  try {
+    displayPath = globalGroupPath(toolId, kind)
+    const plans = buildPlans(kind, { targets: [toolId], scope: 'global', identity: identityConfig })
+    if (!plans.length) return { id, state: 'missing', path: displayPath }
+
+    const manager = new IntegrationManager({ homeRoot })
+    const statuses = manager.inspect(plans)
+
+    const allNotInstalled = statuses.every((s) => s.state === 'not-installed')
+    const anyModified = statuses.some((s) => s.state === 'modified')
+
+    if (allNotInstalled && !installMissing) return { id, state: 'missing', path: displayPath }
+
+    const toWrite = plans.filter((_, index) => {
+      const state = statuses[index].state
+      if (state === 'outdated') return true
+      if (state === 'not-installed') return installMissing
+      return false
+    })
+
+    if (!toWrite.length) {
+      if (allNotInstalled) return { id, state: 'missing', path: displayPath }
+      return { id, state: 'skipped', path: displayPath }
+    }
+
+    if (!dryRun) manager.update(toWrite)
+    return { id, state: 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
+const HARNESS_TARGET_IDS = ['claude-skill']
+for (const target of catalog.targets) {
+  HARNESS_TARGET_IDS.push(`${target.id}-agents`, `${target.id}-skills`)
+}
+
+// buildHarnessTargets — `wanted` (nullable) restricts which targets are
+// even computed/applied. This must happen HERE, not as a post-hoc filter
+// on the returned array: catalogBundleTarget/claudeSkillTarget call
+// manager.update() as a side effect, so filtering after construction would
+// still have mutated every unrequested target's files on disk.
+function buildHarnessTargets(homeRoot, identityConfig, { dryRun, installMissing }, wanted) {
+  const include = (id) => !wanted || wanted.includes(id)
+  const targets = []
+  if (include('claude-skill')) targets.push(claudeSkillTarget(homeRoot, { dryRun, installMissing }))
+  for (const target of catalog.targets) {
+    const agentsId = `${target.id}-agents`
+    const skillsId = `${target.id}-skills`
+    if (include(agentsId)) targets.push(catalogBundleTarget(target.id, 'agents', homeRoot, identityConfig, { dryRun, installMissing }))
+    if (include(skillsId)) targets.push(catalogBundleTarget(target.id, 'skills', homeRoot, identityConfig, { dryRun, installMissing }))
+  }
+  return targets
+}
+
+// run — entry point invoked by `trackfw update harness`. Deliberately a
+// plain function, not its own commander.Command: nesting a Command that
+// redeclares the SAME flag names (--json, --dry-run, --targets,
+// --install-missing) as its parent ('update') triggers a commander@12
+// parsing quirk where the flag binds to the ANCESTOR command's opts()
+// instead of the child's, silently producing `{}` in the child action no
+// matter what was passed on the command line (reproduced and confirmed in
+// isolation while building this ML — see the vault note this ML links).
+// `update.js` instead parses `update harness --json` as ITS OWN single
+// command with an optional positional `[mode]` argument, so there is only
+// ever one Option object per flag name; it calls `run(options)` here when
+// `mode === 'harness'`.
+function run(options) {
+  let wanted
+  try {
+    const requested = options.targets ? String(options.targets).split(',').map((s) => s.trim()).filter(Boolean) : []
+    wanted = validateTargets(HARNESS_TARGET_IDS, requested)
+  } catch (e) {
+    console.error(`✗ ${e.message}`)
+    process.exit(1)
+  }
+
+  const homeRoot = os.homedir()
+  const dryRun = Boolean(options.dryRun)
+  const installMissing = Boolean(options.installMissing)
+
+  // Identidade resolvida do disco antes de buildPlans — pular esta etapa
+  // reverteria silenciosamente os nomes customizados para os defaults
+  // neutros (mesma justificativa de npm/src/integrations/index.js:execute).
+  const identityConfig = identityStore.load(homeRoot)
+
+  const targets = options.json
+    ? silenceConsole(() => buildHarnessTargets(homeRoot, identityConfig, { dryRun, installMissing }, wanted))
+    : buildHarnessTargets(homeRoot, identityConfig, { dryRun, installMissing }, wanted)
+
+  const doc = buildDocument('harness', dryRun, targets)
+
+  if (options.json) {
+    console.log(JSON.stringify(doc, null, 2))
+  } else {
+    console.log(humanReport('harness', dryRun, targets))
+  }
+
+  if (doc.summary.failed > 0) process.exitCode = 1
+}
+
+module.exports = { run, HARNESS_TARGET_IDS, buildHarnessTargets, claudeSkillContent }