trackfw 7.3.0 → 7.5.0

package/src/lib/pathfmt.js

@@ -0,0 +1,43 @@
+'use strict'
+
+/**
+ * pathfmt — ponto único de normalização de separador do CLI Node
+ * (ADR-2026-09-04 "Separador POSIX nos artefatos autorados cujo consumidor não é o
+ * sistema de arquivos", D3: "Não espalhar `strings.ReplaceAll` pelos chamadores. Uma
+ * função por runtime, aplicada onde o valor SAI").
+ *
+ * 🔴 ESCOPO NEGATIVO (D2 da mesma ADR) — esta função é de EMISSÃO, nunca de travessia.
+ * Não aplicar a um caminho antes de `fs.readFileSync`/`fs.statSync`/`fs.writeFileSync`:
+ * normalizar cegamente quebra UNC (`\\server\share`) e o prefixo de caminho longo
+ * (`\\?\`), que exige backslash EXCLUSIVAMENTE — nem o Windows converte. O modo de falha
+ * seria intermitente, que é o pior. `path.join`/`path.relative` continuam sendo o certo
+ * para caminho que vai a uma syscall.
+ *
+ * Aplicar apenas às três categorias que a D1 nomeia, cujo consumidor NÃO é o filesystem:
+ *   1. texto de relatório / saída para humano   (displayPath, mensagens)
+ *   2. chave de dicionário ou identificador     (provenanceKey, node ID, edge.to)
+ *   3. string de comando interpretada por shell (command de hook, gate de wave)
+ *
+ * Substituição INCONDICIONAL de "\" por "/", não `path.posix.normalize` nem uma troca de
+ * `path.sep`: em POSIX `path.sep` é "/" e uma troca por separador seria no-op estrutural,
+ * o que não normalizaria um valor sujo herdado de um commit feito no Windows — exatamente
+ * o defeito que esta função existe para curar
+ * (docs/seguranca/2026-09-01-modelo-de-ameaca-do-separador-em-artefato.md). É a mesma
+ * semântica já pinada em Go (`internal/validator/validator.go:normalizeRefSeparator`) e
+ * Python (`pypi/trackfw/pathfmt.py:normalize_ref_separator`); D4 exige que os 3 sejam
+ * byte-idênticos, então esta escolha não é livre — é herdada.
+ *
+ * Custo aceito e nomeado: em POSIX um "\" literal dentro de um nome de arquivo é DADO, e
+ * esta função o converteria. Vale só para o texto emitido (display/chave), nunca para o
+ * caminho realmente aberto, que não passa por aqui.
+ *
+ * NÃO aplicar ao buffer inteiro de um arquivo — só ao valor já extraído/derivado.
+ *
+ * @param {string} p valor já extraído ou derivado (nunca o buffer de um arquivo)
+ * @returns {string}
+ */
+function normalizeRefSeparator(p) {
+  return p.replace(/\\/g, '/')
+}
+
+module.exports = { normalizeRefSeparator }

package/src/lib/update-engine.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { normalizeRefSeparator } = require('./pathfmt')
+
 // update-engine.js — shared state machine for `trackfw update` and
 // `trackfw update harness` (ML-6C of ROADMAP-2026-07-29-barrier-governanca-
 // e-autoridade-do-orquestrador). Both commands report one of exactly four
