trackfw 2.16.0 → 3.0.0

package/README.md

@@ -363,6 +363,15 @@ are never replaced or removed unless `--force` is explicit, and unmanaged files
 are never removed. Known historical templates are adopted without overwriting;
 unknown unmanaged content cannot be adopted by `update`, even with `--force`.
 
+Without `--scope`, `install`/`update` default to `global` (`~/.claude/...`)
+when stdin is not a TTY, and otherwise prompt interactively with `global`
+pre-selected — the resolved destination paths are printed before anything is
+written. `uninstall` is the one exception: without `--scope` and without a
+TTY it fails instead of guessing, since silently defaulting a destructive
+operation could delete artifacts from the user's home directory. `list` never
+prompts and always assumes `global` unless `--scope` is given, so it reports
+the same destinations `install` actually wrote to.
+
 The 10 roles installed for each tool: **architect · backend · frontend · qa · infra · security · code-quality · dba · ux · data**
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "2.16.0",
+  "version": "3.0.0",
   "description": "Governance CLI for AI-native software delivery and AI coding agents. Enforces traceability: ADR → REQ → ROADMAP → kanban. Native support for Codex, Claude Code, Gemini CLI, Cursor, Copilot, Windsurf, and Amazon Q.",
   "keywords": [
     "cli",

package/src/commands/init.js

@@ -4,6 +4,7 @@ const { t } = require('../i18n')
 const identityStore = require('../identity')
 const identityWizard = require('./identity-wizard')
 const { resolveIdentityPreset, identityFileExists } = identityWizard
+const { resolveScope } = require('./integrations')
 
 const cmd = new Command('init')
 cmd.description(t('init.description'))
@@ -48,9 +49,11 @@ cmd.action(async (options, command) => {
     await generators.scaffold(cfg)
     const aiTools = String(options.aiTools || '').split(',').map(tool => tool.trim()).filter(Boolean)
     const supported = new Set(['claude', 'codex', 'gemini', 'antigravity', 'cursor', 'copilot', 'windsurf', 'amazonq', 'kiro'])
+    // Sem TTY, o escopo nunca é perguntado: default `global` (ADR D1/D4).
+    const scope = await resolveScope({}, { interactive: false })
     for (const tool of aiTools) {
       if (!supported.has(tool)) throw new Error(`Unsupported AI tool: ${tool}`)
-      await generators.installIntegrationTarget(tool, process.cwd())
+      await generators.installIntegrationTarget(tool, process.cwd(), scope)
     }
     console.log(`\n${t('init.success')}`)
     require('../generators/init').printArchitectNextSteps(process.cwd())
@@ -59,7 +62,7 @@ cmd.action(async (options, command) => {
 
   const { input, select, checkbox } = require('@inquirer/prompts')
 
-  let projectName, projectType, frontend, pkgManager, backend, backendFramework, hooks, ci, aiTools, requireReqInCommit
+  let projectName, projectType, frontend, pkgManager, backend, backendFramework, hooks, ci, aiTools, requireReqInCommit, scope
 
   try {
     projectName = await input({
@@ -184,6 +187,11 @@ cmd.action(async (options, command) => {
       ],
     })
 
+    // Escopo de instalação (ADR D4): só pergunta quando há de fato algo para
+    // instalar. `resolveScope` é a mesma função (mesmas strings/mecanismo de
+    // prompt) usada por `agents install` / `skills install`.
+    scope = aiTools.length ? await resolveScope({}, { interactive: true }) : 'global'
+
   } catch (err) {
     // Fallback quando stdin fecha inesperadamente (ex: pipe em TTY simulado)
     const cfg = {
@@ -231,7 +239,7 @@ cmd.action(async (options, command) => {
   const cfg = { projectName, projectType, frontend, backend, backendFramework, pkgManager, hooks, ci, requireReqInCommit }
   await generators.scaffold(cfg)
 
-  for (const tool of (aiTools || [])) await generators.installIntegrationTarget(tool, process.cwd())
+  for (const tool of (aiTools || [])) await generators.installIntegrationTarget(tool, process.cwd(), scope)
 
   console.log(`\n${t('init.success')}`)
   require('../generators/init').printArchitectNextSteps(process.cwd())

package/src/commands/integrations.js

@@ -2,7 +2,7 @@
 
 const os = require('node:os')
 const { Command } = require('commander')
-const { catalog, execute, parseSurfaces } = require('../integrations')
+const { catalog, execute, parseSurfaces, buildPlans } = require('../integrations')
 const identityStore = require('../identity')
 const identityWizard = require('./identity-wizard')
 const { t } = require('../i18n')
@@ -27,6 +27,66 @@ async function promptSelection(kind, options, prompts = require('@inquirer/promp
   options.items = await checkbox({ message: `${kind} to manage`, choices: catalog[kind].map(item => ({ name: item.name, value: item.id })), required: true })
 }
 
+// resolveScope decide o escopo de instalação (ADR-2026-07-25-escopo-de-
+// instalacao-selecionavel-para-agents-e-skills):
+//
+//  - `--scope` explícito (`options.scope !== undefined`) é sempre respeitado
+//    e nunca dispara prompt — apenas validado contra os valores aceitos. A
+//    detecção é por *flag-set* (undefined), nunca por comparação de valor,
+//    para não confundir um `--scope project` explícito com o default.
+//  - Sem flag e `interactive` desligado (comando `list`, D6): default
+//    `global`, nunca lança erro (list nunca é destrutivo).
+//  - Sem flag e stdin não é um TTY (D1): default `global` — exceto para
+//    `uninstall` (ADR D8), que falha exigindo `--scope` explícito. D1 foi
+//    aprovado no enquadramento "onde instalar"; aplicá-lo a uninstall
+//    permitiria que um script de CI que hoje limpa `.claude/agents/` do
+//    repositório passasse a apagar arquivos do home do usuário.
+//  - Sem flag, `interactive` ligado e TTY (D2): pergunta o escopo, com
+//    `global` pré-selecionado, para toda operação incluindo uninstall — o
+//    usuário vê a escolha antes de destruir. Usa o mesmo mecanismo de prompt
+//    (`@inquirer/prompts`) já empregado por `identity-wizard.js`, sem
+//    dependência nova.
+//
+// `interactive` é passado pelo chamador como `false` para `list` — comando de
+// leitura que nunca deve bloquear em prompt, mas que ainda assim precisa do
+// mesmo default `global` para não reportar deployments divergentes dos que o
+// `install` gravou (D6). `operation` identifica install/update/uninstall/list
+// para o branch de D8. Espelha
+// internal/commands/integrations_flags.go:resolveScope.
+async function resolveScope(options, { interactive = true, operation, prompts = require('@inquirer/prompts') } = {}) {
+  if (options.scope !== undefined) {
+    if (options.scope !== 'project' && options.scope !== 'global') throw new Error(`Unsupported scope: ${options.scope}`)
+    return options.scope
+  }
+  if (!interactive) return 'global'
+  if (!process.stdin.isTTY) {
+    if (operation === 'uninstall') throw new Error('uninstall requires --scope in non-interactive mode')
+    return 'global'
+  }
+  const { select } = prompts
+  return select({
+    message: 'Onde instalar os artefatos?',
+    default: 'global',
+    choices: [
+      { name: 'Pasta do usuário (~/.claude) — vale para todos os projetos', value: 'global' },
+      { name: 'Este projeto (.claude) — apenas neste repositório', value: 'project' },
+    ],
+  })
+}
+
+// printResolvedDestinations imprime, antes da gravação, o escopo escolhido e
+// os caminhos de destino que serão afetados (ADR D5) — nunca em modo --json,
+// que já é o canal determinístico consumido por scripts. Recalcula os planos
+// via buildPlans (sem side effect) só para enumerar destinos; a gravação em
+// si acontece depois, em execute().
+function printResolvedDestinations(kind, options) {
+  if (options.json) return
+  const plans = buildPlans(kind, options)
+  const destinations = [...new Set(plans.map(plan => plan.destination))].sort()
+  console.log(`Destino (${options.scope}):`)
+  for (const destination of destinations) console.log(`  ${destination}`)
+}
+
 async function promptAmbiguousSurfaces(kind, options, prompts = require('@inquirer/prompts')) {
   const { select } = prompts
   const selected = parseSurfaces(options.surfaces)
@@ -47,7 +107,7 @@ function createLifecycleCommand(kind) {
     const command = new Command(operation)
       .option('--targets <targets>', 'Comma-separated target CLIs', csv)
       .option('--items <items>', `Comma-separated ${kind} IDs`, csv)
-      .option('--scope <scope>', 'Installation scope: project or global', 'project')
+      .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')
@@ -65,7 +125,14 @@ function createLifecycleCommand(kind) {
 
     command.action(async (options, cmd) => {
       options.surfaces = options.surface || []
-      if (options.scope !== 'project' && options.scope !== 'global') throw new Error(`Unsupported scope: ${options.scope}`)
+
+      // Gate de escopo (ADR D1-D3, D6): resolvido incondicionalmente aqui,
+      // antes de qualquer seleção de targets/surfaces ou construção de
+      // planos, e independentemente de --targets já ter sido informado —
+      // caso contrário o caso mais comum (`agents install --targets claude`)
+      // nunca passaria por prompt algum. `list` (mutation === false) nunca
+      // pergunta (comando de leitura), apenas adota o default `global`.
+      options.scope = await resolveScope(options, { interactive: mutation, operation })
 
       // O booleano de --identity nunca deve chegar a execute()/buildPlans()
       // sob a chave "identity" — essa chave ali é reservada para uma Config
@@ -112,6 +179,10 @@ function createLifecycleCommand(kind) {
         }
       }
 
+      // D5: caminhos de destino impressos antes da gravação, apenas para
+      // operações de mutação (install/update/uninstall) e fora de --json.
+      if (mutation) printResolvedDestinations(kind, options)
+
       const output = execute(kind, operation, options)
       console.log(options.json ? JSON.stringify(output) : human(output))
     })
@@ -120,4 +191,4 @@ function createLifecycleCommand(kind) {
   return root
 }
 
-module.exports = { createLifecycleCommand, csv, human, promptSelection, promptAmbiguousSurfaces }
+module.exports = { createLifecycleCommand, csv, human, promptSelection, promptAmbiguousSurfaces, resolveScope }

package/src/generators/init.js

@@ -1006,12 +1006,35 @@ async function installAmazonQ(cwd = process.cwd()) {
   }
 }
 
-/** Install the canonical agents and skills for one AI target. */
-async function installIntegrationTarget(target, cwd = process.cwd()) {
-  const { execute } = require('../integrations')
+/**
+ * Install the canonical agents and skills for one AI target.
+ *
+ * `scope` defaults to "project" for backward compatibility with the
+ * compatibility entrypoints below (installAgents, installGemini, etc.), that
+ * historical tests exercise directly without going through the `init`
+ * wizard's scope prompt. `trackfw init` itself always passes the scope it
+ * resolved (ADR-2026-07-25-escopo-de-instalacao-selecionavel-para-agents-e-
+ * skills, D4).
+ */
+async function installIntegrationTarget(target, cwd = process.cwd(), scope = 'project') {
+  const { execute, buildPlans } = require('../integrations')
   const roots = { projectRoot: cwd }
-  execute('agents', 'install', { targets: [target], scope: 'project' }, roots)
-  execute('skills', 'install', { targets: [target], scope: 'project' }, roots)
+  const options = { targets: [target], scope }
+  // D5 — transparency: print resolved destinations before writing anything.
+  // buildPlans has no side effects, so it is safe to call here purely to
+  // enumerate destinations; the actual write happens below via execute().
+  // Mirrors printResolvedDestinations in commands/integrations.js and Go's
+  // installAITools (internal/commands/init.go) — this call site (init's AI
+  // tools install) was the one place that stayed silent (divergence #2,
+  // ROADMAP-2026-07-25-escopo-de-instalacao-selecionavel-para-agents-e-skills).
+  const destinations = [
+    ...buildPlans('agents', options).map(plan => plan.destination),
+    ...buildPlans('skills', options).map(plan => plan.destination),
+  ]
+  console.log(`Destino (${scope}):`)
+  for (const destination of [...new Set(destinations)].sort()) console.log(`  ${destination}`)
+  execute('agents', 'install', options, roots)
+  execute('skills', 'install', options, roots)
   console.log(`  ✓ ${target} agents and skills`)
 }