trackfw 2.15.1 → 3.0.0

package/src/commands/integrations.js

@@ -1,7 +1,11 @@
 'use strict'
 
+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')
 
 const csv = value => String(value).split(',').map(entry => entry.trim()).filter(Boolean)
 const collect = (value, previous) => previous.concat(value)
@@ -23,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)
@@ -39,23 +103,86 @@ async function promptAmbiguousSurfaces(kind, options, prompts = require('@inquir
 function createLifecycleCommand(kind) {
   const root = new Command(kind).description(`Manage trackfw ${kind}`)
   for (const operation of ['list', 'install', 'uninstall', 'update']) {
+    const mutation = operation !== 'list'
     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')
-    command.action(async options => {
+
+    // Flags de identidade são exclusivas de agents (ADR D5): skills não têm
+    // identidade, e createLifecycleCommand é compartilhado entre `agents` e
+    // `skills` — sem este filtro por kind, `trackfw skills install
+    // --identity` aceitaria silenciosamente uma flag sem nenhum efeito.
+    // Espelha internal/commands/integrations_flags.go:addIntegrationFlags.
+    if (mutation && kind === 'agents') {
+      command
+        .option('--identity', 'Reconfigure agent identity even if ~/.trackfw/identity.json already exists')
+        .option('--identity-preset <preset>', `Agent identity preset (non-interactive): none, neutral, ${identityStore.presetNames().join(', ')}`)
+    }
+
+    command.action(async (options, cmd) => {
       options.surfaces = options.surface || []
-      if (options.scope !== 'project' && options.scope !== 'global') throw new Error(`Unsupported scope: ${options.scope}`)
-      const mutation = operation !== 'list'
+
+      // 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
+      // de identidade já resolvida (ver src/integrations/index.js:execute).
+      // Colidir os dois faria "agents install --identity" renderizar uma
+      // identidade booleana nos artefatos em vez da Config real.
+      const forceIdentity = options.identity === true
+      delete options.identity
+
+      // --identity-preset é validado e persistido incondicionalmente, acima
+      // de qualquer ramo dependente de TTY abaixo — isso é o que faz um
+      // --identity-preset inválido falhar alto em CI em vez de
+      // silenciosamente não fazer nada. Espelha init.js e
+      // internal/commands/integrations_flags.go:executeIntegrationMutation.
+      let presetChanged = false
+      if (mutation && kind === 'agents') {
+        presetChanged = cmd.getOptionValueSource('identityPreset') === 'cli'
+        if (presetChanged) identityWizard.applyIdentityPresetFlag(os.homedir(), options.identityPreset, operation)
+      }
+
       if (mutation && (!options.targets || !options.targets.length)) {
         if (!process.stdin.isTTY) throw new Error(`${operation} requires --targets in non-interactive mode`)
         await promptSelection(kind, options)
       }
       if (mutation && process.stdin.isTTY) await promptAmbiguousSurfaces(kind, options)
       options.allSurfaces = operation === 'list'
+
+      // Disparo do wizard de identidade (ADR D2): mostrado somente quando o
+      // caminho da flag acima ainda não resolveu a identidade desta
+      // execução, e somente para agents (nunca skills, D5). Roda depois da
+      // seleção de alvo/superfície e antes de execute() para que a
+      // identidade recém-gravada pelo wizard seja a que é renderizada nos
+      // planos abaixo. Espelha
+      // internal/commands/integrations_flags.go:executeIntegrationMutation.
+      if (mutation && kind === 'agents' && !presetChanged) {
+        const homeRoot = os.homedir()
+        const identityExists = identityWizard.identityFileExists(homeRoot)
+        const isTTY = Boolean(process.stdin.isTTY)
+        if (identityWizard.shouldPromptIdentity(kind, isTTY, identityExists, forceIdentity)) {
+          await identityWizard.runIdentityWizard(catalog, homeRoot)
+        } else if (identityExists && !options.json) {
+          const existing = identityStore.load(homeRoot)
+          console.log(t('identity.inUse', { count: String(Object.keys(existing.agents || {}).length) }))
+        }
+      }
+
+      // 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))
     })
@@ -64,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/commands/update.js

@@ -2,7 +2,9 @@
 
 const { Command } = require('commander');
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
+const identityStore = require('../identity');
 
 function readUpdateConfig(rootDir) {
   const yaml = path.join(rootDir, 'trackfw.yaml');
@@ -62,6 +64,11 @@ cmd.action(() => {
   const generators = require('../generators/init');
   const discover = require('./discover');
 
+  // A identidade é carregada uma única vez, fora de qualquer try/catch —
+  // um identity.json corrompido deve abortar o comando inteiro, nunca cair
+  // silenciosamente para os nomes neutros default.
+  const identityConfig = identityStore.load(os.homedir());
+
   console.log('trackfw update — re-aplicando templates atuais...\n');
 
   // 1. Agent rules (marker-delimited, idempotent)
@@ -77,7 +84,7 @@ cmd.action(() => {
       const roots = { projectRoot: cwd };
       const manager = new IntegrationManager(roots);
       for (const kind of ['agents', 'skills']) {
-        const plans = buildPlans(kind, { targets: ['codex'], scope: 'project' });
+        const plans = buildPlans(kind, { targets: ['codex'], scope: 'project', identity: identityConfig });
         const statuses = manager.inspect(plans);
         const existing = plans.filter((_, index) => statuses[index].state !== 'not-installed');
         manager.update(existing);

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`)
 }
 

package/src/i18n/locales/en-US.json

@@ -15,10 +15,21 @@
       "projectType_fullstack": "Full-stack (frontend + backend)",
       "projectType_frontend": "Frontend only",
       "projectType_backend": "Backend only",
-      "projectType_governance": "Governance only (no build stack)"
+      "projectType_governance": "Governance only (no build stack)",
+      "identityPreset": "How would you like to name your agents?",
+      "identityCustomName": "Display name for the agent",
+      "identityNickname": "What should we call you? (optional)"
     },
     "success": "✓ trackfw initialized — run 'trackfw status' to see your governance state."
   },
+  "identity": {
+    "inUse": "identity: {{count}} custom agent(s)",
+    "wizard": {
+      "confirmHeader": "── Confirmation ──────────────────────────────",
+      "confirmQuestion": "Confirm?",
+      "nicknameRowLabel": "What we'll call you:"
+    }
+  },
   "adr": {
     "description": "Manage Architecture Decision Records",
     "new": {

package/src/i18n/locales/es-ES.json

@@ -15,10 +15,21 @@
       "projectType_fullstack": "Full-stack (frontend + backend)",
       "projectType_frontend": "Solo frontend",
       "projectType_backend": "Solo backend",
-      "projectType_governance": "Solo gobernanza (sin stack de build)"
+      "projectType_governance": "Solo gobernanza (sin stack de build)",
+      "identityPreset": "¿Cómo quieres nombrar a tus agentes?",
+      "identityCustomName": "Nombre de exhibición para el agente",
+      "identityNickname": "¿Cómo debemos llamarte? (opcional)"
     },
     "success": "✓ trackfw inicializado — ejecuta 'trackfw status' para ver el estado de gobernanza."
   },
+  "identity": {
+    "inUse": "identidad: {{count}} agente(s) personalizado(s)",
+    "wizard": {
+      "confirmHeader": "── Confirmación ──────────────────────────────",
+      "confirmQuestion": "¿Confirmar?",
+      "nicknameRowLabel": "Cómo te llamaremos:"
+    }
+  },
   "adr": {
     "description": "Gestionar Architecture Decision Records",
     "new": {

package/src/i18n/locales/pt-BR.json

@@ -15,10 +15,21 @@
       "projectType_fullstack": "Full-stack (frontend + backend)",
       "projectType_frontend": "Somente frontend",
       "projectType_backend": "Somente backend",
-      "projectType_governance": "Somente governança (sem stack de build)"
+      "projectType_governance": "Somente governança (sem stack de build)",
+      "identityPreset": "Como você quer nomear seus agentes?",
+      "identityCustomName": "Nome de exibição para o agente",
+      "identityNickname": "Como devemos te chamar? (opcional)"
     },
     "success": "✓ trackfw inicializado — execute 'trackfw status' para ver o estado de governança."
   },
+  "identity": {
+    "inUse": "identidade: {{count}} agente(s) personalizado(s)",
+    "wizard": {
+      "confirmHeader": "── Confirmação ──────────────────────────────",
+      "confirmQuestion": "Confirmar?",
+      "nicknameRowLabel": "Como você será chamado:"
+    }
+  },
   "adr": {
     "description": "Gerenciar Architecture Decision Records",
     "new": {

package/src/identity/config.js

@@ -0,0 +1,134 @@
+'use strict'
+
+const crypto = require('node:crypto')
+const fs = require('node:fs')
+const path = require('node:path')
+
+// SCHEMA_VERSION é a versão de schema atual do arquivo de configuração de
+// identidade. Espelha internal/identity/identity.go:schemaVersion.
+const SCHEMA_VERSION = 1
+
+// slugPattern casa um slug válido: segmentos alfanuméricos em minúsculas
+// unidos por hífens simples, ex.: "zeus", "meu-agente".
+const SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/
+
+function identityPath(homeDir) {
+  return path.join(homeDir, '.trackfw', 'identity.json')
+}
+
+// load lê a configuração de identidade de <homeDir>/.trackfw/identity.json.
+//
+// Se o arquivo não existir, load retorna uma Config vazia sem erro — este é
+// o caminho de não-regressão e nunca deve surgir como falha para quem ainda
+// não customizou sua identidade. Espelha internal/identity/identity.go:Load.
+function load(homeDir) {
+  const filename = identityPath(homeDir)
+  let data
+  try {
+    data = fs.readFileSync(filename, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') return { schema_version: SCHEMA_VERSION, agents: {} }
+    throw new Error(`identity: falha ao ler ${filename}: ${err.message}`)
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(data)
+  } catch (err) {
+    throw new Error(`identity: falha ao decodificar ${filename}: ${err.message}`)
+  }
+  if (parsed.schema_version !== SCHEMA_VERSION) {
+    throw new Error(`identity: versao de schema nao suportada em ${filename}: ${parsed.schema_version} (esperado ${SCHEMA_VERSION})`)
+  }
+  if (!parsed.agents || typeof parsed.agents !== 'object') parsed.agents = {}
+  return parsed
+}
+
+// save persiste cfg em <homeDir>/.trackfw/identity.json de forma atômica.
+// Espelha internal/identity/identity.go:Save — inclusive a omissão de
+// user_nickname vazio e agents vazio, que resulta do comportamento
+// omitempty do encoding/json do Go, e a ordenação alfabética das chaves do
+// mapa agents, que resulta da ordenação de mapas do encoding/json do Go.
+function save(homeDir, cfg) {
+  const out = { schema_version: SCHEMA_VERSION }
+  if (cfg.user_nickname) out.user_nickname = cfg.user_nickname
+  const agents = cfg.agents || {}
+  const ids = Object.keys(agents).sort()
+  if (ids.length > 0) {
+    const sortedAgents = {}
+    for (const id of ids) {
+      sortedAgents[id] = { display_name: agents[id].display_name, slug: agents[id].slug }
+    }
+    out.agents = sortedAgents
+  }
+
+  const data = `${JSON.stringify(out, null, 2)}\n`
+  const filename = identityPath(homeDir)
+  atomicWrite(filename, data, 0o600)
+}
+
+// atomicWrite grava data em filename de forma atômica: cria um arquivo
+// temporário no mesmo diretório, escreve, sincroniza e então renomeia para o
+// lugar final. Espelha internal/identity/identity.go:atomicWrite.
+function atomicWrite(filename, data, mode) {
+  const directory = path.dirname(filename)
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 })
+  const temporaryName = path.join(directory, `.trackfw-tmp-${process.pid}-${crypto.randomBytes(6).toString('hex')}`)
+  const fd = fs.openSync(temporaryName, 'w', mode)
+  try {
+    fs.writeSync(fd, data)
+    fs.fsyncSync(fd)
+  } finally {
+    fs.closeSync(fd)
+  }
+  fs.renameSync(temporaryName, filename)
+}
+
+// agentName retorna o display name customizado sufixado com "-tf". Este é o
+// único lugar do código onde o sufixo "-tf" é aplicado a um slug. Espelha
+// internal/identity/identity.go:AgentName.
+function agentName(slug) {
+  return `${slug}-tf`
+}
+
+// validate verifica cfg quanto à integridade estrutural e referencial:
+//   - todo id de agente em cfg.agents deve estar presente em knownIds
+//   - display_name não pode ser vazio
+//   - slug deve casar com ^[a-z0-9]+(-[a-z0-9]+)*$
+//   - slugs devem ser únicos entre os agentes
+//   - slug não pode terminar com o sufixo "-tf" (ele é acrescentado
+//     automaticamente por agentName)
+// Espelha internal/identity/identity.go:Validate.
+function validate(cfg, knownIds) {
+  const known = new Set(knownIds)
+  const seenSlugs = new Map()
+  const agents = (cfg && cfg.agents) || {}
+
+  for (const [id, agent] of Object.entries(agents)) {
+    if (!known.has(id)) {
+      throw new Error(`identity: agente desconhecido "${id}" nao esta na lista de agentes conhecidos`)
+    }
+    if (!agent.display_name) {
+      throw new Error(`identity: display_name vazio para o agente "${id}"`)
+    }
+    if (!SLUG_PATTERN.test(agent.slug)) {
+      throw new Error(`identity: slug invalido "${agent.slug}" para o agente "${id}" (esperado padrao ${SLUG_PATTERN.source})`)
+    }
+    if (seenSlugs.has(agent.slug)) {
+      throw new Error(`identity: slug duplicado "${agent.slug}" entre os agentes "${seenSlugs.get(agent.slug)}" e "${id}"`)
+    }
+    if (agent.slug.endsWith('-tf')) {
+      throw new Error(`identity: slug "${agent.slug}" do agente "${id}" nao deve incluir o sufixo "-tf"; ele e acrescentado automaticamente (use "${agent.slug.slice(0, -3)}" em vez de "${agent.slug}")`)
+    }
+    seenSlugs.set(agent.slug, id)
+  }
+}
+
+// lookup retorna a identidade configurada para id, se houver. Espelha
+// internal/identity/identity.go:Lookup.
+function lookup(cfg, id) {
+  const agents = (cfg && cfg.agents) || {}
+  return Object.prototype.hasOwnProperty.call(agents, id) ? agents[id] : undefined
+}
+
+module.exports = { SCHEMA_VERSION, load, save, agentName, validate, lookup, identityPath }

package/src/identity/index.js

@@ -0,0 +1,19 @@
+'use strict'
+
+const { slugify } = require('./slug')
+const { knownAgentIds, preset, presetNames } = require('./preset')
+const { load, save, agentName, validate, lookup, identityPath, SCHEMA_VERSION } = require('./config')
+
+module.exports = {
+  slugify,
+  knownAgentIds,
+  preset,
+  presetNames,
+  load,
+  save,
+  agentName,
+  validate,
+  lookup,
+  identityPath,
+  SCHEMA_VERSION,
+}