trackfw 7.1.0 → 7.2.0

package/src/integrations/index.js

@@ -56,7 +56,7 @@ function buildPlans(kind, options = {}) {
       for (const item of selected.itemEntries) {
         for (const installPath of paths) {
           const destination = installPath.path.replace('{{id}}', item.id)
-          let 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, agentModels: options.agentModels || {} })
           // 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"

package/src/integrations/render.js

@@ -97,6 +97,19 @@ function mapModelCursor(model) {
   return CURSOR_MODEL_MAP[model] || ''
 }
 
+// containsControlChar reports whether s contains any ASCII control character
+// (U+0000–U+001F) or a Unicode line/paragraph separator (U+2028, U+2029).
+// Mirrors internal/integrations/render.go:containsControlChar (ML-5C).
+// In JavaScript, strings are UTF-16; U+2028/U+2029 are single code units
+// accessible via charCodeAt, so no surrogate-pair handling is needed.
+function containsControlChar(s) {
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i)
+    if (c < 0x20 || c === 0x2028 || c === 0x2029) return true
+  }
+  return false
+}
+
 // 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 é
@@ -105,7 +118,14 @@ function mapModelCursor(model) {
 // espelha a detecção de fronteira usada por rewriteFrontmatterFields,
 // escopada à chave única "model". Espelha
 // internal/integrations/render.go:rewriteFrontmatterModelLine.
+//
+// Throws an Error if value contains any ASCII control character (U+0000–U+001F).
+// Model IDs never require control characters; any such value is rejected to
+// prevent frontmatter injection (ML-5A).
 function rewriteFrontmatterModelLine(source, value) {
+  if (containsControlChar(value)) {
+    throw new Error(`model value contains control character and was rejected: model IDs never require newlines or other control characters (got ${JSON.stringify(value)})`)
+  }
   const trimmed = String(source).trim()
   if (!trimmed.startsWith('---\n')) return trimmed
   const end = trimmed.indexOf('\n---', 4)
@@ -296,6 +316,27 @@ function frontmatterName(content) {
   return undefined
 }
 
+// isVersionString reports whether s is a bare version string (digits and dots
+// only, e.g. "5", "4.6", "1.0.2"). Mirrors internal/integrations/render.go:isVersionString.
+// Values that don't match — pre-composed IDs like "claude-sonnet-4-5-20250929" (hyphens),
+// "latest" (letters), or "" (empty) — return false and the caller uses the value literally
+// (escape hatch, ADR-2026-08-21 §3).
+function isVersionString(s) {
+  if (!s) return false
+  return /^[0-9]+(\.[0-9]+)*$/.test(s)
+}
+
+// composeClaudeModelID builds a Claude model identifier from tier and version,
+// applying the three composition rules from the official Anthropic docs.
+// Mirrors internal/integrations/render.go:composeClaudeModelID.
+//   Rule 1: dots become hyphens ("4.6" → "claude-sonnet-4-6")
+//   Rule 2: major-only version never gets "-0" ("5" → "claude-sonnet-5")
+//   Rule 3: handled via escape hatch — pre-composed IDs are never version strings
+function composeClaudeModelID(tier, version) {
+  const hyphenated = version.replace(/\./g, '-')
+  return `claude-${tier}-${hyphenated}`
+}
+
 // render converte um item canônico do catálogo para a representação nativa
 // declarada por uma surface alvo. Quando identity carrega uma identidade
 // customizada para item.id, o name/description/body renderizados são
@@ -321,7 +362,12 @@ 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, target }) {
+//
+// agentModels (opcional) — objeto de tier→versão lido de trackfw.yaml's agent_models.
+// Ausente ou vazio: saída idêntica a antes. Somente o alvo "claude" recebe IDs
+// compostos; Codex, Cursor, Antigravity, OpenCode, Gemini, Kiro não são afetados
+// (ADR-2026-08-21 §4 — gate, não cuidado).
+function render({ kind, content, capability, item, identity: cfg, target, agentModels }) {
   if (kind === 'skills') return normalize(content)
 
   const id = item && cfg ? lookupIdentity(cfg, item.id) : undefined
@@ -407,6 +453,18 @@ function render({ kind, content, capability, item, identity: cfg, target }) {
   if (target === 'cursor') {
     const mappedModel = mapModelCursor(parts.model)
     source = mappedModel ? rewriteFrontmatterModelLine(source, mappedModel) : removeFrontmatterModelLine(source)
+  } else if (target === 'claude' && agentModels && Object.keys(agentModels).length > 0) {
+    // Allowlist: only the "claude" target receives composed model IDs.
+    // Codex, Cursor, Antigravity, OpenCode, Gemini, Kiro and any other target are left
+    // untouched even when agentModels is populated (ADR-2026-08-21 §4 — gate, not cuidado).
+    const version = agentModels[parts.model]
+    if (version) {
+      const modelID = isVersionString(version)
+        ? composeClaudeModelID(parts.model, version)
+        : version // escape hatch: non-version value used literally (ADR-2026-08-21 §3)
+      source = rewriteFrontmatterModelLine(source, modelID)
+    }
+    // Empty string version means "no pin": leave source unchanged (tier alias preserved).
   }
   if (!id) return normalize(source)
   const withBody = insertBodyPrefix(source, greeting)
@@ -415,4 +473,60 @@ function render({ kind, content, capability, item, identity: cfg, target }) {
   return normalize(withSignature)
 }
 
-module.exports = { render, markdownParts, frontmatterName, greetingLine, insertBodyPrefix, rewriteFrontmatterFields, rewriteSignatureLine }
+// resolveAgentModel returns the model string that render() would write to the
+// model field of an artifact with the given representation and targetID, for
+// an agent with the given tier. Mirrors
+// internal/integrations/models.go:ResolveAgentModel.
+//
+// Returns { resolved: string, present: boolean }.
+// present=false means the artifact format omits the model field entirely — the
+// caller should display "—" or equivalent rather than the tier alias.
+//
+// agentModels applies only for the "claude" target (ADR-2026-08-21 §4).
+function resolveAgentModel(tier, representation, targetID, agentModels) {
+  if (representation === 'custom-agent-toml') {
+    const v = resolveModelCodex(tier)
+    return { resolved: v, present: v !== '' }
+  }
+  if (representation === 'cli-agent-json' || representation === 'agent-json') {
+    return { resolved: '', present: false }
+  }
+  if (representation === 'agent-directory') {
+    const v = resolveModel(tier)
+    return { resolved: v, present: v !== '' }
+  }
+  if (representation === 'opencode-agent') {
+    return { resolved: '', present: false }
+  }
+  // default branch — mirrors render()'s default case
+  if (targetID === 'cursor') {
+    const v = mapModelCursor(tier)
+    return { resolved: v, present: v !== '' }
+  }
+  if (targetID === 'claude') {
+    const am = agentModels || {}
+    const version = am[tier]
+    if (version) {
+      const modelID = isVersionString(version) ? composeClaudeModelID(tier, version) : version
+      return { resolved: modelID, present: true }
+    }
+    // no pin → tier alias unchanged
+  }
+  return { resolved: tier, present: true }
+}
+
+// looksLikeSuspectModelValue reports whether v is an agent_models value that
+// will trigger the escape-hatch path and likely produce an invalid model
+// identifier in the rendered artifact. Returns true when v is not a bare
+// version string AND does not start with "claude-". Callers should emit a
+// per-tier warning to stderr (not per-row) when this returns true.
+// Mirrors internal/integrations/models.go:LooksLikeSuspectModelValue.
+// looksLikeSuspectModelValue mirrors internal/integrations/models.go:LooksLikeSuspectModelValue.
+// ML-5A: values with control characters are always suspect — rewriteFrontmatterModelLine
+// rejects them outright, so this function must agree with the write path to keep the
+// "agents models" inspection command aligned with "agents install/update" behavior.
+function looksLikeSuspectModelValue(v) {
+  return containsControlChar(v) || (!isVersionString(v) && !v.startsWith('claude-'))
+}
+
+module.exports = { render, markdownParts, frontmatterName, greetingLine, insertBodyPrefix, rewriteFrontmatterFields, rewriteFrontmatterModelLine, rewriteSignatureLine, isVersionString, composeClaudeModelID, resolveAgentModel, looksLikeSuspectModelValue }

package/src/push/runner.js

@@ -0,0 +1,223 @@
+'use strict'
+
+/**
+ * push/runner.js — Core implementation of `trackfw push`.
+ *
+ * Empurra commits já criados, sem commitar e sem abrir PR/MR.
+ * Reusa os helpers de npm/src/ship/runner.js; nunca reimplementa a lógica de governança,
+ * detecção de squash-merge ou construção de push args.
+ *
+ * See ADR-2026-08-22-comandos-de-entrega-separados-push-proprio-e-ship-como-composicao.md.
+ */
+
+const {
+  isShipBranch,
+  isGatedShipBranch,
+  isGitWriteCmd,
+  checkShipGovernance,
+  detectPendingSquashMerges,
+  defaultCheckPROpen,
+  buildPushArgs,
+  defaultExecGit,
+} = require('../ship/runner')
+
+/**
+ * defaultCheckGovernance delegates to checkShipGovernance — the same hard gate used by
+ * `trackfw ship` and `trackfw commit`.
+ * @returns {string[]}
+ */
+function defaultCheckGovernance() {
+  return checkShipGovernance()
+}
+
+const { resolve: forgeResolve } = require('../forge/resolve')
+const { forgeAdapter } = require('../forge/adapter')
+
+// push --force-with-lease refusal messages — "trackfw push" (not "ship") because this command
+// closes the commit→push cycle without opening a PR. See
+// ADR-2026-08-22-comandos-de-entrega-separados-push-proprio-e-ship-como-composicao.md.
+// Defined here (not imported from ship/runner.js) to keep push's user-visible messages
+// independent of ship's contract string.
+const PUSH_FORCE_LEASE_NO_FORGE_CLI_MSG =
+  'trackfw push --force-with-lease requires a forge CLI (gh, glab, or az) to confirm an open pull/merge request before rewriting remote history. No forge CLI is available for this repository — install and authenticate it, or push without --force-with-lease.'
+
+function pushForceLeaseNoPROpenMsg(branch) {
+  return `trackfw push --force-with-lease refuses to run: branch "${branch}" has no open pull/merge request. Open the PR/MR first (trackfw ship without --force-with-lease, or your forge's web UI), then retry.`
+}
+
+function pushForceLeaseCannotVerifyMsg(branch, cliName, errMessage) {
+  return `trackfw push --force-with-lease could not verify whether branch "${branch}" has an open pull/merge request (${cliName} CLI error: ${errMessage}). Refusing rather than risking a force push without a verified PR — check your ${cliName} CLI authentication and retry.`
+}
+
+/**
+ * runPush implements the push sequence: branch validation, governance, force-with-lease gate,
+ * squash-merge detection, and push. Never commits and never opens a PR/MR.
+ *
+ * @param {{ dryRun?: boolean, forceWithLease?: boolean }} opts
+ * @param {{
+ *   execGit?: function,
+ *   checkGovernance?: function,
+ *   writeErr?: function,
+ *   configForge?: string,
+ *   repoDir?: string,
+ *   availFn?: function,
+ *   checkPROpen?: function,
+ * }} deps
+ * @returns {number} exit code (0 = success)
+ */
+function runPush(opts, deps) {
+  opts = opts || {}
+  deps = deps || {}
+
+  const execGit = deps.execGit || defaultExecGit
+  const checkGovernanceFn = deps.checkGovernance || defaultCheckGovernance
+  // writeln is injectable (mirrors ship/runner.js) so tests can capture stdout without spawning
+  // a real process. Production callers omit it and fall back to process.stdout.
+  const writeln = deps.writeln || ((s) => process.stdout.write(s + '\n'))
+  // "Error: " prefix — mirrors Go exactly: push.go returns messages as errors, and
+  // root.go's ExecuteC path emits `cmd.ErrPrefix() + " " + err.Error() + "\n"` —
+  // cmd.ErrPrefix() is "Error:", so the combined line is "Error: <message>\n".
+  const writeErr = deps.writeErr || ((s) => process.stderr.write(`Error: ${s}\n`))
+
+  // Inner wrapper: skips write commands in --dry-run mode.
+  function git(args) {
+    if (opts.dryRun && isGitWriteCmd(args)) {
+      writeln(`[dry-run] git ${args.join(' ')}`)
+      return { stdout: '', error: null }
+    }
+    return execGit(args)
+  }
+
+  // ─── Step 1: Branch validation ─────────────────────────────────────────────
+  const branchResult = execGit(['symbolic-ref', '--short', 'HEAD'])
+  if (branchResult.error) {
+    writeErr(`could not determine current branch (are you in a git repo?): ${branchResult.error.message}`)
+    return 1
+  }
+  const branch = branchResult.stdout.trim()
+
+  // main/master is blocked unconditionally.
+  if (branch === 'main' || branch === 'master') {
+    writeErr(`trackfw push cannot run on "${branch}" — use a feature branch:\n  git checkout -b feat/<slug>`)
+    return 1
+  }
+
+  if (!isShipBranch(branch)) {
+    writeErr(
+      `branch "${branch}" does not match the required pattern feat|fix|refactor|chore|docs/<slug>\n` +
+      'Rename your branch or create a new one:\n  git checkout -b feat/<slug>'
+    )
+    return 1
+  }
+
+  writeln(`Branch: ${branch}`)
+
+  // ─── Step 2: Governance ────────────────────────────────────────────────────
+  // push never reads the index — no doc-only exception. Governance is either
+  // skipped (chore/docs) or enforced (feat/fix/refactor), nothing in between.
+  if (!isGatedShipBranch(branch)) {
+    // chore/docs: housekeeping types already exempted from this gate by
+    // `trackfw branch new` and `trackfw commit` — push without it too.
+    writeln('Governance: skipped (chore/docs branch)')
+  } else {
+    const violations = checkGovernanceFn()
+    if (violations.length > 0) {
+      writeln('\nGovernance check failed:')
+      for (const v of violations) {
+        writeln(`  ${v}`)
+      }
+      writeln('\nCreate the required artifacts before running push:')
+      writeln('  trackfw req new "<title>"')
+      writeln('  trackfw roadmap new "<title>"')
+      writeln('  trackfw roadmap move <name> wip')
+      writeln("\nNote: this governance check is a hard gate — it is not affected by lenient")
+      writeln("mode or per-rule severity configured in trackfw.yaml. If 'trackfw validate'")
+      writeln("passes but 'trackfw push' aborts here, you likely have lenient mode")
+      writeln("configured — push always requires REQ + roadmap in wip/.")
+      writeErr(`governance check failed: ${violations.length} violation(s)`)
+      return 1
+    }
+
+    writeln('Governance: OK')
+  }
+
+  // ─── Step 2.5: force-with-lease gate ───────────────────────────────────────
+  // Runs before any write (push) — a refusal here never leaves the caller unable to push.
+  // Read-only, so it runs in --dry-run too.
+  if (opts.forceWithLease) {
+    const { stdout: gateRemoteURLRaw } = execGit(['remote', 'get-url', 'origin'])
+    const gateRemoteURL = (gateRemoteURLRaw || '').trim()
+
+    let resolution
+    try {
+      resolution = forgeResolve({
+        flagForge: '',
+        configForge: deps.configForge || '',
+        remoteURL: gateRemoteURL,
+        repoDir: deps.repoDir || '',
+      })
+    } catch (resErr) {
+      writeErr(resErr.message)
+      return 1
+    }
+
+    const adapter = forgeAdapter(resolution.forge, deps.availFn || undefined)
+    if (resolution.forge === 'manual' || !adapter.available) {
+      writeErr(PUSH_FORCE_LEASE_NO_FORGE_CLI_MSG)
+      return 1
+    }
+
+    const checkPROpen = deps.checkPROpen || defaultCheckPROpen
+    let open
+    try {
+      open = checkPROpen(adapter, branch)
+    } catch (prErr) {
+      writeErr(pushForceLeaseCannotVerifyMsg(branch, adapter.cliName, prErr.message))
+      return 1
+    }
+    if (!open) {
+      writeErr(pushForceLeaseNoPROpenMsg(branch))
+      return 1
+    }
+
+    writeln(`force-with-lease: open ${adapter.noun} confirmed for "${branch}" (${resolution.forge}).`)
+  }
+
+  // ─── Step 3: Squash-merge detection ────────────────────────────────────────
+  if (opts.dryRun) {
+    writeln('[dry-run] git fetch origin --prune')
+  } else {
+    const { error: fetchErr } = execGit(['fetch', 'origin', '--prune'])
+    if (fetchErr) {
+      writeln('Warning: could not fetch origin (offline or no remote); skipping squash-merge check.')
+    } else {
+      detectPendingSquashMerges(branch, execGit, writeln)
+    }
+  }
+
+  // ─── Step 4: Push ──────────────────────────────────────────────────────────
+  let pushArgs = buildPushArgs(branch, execGit)
+  if (opts.forceWithLease) {
+    // Fixed position: push --force-with-lease [-u] origin <branch> — identical
+    // across the 3 CLIs (the parity gate compares this literally).
+    pushArgs = [pushArgs[0], '--force-with-lease', ...pushArgs.slice(1)]
+  }
+  const { error: pushErr } = git(pushArgs)
+  if (pushErr) {
+    writeErr(`git push failed: ${pushErr.message}`)
+    return 1
+  }
+
+  if (!opts.dryRun) {
+    writeln(`Pushed: ${branch} → origin/${branch}`)
+  }
+
+  return 0
+}
+
+module.exports = {
+  runPush,
+  PUSH_FORCE_LEASE_NO_FORGE_CLI_MSG,
+  pushForceLeaseNoPROpenMsg,
+  pushForceLeaseCannotVerifyMsg,
+}