trackfw 3.0.0 → 4.0.0

package/src/integrations/catalog.js

@@ -31,4 +31,28 @@ function readAsset(item) {
   return fs.readFileSync(path.join(ASSET_ROOT, relative), 'utf8')
 }
 
-module.exports = { catalog, items, target, surfaceFor, readAsset }
+// truncateBeforeIdSegment drops the "{{id}}"-bearing path segment and
+// everything after it, returning the shared parent directory — mirrors
+// internal/integrations/plan.go:truncateBeforeIDSegment.
+function truncateBeforeIdSegment(p) {
+  const segments = p.split('/')
+  const index = segments.findIndex(segment => segment.includes('{{id}}'))
+  if (index === -1) return p
+  return segments.slice(0, index).join('/')
+}
+
+// globalGroupPath returns the tilde-abbreviated directory shared by every
+// catalog item of (toolId, kind) at global scope, derived from the catalog's
+// own path template rather than any individual installed plan's destination
+// — so the reported path never depends on catalog item iteration order. See
+// docs/cli-parity.md, "Declared harness targets — pinned list", and the Go
+// counterpart internal/integrations/plan.go:GlobalGroupPath.
+function globalGroupPath(toolId, kind) {
+  const targetEntry = target(toolId)
+  const surface = surfaceFor(targetEntry, undefined, kind)
+  const installPath = surface.paths[kind].find(entry => entry.scope === 'global')
+  if (!installPath) throw new Error(`target ${toolId} has no global ${kind} path`)
+  return truncateBeforeIdSegment(installPath.path)
+}
+
+module.exports = { catalog, items, target, surfaceFor, readAsset, globalGroupPath }

package/src/integrations/index.js

@@ -2,11 +2,12 @@
 
 const os = require('node:os')
 
-const { catalog, items, target, surfaceFor, readAsset } = require('./catalog')
+const { catalog, items, target, surfaceFor, readAsset, globalGroupPath } = require('./catalog')
 const { render } = require('./render')
 const { IntegrationManager } = require('./manager')
 const { legacyHashes } = require('./legacy')
 const identityStore = require('../identity')
