trackfw 3.0.0 → 4.0.0

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;

package/src/config/index.js

@@ -26,9 +26,11 @@ function defaults() {
     lenientUntil: '',
     wipLimit: 1,
     wipBySquad: false,
+    staleWipDays: 7,
     requireReqInCommit: false,
     strictCiPaths: false,
     traceIdField: '',
+    forge: '',
     // NOVOS campos:
     linkFields: {
       req:     ['REQ:'],
@@ -42,7 +44,7 @@ function defaults() {
       wip_limit:            'error',
       stale_wip:            'warning',
       adr_orphan:           'warning',
-      ref_targets_exist:    'warning',
+      ref_targets_exist:    'error',
       folder_status:        'warning',
       filename_uniqueness:  'error',
       blocked_by_draft_adr: 'error',
@@ -191,9 +193,11 @@ function parse(content, cfg) {
       case 'lenient_until':         cfg.lenientUntil = val; break;
       case 'wip_limit':             { const n = parseInt(val, 10); if (n > 0) cfg.wipLimit = n; break; }
       case 'wip_by_squad':          cfg.wipBySquad = val === 'true'; break;
+      case 'stale_wip_days':        { const n = parseInt(val, 10); if (n > 0) cfg.staleWipDays = n; break; }
       case 'require_req_in_commit': cfg.requireReqInCommit = val === 'true'; break;
       case 'strict_ci_paths':       cfg.strictCiPaths = val === 'true'; break;
       case 'trace_id_field':        cfg.traceIdField = val.replace(/^["']|["']$/g, ''); break;
+      case 'forge':                 cfg.forge = val.replace(/^["']|["']$/g, ''); break;
       case 'link_fields':           inLinkFields = true; break;
       case 'acceptance_markers':    inAcceptanceMarkers = true; acceptanceMarkers = []; break;
       case 'rules':                 inRules = true; rules = {}; break;
@@ -208,4 +212,3 @@ const NAMESPACING_FLAT = 'flat';
 const NAMESPACING_BY_AGENT = 'by_agent';
 
 module.exports = { load, reset, defaults, expandPath, NAMESPACING_FLAT, NAMESPACING_BY_AGENT };
-

package/src/forge/adapter.js

@@ -0,0 +1,189 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Verificação de disponibilidade de CLI — scan puro no PATH sem subprocess
+// ---------------------------------------------------------------------------
+
+/**
+ * Verifica se um executável está disponível no PATH, respeitando
+ * TRACKFW_DISABLE_EXTERNAL_COMMANDS (mesmo padrão de discover.go).
+ * @param {string} name
+ * @returns {boolean}
+ */
+function _defaultAvailFn(name) {
+  if (!name) return false;
+  if (process.env.TRACKFW_DISABLE_EXTERNAL_COMMANDS === '1') return false;
+
+  const dirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  const isWindows = process.platform === 'win32';
+  const exts = isWindows
+    ? (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';')
+    : [''];
+
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      try {
+        const candidate = path.join(dir, name + ext);
+        fs.accessSync(candidate, fs.constants.F_OK | fs.constants.X_OK);
+        return true;
+      } catch (_) {
+        // continua
+      }
+    }
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Conversão de remote URL → base HTTPS
+// ---------------------------------------------------------------------------
+
+/**
+ * Converte qualquer formato de remote git (git@, ssh://, https://, http://)
+ * para URL base HTTPS sem .git.
+ *
+ * Normalização especial para Azure SSH:
+ *   git@ssh.dev.azure.com:v3/org/project/repo → https://dev.azure.com/org/project/_git/repo
+ *
+ * @param {string} rawURL
+ * @param {string} forge
+ * @returns {string}
+ */
+function remoteHTTPSBase(rawURL, forge) {
+  if (!rawURL) return '';
+  rawURL = rawURL.trim();
+  if (!rawURL) return '';
+
+  let host = '';
+  let pathStr = '';
+
+  if (rawURL.startsWith('git@')) {
+    // git@host:path
+    const rest = rawURL.slice(4);
+    const colonIdx = rest.indexOf(':');
+    if (colonIdx < 0) return '';
+    host = rest.slice(0, colonIdx).toLowerCase();
+    pathStr = rest.slice(colonIdx + 1);
+
+  } else if (rawURL.startsWith('ssh://')) {
+    // ssh://[user@]host/path
+    let rest = rawURL.slice(6);
+    const atIdx = rest.indexOf('@');
+    if (atIdx >= 0) rest = rest.slice(atIdx + 1);
+    const slashIdx = rest.indexOf('/');
+    if (slashIdx < 0) {
+      host = rest.toLowerCase();
+    } else {
+      host = rest.slice(0, slashIdx).toLowerCase();
+      pathStr = rest.slice(slashIdx + 1);
+    }
+
+  } else if (rawURL.startsWith('https://') || rawURL.startsWith('http://')) {
+    let rest = rawURL.replace(/^https?:\/\//, '');
+    const atIdx = rest.indexOf('@');
+    if (atIdx >= 0) rest = rest.slice(atIdx + 1);
+    const slashIdx = rest.indexOf('/');
+    if (slashIdx < 0) {
+      host = rest.toLowerCase();
+    } else {
+      host = rest.slice(0, slashIdx).toLowerCase();
+      pathStr = rest.slice(slashIdx + 1);
+    }
+
+  } else {
+    return '';
+  }
+
+  pathStr = pathStr.replace(/\.git$/, '').replace(/^\/|\/$/g, '');
+
+  // Normalização Azure SSH
+  if (forge === 'azure' && host === 'ssh.dev.azure.com') {
+    host = 'dev.azure.com';
+    pathStr = pathStr.replace(/^v3\//, '');
+    const parts = pathStr.split('/');
+    if (parts.length === 3) {
+      pathStr = `${parts[0]}/${parts[1]}/_git/${parts[2]}`;
+    }
+  }
+
+  if (!pathStr) return `https://${host}`;
+  return `https://${host}/${pathStr}`;
+}
+
+// ---------------------------------------------------------------------------
+// Adapter
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} Adapter
+ * @property {string} forge
+ * @property {string} noun        - "Pull Request" ou "Merge Request"
+ * @property {string} cliName     - nome do executável (vazio = sem CLI)
+ * @property {string[]} cliArgs   - argumentos para criar PR/MR
+ * @property {boolean} available  - false quando CLI ausente
+ * @property {function(string, string): string} fallbackURL
+ */
+
+/**
+ * Retorna o Adapter para o forge informado.
+ *
+ * @param {string} forge
+ * @param {function(string): boolean} [availFn]  - injeta verificação de CLI (para testes)
+ * @returns {Adapter}
+ */
+function forgeAdapter(forge, availFn) {
+  if (typeof availFn !== 'function') {
+    availFn = _defaultAvailFn;
+  }
+
+  let noun = 'Pull Request';
+  let cliName = '';
+  let cliArgs = [];
+  let available = false;
+
+  switch (forge) {
+    case 'github':
+      cliName = 'gh';
+      cliArgs = ['pr', 'create'];
+      available = availFn('gh');
+      break;
+    case 'gitlab':
+      noun = 'Merge Request';
+      cliName = 'glab';
+      cliArgs = ['mr', 'create'];
+      available = availFn('glab');
+      break;
+    case 'azure':
+      cliName = 'az';
+      cliArgs = ['repos', 'pr', 'create'];
+      available = availFn('az');
+      break;
+    case 'bitbucket':
+      // Bitbucket não possui CLI — nunca chama availFn
+      break;
+    default:
+      // forge desconhecido: sem CLI, sem disponibilidade
+      break;
+  }
+
+  const adapter = { forge, noun, cliName, cliArgs, available };
+
+  adapter.fallbackURL = function (remoteURL, branch) {
+    const base = remoteHTTPSBase(remoteURL, forge);
+    if (!base) return '';
+    switch (forge) {
+      case 'github':    return `${base}/compare/${branch}?expand=1`;
+      case 'gitlab':    return `${base}/-/merge_requests/new?merge_request[source_branch]=${branch}`;
+      case 'bitbucket': return `${base}/pull-requests/new?source=${branch}`;
+      case 'azure':     return `${base}/pullrequestcreate?sourceRef=${branch}`;
+      default:          return '';
+    }
+  };
+
+  return adapter;
+}
+
+module.exports = { forgeAdapter, remoteHTTPSBase };