token-trace-manager 0.7.0

package/bin/ttm.mjs

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+// CLI do token-trace-manager. Uso: ttm <comando> [opções]
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFile } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { readConfig, writeConfig, setTarget, removeTarget, validateConfig, KNOWN_PROTOCOLS } from '../lib/config.mjs'
+import { ensureDaemon, stopDaemon, daemonHealth, fetchDaemon } from '../lib/daemon-client.mjs'
+import { linkTui, unlinkTui } from '../lib/link.mjs'
+import { PRICING_LAST_UPDATED } from '../lib/pricing.mjs'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+const HELP = `ttm — rastreio universal de tokens/custo para TUIs de código
+
+Comandos:
+  ttm start                     Sobe o daemon do proxy (idempotente)
+  ttm stop                      Para o daemon
+  ttm status                    Estado do daemon + resumo da configuração
+  ttm label <TICKET-123|none>   Define (ou limpa) o label padrão para tráfego sem label na URL
+  ttm tokens <TICKET-123> [--since 30d]
+                                Imprime SÓ a quantidade de tokens da tarefa (pra colar no Jira)
+  ttm audit [--since 7d]        Audita: re-multiplica tokens x taxas gravadas e reconcilia,
+                                id a id, com o log independente do Claude Code
+  ttm summary [--since 7d]      Resumo de uso/custo no terminal
+  ttm dashboard [--since 7d] [--out arquivo.html]
+                                Abre o dashboard ao vivo (ou exporta HTML estático)
+  ttm targets                   Lista os targets configurados (provedores upstream)
+  ttm config [porta <n>]        Mostra config; 'porta <n>' troca a porta do proxy
+  ttm config target <name> <url> [--protocol P] [--env VAR]
+                                Adiciona/remove/lista targets custom (fallback manual ao link)
+  ttm link <tui> [--label T] [--repo] [--force]
+                                Descobre a base URL que o <tui> já usa, vira upstream,
+                                e reescreve a config do <tui> pra apontar pro ttm.
+                                Preserva redirect prévio (z.ai/GLM/...) — não re-routa
+                                pro vendor real. TUIs: claude-code, codex, opencode, gemini-cli
+  ttm unlink <tui>              Desfaz o link: restaura a config original do <tui> e remove o target
+  ttm setup <tui>               Mostra o snippet de configuração para um TUI
+                                (claude-code, codex, opencode, gemini-cli, kilo, ...)
+
+O proxy escuta só em 127.0.0.1. Conteúdo de prompts/respostas fica em payloads/
+locais se 'storePayloads' estiver ligado (default: sim) — chaves de API nunca
+são gravadas. Preços atualizados em ${PRICING_LAST_UPDATED}.`
+
+function flag(args, name, dflt) {
+  const i = args.indexOf(name)
+  if (i === -1) return dflt
+  return args[i + 1] ?? dflt
+}
+
+function fmtTok(n) {
+  n = n || 0
+  if (n >= 1e9) return (n / 1e9).toFixed(2) + 'B'
+  if (n >= 1e6) return (n / 1e6).toFixed(2) + 'M'
+  if (n >= 1e3) return (n / 1e3).toFixed(1) + 'k'
+  return String(n)
+}
+
+const fmtUsd = n => '$' + (n || 0).toFixed(2)
+
+async function main() {
+  const [cmd, ...args] = process.argv.slice(2)
+  const cfg = readConfig()
+
+  switch (cmd) {
+    case 'start': {
+      const { started, health, restartedFrom } = await ensureDaemon()
+      console.log(
+        restartedFrom
+          ? `daemon reiniciado (v${restartedFrom} -> v${health.version}) em http://127.0.0.1:${cfg.port} (pid ${health.pid})`
+          : started
+            ? `daemon iniciado em http://127.0.0.1:${cfg.port} (pid ${health.pid})`
+            : `daemon já estava rodando em http://127.0.0.1:${cfg.port} (pid ${health.pid}, uptime ${health.uptime_s}s)`,
+      )
+      return
+    }
+
+    case 'stop': {
+      const r = await stopDaemon()
+      console.log(r.stopped ? `daemon parado (pid ${r.pid})` : `nada a parar: ${r.reason}`)
+      return
+    }
+
+    case 'status': {
+      const h = await daemonHealth()
+      if (!h) {
+        console.log(`daemon: PARADO (rode \`ttm start\`) — porta configurada: ${cfg.port}`)
+        return
+      }
+      const label = (await fetchDaemon('/api/label')).defaultLabel
+      console.log(`daemon: RODANDO em http://127.0.0.1:${cfg.port} (pid ${h.pid}, v${h.version}, uptime ${h.uptime_s}s)`)
+      console.log(`label padrão: ${label ?? '(nenhum — use labels na URL ou \`ttm label X\`)'}`)
+      console.log(`dashboard: http://127.0.0.1:${cfg.port}/dashboard`)
+      return
+    }
+
+    case 'label': {
+      const value = args[0]
+      if (!value) {
+        await ensureDaemon()
+        console.log(`label padrão atual: ${(await fetchDaemon('/api/label')).defaultLabel ?? '(nenhum)'}`)
+        return
+      }
+      await ensureDaemon()
+      const label = value === 'none' || value === 'nenhum' ? null : value
+      const r = await fetchDaemon('/api/label', { method: 'POST', body: { label } })
+      console.log(label ? `label padrão definido: ${r.defaultLabel}` : 'label padrão removido')
+      return
+    }
+
+    case 'tokens': {
+      const key = args[0]
+      if (!key) {
+        console.error('uso: ttm tokens <TICKET-123> [--since 30d] [--raw]  (métrica lidos/escritos, estilo Langfuse)')
+        process.exit(1)
+      }
+      await ensureDaemon()
+      const since = flag(args, '--since', '30d')
+      const r = await fetchDaemon(
+        `/api/summary?since=${encodeURIComponent(since)}&label=${encodeURIComponent(key.toUpperCase())}`,
+      )
+      if (args.includes('--raw')) {
+        console.log(r.totalTokens) // só o total, para scripts
+        return
+      }
+      console.log(`lidos=${r.tokensIn ?? 0} escritos=${r.tokensOut ?? 0} total=${r.totalTokens}`)
+      return
+    }
+
+    case 'audit': {
+      const { runAudit } = await import('../lib/audit.mjs')
+      const since = flag(args, '--since', null)
+      const sinceIso = since
+        ? new Date(Date.now() - parseInt(since, 10) * (since.endsWith('h') ? 3600000 : 86400000)).toISOString()
+        : null
+      const r = await runAudit({ sinceIso })
+      console.log(`auditoria (${since ?? 'tudo'}) — ${r.eventCount} eventos\n`)
+      console.log(`[1] matemática interna (custo = tokens x taxas gravadas na hora da chamada)`)
+      console.log(`    verificados: ${r.math.checked}  |  exatos: ${r.math.ok}  |  divergentes: ${r.math.drift.length}  |  sem recibo de taxas (eventos antigos): ${r.math.noRates}`)
+      for (const d of r.math.drift.slice(0, 5)) {
+        console.log(`    ! evento #${d.id} (${d.label ?? 'sem label'}): gravado $${d.stored?.toFixed(6)} vs recalculado $${d.recomputed.toFixed(6)}`)
+      }
+      console.log(`\n[2] reconciliação com fontes independentes (agnóstico ao harness)`)
+      let mismatchTotal = 0
+      for (const s of r.sources) {
+        if (!s.available) {
+          console.log(`    - ${s.title}: indisponível nesta máquina`)
+          continue
+        }
+        mismatchTotal += s.mismatches.length
+        console.log(
+          `    - ${s.title} [${s.strategy === 'provider_id' ? 'casa por id do provedor' : 'casa por impressão digital'}]: ` +
+            `casados: ${s.matched}  |  idênticos token a token: ${s.identical}  |  divergentes: ${s.mismatches.length}`,
+        )
+        for (const m of s.mismatches.slice(0, 5)) {
+          console.log(`      ! evento #${m.event_id} (${m.label ?? 'sem label'}): ${JSON.stringify(m.fields)}`)
+        }
+      }
+      if (r.uncovered.length) {
+        console.log(`    - sem fonte local que cubra: ${r.uncovered.length} evento(s) — normal para TUIs sem log próprio de usage`)
+        for (const u of r.uncovered.slice(0, 3)) {
+          console.log(`      · #${u.id} ${u.label ?? 'sem label'} via ${(u.client || '?').split(' ')[0]} (${u.target})`)
+        }
+      }
+      const clean = r.math.drift.length === 0 && mismatchTotal === 0
+      console.log(clean ? '\n✓ nenhuma divergência encontrada' : '\n✗ divergências acima — investigue')
+      process.exit(clean ? 0 : 1)
+    }
+
+    case 'summary': {
+      await ensureDaemon()
+      const since = flag(args, '--since', '30d')
+      const r = await fetchDaemon(`/api/summary?since=${encodeURIComponent(since)}`)
+      console.log(`período: ${since} — ${r.eventCount} chamadas, ${fmtTok(r.totalTokens)} tokens, ${fmtUsd(r.totalCost)}${r.costKnown ? '' : ' (custo parcial: há modelos sem preço na tabela)'}`)
+      for (const l of r.byLabel.slice(0, 10)) {
+        console.log(`  ${l.key.padEnd(20)} ${fmtTok(l.tokens).padStart(9)} tok  ${fmtUsd(l.cost).padStart(9)}  (${l.events} chamadas)`)
+      }
+      return
+    }
+
+    case 'dashboard': {
+      await ensureDaemon()
+      const since = flag(args, '--since', '30d')
+      const out = flag(args, '--out', null)
+      if (out) {
+        const report = await fetchDaemon(`/api/summary?since=${encodeURIComponent(since)}`)
+        const template = fs.readFileSync(path.join(__dirname, '..', 'templates', 'dashboard.html'), 'utf8')
+        const json = JSON.stringify(report).replace(/</g, '\\u003c')
+        fs.writeFileSync(out, template.replace('"__REPORT_DATA__"', () => json))
+        console.log(`dashboard exportado: ${out}`)
+        return
+      }
+      const url = `http://127.0.0.1:${cfg.port}/dashboard?since=${encodeURIComponent(since)}`
+      console.log(url)
+      const opener = process.platform === 'darwin' ? 'open' : 'xdg-open'
+      execFile(opener, [url], () => {})
+      return
+    }
+
+    case 'targets': {
+      console.log(`targets registrados (primeiro segmento do path escolhe o upstream):`)
+      for (const [name, t] of Object.entries(cfg.targets)) {
+        console.log(`  /${name.padEnd(12)} -> ${t.targetUrl}  [protocolo: ${t.protocol}]`)
+      }
+      console.log(`\nproxyUrl: ${cfg.proxyUrl}`)
+      return
+    }
+
+    case 'config': {
+      if (args[0] === 'porta' || args[0] === 'port') {
+        const n = parseInt(args[1], 10)
+        if (isNaN(n) || n < 1024 || n > 65535) {
+          console.error('porta deve ser um número entre 1024 e 65535')
+          process.exit(1)
+        }
+        writeConfig({ port: n, proxyUrl: `http://127.0.0.1:${n}` })
+        console.log(`porta alterada para ${n} — rode \`ttm stop && ttm start\` para aplicar`)
+        return
+      }
+      if (args[0] === 'target') {
+        // ttm config target                          -> lista
+        // ttm config target <name> <url> [opts]      -> set
+        // ttm config target <name> --remove          -> remove (ordem qualquer)
+        const sub = args.slice(1)
+        const isList = sub.length === 0 || sub.includes('--list') || sub.includes('list')
+        const isRemove = sub.includes('--remove') || sub.includes('remove')
+        const positional = sub.filter(x => x && !x.startsWith('--') && x !== 'list' && x !== 'remove')
+        if (isList) {
+          const c = readConfig()
+          for (const [name, t] of Object.entries(c.targets)) {
+            const inv = t._invalid ? ' [PROTOCOLO INVÁLIDO]' : ''
+            const env = t.targetUrlEnv ? ` via env ${t.targetUrlEnv}` : ''
+            console.log(`  /${name.padEnd(14)} -> ${t.targetUrl}${env}  [protocolo: ${t.protocol}]${inv}`)
+          }
+          const { warnings } = validateConfig(c)
+          for (const w of warnings) console.error(`  ! ${w}`)
+          return
+        }
+        if (isRemove) {
+          const name = positional[0]
+          if (!name) { console.error('uso: ttm config target <name> --remove'); process.exit(1) }
+          removeTarget(name)
+          console.log(`target "${name}" removido`)
+          return
+        }
+        const name = positional[0]
+        const url = positional[1]
+        if (!name || !url) {
+          console.error('uso: ttm config target <name> <url> [--protocol P] [--env VAR]')
+          process.exit(1)
+        }
+        const protocol = flag(sub, '--protocol', 'anthropic')
+        const envVar = flag(sub, '--env', null)
+        if (!KNOWN_PROTOCOLS.includes(protocol)) {
+          console.error(`protocolo inválido "${protocol}" — válidos: ${KNOWN_PROTOCOLS.join(', ')}`)
+          process.exit(1)
+        }
+        const spec = { targetUrl: url, protocol }
+        if (envVar) spec.targetUrlEnv = envVar
+        setTarget(name, spec)
+        console.log(`target "${name}" -> ${url} [protocolo: ${protocol}${envVar ? `, env: ${envVar}` : ''}]`)
+        return
+      }
+      console.log(JSON.stringify({ ...cfg, pricingLastUpdated: PRICING_LAST_UPDATED }, null, 2))
+      return
+    }
+
+    case 'link': {
+      const tui = args[0]
+      if (!tui) { console.error('uso: ttm link <tui> [--label TICKET] [--repo] [--force]'); process.exit(1) }
+      const label = flag(args, '--label', null)
+      const repo = args.includes('--repo')
+      const force = args.includes('--force')
+      const r = await linkTui(tui, { label, repo, force })
+      if (r.supported === false) {
+        console.error(`TUI "${tui}" não tem auto-link. TUIs suportados: claude-code, codex, opencode, gemini-cli. Use \`ttm setup ${tui}\` para snippet manual.`)
+        process.exit(1)
+      }
+      if (r.needsForce) {
+        console.error(r.hint)
+        process.exit(1)
+      }
+      if (r.error) {
+        console.error(r.error)
+        process.exit(1)
+      }
+      if (r.alreadyLinked) {
+        console.log(`já linkado: ${r.tui} -> ${r.upstream} (proxy: ${r.proxyBaseUrl})`)
+        if (r.label) console.log(`label padrão: ${r.label}`)
+        return
+      }
+      console.log(`linkado: ${r.tui} -> upstream ${r.upstream} [protocolo: ${r.protocol}]`)
+      console.log(`  base URL do ${r.tui} agora aponta pra: ${r.proxyBaseUrl}`)
+      if (r.rewrite.done) {
+        console.log(`  config do TUI reescrita em: ${r.rewrite.writeTarget} (fonte: ${r.rewrite.source})`)
+      } else {
+        console.log(`  ⚠ ${r.rewrite.note}`)
+        console.log(`  rode no seu shell:  ${r.rewrite.exportLine}`)
+      }
+      if (r.label) console.log(`label padrão: ${r.label}`)
+      console.log(`  reinicie o ${r.tui} para que ele pegue a nova base URL`)
+      return
+    }
+
+    case 'unlink': {
+      const tui = args[0]
+      if (!tui) { console.error('uso: ttm unlink <tui>'); process.exit(1) }
+      const r = await unlinkTui(tui)
+      if (r.notLinked) {
+        console.log(`nada a desfazer: ${r.tui} não estava linkado`)
+        return
+      }
+      console.log(`deslinkado: ${r.tui}`)
+      if (r.restore.done) {
+        console.log(`  config original restaurada em: ${r.restore.writeTarget}`)
+      } else {
+        console.log(`  ⚠ ${r.restore.note}`)
+        console.log(`  rode no seu shell:  ${r.restore.exportLine}`)
+      }
+      console.log(`  reinicie o ${r.tui} para aplicar`)
+      return
+    }
+
+    case 'setup': {
+      const { setupSnippet } = await import('../lib/setup-snippets.mjs')
+      console.log(setupSnippet(args[0], cfg))
+      return
+    }
+
+    default:
+      console.log(HELP)
+      if (cmd && cmd !== 'help' && cmd !== '--help' && cmd !== '-h') {
+        console.error(`\ncomando desconhecido: ${cmd}`)
+        process.exit(1)
+      }
+  }
+}
+
+main().catch(err => {
+  console.error(`erro: ${err.message}`)
+  process.exit(1)
+})

