trackfw 3.1.0 → 4.0.0

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 }

package/src/commands/update.js

@@ -5,6 +5,12 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const identityStore = require('../identity');
+const { runFileTarget, validateTargets, buildDocument, humanReport, silenceConsole } = require('../lib/update-engine');
+
+// `trackfw update` is project-scoped only — see docs/cli-parity.md,
+// "`trackfw update` vs `trackfw update harness`". It must NEVER touch global
+// state (~/.claude, ~/.codex, etc.). Global artifacts moved to
+// `trackfw update harness` (update-harness.js).
 
 function readUpdateConfig(rootDir) {
   const yaml = path.join(rootDir, 'trackfw.yaml');
@@ -50,99 +56,227 @@ function updateHooksSurgical(cfg, rootDir) {
   }
 }
 
-const cmd = new Command('update');
-cmd.description('Update trackfw-managed artifacts to the current version');
-cmd.action(() => {
-  const cwd = process.cwd();
-  const yaml = path.join(cwd, 'trackfw.yaml');
-  if (!fs.existsSync(yaml)) {
-    console.error('✗ trackfw.yaml não encontrado — execute trackfw init primeiro');
-    process.exit(1);
+// codexProjectAgentsTarget — installs/reports the project-scoped Codex
+// agents/skills bundle (catalog-based). Uses IntegrationManager.inspect,
+// which is read-only, to compute state under --dry-run too; only the
+// mutating manager.update() call is skipped when dryRun is true. Kept
+// separate from runFileTarget because IntegrationManager already owns a
+// correct, manifest-aware not-installed/current/outdated/modified state
+// machine — re-deriving it via directory hashing would risk diverging from
+// that source of truth (and would need the .trackfw manifest copied into
+// the simulation, which is unnecessary complexity here).
+function codexProjectAgentsTarget(cwd, identityConfig, { dryRun, installMissing }) {
+  const id = 'codex-project-agents';
+  const displayPath = '.codex/agents, .agents/skills';
+  const detected = fs.existsSync(path.join(cwd, 'AGENTS.md')) || fs.existsSync(path.join(cwd, '.codex'));
+  if (!detected) return { id, state: 'missing', path: displayPath };
+
+  try {
+    const { buildPlans, IntegrationManager } = require('../integrations');
+    const manager = new IntegrationManager({ projectRoot: cwd });
+    let wroteAny = false;
+    for (const kind of ['agents', 'skills']) {
+      const plans = buildPlans(kind, { targets: ['codex'], scope: 'project', identity: identityConfig });
+      const statuses = manager.inspect(plans);
+      const toWrite = plans.filter((_, index) => {
+        const state = statuses[index].state;
+        return state === 'outdated' || (installMissing && state === 'not-installed');
+      });
+      if (toWrite.length) {
+        wroteAny = true;
+        if (!dryRun) manager.update(toWrite);
+      }
+    }
+    return { id, state: wroteAny ? 'updated' : 'skipped', path: displayPath };
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message };
   }
+}
 
-  const cfg = readUpdateConfig(cwd);
+// PROJECT_TARGET_IDS — the fixed declared order for `trackfw update`
+// targets. `ci-workflow` and `git-hooks` only appear when the project's
+// trackfw.yaml opted into a CI system / hook framework — see ambiguity
+// note in the ML-6C handoff report about config-conditional target lists.
+const PROJECT_TARGET_IDS = [
+  'agent-rules',
+  'agent-hooks',
+  'codex-project-agents',
+  'validate-script',
+  'ci-workflow',
+  'git-hooks',
+  'claude-commands',
+];
+
+// buildProjectTargets — `wanted` (nullable) restricts which targets are
+// even computed/applied. This must be enforced HERE, before any apply()
+// runs, not as a post-hoc filter on the returned array: every target's
+// apply() is a real filesystem side effect (outside --dry-run), so
+// filtering afterwards would still have written every unrequested target.
+function buildProjectTargets(cwd, cfg, identityConfig, { dryRun, installMissing }, wanted) {
   const generators = require('../generators/init');
   const discover = require('./discover');
+  const hooksGen = require('../generators/hooks');
+  const include = (id) => !wanted || wanted.includes(id);
 
-  // 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());
+  const targets = [];
 
-  console.log('trackfw update — re-aplicando templates atuais...\n');
+  if (include('agent-rules')) targets.push(runFileTarget({
+    id: 'agent-rules',
+    path: 'CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .windsurfrules, .amazonq/developer/guidelines.md, .cursor/rules/trackfw.mdc',
+    root: cwd,
+    relPaths: ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md', '.github/copilot-instructions.md', '.windsurfrules', '.amazonq/developer/guidelines.md', '.cursor/rules/trackfw.mdc'],
+    apply: (root) => generators.injectRulesDetected(root),
+    dryRun,
+    installMissing,
+  }));
 
-  // 1. Agent rules (marker-delimited, idempotent)
-  try {
-    generators.injectRulesDetected(cwd);
-    console.log('  ✓ agent rules atualizadas');
-  } catch (e) {
-    console.log(`  ⚠ agent rules: ${e.message}`);
-  }
-  if (fs.existsSync(path.join(cwd, 'AGENTS.md')) || fs.existsSync(path.join(cwd, '.codex'))) {
-    try {
-      const { buildPlans, IntegrationManager } = require('../integrations');
-      const roots = { projectRoot: cwd };
-      const manager = new IntegrationManager(roots);
-      for (const kind of ['agents', 'skills']) {
-        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);
-      }
-    } catch (e) {
-      console.warn(`  ⚠ Codex integration: ${e.message}`);
-    }
-  }
+  if (include('agent-hooks')) targets.push(runFileTarget({
+    id: 'agent-hooks',
+    path: '.claude/settings.json, .codex/hooks.json, .gemini/settings.json, .kiro/hooks/trackfw-attention.json, .github/hooks/trackfw-attention.json, .cursor/hooks.json, scripts/trackfw-attention-*.sh',
+    root: cwd,
+    relPaths: [
+      '.claude/settings.json',
+      '.codex/hooks.json',
+      '.gemini/settings.json',
+      '.kiro/hooks/trackfw-attention.json',
+      '.github/hooks/trackfw-attention.json',
+      '.cursor/hooks.json',
+      'scripts/trackfw-attention-signal.sh',
+      'scripts/trackfw-attention-cleanup.sh',
+    ],
+    apply: (root) => {
+      hooksGen.injectHooksDetected(root);
+      hooksGen.generateAttentionScripts(cfg, root);
+    },
+    dryRun,
+    installMissing,
+  }));
 
-  // 1b. Agent hooks (attention signal/cleanup)
-  try {
-    const { injectHooksDetected, generateAttentionScripts } = require('../generators/hooks');
-    injectHooksDetected(cwd);
-    generateAttentionScripts(cfg, cwd);
-    console.log('  ✓ agent hooks atualizados');
-  } catch (e) {
-    console.warn(`  ⚠ agent hooks: ${e.message}`);
+  if (include('codex-project-agents')) targets.push(codexProjectAgentsTarget(cwd, identityConfig, { dryRun, installMissing }));
+
+  if (include('validate-script')) targets.push(runFileTarget({
+    id: 'validate-script',
+    path: 'scripts/trackfw-validate.sh',
+    root: cwd,
+    relPaths: ['scripts/trackfw-validate.sh'],
+    // Reuses generators/init.js's generateValidateScript — the SAME
+    // generator `trackfw init` uses to write this file — not
+    // discover.js's writeValidateScript, which produces a different
+    // (simpler, non-per-backend) script and made every `update` re-run
+    // report "updated" against a project actually already current
+    // (ML-6H fix). readUpdateConfig returns raw trackfw.yaml keys
+    // (snake_case, e.g. "pkg_manager"); buildValidateScript expects the
+    // camelCase shape used by the rest of the init generators.
+    apply: (root) => generators.generateValidateScript({
+      backend: cfg.backend,
+      frontend: cfg.frontend,
+      pkgManager: cfg.pkg_manager,
+    }, root),
+    dryRun,
+    installMissing,
+  }));
+
+  if (include('ci-workflow') && (cfg.ci === 'github-actions' || cfg.ci === 'github_actions')) {
+    targets.push(runFileTarget({
+      id: 'ci-workflow',
+      path: '.github/workflows/trackfw-validate.yml',
+      root: cwd,
+      relPaths: ['.github/workflows/trackfw-validate.yml'],
+      apply: (root) => discover.writeCIWorkflowForce(root),
+      dryRun,
+      installMissing,
+    }));
   }
 
-  // 2. Validate script (trackfw-owned, overwrite)
-  try {
-    discover.writeValidateScript(cwd);
-    console.log('  ✓ scripts/trackfw-validate.sh atualizado');
-  } catch (e) {
-    console.log(`  ⚠ validate script: ${e.message}`);
+  if (include('git-hooks') && (cfg.hooks === 'husky' || cfg.hooks === 'lefthook')) {
+    const relPath = cfg.hooks === 'husky' ? '.husky/pre-commit' : 'lefthook.yml';
+    targets.push(runFileTarget({
+      id: 'git-hooks',
+      path: relPath,
+      root: cwd,
+      relPaths: [relPath],
+      apply: (root) => updateHooksSurgical(cfg, root),
+      dryRun,
+      installMissing,
+    }));
   }
 
-  // 3. CI workflow (trackfw-owned, overwrite)
-  if (cfg.ci === 'github-actions' || cfg.ci === 'github_actions') {
-    try {
-      discover.writeCIWorkflowForce(cwd);
-      console.log('  ✓ .github/workflows/trackfw-validate.yml atualizado');
-    } catch (e) {
-      console.log(`  ⚠ CI workflow: ${e.message}`);
-    }
+  if (include('claude-commands')) targets.push(runFileTarget({
+    id: 'claude-commands',
+    path: '.claude/commands/trackfw',
+    root: cwd,
+    relPaths: ['.claude/commands/trackfw'],
+    apply: (root) => generators.generateClaudeCommandsForce(root),
+    dryRun,
+    installMissing,
+  }));
+
+  return targets;
+}
+
+const cmd = new Command('update');
+cmd.description('Update trackfw-managed artifacts. Bare form is project-scoped (never touches global state); `update harness` updates the global harness instead.');
+// `[mode]` is a plain positional argument, not a nested commander.Command —
+// see the long comment in update-harness.js:run for why: a real subcommand
+// redeclaring the same --json/--dry-run/--targets/--install-missing flags
+// as this parent silently drops them (commander@12 quirk, confirmed by
+// reproduction). One Command, one Option per flag, branch on `mode` inside
+// a single action — this is the only structure that parses correctly.
+cmd.argument('[mode]', 'Pass "harness" to update the global harness instead of the current project');
+cmd.option('--dry-run', 'Compute and report states without writing anything');
+cmd.option('--json', 'Emit the result document as JSON');
+cmd.option('--targets <ids>', 'Comma-separated subset of target ids');
+cmd.option('--install-missing', 'Allow missing targets to be installed');
+cmd.action((mode, options) => {
+  if (mode === 'harness') {
+    return require('./update-harness').run(options);
+  }
+  if (mode) {
+    console.error(`✗ Unknown update mode: ${mode} (expected "harness" or no argument)`);
+    process.exit(1);
   }
 
-  // 4. Git hooks (surgical)
-  updateHooksSurgical(cfg, cwd);
+  const cwd = process.cwd();
+  const yaml = path.join(cwd, 'trackfw.yaml');
+  if (!fs.existsSync(yaml)) {
+    console.error('✗ trackfw.yaml não encontrado — execute trackfw init primeiro');
+    process.exit(1);
+  }
 
-  // 5. Claude commands (force overwrite)
+  let wanted;
   try {
-    generators.generateClaudeCommandsForce(cwd);
-    console.log('  ✓ .claude/commands/trackfw/ atualizado');
+    const requested = options.targets ? String(options.targets).split(',').map((s) => s.trim()).filter(Boolean) : [];
+    wanted = validateTargets(PROJECT_TARGET_IDS, requested);
   } catch (e) {
-    console.log(`  ⚠ Claude commands: ${e.message}`);
+    console.error(`✗ ${e.message}`);
+    process.exit(1);
   }
 
-  // 6. Global skill (force overwrite)
-  try {
-    generators.installSkillsForce(cwd);
-    console.log('  ✓ skill global atualizada');
-  } catch (e) {
-    console.log(`  ⚠ skills: ${e.message}`);
+  const cfg = readUpdateConfig(cwd);
+  const dryRun = Boolean(options.dryRun);
+  const installMissing = Boolean(options.installMissing);
+
+  // 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());
+
+  // With --json, stdout must carry only the result document — apply()
+  // functions log human progress lines as a side effect; silence them so a
+  // consumer parsing --json output never has to skip preamble noise.
+  const targets = options.json
+    ? silenceConsole(() => buildProjectTargets(cwd, cfg, identityConfig, { dryRun, installMissing }, wanted))
+    : buildProjectTargets(cwd, cfg, identityConfig, { dryRun, installMissing }, wanted);
+
+  const doc = buildDocument('project', dryRun, targets);
+
+  if (options.json) {
+    console.log(JSON.stringify(doc, null, 2));
+  } else {
+    console.log(humanReport('project', dryRun, targets));
   }
 
-  console.log('\n✓ trackfw update concluído');
-  require('../generators/init').printArchitectNextSteps(process.cwd())
+  if (doc.summary.failed > 0) process.exitCode = 1;
 });
 
 module.exports = cmd;