trackfw 6.9.1 → 7.0.0

package/src/i18n/locales/en-US.json

@@ -115,22 +115,6 @@
     "tail": "Number of recent transitions to show",
     "header": "── trackfw log ─────────────────────────"
   },
-  "plugins": {
-    "description": "Manage trackfw plugins",
-    "list": {
-      "description": "List installed plugins",
-      "empty": "No plugins installed. Use `trackfw plugins add <user/repo>` to install one."
-    },
-    "add": {
-      "description": "Install a plugin from GitHub Releases (user/repo or user/repo@tag)",
-      "installing": "Installing plugin from {{repo}}...",
-      "success": "Plugin \"{{name}}\" installed successfully."
-    },
-    "remove": {
-      "description": "Remove an installed plugin",
-      "success": "Plugin \"{{name}}\" removed."
-    }
-  },
   "metrics": {
     "description": "Show delivery metrics",
     "no_data": "No transitions recorded yet.",
@@ -138,8 +122,6 @@
     "export": "Export metrics to CSV file"
   },
   "errors": {
-    "notFound": "Not found: {{path}}",
-    "downloadFailed": "download failed: HTTP {{status}} for {{url}}",
-    "pluginNotFound": "plugin \"{{name}}\" not found"
+    "notFound": "Not found: {{path}}"
   }
 }

package/src/i18n/locales/es-ES.json

@@ -115,22 +115,6 @@
     "tail": "Número de transiciones recientes a mostrar",
     "header": "── trackfw log ─────────────────────────"
   },
-  "plugins": {
-    "description": "Gestionar plugins de trackfw",
-    "list": {
-      "description": "Listar plugins instalados",
-      "empty": "No hay plugins instalados. Usa `trackfw plugins add <user/repo>` para instalar uno."
-    },
-    "add": {
-      "description": "Instalar un plugin desde GitHub Releases (user/repo o user/repo@tag)",
-      "installing": "Instalando plugin desde {{repo}}...",
-      "success": "Plugin \"{{name}}\" instalado correctamente."
-    },
-    "remove": {
-      "description": "Eliminar un plugin instalado",
-      "success": "Plugin \"{{name}}\" eliminado."
-    }
-  },
   "metrics": {
     "description": "Muestra métricas de entrega",
     "no_data": "No hay transiciones registradas aún.",
@@ -138,8 +122,6 @@
     "export": "Exportar métricas a archivo CSV"
   },
   "errors": {
-    "notFound": "No encontrado: {{path}}",
-    "downloadFailed": "fallo en la descarga: HTTP {{status}} para {{url}}",
-    "pluginNotFound": "plugin \"{{name}}\" no encontrado"
+    "notFound": "No encontrado: {{path}}"
   }
 }

package/src/i18n/locales/pt-BR.json

@@ -115,22 +115,6 @@
     "tail": "Número de transições recentes a exibir",
     "header": "── trackfw log ─────────────────────────"
   },
-  "plugins": {
-    "description": "Gerenciar plugins do trackfw",
-    "list": {
-      "description": "Listar plugins instalados",
-      "empty": "Nenhum plugin instalado. Use `trackfw plugins add <user/repo>` para instalar um."
-    },
-    "add": {
-      "description": "Instalar um plugin do GitHub Releases (user/repo ou user/repo@tag)",
-      "installing": "Instalando plugin de {{repo}}...",
-      "success": "Plugin \"{{name}}\" instalado com sucesso."
-    },
-    "remove": {
-      "description": "Remover um plugin instalado",
-      "success": "Plugin \"{{name}}\" removido."
-    }
-  },
   "metrics": {
     "description": "Exibe métricas de delivery",
     "no_data": "Nenhuma transição registrada ainda.",
@@ -138,8 +122,6 @@
     "export": "Exportar métricas para arquivo CSV"
   },
   "errors": {
-    "notFound": "Não encontrado: {{path}}",
-    "downloadFailed": "falha no download: HTTP {{status}} para {{url}}",
-    "pluginNotFound": "plugin \"{{name}}\" não encontrado"
+    "notFound": "Não encontrado: {{path}}"
   }
 }