package/commands/config.md

@@ -0,0 +1,13 @@
+---
+description: Mostra a configuração do proxy (porta, targets, label) e como ajustá-la
+---
+
+Chame a ferramenta MCP `ttm_status` e apresente em português:
+- proxyUrl e porta
+- targets registrados (nome → targetUrl do provedor)
+- label padrão atual
+
+Se o usuário quiser MUDAR algo, explique os caminhos:
+- Porta: `node <plugin>/bin/ttm.mjs config porta <n>` no terminal (ou editar `~/.claude/plugins/data/token-trace-manager/config.json`), seguido de `ttm stop && ttm start`.
+- Targets extras (ex: um gateway interno): adicionar em `targets` no mesmo `config.json`, com `targetUrl` e `protocol` (`anthropic` | `openai` | `openai-responses` | `gemini`).
+- Preços de modelos não listados: criar `pricing.override.json` no mesmo diretório com `{ "<model-id>": { "input": X, "output": Y } }` (USD por 1M tokens).

package/commands/dashboard.md

@@ -0,0 +1,7 @@
+---
+description: Abre o dashboard local de uso/custo de tokens
+---
+
+Chame a ferramenta MCP `ttm_dashboard_url` (ela garante que o daemon está de pé) e devolva a URL ao usuário em português, explicando que é um dashboard ao vivo servido localmente (só em 127.0.0.1) com custo por label/ticket, provedor, modelo, cliente (TUI) e dia.
+
+Se o usuário pediu uma janela específica (ex: "últimos 7 dias"), acrescente `?since=7d` à URL retornada.