+const { injectRulesForTool } = require('../generators/init')
 
 function parseSurfaces(values = []) {
   const result = {}
@@ -107,7 +108,24 @@ function execute(kind, operation, options = {}, roots = {}) {
   else if (operation === 'update') statuses = manager.update(plans, { force: options.force })
   else if (operation === 'uninstall') statuses = manager.uninstall(plans, { force: options.force })
   else throw new Error(`Unsupported integration operation: ${operation}`)
+
+  // Auxiliary rules files (GEMINI.md, .github/copilot-instructions.md,
+  // .windsurfrules, .amazonq/developer/guidelines.md, etc.) are outside the
+  // agents/skills catalog managed by IntegrationManager above — they are a
+  // separate, tool-specific mechanism (injectRulesForTool), and this is the
+  // canonical catalog-based install path (`trackfw agents|skills install
+  // --targets <tool>`). Mirrors internal/commands/integrations_flags.go:
+  // executeIntegrationMutation (ML-5E/ML-5G of ROADMAP-2026-07-29-barrier-
+  // governanca-e-autoridade-do-orquestrador). Scoped to "install" only,
+  // mirroring the one-shot semantics the removed deprecated CLI aliases had.
+  // injectRulesForTool no-ops for targets without a rules surface (e.g.
+  // antigravity, kiro) and is idempotent for repeated runs.
+  if (operation === 'install') {
+    const targetValues = options.targets && options.targets.length ? options.targets : catalog.targets.map(entry => entry.id)
+    for (const targetID of targetValues) injectRulesForTool(targetID, manager.roots.project)
+  }
+
   return result(kind, plans, statuses)
 }
 
-module.exports = { catalog, buildPlans, execute, IntegrationManager, parseSurfaces }
+module.exports = { catalog, buildPlans, execute, IntegrationManager, parseSurfaces, globalGroupPath }

package/src/integrations/render.js

@@ -80,8 +80,8 @@ function toolsFor(itemId) {
 // identidade configurada. Sem apelido configurado, apenas o display name do
 // agente é mencionado. Espelha internal/integrations/render.go:greetingLine.
 function greetingLine(displayName, nickname) {
-  if (!nickname) return `Você é ${displayName}.`
-  return `Você é ${displayName}. Trate o usuário como ${nickname}.`
+  if (!nickname) return `You are ${displayName}.`
+  return `You are ${displayName}. Address the user as ${nickname}.`
 }
 
 // insertBodyPrefix insere prefix como a nova primeira linha da seção de
@@ -103,6 +103,54 @@ function insertBodyPrefix(source, prefix) {
   return `${head}\n\n${prefix}\n\n${rest}`
 }
 
+// rewriteSignatureLine reescreve a última linha da seção de corpo de um
+// markdown cru (frontmatter + corpo) que casa com o padrão de assinatura
+// `^— <nome>, <título>$` (travessão em-dash U+2014, espaço, nome, vírgula,
+// espaço, título). Apenas o grupo de nome (primeiro) é substituído por
+// displayName; o título (segundo grupo) é preservado byte a byte.
+//
+// Escopo: a função opera somente no corpo (após o fechamento do frontmatter).
+// Uma linha de assinatura dentro do frontmatter nunca é tocada — a detecção
+// de fronteira espelha rewriteFrontmatterFields exatamente.
+//
+// Se nenhuma linha do corpo casar com o padrão, source é retornado inalterado.
+// Se displayName for vazio, source é retornado inalterado. A função nunca
+// inventa uma assinatura que não estava presente.
+//
+// Espelha internal/integrations/render.go:rewriteSignatureLine.
+function rewriteSignatureLine(source, displayName) {
+  if (!displayName) return source
+  const trimmed = String(source).trim()
+
+  // Localiza o início do corpo — espelha a detecção de fronteira de
+  // rewriteFrontmatterFields para que o escopo de ambas as funções coincida.
+  let bodyStart = 0
+  if (trimmed.startsWith('---\n')) {
+    const end = trimmed.indexOf('\n---', 4)
+    if (end >= 0) {
+      bodyStart = end + 4 // aponta para o char imediatamente após "\n---"
+    }
+  }
+  const head = trimmed.slice(0, bodyStart)
+  const bodySection = trimmed.slice(bodyStart)
+
+  const lines = bodySection.split('\n')
+  // Percorre de trás para frente para encontrar a ÚLTIMA linha candidata.
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]
+    if (!line.startsWith('— ')) continue
+    const rest = line.slice('— '.length) // pula "— "
+    const commaIdx = rest.indexOf(', ')
+    if (commaIdx < 0) continue
+    const title = rest.slice(commaIdx + 2)
+    if (!title) continue
+    lines[i] = `— ${displayName}, ${title}`
+    return head + lines.join('\n')
+  }
+  // Nenhuma linha de assinatura encontrada — retorna source inalterado.
+  return source
+}
+
 // rewriteFrontmatterFields substitui as linhas "name:" e "description:" do
 // frontmatter de um markdown cru por name e description, preservando toda
 // outra linha do frontmatter byte a byte (ordem, espaçamento, estilo de
