trackfw 7.3.0 → 7.4.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 } = require('../validator')
+const { normalizeRefSeparator } = require('../lib/pathfmt')
 
 const ROADMAP_STATES = ['wip', 'backlog', 'blocked', 'done', 'abandoned']
 
@@ -70,7 +72,15 @@ 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)
+    // 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 })
   }
   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)

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