package/commands/link.md

@@ -0,0 +1,12 @@
+---
+description: Define o label padrão (ticket Jira) atribuído ao tráfego do proxy
+argument-hint: <TICKET-123 | none>
+---
+
+Chame a ferramenta MCP `ttm_activate` com `label` = `$ARGUMENTS` (ou `ttm_set_label` com `null` se o usuário passou `none`/`nenhum`). Sem argumento nenhum, chame `ttm_activate` sem label — ela detecta o ticket pela branch git. Se o usuário disser que já estava trabalhando antes de criar o card, use `retroactive_minutes` com a janela que ele indicar.
+
+Contexto para explicar ao usuário (em português, uma ou duas frases):
+- O label padrão vale para TODO tráfego que passar pelo proxy sem label embutido na URL, de qualquer TUI, até ser trocado.
+- Para atribuição por repositório/branch sem depender do label padrão, o caminho é embutir o ticket na própria base URL (ex: `http://127.0.0.1:25519/anthropic/PROJ-123`) — mencione isso se o usuário parecer trabalhar em vários tickets ao mesmo tempo.
+
+Se o usuário não passou argumento, chame `ttm_status` e informe apenas o label padrão atual.

package/commands/setup.md

@@ -0,0 +1,19 @@
+---
+description: Configura o Claude Code (ou mostra o snippet de outro TUI) para passar pelo proxy de tokens
+argument-hint: "[claude-code | codex | opencode | gemini-cli | kilo | ...]"
+---
+
+O objetivo é apontar a base URL do TUI para o proxy local (`http://127.0.0.1:<porta>/<target>[/<TICKET-123>]`). Chame `ttm_status` para obter a porta e os targets atuais.
+
+**Se `$ARGUMENTS` for vazio ou `claude-code`** — o TUI é o próprio Claude Code:
+1. Explique que a variável `ANTHROPIC_BASE_URL` precisa estar definida ANTES do Claude Code iniciar, então a mudança só vale para sessões novas.
+2. Proponha (e, com aprovação do usuário, aplique) adicionar ao `~/.claude/settings.json` — preservando o conteúdo existente — o bloco:
+   ```json
+   "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:<porta>/anthropic" }
+   ```
+   Se o usuário quiser atribuição automática por ticket num repo específico, sugira colocar o mesmo bloco no `.claude/settings.json` DO REPO com o ticket no path (ex: `/anthropic/PROJ-123`).
+3. Avise: para desfazer, basta remover a env; e se o daemon estiver parado, as chamadas falham — o Claude Code não inicia sem conseguir falar com a URL. Sugira validar com `ttm_status` que o daemon está de pé antes de reiniciar.
+
+**Se `$ARGUMENTS` nomear outro TUI** (codex, opencode, gemini-cli, kilo, etc.): rode `node ${CLAUDE_PLUGIN_ROOT}/bin/ttm.mjs setup $ARGUMENTS` via Bash e apresente o snippet impresso, explicando em português onde colar.
+
+Sempre termine confirmando que o daemon está rodando (`ttm_status`) — sem ele de pé, o TUI configurado fica sem resposta.

package/commands/status.md

@@ -0,0 +1,13 @@
+---
+description: Mostra o estado do proxy de tokens e o resumo de uso/custo
+---
+
+Chame a ferramenta MCP `ttm_status` e depois `ttm_usage_summary` (sem argumentos, janela padrão de 30 dias).
+
+Responda em português, compacto:
+1. Daemon rodando ou parado (se parado, diga que `ttm_dashboard_url` ou `ttm start` no terminal sobe ele).
+2. Label padrão atual (ou que o tráfego está caindo em "Sem label").
+3. Total de chamadas, tokens e custo da janela, e os 3 maiores labels por custo.
+4. A URL do dashboard.
+
+Se `costKnown` vier `false`, avise que o custo é parcial (há modelos sem preço na tabela — tokens registrados mesmo assim).