trackfw 7.0.0 → 7.2.0

package/src/commands/integrations.js

@@ -3,14 +3,32 @@
 const os = require('node:os')
 const { Command } = require('commander')
 const { catalog, execute, parseSurfaces, buildPlans } = require('../integrations')
+const { surfaceFor, readAsset } = require('../integrations/catalog')
+const { markdownParts, resolveAgentModel, looksLikeSuspectModelValue } = require('../integrations/render')
 const identityStore = require('../identity')
 const identityWizard = require('./identity-wizard')
 const { t } = require('../i18n')
 const { createThirdPartyCommand } = require('./thirdparty')
+const configModule = require('../config')
 
 const csv = value => String(value).split(',').map(entry => entry.trim()).filter(Boolean)
 const collect = (value, previous) => previous.concat(value)
 
+// forceHelp returns the --force help text for a mutation subcommand. The
+// three operations grant --force different powers, and a single shared
+// string previously overstated update/uninstall's reach while never
+// mentioning install's ability to adopt unmanaged bytes — that ambiguity is
+// what sent a user straight into the "Unmanaged artifact does not match a
+// trackfw template" error on `update --force` (see unmanagedArtifactError in
+// src/integrations/manager.js for the matching remediation). Mirrors
+// internal/commands/integrations_flags.go:forceHelp and
+// pypi/trackfw/integrations/command.py.
+function forceHelp(operation) {
+  if (operation === 'install') return 'Replace a modified managed artifact, or adopt/overwrite an unmanaged file already on disk'
+  if (operation === 'uninstall') return 'Remove a modified managed artifact'
+  return "Replace a modified managed artifact; never adopts unmanaged bytes — use 'install --force' for that"
+}
+
 function human(result) {
   const lines = [`Available ${result.kind} (catalog ${result.catalog_version}):`]
   for (const item of result.items) lines.push(`  ${item.id.padEnd(14)} ${item.name} — ${item.description}`)
@@ -109,6 +127,10 @@ function createLifecycleCommand(kind) {
   // internal/commands/integrations_flags.go registering `third-party` in
   // newIntegrationsLifecycleCmd.
   root.addCommand(createThirdPartyCommand(kind))
+  // "models" is agents-only: skills have no model field, and surfacing this
+  // under `trackfw skills models` would mislead users. Mirrors the identity
+  // flag gate and the Go/Python implementations.
+  if (kind === 'agents') root.addCommand(createAgentModelsCommand())
   for (const operation of ['list', 'install', 'uninstall', 'update']) {
     const mutation = operation !== 'list'
     const command = new Command(operation)
@@ -117,7 +139,7 @@ function createLifecycleCommand(kind) {
       .option('--scope <scope>', 'Installation scope: project or global (default: global; asks interactively)')
       .option('--surface <target=surface>', 'Surface selection (repeatable)', collect, [])
       .option('--json', 'Print deterministic JSON')
-      .option('--force', 'Replace or remove modified artifacts')
+      .option('--force', forceHelp(operation))
 
     // Flags de identidade são exclusivas de agents (ADR D5): skills não têm
     // identidade, e createLifecycleCommand é compartilhado entre `agents` e
@@ -199,6 +221,7 @@ function createLifecycleCommand(kind) {
         }
       }
 
+      options.agentModels = configModule.load().agentModels || {}
       const output = execute(kind, operation, options)
       console.log(options.json ? JSON.stringify(output) : human(output))
     })
@@ -207,4 +230,58 @@ function createLifecycleCommand(kind) {
   return root
 }
 
-module.exports = { createLifecycleCommand, csv, human, promptSelection, promptAmbiguousSurfaces, resolveScope }
+// createAgentModelsCommand returns the "models" subcommand of "trackfw agents".
+// Lists, for each catalog agent × target pair, the model identifier that
+// install/update would write to the generated artifact. Mirrors
+// internal/commands/agents_models.go:newAgentModelsCmd and
+// pypi/trackfw/integrations/command.py:_run_models.
+//
+// Column widths must match Go and Python for byte-identical output.
+const MODELS_AGENT_WIDTH = 14
+const MODELS_TIER_WIDTH = 8
+const MODELS_TARGET_WIDTH = 12
+const MODELS_NA = '—'
+
+function pad(s, width) {
+  return String(s).padEnd(width)
+}
+
+function createAgentModelsCommand() {
+  const cmd = new Command('models')
+    .description('Show the resolved model each agent uses per target')
+  cmd.action(() => {
+    const agentModels = configModule.load().agentModels || {}
+
+    // Warnings: emit once per suspect tier, sorted, to stderr.
+    const suspectTiers = Object.keys(agentModels)
+      .filter(tier => looksLikeSuspectModelValue(agentModels[tier]))
+      .sort()
+    for (const tier of suspectTiers) {
+      process.stderr.write(
+        `WARN: agent_models.${tier} = ${JSON.stringify(agentModels[tier])} — not a version string and not a claude- model ID; will be written literally and may produce an invalid model identifier\n`
+      )
+    }
+
+    const lines = []
+    lines.push(`${pad('AGENT', MODELS_AGENT_WIDTH)} ${pad('TIER', MODELS_TIER_WIDTH)} ${pad('TARGET', MODELS_TARGET_WIDTH)} RESOLVED`)
+
+    for (const agent of catalog.agents) {
+      const source = readAsset(agent)
+      const parts = markdownParts(source)
+      const tier = parts.model || 'sonnet'
+
+      for (const target of catalog.targets) {
+        const surface = surfaceFor(target, null, 'agents')
+        const representation = surface.capabilities.agents.representation
+        const { resolved, present } = resolveAgentModel(tier, representation, target.id, agentModels)
+        const display = present ? resolved : MODELS_NA
+        lines.push(`${pad(agent.id, MODELS_AGENT_WIDTH)} ${pad(tier, MODELS_TIER_WIDTH)} ${pad(target.id, MODELS_TARGET_WIDTH)} ${display}`)
+      }
+    }
+
+    console.log(lines.join('\n'))
+  })
+  return cmd
+}
+
+module.exports = { createLifecycleCommand, createAgentModelsCommand, csv, human, promptSelection, promptAmbiguousSurfaces, resolveScope }

package/src/commands/push.js

@@ -0,0 +1,51 @@
+'use strict'
+
+const { Command } = require('commander')
+const { runPush } = require('../push/runner')
+const config = require('../config')
+
+function createPushCommand() {
+  const cmd = new Command('push')
+  cmd
+    .description(
+      'trackfw push pushes already-created commits without committing and without opening a PR/MR.\n\n' +
+      '  1. Validates branch name — must match feat|fix|refactor|chore|docs/<slug>\n' +
+      '  2. Validates governance — REQ + roadmap in wip/ must exist for feat/fix/refactor branches\n' +
+      '     (hard gate: not affected by lenient mode or per-rule severity); chore/docs branches skip\n' +
+      '     this check, mirroring \'trackfw commit\'\n' +
+      '  3. Detects pending squash-merges in other branches (advisory only)\n' +
+      '  4. Pushes to origin (adds -u if no upstream is configured yet)\n\n' +
+      'push never commits and never opens a PR/MR.\n' +
+      'Does not accept -m. If you have not committed yet, run \'trackfw commit -m "..."\' first.\n\n' +
+      'Compositional vocabulary:\n' +
+      '  trackfw commit -m "..."   commits\n' +
+      '  trackfw push              pushes\n' +
+      '  trackfw ship -m "..."     commit + push + PR (composition)\n\n' +
+      "--force-with-lease pushes with 'git push --force-with-lease' instead of a plain push — for\n" +
+      'the post-rebase case, where a plain push is rejected. It only runs when the branch already\n' +
+      "has an open PR/MR (verified via the resolved forge CLI): the safe path is always to open the\n" +
+      'PR first.'
+    )
+    .option('--dry-run', 'Print what would be done without executing write commands', false)
+    .option('--force-with-lease', 'Governed force-push (git push --force-with-lease); requires an open PR/MR on this branch', false)
+    .action((options) => {
+      const cfg = config.load()
+      const exitCode = runPush(
+        {
+          dryRun: options.dryRun || false,
+          forceWithLease: options.forceWithLease || false,
+        },
+        {
+          configForge: cfg.forge || '',
+          repoDir: '.',
+        }
+      )
+      if (exitCode !== 0) {
+        process.exit(exitCode)
+      }
+    })
+
+  return cmd
+}
+
+module.exports = createPushCommand()

package/src/commands/release.js

@@ -0,0 +1,47 @@
+'use strict'
+
+const { Command } = require('commander')
+const { runReleaseTag } = require('../release/runner')
+const config = require('../config')
+
+function createReleaseCommand() {
+  const cmd = new Command('release')
+  cmd.description('Governed release operations')
+
+  const tagCmd = new Command('tag')
+  tagCmd
+    .description(
+      'Create and publish an annotated release tag.\n\n' +
+      "It exists because 'trackfw ship' only pushes branches — tag is not a branch operation,\n" +
+      "and ship's governance gate (\"REQ + roadmap in wip/\") does not apply to release. See\n" +
+      'ADR-2026-08-19-caminho-governado-para-push-forcado-e-tag-de-release.md.\n\n' +
+      'Every precondition below refuses with a message naming what to fix — this command\n' +
+      'never guesses:\n' +
+      '  1. Working tree must be clean.\n' +
+      '  2. The default branch (main/master), if checked out locally, must be up to date with origin.\n' +
+      '  3. The 4 version files must all match <version> exactly.\n' +
+      '  4. CHANGELOG.md must have a "## [<version>] - YYYY-MM-DD" section.\n' +
+      '  5. The tag must not already exist, locally or on origin.\n' +
+      '  6. The GitHub CLI (gh) must be available and authenticated — release tag currently\n' +
+      '     only supports GitHub; other forges are refused with instructions to push the tag\n' +
+      '     manually.\n\n' +
+      'On success, it publishes the tag via two GitHub API calls (POST git/tags then POST\n' +
+      'git/refs), preserving the annotation.'
+    )
+    .argument('<version>', 'Version to tag (with or without a leading "v")')
+    .action((version) => {
+      const cfg = config.load()
+      const exitCode = runReleaseTag(version, {
+        configForge: cfg.forge || '',
+        repoDir: '.',
+      })
+      if (exitCode !== 0) {
+        process.exit(exitCode)
+      }
+    })
+
+  cmd.addCommand(tagCmd)
+  return cmd
+}
+
+module.exports = createReleaseCommand()

package/src/commands/serve.js

@@ -13,6 +13,48 @@ const { handleAttention } = require('../serve/api_attention')
 
 const STATIC_DIR = path.join(__dirname, '..', 'serve', 'static')
 
+// Aviso pinado, byte-idêntico entre os 3 runtimes (Go, Node.js, Python) — ver
+// docs/cli-parity.md "`trackfw serve` — endereço de escuta, `--host` e
+// aviso de exposição". Emitido quando --host resolve para uma interface
+// diferente de loopback.
+function exposureWarning(host, port) {
+  return `WARNING: trackfw serve is binding to ${host}:${port} — the governance chain (ADRs, REQs, roadmaps) will be readable without authentication by any device that can reach it.`
+}
+
+// Texto de --help pinado, byte-idêntico entre os 3 runtimes.
+const SERVE_HOST_FLAG_HELP = 'Host to bind to (loopback only by default; use 0.0.0.0 to expose on the network)'
+
+// Espelha internal/serve/serve.go IsLoopbackHost — 'localhost' ou IP loopback
+// (IPv4 127.0.0.0/8 inteiro, ou IPv6 ::1), igual a net.IP.IsLoopback() do Go
+// e ipaddress.ip_address(...).is_loopback do Python.
+function isLoopbackHost(host) {
+  const net = require('net')
+  if (host === 'localhost') return true
+  if (net.isIPv4(host)) {
+    return host.split('.')[0] === '127'
+  }
+  if (net.isIPv6(host)) {
+    return host === '::1' || host === '0:0:0:0:0:0:0:1'
+  }
+  return false
+}
+
+// Espelha internal/serve/serve.go DisplayURL — URL a imprimir e a abrir no
+// browser. 'localhost' é mantido só para 'localhost' ou IPv4 loopback
+// (127.0.0.0/8), para não mudar a saída do caso comum; hosts IPv6 usam
+// colchetes; qualquer outro host é impresso como está.
+function displayUrl(host, port) {
+  const net = require('net')
+  if (host === 'localhost') return `http://localhost:${port}`
+  if (net.isIPv4(host)) {
+    return host.split('.')[0] === '127' ? `http://localhost:${port}` : `http://${host}:${port}`
+  }
+  if (net.isIPv6(host)) {
+    return `http://[${host}]:${port}`
+  }
+  return `http://${host}:${port}`
+}
+
 // Mapa de extensão → Content-Type
 const MIME = {
   '.html': 'text/html; charset=utf-8',
@@ -141,19 +183,25 @@ function createServeCommand() {
   cmd
     .description('Inicia o servidor HTTP do trackfw dashboard (kanban + chain + metrics)')
     .option('--port <port>', 'Porta do servidor', '8080')
+    .option('--host <host>', SERVE_HOST_FLAG_HELP, '127.0.0.1')
     .option('--no-open', 'Não abrir o browser automaticamente')
     .action((opts) => {
       const cfg = config.load()
       const port = parseInt(opts.port, 10) || 8080
+      const host = opts.host
 
       const server = createServer(cfg, port)
 
-      server.listen(port, '127.0.0.1', () => {
-        console.log(`trackfw serve: http://localhost:${port}`)
+      if (!isLoopbackHost(host)) {
+        console.error(exposureWarning(host, port))
+      }
+
+      server.listen(port, host, () => {
+        const url = displayUrl(host, port)
+        console.log(`trackfw serve: ${url}`)
 
         if (opts.open !== false) {
           // Tentar abrir o browser
-          const url = `http://localhost:${port}`
           const { exec } = require('child_process')
           const platform = process.platform
           let openCmd
@@ -187,4 +235,4 @@ function createServeCommand() {
   return cmd
 }
 
-module.exports = { createServeCommand, createServer }
+module.exports = { createServeCommand, createServer, isLoopbackHost, displayUrl }

package/src/commands/ship.js

@@ -15,16 +15,23 @@ function createShipCommand() {
       "     this check, mirroring 'trackfw commit'\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' +
+      '  5. Commits with Conventional Commits format (-m is required, unless nothing is staged\n' +
+      '     and --force-with-lease is set — see below)\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'."
+      "This command never executes 'git add .' or 'git add -A'.\n\n" +
+      "--force-with-lease pushes with 'git push --force-with-lease' instead of a plain push —\n" +
+      "for the post-rebase case, where a plain push is rejected. It only runs when the branch\n" +
+      "already has an open PR/MR (verified via the resolved forge CLI): the safe path is\n" +
+      "always to open the PR first. When nothing is staged, it pushes existing commits\n" +
+      "without requiring -m."
     )
     .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)', '')
+    .option('--force-with-lease', 'Governed force-push (git push --force-with-lease); requires an open PR/MR on this branch', false)
     .action((options) => {
       const cfg = config.load()
       const exitCode = runShip(
@@ -33,6 +40,7 @@ function createShipCommand() {
           dryRun: options.dryRun || false,
           noPR: options.pr === false,
           forge: options.forge || '',
+          forceWithLease: options.forceWithLease || false,
         },
         {
           configForge: cfg.forge || '',