@@ -176,8 +224,10 @@ function frontmatterName(content) {
 //     gemini, cursor, copilot, kiro-ide, windsurf), retorna o source cru
 //     normalizado com o frontmatter ainda anexado. Quando há identidade
 //     configurada, suas linhas "name:"/"description:" são reescritas no
-//     lugar (ver rewriteFrontmatterFields) — necessário porque a seleção de
-//     subagent do Claude Code lê apenas o frontmatter, nunca o corpo.
+//     lugar (ver rewriteFrontmatterFields) e a última linha de assinatura do
+//     corpo com padrão `^— <nome>, <título>$` é reescrita com o display name
+//     da identidade (ver rewriteSignatureLine) — necessário porque a seleção
+//     de subagent do Claude Code lê apenas o frontmatter, nunca o corpo.
 //
 // Ambas as rotas devem receber a injeção de identidade. Quando não há
 // identidade configurada para item.id, name/description/body ficam
@@ -231,7 +281,8 @@ function render({ kind, content, capability, item, identity: cfg }) {
   if (!id) return normalize(content)
   const withBody = insertBodyPrefix(content, greeting)
   const withFrontmatter = rewriteFrontmatterFields(withBody, name, description)
-  return normalize(withFrontmatter)
+  const withSignature = rewriteSignatureLine(withFrontmatter, id.display_name)
+  return normalize(withSignature)
 }
 
-module.exports = { render, markdownParts, frontmatterName, greetingLine, insertBodyPrefix, rewriteFrontmatterFields }
+module.exports = { render, markdownParts, frontmatterName, greetingLine, insertBodyPrefix, rewriteFrontmatterFields, rewriteSignatureLine }

package/src/lib/update-engine.js

@@ -0,0 +1,217 @@
+'use strict'
+
+// 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
+// states per target (`updated`, `skipped`, `missing`, `failed`) and emit the
+// same JSON document shape — see docs/cli-parity.md, section
+// "`trackfw update` vs `trackfw update harness`" for the frozen contract.
+//
+// Key invariant enforced here: a `missing` target is NEVER installed unless
+// `installMissing` is explicitly true. This is the single most
+// safety-critical rule in the contract, so it is centralized in
+// `runFileTarget` rather than re-implemented per target.
+
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const crypto = require('crypto')
+
+function sha256(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex')
+}
+
+function collectDirEntries(dir) {
+  const out = []
+  function walk(current, rel) {
+    let entries
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true })
+    } catch (_) {
+      return
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name))
+    for (const entry of entries) {
+      const childRel = rel ? path.join(rel, entry.name) : entry.name
+      const childAbs = path.join(current, entry.name)
+      if (entry.isDirectory()) walk(childAbs, childRel)
+      else out.push([childRel, sha256(fs.readFileSync(childAbs))])
+    }
+  }
+  walk(dir, '')
+  return out
+}
+
+// hashPath — returns null when the path does not exist, a content hash for
+// a file, or a hash of the recursive (relative-path, content-hash) listing
+// for a directory. Used to detect "nothing changed" without caring whether
+// the target is a single file or a directory of generated artifacts.
+function hashPath(target) {
+  if (!fs.existsSync(target)) return null
+  const stat = fs.lstatSync(target)
+  if (stat.isDirectory()) return JSON.stringify(collectDirEntries(target))
+  return sha256(fs.readFileSync(target))
+}
+
+function copyPath(src, dst) {
+  if (!fs.existsSync(src)) return
+  const stat = fs.lstatSync(src)
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dst, { recursive: true })
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+      copyPath(path.join(src, entry.name), path.join(dst, entry.name))
+    }
+  } else {
+    fs.mkdirSync(path.dirname(dst), { recursive: true })
+    fs.copyFileSync(src, dst)
+  }
+}
+
+// silenceConsole — apply()s reused from generators/init.js and friends log
+// their own progress via console.log; those messages are only meaningful
+// against the real root, not the scratch copy used to predict --dry-run
+// state. Suppressed during simulation only.
+function silenceConsole(fn) {
+  const original = console.log
+  console.log = () => {}
+  try {
+    return fn()
+  } finally {
+    console.log = original
+  }
+}
+
+/**
+ * runFileTarget — computes updated/skipped/missing/failed for a target whose
+ * only observable effect is writing under a fixed set of paths (files or
+ * directories) relative to `root`, by diffing content hashes before/after
+ * invoking `apply(root)`.
+ *
+ * - `--dry-run`: `apply` runs against a scratch temp directory seeded only
+ *   with copies of the paths that already exist under `root` — the real
+ *   `root` is never touched.
+ * - real run: `apply` runs directly against `root`.
+ * - `missing` (nothing present under any of `relPaths`) never triggers
+ *   `apply` unless `installMissing` is true.
+ */
+function runFileTarget({ id, path: displayPath, root, relPaths, apply, dryRun, installMissing }) {
+  const before = relPaths.map(rel => hashPath(path.join(root, rel)))
+  const allMissingBefore = before.every(h => h === null)
+
+  if (allMissingBefore && !installMissing) {
+    return { id, state: 'missing', path: displayPath }
+  }
+
+  try {
+    let after
+    if (dryRun) {
+      const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'trackfw-update-'))
+      try {
+        for (const rel of relPaths) copyPath(path.join(root, rel), path.join(tmp, rel))
+        silenceConsole(() => apply(tmp))
+        after = relPaths.map(rel => hashPath(path.join(tmp, rel)))
+      } finally {
+        fs.rmSync(tmp, { recursive: true, force: true })
+      }
+    } else {
+      apply(root)
+      after = relPaths.map(rel => hashPath(path.join(root, rel)))
+    }
+
+    const allMissingAfter = after.every(h => h === null)
+    if (allMissingBefore && allMissingAfter) return { id, state: 'missing', path: displayPath }
+    const unchanged = before.length === after.length && before.every((h, i) => h === after[i])
+    return { id, state: unchanged ? 'skipped' : 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
+function summarize(targets) {
+  const summary = { updated: 0, skipped: 0, missing: 0, failed: 0 }
+  for (const t of targets) summary[t.state] += 1
+  return summary
+}
+
+// tildeify — the contract's JSON example shows global paths abbreviated as
+// `~/...`; emitting the absolute path would both break byte-parity with the
+// other runtimes and leak the local username into committed/shared output.
+//
+// Both operands are run through path.normalize before comparison: a raw
+// process.env.HOME can contain a redundant separator (e.g. macOS's default
+// $TMPDIR ends in "/", so a test harness building HOME as `"$TMPDIR/foo"`
+// yields ".../T//foo"), while `absPath` here is always produced via
+// path.join, which normalizes internally — comparing the two without
+// normalizing homeRoot first made the prefix check silently fail and fall
+// through to the absolute-path branch. Mirrors Python's _tildeify
+// (pypi/trackfw/commands/update_harness.py), which normalizes both sides
+// via os.path.normpath for the same reason.
+//
+// A second, subtler case (ML-6H): path.normalize PRESERVES a trailing
+// separator when the input already has one (macOS's default $TMPDIR itself
+// ends in "/", so a HOME built as "$TMPDIR/foo" collapses the internal
+// "//" but still ends in a single trailing "/"). The prefix check below
+// then appended ANOTHER path.sep, comparing against ".../foo//" — which
+// normalizedPath (which never carries a trailing separator, since it comes
+// from path.join) never starts with — so the check silently failed and
+// 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.
+function tildeify(homeRoot, absPath) {
+  let normalizedHome = path.normalize(homeRoot)
+  if (normalizedHome.length > path.sep.length && normalizedHome.endsWith(path.sep)) {
+    normalizedHome = normalizedHome.slice(0, -path.sep.length)
+  }
+  const normalizedPath = path.normalize(absPath)
+  if (normalizedPath === normalizedHome) return '~'
+  if (normalizedPath.startsWith(normalizedHome + path.sep)) return '~' + normalizedPath.slice(normalizedHome.length)
+  return normalizedPath
+}
+
+// validateTargets — throws (usage error) when the caller asked for an id
+// that does not exist in the declared universe for this command. Returns
+// the requested id list unchanged (or null when no filter was requested).
+function validateTargets(allIds, wanted) {
+  if (!wanted || !wanted.length) return null
+  for (const id of wanted) {
+    if (!allIds.includes(id)) throw new Error(`Unknown update target: ${id}`)
+  }
+  return wanted
+}
+
+function buildDocument(scope, dryRun, targets) {
+  return {
+    scope,
+    dry_run: dryRun,
+    targets: targets.map(t => {
+      const entry = { id: t.id, state: t.state, path: t.path }
+      if (t.state === 'failed' && t.message) entry.message = t.message
+      return entry
+    }),
+    summary: summarize(targets),
+  }
+}
+
+function humanReport(scope, dryRun, targets) {
+  const lines = [`trackfw update — scope: ${scope}${dryRun ? ' (dry-run)' : ''}`, '']
+  for (const t of targets) {
+    const mark = { updated: '✓', skipped: '·', missing: '—', failed: '✗' }[t.state] || '?'
+    const suffix = t.state === 'failed' && t.message ? ` (${t.message})` : ''
+    lines.push(`  ${mark} ${t.id.padEnd(24)} ${t.state.padEnd(8)} ${t.path}${suffix}`)
+  }
+  const summary = summarize(targets)
+  lines.push('', `updated=${summary.updated} skipped=${summary.skipped} missing=${summary.missing} failed=${summary.failed}`)
+  return lines.join('\n')
+}
+
+module.exports = {
+  hashPath,
+  copyPath,
+  runFileTarget,
+  summarize,
+  tildeify,
+  validateTargets,
+  buildDocument,
+  humanReport,
+  silenceConsole,
+}