package/src/integrations/index.js

@@ -8,6 +8,7 @@ const { IntegrationManager } = require('./manager')
 const { legacyHashes } = require('./legacy')
 const identityStore = require('../identity')
 const { injectRulesForTool } = require('../generators/init')
+const { applyThirdPartyReferences } = require('../thirdparty/references')
 
 function parseSurfaces(values = []) {
   const result = {}
@@ -55,7 +56,17 @@ function buildPlans(kind, options = {}) {
       for (const item of selected.itemEntries) {
         for (const installPath of paths) {
           const destination = installPath.path.replace('{{id}}', item.id)
-          const content = render({ target: targetEntry.id, kind, item, content: readAsset(item), capability, destination, identity: identityConfig })
+          let content = render({ target: targetEntry.id, kind, item, content: readAsset(item), capability, destination, identity: identityConfig })
+          // D5/D9 extension point: reproduce any persisted third-party
+          // reference block so regenerating this exact artifact (e.g. a
+          // later `trackfw agents update`) settles at state "current"
+          // instead of treating the attachment as drift. See the doc
+          // comment on applyThirdPartyReferences (../thirdparty/references.js)
+          // for why this cannot live inside render() itself. Mirrors
+          // internal/integrations/plan.go:BuildPlans.
+          if (kind === 'agents' && options.projectRoot) {
+            content = applyThirdPartyReferences(options.projectRoot, content, targetEntry.id, item.id)
+          }
           const claim = { target: targetEntry.id, surface: surface.id, scope, kind, item: item.id }
           plans.push({
             claim,
@@ -100,8 +111,14 @@ function execute(kind, operation, options = {}, roots = {}) {
   // executeIntegrationMutation/executeIntegrationList).
   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, { onSkip: options.onSkip })
+  // D5/D9: manager.roots.project lets buildPlans reproduce any persisted
+  // third-party reference block (see the projectRoot doc comment above the
+  // applyThirdPartyReferences call in buildPlans) so a plain `agents update`
+  // settles at state "current" after a third-party attachment instead of
+  // reporting drift. Mirrors internal/commands/integrations_flags.go passing
+  // manager.ProjectRoot to BuildPlans at both call sites.
+  const plans = buildPlans(kind, { ...options, identity: identityConfig, projectRoot: options.projectRoot || manager.roots.project })
   let statuses
   if (operation === 'list') statuses = manager.inspect(plans)
   else if (operation === 'install') statuses = manager.install(plans, { force: options.force })

package/src/integrations/manager.js

@@ -10,8 +10,21 @@ const { tildeify } = require('../lib/update-engine')
 
 const SCHEMA_VERSION = 1
 const sha256 = content => crypto.createHash('sha256').update(content).digest('hex')
-const claimKey = claim => [claim.target, claim.surface, claim.scope, claim.kind, claim.item].join('\u0000')
-const cleanClaim = claim => ({ target: claim.target, surface: claim.surface, scope: claim.scope, kind: claim.kind, item: claim.item })
+// claimKey includes origin (ADR-2026-08-15 D11) so a catalog claim and a
+// third-party claim that happen to share target/surface/scope/kind/item are
+// never treated as the same ownership record — mirrors Go's Claim struct
+// equality (`==`), field-by-field, which already includes Origin
+// (internal/integrations/manager.go's claimOwned/appendClaim/removeClaim).
+const claimKey = claim => [claim.target, claim.surface, claim.scope, claim.kind, claim.item, claim.origin || ''].join('\u0000')
+// cleanClaim omits origin entirely when falsy/absent, mirroring Go's
+// `json:"origin,omitempty"` — a catalog claim (origin "") must serialize
+// with NO "origin" key at all, byte-identical to a manifest written before
+// this field existed (retrocompatibility, D11).
+const cleanClaim = claim => {
+  const out = { target: claim.target, surface: claim.surface, scope: claim.scope, kind: claim.kind, item: claim.item }
+  if (claim.origin) out.origin = claim.origin
+  return out
+}
 
 class IntegrationManager {
   constructor({ projectRoot = process.cwd(), homeRoot = os.homedir() } = {}, { onSkip } = {}) {

package/src/integrations/render.js

@@ -67,6 +67,92 @@ function resolveModel(model) {
   return MODEL_MAP[model] || ''
 }
 
+// Mapa de model: nomes canônicos do catálogo → ID de modelo aceito pelo Codex
+// CLI. Fonte: documentação Codex CLI pesquisada em 2026-08-14 (ver ADR
+// ADR-2026-08-14-roteamento-de-model-tier-por-alvo-no-render-de-agentes-para-
+// codex-e-cursor). IDs de modelo Codex são versionados e mudam com o ciclo de
+// release da OpenAI.
+const CODEX_MODEL_MAP = { opus: 'gpt-5.4', sonnet: 'gpt-5.4-mini' }
+
+// resolveModelCodex converte o modelo canônico para o ID de modelo aceito
+// pelo Codex CLI. Retorna o valor mapeado, ou string vazia se a linha model
+// deve ser omitida (valor desconhecido ou ausente). Espelha
+// internal/integrations/render.go:mapModelCodex.
+function resolveModelCodex(model) {
+  if (!model) return ''
+  return CODEX_MODEL_MAP[model] || ''
+}
+
+// Mapa de model: nomes canônicos do catálogo → valor aceito pela Cursor
+// (fonte: cursor.com/docs/subagents, ver ADR ADR-2026-08-14-roteamento-de-
+// model-tier-por-alvo-no-render-de-agentes-para-codex-e-cursor).
+const CURSOR_MODEL_MAP = { opus: 'claude-opus-5[effort=high]', sonnet: 'composer-2.5[fast=true]' }
+
+// mapModelCursor converte o modelo canônico para o valor aceito pela Cursor.
+// Retorna o valor mapeado, ou string vazia se a linha "model:" deve ser
+// removida do frontmatter (Cursor cai no default "inherit"/Auto). Espelha
+// internal/integrations/render.go:mapModelCursor.
+function mapModelCursor(model) {
+  if (!model) return ''
+  return CURSOR_MODEL_MAP[model] || ''
+}
+
+// rewriteFrontmatterModelLine substitui a linha "model:" do frontmatter de um
+// markdown cru por value, preservando toda outra linha do frontmatter e o
+// corpo byte a byte. Se o frontmatter não tiver linha "model:", uma é
+// anexada como última linha do bloco de frontmatter. Se source não tiver
+// frontmatter reconhecível, source é retornado sem alteração (trimado) —
+// espelha a detecção de fronteira usada por rewriteFrontmatterFields,
+// escopada à chave única "model". Espelha
+// internal/integrations/render.go:rewriteFrontmatterModelLine.
+function rewriteFrontmatterModelLine(source, value) {
+  const trimmed = String(source).trim()
+  if (!trimmed.startsWith('---\n')) return trimmed
+  const end = trimmed.indexOf('\n---', 4)
+  if (end < 0) return trimmed
+  const frontmatter = trimmed.slice(4, end)
+  const rest = trimmed.slice(end) // começa com "\n---", seguido do corpo
+
+  const lines = frontmatter.split('\n')
+  let found = false
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const separator = line.indexOf(':')
+    if (separator < 0 || line.slice(0, separator).trim() !== 'model') continue
+    const rawValue = line.slice(separator + 1).trim()
+    const quoted = rawValue.length >= 2 && rawValue.startsWith('"') && rawValue.endsWith('"')
+    lines[i] = quoted ? `model: "${value}"` : `model: ${value}`
+    found = true
+    break
+  }
+  if (!found) lines.push(`model: ${value}`)
+
+  return `---\n${lines.join('\n')}${rest}`
+}
+
+// removeFrontmatterModelLine remove a linha "model:" do frontmatter de um
+// markdown cru, se presente, preservando toda outra linha do frontmatter e o
+// corpo byte a byte. Se source não tiver linha "model:" ou frontmatter
+// reconhecível, source é retornado sem alteração (trimado). Espelha
+// internal/integrations/render.go:removeFrontmatterModelLine.
+function removeFrontmatterModelLine(source) {
+  const trimmed = String(source).trim()
+  if (!trimmed.startsWith('---\n')) return trimmed
+  const end = trimmed.indexOf('\n---', 4)
+  if (end < 0) return trimmed
+  const frontmatter = trimmed.slice(4, end)
+  const rest = trimmed.slice(end) // começa com "\n---", seguido do corpo
+
+  const lines = frontmatter.split('\n')
+  const kept = lines.filter(line => {
+    const separator = line.indexOf(':')
+    return !(separator >= 0 && line.slice(0, separator).trim() === 'model')
+  })
+  if (kept.length === lines.length) return trimmed
+
+  return `---\n${kept.join('\n')}${rest}`
+}
+
 // toolsFor retorna SET_ARCH para o agente canônico "architect" (item.id do
 // catálogo, não o nome renderizado — que pode ser customizado pela
 // identidade), SET_IMPL para os demais. IDs proibidos (edit_file, read_file,
@@ -235,12 +321,13 @@ function frontmatterName(content) {
 // normalize(content) — a mesma expressão usada antes de existir suporte a
 // identidade — então a saída sem identidade é garantida byte a byte
 // inalterada por construção, não por coincidência.
-function render({ kind, content, capability, item, identity: cfg }) {
+function render({ kind, content, capability, item, identity: cfg, target }) {
   if (kind === 'skills') return normalize(content)
 
   const id = item && cfg ? lookupIdentity(cfg, item.id) : undefined
   const parts = markdownParts(content)
   let { name, description, body } = parts
+  let source = content
   let greeting = ''
   if (id) {
     greeting = greetingLine(id.display_name, (cfg && cfg.user_nickname) || '')
@@ -250,7 +337,14 @@ function render({ kind, content, capability, item, identity: cfg }) {
   }
 
   if (capability.representation === 'custom-agent-toml') {
-    return `name = ${JSON.stringify(name.replaceAll('-', '_'))}\ndescription = ${JSON.stringify(description)}\ndeveloper_instructions = ${JSON.stringify(body)}\n`
+    const lines = [
+      `name = ${JSON.stringify(name.replaceAll('-', '_'))}`,
+      `description = ${JSON.stringify(description)}`,
+    ]
+    const mappedModel = resolveModelCodex(parts.model)
+    if (mappedModel) lines.push(`model = ${JSON.stringify(mappedModel)}`)
+    lines.push(`developer_instructions = ${JSON.stringify(body)}`)
+    return `${lines.join('\n')}\n`
   }
   if (capability.representation === 'cli-agent-json' || capability.representation === 'agent-json') {
     // Ordem alfabética das chaves (description, name, prompt) é obrigatória:
@@ -310,8 +404,12 @@ function render({ kind, content, capability, item, identity: cfg }) {
     return out
   }
 
-  if (!id) return normalize(content)
-  const withBody = insertBodyPrefix(content, greeting)
+  if (target === 'cursor') {
+    const mappedModel = mapModelCursor(parts.model)
+    source = mappedModel ? rewriteFrontmatterModelLine(source, mappedModel) : removeFrontmatterModelLine(source)
+  }
+  if (!id) return normalize(source)
+  const withBody = insertBodyPrefix(source, greeting)
   const withFrontmatter = rewriteFrontmatterFields(withBody, name, description)
   const withSignature = rewriteSignatureLine(withFrontmatter, id.display_name)
   return normalize(withSignature)

package/src/lib/unknown-command.js

@@ -0,0 +1,82 @@
+'use strict'
+
+// unknown-command.js — canonical cross-CLI "unknown command" message and the
+// shared suggestion algorithm.
+//
+// ADR-2026-08-15-remocao-do-subsistema-de-plugins-em-vez-de-gate-de-binario-de-
+// terceiro.md (D3): argument dispatch to an external `trackfw-<name>` binary was
+// removed together with the plugin subsystem. An unrecognized top-level command
+// now always produces the message below instead — in all three CLIs.
+//
+// The plain (no-transposition) Levenshtein distance and the suggestion-picking
+// rule here are reimplemented IDENTICALLY in Go (internal/commands/root.go,
+// suggestCommand/levenshteinDistance) and Python (pypi/trackfw/cli.py,
+// _suggest_command/_levenshtein_distance) — deliberately NOT delegated to each
+// framework's own suggestion helper (cobra's Command.SuggestionsFor, commander's
+// suggestSimilar), which use different distance functions/thresholds and would
+// make the three CLIs disagree on whether/what to suggest for the same typo.
+// Parity is enforced by scripts/check-unknown-command-parity.sh.
+
+function levenshteinDistance(a, b) {
+  const la = a.length
+  const lb = b.length
+  const d = []
+  for (let i = 0; i <= la; i++) {
+    d.push(new Array(lb + 1).fill(0))
+    d[i][0] = i
+  }
+  for (let j = 0; j <= lb; j++) {
+    d[0][j] = j
+  }
+  for (let i = 1; i <= la; i++) {
+    for (let j = 1; j <= lb; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      d[i][j] = Math.min(
+        d[i - 1][j] + 1, // deletion
+        d[i][j - 1] + 1, // insertion
+        d[i - 1][j - 1] + cost, // substitution
+      )
+    }
+  }
+  return d[la][lb]
+}
+
+// suggestCommand — a candidate is eligible when its case-insensitive
+// Levenshtein distance to `typed` is <= 2, OR it is a case-insensitive prefix
+// match (candidate starts with the typed text). Among eligible candidates the
+// winner is the one with the lowest distance, alphabetical tie-break, so the
+// pick is deterministic and single — matching Go/Python exactly.
+function suggestCommand(typed, candidates) {
+  const lowerTyped = typed.toLowerCase()
+  let bestDist = -1
+  let best = ''
+  for (const candidate of candidates) {
+    const lowerC = candidate.toLowerCase()
+    const dist = levenshteinDistance(lowerTyped, lowerC)
+    const prefixMatch = lowerTyped.length > 0 && lowerC.startsWith(lowerTyped)
+    if (dist > 2 && !prefixMatch) continue
+    if (bestDist === -1 || dist < bestDist || (dist === bestDist && candidate < best)) {
+      bestDist = dist
+      best = candidate
+    }
+  }
+  return bestDist === -1 ? null : best
+}
+
+// formatUnknownCommandError — canonical message, byte-identical across the
+// three CLIs modulo the typed name and the suggestion (present only when
+// suggestCommand finds an eligible candidate):
+//   Error: unknown command "x" for "trackfw"
+//   Did you mean "validate"?
+//   Run 'trackfw --help' for usage.
+function formatUnknownCommandError(typed, candidates, cmdPath) {
+  const lines = [`Error: unknown command "${typed}" for "${cmdPath}"`]
+  const suggestion = suggestCommand(typed, candidates)
+  if (suggestion) {
+    lines.push(`Did you mean "${suggestion}"?`)
+  }
+  lines.push(`Run '${cmdPath} --help' for usage.`)
+  return lines.join('\n')
+}
+
+module.exports = { levenshteinDistance, suggestCommand, formatUnknownCommandError }