trackfw 3.1.0 → 5.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 = {}
@@ -100,14 +101,31 @@ function execute(kind, operation, options = {}, roots = {}) {
   const homeRoot = roots.homeRoot || os.homedir()
   const identityConfig = options.identity !== undefined ? options.identity : identityStore.load(homeRoot)
   const plans = buildPlans(kind, { ...options, identity: identityConfig })
-  const manager = new IntegrationManager(roots)
+  const manager = new IntegrationManager(roots, { onSkip: options.onSkip })
   let statuses
   if (operation === 'list') statuses = manager.inspect(plans)
   else if (operation === 'install') statuses = manager.install(plans, { force: options.force })
   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/manager.js

@@ -6,6 +6,7 @@ const os = require('node:os')
 const path = require('node:path')
 
 const { frontmatterName } = require('./render')
+const { tildeify } = require('../lib/update-engine')
 
 const SCHEMA_VERSION = 1
 const sha256 = content => crypto.createHash('sha256').update(content).digest('hex')
@@ -13,8 +14,9 @@ const claimKey = claim => [claim.target, claim.surface, claim.scope, claim.kind,
 const cleanClaim = claim => ({ target: claim.target, surface: claim.surface, scope: claim.scope, kind: claim.kind, item: claim.item })
 
 class IntegrationManager {
-  constructor({ projectRoot = process.cwd(), homeRoot = os.homedir() } = {}) {
+  constructor({ projectRoot = process.cwd(), homeRoot = os.homedir() } = {}, { onSkip } = {}) {
     this.roots = { project: path.resolve(projectRoot), global: path.resolve(homeRoot) }
+    this.onSkip = onSkip
   }
 
   manifestPath(scope) { return path.join(this.roots[scope], '.trackfw', 'integrations-manifest.json') }
@@ -127,17 +129,33 @@ class IntegrationManager {
     const manifests = new Map()
     for (const { plan } of resolved) if (!manifests.has(plan.claim.scope)) manifests.set(plan.claim.scope, this.loadManifest(plan.claim.scope))
     const desiredByFile = new Map()
+    const skippedFiles = new Set()
     for (const item of resolved) {
       const desired = sha256(item.plan.content)
       if (operation !== 'uninstall' && desiredByFile.has(item.file) && desiredByFile.get(item.file) !== desired) throw new Error(`Conflicting content planned for: ${item.file}`)
       desiredByFile.set(item.file, desired)
-      this.preflight(operation, item, manifests.get(item.plan.claim.scope), force)
+      const skip = this.preflight(operation, item, manifests.get(item.plan.claim.scope), force)
+      if (skip) {
+        skippedFiles.add(item.file)
+        if (typeof this.onSkip === 'function') {
+          // O manager compõe a linha completa e passa tilde-abreviado como
+          // destination (contrato: docs/cli-parity.md, "Valor de cada
+          // parâmetro — pinado"). A remediação é derivada de
+          // plan.claim.scope por artefato, nunca de inferência sobre o
+          // caminho renderizado.
+          const abbrev = this.tildeAbbrev(item.file, item.plan.claim.scope)
+          const remediation = item.plan.claim.scope === 'global' ? 'trackfw update harness' : 'trackfw update'
+          const reason = `warning: skipping outdated artifact ${abbrev}; run '${remediation}' to refresh it`
+          this.onSkip(abbrev, reason)
+        }
+      }
     }
+    const active = resolved.filter(item => !skippedFiles.has(item.file))
     const snapshots = new Map()
-    for (const item of resolved) this.snapshot(snapshots, item.file)
+    for (const item of active) this.snapshot(snapshots, item.file)
     for (const scope of manifests.keys()) this.snapshot(snapshots, this.manifestPath(scope))
     try {
-      for (const item of resolved) this.apply(operation, item, manifests.get(item.plan.claim.scope), force)
+      for (const item of active) this.apply(operation, item, manifests.get(item.plan.claim.scope), force)
       for (const [scope, manifest] of [...manifests].sort(([a], [b]) => a.localeCompare(b))) this.saveManifest(scope, manifest)
     } catch (error) {
       this.rollback(snapshots)
@@ -153,13 +171,14 @@ class IntegrationManager {
     const owned = Boolean(record && record.claims.some(claim => claimKey(claim) === claimKey(plan.claim)))
     if (operation === 'install') {
       if (status.state === 'modified' && !force) throw new Error(`Artifact is modified; use --force: ${file}`)
-      if (status.state === 'outdated' && owned && !force) throw new Error(`Artifact is outdated; use update: ${file}`)
+      if (status.state === 'outdated' && owned && !force) return true // skip: bytes preserved, batch continues
     } else if (operation === 'update') {
       if (!owned && status.state === 'modified') throw new Error(`Unmanaged artifact does not match a trackfw template: ${file}`)
       if (status.state === 'modified' && !force) throw new Error(`Artifact is modified; use --force: ${file}`)
     } else if (operation === 'uninstall' && owned && status.state === 'modified' && !force) {
       throw new Error(`Artifact is modified; use --force: ${file}`)
     }
+    return false
   }
 
   // detectNameCollision protege contra dois artefatos de agente gerenciados
@@ -273,6 +292,16 @@ class IntegrationManager {
     }
   }
 
+  // tildeAbbrev — retorna o caminho de exibição abreviado para uso em mensagens
+  // de aviso de skip. Espelha internal/integrations/manager.go:tildeAbbrev.
+  // - scope global: substitui homeRoot por '~' (via tildeify, com salvaguarda
+  //   de barra dupla corrigida no ML-6H).
+  // - scope de projeto: caminho relativo ao projectRoot, sem './' prefixo.
+  tildeAbbrev(file, scope) {
+    if (scope === 'global') return tildeify(this.roots.global, file)
+    return path.relative(this.roots.project, file)
+  }
+
   cleanEmpty(directory, root) {
     while (directory !== root) {
       const rel = path.relative(root, directory)

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,
+}

package/src/validator/index.js

@@ -1288,7 +1288,9 @@ module.exports = {
   listDir,
   tryListDir,
   resolveReqFiles,
+  resolveStateDirs,
   resolveWIPDirs,
+  resolveDoneDirs,
   readGovernanceMode,
   readWIPConfig,
   parseSquadFromFrontmatter,