@@ -169,6 +171,17 @@ function summarize(targets) {
 // fell through to the absolute-path branch even though homeRoot had
 // already been normalized. Stripping a trailing separator from
 // normalizedHome (root "/" excepted) before the prefix check closes this.
+// ML-2A (ADR-2026-09-04, D1 categoria 1 — "texto de relatorio / saida para humano"):
+// os TRES retornos de caminho passam por normalizeRefSeparator. A variavel que recebe
+// esta funcao chama-se literalmente displayPath (npm/src/commands/update-harness.js) e
+// vai para o campo `path` do documento JSON do relatorio — o consumidor nunca e o
+// sistema de arquivos. E o "~" que ela emite ja e POSIX-ismo puro (nenhum shell do
+// Windows expande til), entao devolver "~\\.claude\\settings.json" era incoerente com a
+// decisao ja tomada ao escolher o til.
+//
+// 🔴 A normalizacao e do VALOR DE SAIDA. path.normalize acima continua operando no
+// separador nativo, e `absPath` (o caminho que o chamador realmente abre) nao e
+// alterado por esta funcao — ela nao muda como o produto abre arquivo (ADR D2).
 function tildeify(homeRoot, absPath) {
   let normalizedHome = path.normalize(homeRoot)
   if (normalizedHome.length > path.sep.length && normalizedHome.endsWith(path.sep)) {
@@ -176,8 +189,8 @@ function tildeify(homeRoot, absPath) {
   }
   const normalizedPath = path.normalize(absPath)
   if (normalizedPath === normalizedHome) return '~'
-  if (normalizedPath.startsWith(normalizedHome + path.sep)) return '~' + normalizedPath.slice(normalizedHome.length)
-  return normalizedPath
+  if (normalizedPath.startsWith(normalizedHome + path.sep)) return normalizeRefSeparator('~' + normalizedPath.slice(normalizedHome.length))
+  return normalizeRefSeparator(normalizedPath)
 }
 
 // validateTargets — throws (usage error) when the caller asked for an id

package/src/serve/api_board.js

@@ -2,6 +2,8 @@
 
 const fs = require('fs')
 const path = require('path')
+const { resolveAgentNamespaces } = require('../validator')
+const { normalizeRefSeparator } = require('../lib/pathfmt')
 
 const STATES = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
 
@@ -45,9 +47,15 @@ function scanState(dir, state, agent, roadmapDir) {
     let content = ''
     try { content = fs.readFileSync(path.join(dir, file), 'utf8') } catch (_) {}
     const title = extractTitle(content, file)
-    const relPath = agent
+    // IDENTIFICADOR emitido em JSON, nao caminho de travessia (ADR-2026-09-04, D1
+    // categoria 2): o frontend devolve este valor verbatim em GET /api/file?path=...,
+    // onde o servidor refaz path.join — no Windows o join reconverte "/" para o
+    // separador nativo, entao o round-trip fecha. O path.join da linha 47 acima, que
+    // e o caminho realmente lido por fs.readFileSync, permanece intocado: as duas
+    // expressoes sao independentes sobre os mesmos operandos (ADR D2).
+    const relPath = normalizeRefSeparator(agent
       ? path.join(roadmapDir, agent, state, file)
-      : path.join(roadmapDir, state, file)
+      : path.join(roadmapDir, state, file))
 
     items.push({ file, title, state, agent: agent || '', path: relPath })
   }
@@ -68,14 +76,7 @@ function handleBoard(cfg, req, res) {
   const agentSet = new Set()
 
   if (namespacing === 'by_agent') {
-    let agents = cfg.agents || []
-    if (!agents.length) {
-      try {
-        agents = fs.readdirSync(roadmapDir).filter(f => {
-          try { return fs.statSync(path.join(roadmapDir, f)).isDirectory() } catch (_) { return false }
-        })
-      } catch (_) { agents = [] }
-    }
+    const agents = resolveAgentNamespaces(cfg, roadmapDir)
     for (const agent of agents) {
       agentSet.add(agent)
       for (const state of STATES) {

package/src/serve/api_chain.js

@@ -2,6 +2,8 @@
 
 const fs = require('fs')
 const path = require('path')
+const { resolveAgentNamespaces, extractRefPath } = require('../validator')
+const { normalizeRefSeparator } = require('../lib/pathfmt')
 
 const ROADMAP_STATES = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
 
@@ -70,8 +72,16 @@ function collectNodes(dir, type, state) {
     try { content = fs.readFileSync(path.join(dir, file), 'utf8') } catch (_) {}
     const fm = parseFrontmatter(content)
     const title = extractTitle(content, file)
-    const id = path.join(dir, file)
-    nodes.push({ id, type, title, state, fm })
+    // node ID do grafo — IDENTIFICADOR emitido em JSON (ADR-2026-09-04, D1 categoria 2),
+    // e tambem o alvo de toda aresta: resolveRef() abaixo so devolve valores vindos de
+    // fileIndex/titleIndex, isto e, sempre um node id — nunca o valor cru do frontmatter.
+    // Normalizar o id aqui, portanto, normaliza `edge.to` por construcao.
+    //
+    // 🔴 O path.join da linha 71 (fs.readFileSync) e uma EXPRESSAO INDEPENDENTE sobre os
+    // mesmos operandos: normalizar esta nao pode afeta-la. O caminho de travessia
+    // permanece nativo (ADR D2). Espelha internal/serve/api_chain.go:111.
+    const id = normalizeRefSeparator(path.join(dir, file))
+    nodes.push({ id, type, title, state, fm, content })
   }
   return nodes
 }
@@ -102,14 +112,7 @@ function handleChain(cfg, req, res) {
 
   // REQs
   if (namespacing === 'by_agent') {
-    let agents = cfg.agents || []
-    if (!agents.length) {
-      try {
-        agents = fs.readdirSync(reqDir).filter(f => {
-          try { return fs.statSync(path.join(reqDir, f)).isDirectory() } catch (_) { return false }
-        })
-      } catch (_) {}
-    }
+    const agents = resolveAgentNamespaces(cfg, reqDir)
     for (const agent of agents) {
       for (const state of ROADMAP_STATES) {
         const dir = path.join(reqDir, agent, state)
@@ -122,14 +125,7 @@ function handleChain(cfg, req, res) {
 
   // Roadmaps
   if (namespacing === 'by_agent') {
-    let agents = cfg.agents || []
-    if (!agents.length) {
-      try {
-        agents = fs.readdirSync(roadmapDir).filter(f => {
-          try { return fs.statSync(path.join(roadmapDir, f)).isDirectory() } catch (_) { return false }
-        })
-      } catch (_) {}
-    }
+    const agents = resolveAgentNamespaces(cfg, roadmapDir)
     for (const agent of agents) {
       for (const state of ROADMAP_STATES) {
         const dir = path.join(roadmapDir, agent, state)
@@ -173,8 +169,21 @@ function handleChain(cfg, req, res) {
 
   function resolveRef(val) {
     if (!val) return null
-    // Tenta pelo nome de arquivo
-    const base = val.replace(/\.md$/, '').toLowerCase().trim()
+    // Tenta pelo nome de arquivo — path.basename(val), não val cru: o formato canônico
+    // gravado por `trackfw req new`/`roadmap new` é o CAMINHO COMPLETO (ADR-2026-08-01), não o
+    // basename isolado. Sem o basename() aqui, um vínculo real como
+    // "docs/roadmaps/wip/ROADMAP-x.md" nunca batia contra a chave "roadmap-x" do fileIndex —
+    // achado do ML-3D: nenhuma aresta REQ/ADR/Roadmap gerada pelo CLI jamais resolvia por este
+    // caminho, mascarado porque os testes existentes só cobrem valor já-basename.
+    //
+    // Por que este arquivo NÃO importa validator.resolveRoadmapRef (ao contrário de
+    // internal/serve/api_chain.go, ML-3D): fileIndex é indexado por basename ACROSS todos os
+    // estados (wip/backlog/blocked/done/abandoned) desde antes desta correção — um vínculo
+    // `roadmap:` "wip/X.md" já resolve contra o node real em "done/X.md" sem fallback extra.
+    // O mecanismo do ML-3B/3D (caminho literal gravado com pasta de estado velha) não afeta
+    // este CLI porque ele nunca comparou por igualdade de caminho completo — só por basename/
+    // título. Ver docs/cli-parity.md, seção "serve: /api/chain".
+    const base = path.basename(val).replace(/\.md$/, '').toLowerCase().trim()
     if (fileIndex.has(base)) return fileIndex.get(base)
     // Tenta pelo título
     const norm = val.toLowerCase().trim()
@@ -206,6 +215,20 @@ function handleChain(cfg, req, res) {
         if (target && target !== id) addEdge(id, target)
       }
     }
+
+    // ML-3D: `trackfw req new` (npm/src/generators/req.js) grava `adr: ""` e `roadmap: ""`
+    // SEMPRE vazios no frontmatter — o valor real vive no corpo, em "## Linked ADR / ADR:
+    // <path>" e "## Linked Roadmap / Roadmap: <path>". O laço de frontmatter acima nunca
+    // encontra esse vínculo para uma REQ gerada pelo próprio CLI (não é caso de borda: é o
+    // formato canônico inteiro). validator.extractRefPath varre o CONTEÚDO inteiro
+    // linha-a-linha (mesma função usada por validateRefTargetsExist) — ponto único de
+    // extração, não duplicado aqui.
+    for (const field of ['req', 'adr', 'roadmap']) {
+      const val = extractRefPath(node.content || '', field)
+      if (!val) continue
+      const target = resolveRef(val)
+      if (target && target !== id) addEdge(id, target)
+    }
   }
 
   // Montar nodes de saída sem o campo fm interno

package/src/serve/api_metrics.js

@@ -3,6 +3,7 @@
 const fs = require('fs')
 const path = require('path')
 const { parseLog, calculate } = require('../commands/metrics')
+const { resolveAgentNamespaces } = require('../validator')
 
 const STATES = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
 const MS_PER_DAY = 24 * 60 * 60 * 1000
@@ -34,14 +35,7 @@ function buildStateDistribution(cfg) {
   const namespacing = cfg.roadmapNamespacing || 'flat'
 
   if (namespacing === 'by_agent') {
-    let agents = cfg.agents || []
-    if (!agents.length) {
-      try {
-        agents = fs.readdirSync(roadmapDir).filter(f => {
-          try { return fs.statSync(path.join(roadmapDir, f)).isDirectory() } catch (_) { return false }
-        })
-      } catch (_) { agents = [] }
-    }
+    const agents = resolveAgentNamespaces(cfg, roadmapDir)
     for (const agent of agents) {
       for (const state of STATES) {
         dist[state] = (dist[state] || 0) + countFilesInState(path.join(roadmapDir, agent, state))