ai-usage-metrics 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Breno Luiz
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,218 @@
1
- # Temporary Holding Version
1
+ # ai-usage-metrics
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![Licença: MIT](https://img.shields.io/badge/licen%C3%A7a-MIT-blue.svg)](LICENSE)
4
+ [![Node.js >= 24](https://img.shields.io/badge/node-%3E%3D24-339933.svg)](https://nodejs.org/)
5
+ [![Dependências: 0](https://img.shields.io/badge/depend%C3%AAncias-0-brightgreen.svg)](package.json)
6
+
7
+ Mede, no seu computador, quanto e onde você usa ferramentas de IA para programar, e publica um painel em SVG no seu próprio repositório do GitHub, pronto para o README do perfil.
8
+
9
+ <picture>
10
+ <source media="(prefers-color-scheme: dark)" srcset="examples/metrics.example.dark.svg">
11
+ <img alt="Painel de exemplo com sessões, mensagens, tokens, dias ativos, sessões por mês e projetos com mais uso" src="examples/metrics.example.light.svg">
12
+ </picture>
13
+
14
+ <sub>Painel gerado com dados fictícios (`examples/`).</sub>
15
+
16
+ ## Por que existe
17
+
18
+ Quem usa assistentes de IA todo dia raramente tem números sobre isso: quantas sessões, em quais projetos, com que volume. As próprias ferramentas já guardam esses registros no seu disco. O `ai-usage-metrics` lê esses registros, agrega, anonimiza e gera um painel que você controla, sem servidor de terceiros e sem enviar o conteúdo de nenhuma conversa.
19
+
20
+ ## Recursos
21
+
22
+ - **100% local e somente leitura.** Os registros das ferramentas nunca são alterados.
23
+ - **Determinístico.** Todo número é calculado por código; não há IA no meio.
24
+ - **Zero dependências.** Apenas Node.js 24+ e `git`.
25
+ - **Privacidade por padrão.** Só contagens e datas saem da sua máquina; projetos aparecem anonimizados (`projeto-privado-N`) a menos que você escolha nomes públicos.
26
+ - **Publicação com trava.** O `publish` é um dry-run por padrão e só envia com confirmação explícita.
27
+ - **Atualização diária** por tarefa agendada (Agendador de Tarefas do Windows ou `cron`).
28
+ - **Temas** claro, escuro ou automático, em inglês ou português (pt-BR).
29
+
30
+ ## Fontes suportadas
31
+
32
+ | Ferramenta | O que é medido |
33
+ |---|---|
34
+ | Claude Code (CLI e extensão do VS Code) | sessões, mensagens, tokens e projeto |
35
+ | Cline (CLI) | sessões, mensagens, tokens e projeto |
36
+ | ChatGPT (via catálogo do app desktop) | só o número de sessões por dia |
37
+
38
+ Ainda não suportados: Cursor, GitHub Copilot CLI, Gemini/Antigravity, threads do Codex, DeepSeek e o uso de ChatGPT ou Claude no navegador (sem dados locais). Os formatos, as limitações e o status de cada fonte estão em [`docs/fontes-de-dados.md`](docs/fontes-de-dados.md).
39
+
40
+ ## Instalação
41
+
42
+ Requisitos: **Node.js 24 ou mais novo** (usa `node:sqlite`) e **git**.
43
+
44
+ Rode sem instalar, com `npx`:
45
+
46
+ ```bash
47
+ npx ai-usage-metrics --help
48
+ ```
49
+
50
+ Ou instale globalmente:
51
+
52
+ ```bash
53
+ npm install -g ai-usage-metrics
54
+ ai-usage-metrics --help
55
+ ```
56
+
57
+ Também dá para rodar direto do código-fonte:
58
+
59
+ ```bash
60
+ git clone https://github.com/brenoluizdev/ai-usage-metrics.git
61
+ cd ai-usage-metrics
62
+ node bin/ai-usage-metrics.mjs --help
63
+ ```
64
+
65
+ Nos exemplos abaixo, `ai-usage-metrics` é o comando instalado. Com `npx`, escreva `npx ai-usage-metrics`; a partir do código-fonte, `node bin/ai-usage-metrics.mjs`.
66
+
67
+ ## Início rápido
68
+
69
+ 1. Crie, no GitHub, um repositório **público e vazio** chamado `seu-usuario/ai-metrics`. A ferramenta não cria nada no GitHub.
70
+ 2. Gere a configuração local:
71
+ ```bash
72
+ ai-usage-metrics init --user seu-usuario --public meu-site,outro-projeto --lang pt-BR --title "Meu uso de IA"
73
+ ```
74
+ O `init` grava o `config.json` e imprime o trecho de README e as instruções de agendamento.
75
+
76
+ **Contas novas do GitHub:** o e-mail de commit padrão (`usuario@users.noreply.github.com`) pode não vincular os commits ao seu perfil. Se isso acontecer, edite o `config.json` e defina `"commitEmail"` com o formato que inclui o ID numérico, `ID+usuario@users.noreply.github.com` (o ID aparece em Settings > Emails, ou em `https://api.github.com/users/seu-usuario`).
77
+ 3. Veja o que sairia, sem enviar nada:
78
+ ```bash
79
+ ai-usage-metrics export
80
+ ai-usage-metrics render
81
+ ai-usage-metrics publish # dry-run
82
+ ```
83
+ Abra `~/.ai-usage-metrics/out/metrics.svg` no navegador para conferir o painel.
84
+ 4. Envie uma vez, conferindo a lista de arquivos, os números e os nomes públicos que o comando mostra:
85
+ ```bash
86
+ ai-usage-metrics publish --yes
87
+ ```
88
+ 5. Cole no README do seu perfil (repositório `seu-usuario/seu-usuario`):
89
+ ```markdown
90
+ ![AI usage](https://raw.githubusercontent.com/seu-usuario/ai-metrics/main/metrics.svg)
91
+ ```
92
+
93
+ ## Como funciona
94
+
95
+ ```
96
+ tarefa agendada (1x/dia)
97
+ -> a CLI lê os registros locais, agrega e anonimiza
98
+ -> metrics.json + metrics.svg (gerados na sua máquina)
99
+ -> git push para <seu-usuario>/ai-metrics (repositório público seu)
100
+ -> o README do perfil aponta para o SVG
101
+ ```
102
+
103
+ Só a última etapa usa a rede (`git clone`, `fetch` e `push` para o remoto que você configurou), e só depois da sua confirmação.
104
+
105
+ ## Comandos
106
+
107
+ | Comando | O que faz |
108
+ |---|---|
109
+ | `sources` | lista as fontes e se existem neste computador |
110
+ | `report` | resumo no terminal. **Mostra nomes reais de projetos: não cole em lugar público** |
111
+ | `export` | gera o JSON agregado e anonimizado (esquema v1, em [`docs/esquema.md`](docs/esquema.md)) |
112
+ | `render` | gera o SVG a partir do JSON (`--theme auto\|light\|dark`, `--title`, `--lang en\|pt-BR`) |
113
+ | `publish` | dry-run por padrão; com `--yes` (ou resposta interativa) envia o JSON e o SVG |
114
+ | `init` | cria a configuração local e imprime o trecho de README e o agendamento |
115
+ | `run` | `export`, `render` e `publish` numa etapa, para o agendador. No agendador use `--non-interactive` (nunca pergunta nada) |
116
+
117
+ Opções gerais: `--state-dir <pasta>`, `--config <arquivo>`, `--since <30d|AAAA-MM-DD>`, `--tool <id>` (repetível) e `--top <n>`. Rode `--help` para a lista completa.
118
+
119
+ Tudo fica em `~/.ai-usage-metrics` (configuração, estado, clone de dados em `repo/` e saídas em `out/`). Use uma pasta própria para o estado: raiz de unidade, a pasta pessoal inteira e pastas que já são repositórios git são recusadas.
120
+
121
+ ## Configuração
122
+
123
+ O arquivo `config.json` aceita as chaves abaixo. Chaves desconhecidas são recusadas, para que um erro de digitação não desligue uma trava em silêncio.
124
+
125
+ | Chave | Padrão | Significado |
126
+ |---|---|---|
127
+ | `githubUser` | (obrigatória) | seu usuário do GitHub |
128
+ | `dataRepo` | `ai-metrics` | repositório público de dados |
129
+ | `branch` | `main` | branch que recebe o push |
130
+ | `publicProjects` | `[]` | projetos que podem aparecer com nome: uma lista (`["meu-app"]`) ou um mapa (`{"pasta": "Nome público"}`). A chave do mapa pode ser o caminho completo, para separar pastas com o mesmo nome. Todo o resto é anonimizado |
131
+ | `theme` | `auto` | `auto` (segue o tema do visitante), `light` ou `dark` |
132
+ | `title` | (nenhum) | título do SVG, até 60 caracteres, sem caminho, e-mail nem nome de arquivo |
133
+ | `lang` | `en` | `en` ou `pt-BR` |
134
+ | `autoPublish` | `false` | permite que `run` envie sem confirmação, no agendador |
135
+ | `remoteUrl` | `https://github.com/<user>/<repo>.git` | outro remoto: só `https://host/caminho`, `git@host:caminho` ou `ssh://git@host/caminho`, sem usuário, senha nem token |
136
+ | `commitName` | `githubUser` | nome do autor do commit público |
137
+ | `commitEmail` | `<githubUser>@users.noreply.github.com` | e-mail do autor do commit público. Qualquer e-mail que não seja o noreply do GitHub exige confirmação extra |
138
+
139
+ ## Publicação segura
140
+
141
+ O `publish` foi desenhado para que um envio acidental seja difícil:
142
+
143
+ - **Dry-run por padrão.** Sem `--yes`, nada é enviado. Ele mostra o repositório e a branch, os arquivos (só `metrics.json` e `metrics.svg`), a diferença contra o que já está publicado, os números, quantos projetos estão anonimizados, **quais nomes ficariam públicos** e o **autor do commit**.
144
+ - **Validação antes de enviar.** O JSON passa por uma allowlist estrita do esquema (qualquer campo extra, texto livre, caminho ou e-mail é rejeitado), pela barreira de privacidade e pela checagem dos nomes públicos. O SVG é gerado de novo a partir do JSON validado.
145
+ - **Nunca `--force`.** Se o remoto avançou de forma incompatível, o push falha e nada é sobrescrito.
146
+ - **Sem token.** Usa o `git` e as credenciais que você já tem (gerenciador de credenciais ou SSH). Não pede, não guarda e não registra credenciais.
147
+ - **Um único `metrics.json` agregado**, sem arquivo por projeto, para não criar uma linha do tempo detalhada no histórico do repositório.
148
+ - O `git` roda sem os seus hooks, com ambiente limpo e só com `https` e `ssh` permitidos.
149
+
150
+ ## Agendamento
151
+
152
+ O `init` imprime as instruções e **não instala nada**. No Windows ele imprime duas versões do `schtasks`, uma para o `cmd.exe` e outra para o PowerShell; use a do terminal onde for colar. No Linux e no macOS, use `cron`. Exemplo (cmd.exe):
153
+
154
+ ```
155
+ schtasks /Create /SC DAILY /ST 12:00 /TN "ai-usage-metrics" /TR "\"C:\caminho\node.exe\" \"C:\caminho\bin\ai-usage-metrics.mjs\" run --non-interactive"
156
+ ```
157
+
158
+ A tarefa roda sem terminal, então:
159
+
160
+ - **mantenha o `--non-interactive`** se montar o comando à mão. O Agendador do Windows dá um console ao processo, e sem essa opção o `run` entende que há uma pessoa digitando e fica esperando a resposta de `[s/N]` para sempre (a versão 0.1.0 tinha esse defeito; a 0.1.1 corrige e o `init` já imprime o comando com a opção);
161
+ - o `git` precisa ter credencial salva, senão o push falha (não trava esperando senha);
162
+ - `run` sem terminal **só gera os arquivos**, a menos que você tenha definido `"autoPublish": true` **e** feito antes um `publish` manual confirmado em um terminal interativo;
163
+ - a aprovação fica amarrada ao repositório e à branch de destino, ao nome e e-mail do autor do commit e aos pares pasta -> nome público. Se qualquer um mudar, o envio automático é bloqueado e explica como reaprovar;
164
+ - só uma execução por vez usa a pasta de estado (arquivo `.lock`).
165
+
166
+ ## Privacidade e segurança
167
+
168
+ - **O que é lido:** só campos estruturais (datas, contagens, tokens e o nome da última pasta do projeto). O texto das conversas é descartado.
169
+ - **O que é publicado:** contagens, datas e nomes de projeto, anonimizados por padrão. Datas, volume diário e a ordem do ranking continuam públicos, mesmo com nomes anonimizados.
170
+ - **O histórico de um repositório público é permanente.** Apagar um arquivo depois não remove o que já foi enviado (clones e forks podem tê-lo). Por isso o `publish` é dry-run por padrão: confira antes de confirmar.
171
+ - **Os dados são autodeclarados.** Qualquer pessoa pode editar o JSON do próprio repositório; o painel não prova nada para terceiros.
172
+
173
+ O modelo de ameaças, as travas e como reportar uma vulnerabilidade estão em [`SECURITY.md`](SECURITY.md).
174
+
175
+ ## Limitações
176
+
177
+ - **Validado apenas no Windows.** Linux e macOS usam `os.homedir()` e `path`, mas não foram testados: trate como não suportados até alguém confirmar.
178
+ - **Os formatos das ferramentas mudam.** Claude Code, Cline e o app do ChatGPT não documentam seus arquivos locais. Uma atualização pode quebrar um adaptador ou subcontar (o Claude Code, por exemplo, apaga sessões antigas por idade).
179
+ - Os números são aproximados e as datas estão em UTC.
180
+ - O ChatGPT cobre só o que o app desktop sincronizou, e só a contagem por dia.
181
+
182
+ ## Estrutura do projeto
183
+
184
+ ```
185
+ bin/ ponto de entrada da CLI
186
+ src/ comandos, adaptadores das fontes, agregação, privacidade, publicação e SVG
187
+ test/ testes com fixtures sintéticas e repositório git local como remoto
188
+ docs/ esquema do JSON e fontes de dados
189
+ examples/ JSON e SVG de exemplo (dados fictícios)
190
+ templates/ workflow opcional do GitHub Actions
191
+ ```
192
+
193
+ ## Contribuindo
194
+
195
+ ### Adicionar uma fonte
196
+
197
+ 1. Crie `src/adapters/minha-fonte.mjs` exportando um `Adapter` (contrato em `src/types.mjs`): `id` (minúsculas, números e hífen), `name`, `capabilities`, `available(ctx)` e `events(ctx)`, um gerador assíncrono de eventos `{tool, project, session, ts, kind, tokens?}`.
198
+ 2. Registre em `src/adapters/index.mjs`.
199
+ 3. Teste com uma fixture **sintética** em `test/` (veja `test/fixtures.mjs`). Nunca use conversas reais.
200
+ 4. Documente o formato em `docs/fontes-de-dados.md`.
201
+
202
+ O adaptador deve ler só campos estruturais e descartar qualquer texto.
203
+
204
+ ### Desenvolvimento
205
+
206
+ ```bash
207
+ npm test # node:test, fixtures sintéticas, repositório git bare local como remoto
208
+ npm run lint # checagem de sintaxe (node --check), sem dependências
209
+ npm run exemplo # regera examples/ (JSON e SVG sintéticos)
210
+ ```
211
+
212
+ ### Workflow opcional do GitHub Actions
213
+
214
+ `templates/github-actions/render-svg.yml` regera o `metrics.svg` quando o `metrics.json` muda, com permissões mínimas e as ações fixadas por SHA de commit. É opcional, porque o `publish` já envia o SVG pronto. Ele depende de o pacote estar publicado no npm e ainda não foi testado em um GitHub real.
215
+
216
+ ## Licença
217
+
218
+ [MIT](LICENSE)
package/SECURITY.md ADDED
@@ -0,0 +1,85 @@
1
+ # Segurança e privacidade
2
+
3
+ ## O que a ferramenta lê e o que ela publica
4
+
5
+ - **Lê** (somente leitura) os registros locais de cada fonte (ver `docs/fontes-de-dados.md`). Usa apenas datas, contagens, tokens e o nome da última pasta do projeto. Texto de conversas, código, títulos e ids de sessão são descartados em memória.
6
+ - **Publica** exatamente dois arquivos no repositório de dados que você configurou: `metrics.json` (agregado, esquema v1) e `metrics.svg`.
7
+ - **Nunca** vão para o JSON/SVG: texto de conversa, código, caminhos, nome de usuário do sistema, e-mail, ids de sessão, nomes de modelo.
8
+ - Os bancos SQLite das outras ferramentas (Cline, app do ChatGPT) são abertos com `readOnly: true`; um teste confirma que a opção é respeitada e que o arquivo não muda depois da leitura.
9
+
10
+ ## Travas
11
+
12
+ 1. **Allowlist estrita de campos e formatos** (`src/schema.mjs`): campo extra, texto livre, caminho e e-mail são rejeitados; ids de ferramenta reservados (`constructor`, `__proto__`...) também.
13
+ 2. **Barreira de privacidade** (`src/privacy.mjs`): recusa caminho de disco, pasta pessoal, e-mail e nomes de arquivo de dados. Vale para o JSON, para o **título** (`title` da config e `--title`) e para o **SVG final**, antes de gravar ou enviar. O nome público (alias) também é validado: não pode ser igual ao seu usuário do sistema nem à sua pasta pessoal, nem parecer caminho, e-mail ou arquivo.
14
+ 3. Projetos anonimizados por padrão; nomes públicos só pela lista em `config.json`, conferidos de novo no `publish`. A lista aceita o nome da pasta ou o **caminho completo** (`{"C:\\dev\\app": "app-pessoal"}`) para separar pastas homônimas; se mais de uma pasta distinta resolver para o mesmo nome público, `export`, `publish` (dry-run) e `report` avisam.
15
+ 4. `publish` é dry-run por padrão e só envia com `--yes` ou confirmação interativa. Nunca usa `--force`.
16
+ 5. **Envio automático amarrado ao que você aprovou.** O agendador (`run` sem terminal) só envia com `autoPublish: true` e depois de um `publish` manual confirmado **em terminal interativo** (`publish --yes` sem terminal envia, mas não conta como aprovação). A aprovação guarda, em `state.json`: os nomes públicos, o destino `{remoto normalizado, branch, commitName, commitEmail}` (nome e e-mail EFETIVOS do autor, inclusive o padrão noreply) e os pares `pasta -> nome público`. Se qualquer um mudar, o automático é **bloqueado** com a explicação do que mudou. Para reaprovar: rode `ai-usage-metrics publish` num terminal, confira o dry-run e confirme (vale mesmo quando nada mudou nos números). Estados antigos, sem destino ou sem autor registrado, também bloqueiam até a reaprovação.
17
+ 6. **Remoto restrito.** Só `https://host/caminho` (sem usuário/senha/token), `git@host:caminho` e `ssh://git@host/caminho` (sem senha). A validação olha a string **crua**, antes de o parser de URL normalizá-la: só ASCII imprimível, `%` (codificação percentual) é recusado em qualquer posição do caminho, segmentos `.`/`..` são recusados, e hosts com rótulo `xn--` (punycode) são **recusados** (escolha mais segura: um domínio internacionalizado pode imitar outro; se você realmente usa um, rode o git manualmente). Recusados: `http://`, `git://`, `file://`, caminhos locais e UNC, `ext::`/`xyz::`, nomes começando com `-`, espaços e caracteres de controle. O git roda com `protocol.allow=never` e libera só `https` e `ssh`. Mensagens de erro e saídas nunca repetem a URL fornecida e removem `usuario:senha@` de qualquer texto do git. **Política de host:** só nome DNS público com ponto. São recusados `localhost` e `*.localhost`, nomes sem ponto (`servidor`), sufixos internos (`.local`, `.localdomain`, `.internal`, `.intranet`, `.lan`, `.home`, `.corp`), IPs literais IPv4 em qualquer notação (decimal `2130706433`, hex `0x7f000001`, octal, formato curto `127.1`) e qualquer host com um rótulo só numérico ou começando com `0x` (o `getaddrinfo` do sistema converte esses em IP); IPv6 já era recusado. Um host diferente de `github.com` (por exemplo um GitHub Enterprise seu) **é aceito**, mas o dry-run mostra um aviso destacado com o host; o envio automático continua amarrado ao destino aprovado. **SCP x ssh://:** `git@host:u/r` (caminho relativo ao HOME do servidor) e `ssh://git@host/u/r` (caminho absoluto) são destinos DIFERENTES: trocar de uma forma para a outra conta como mudança (bloqueia o automático até nova aprovação manual e faz o clone ser recriado, com aviso); a forma normalizada guardada em `state.json` é `scp://git@host/u/r`. (`AI_USAGE_METRICS_TEST_ALLOW_LOCAL_REMOTE=1` libera remoto local e é **somente para os testes**: é lida do ambiente do processo, nunca do `config.json`; não a defina no agendador nem no seu shell. Ela também deixa o git receber `GIT_CONFIG_GLOBAL`/`GIT_CONFIG_NOSYSTEM` do ambiente, o que é só para isolar os testes.)
18
+ 7. **Ambiente do git por allowlist.** O `git` recebe só variáveis neutras (PATH, HOME/USERPROFILE, temporários, idioma, `SSH_AUTH_SOCK`...). Não são repassadas `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, `GIT_OBJECT_DIRECTORY`, `GIT_CONFIG_COUNT/KEY_n/VALUE_n`, `GIT_SSH_COMMAND`, `GIT_SSH`, `GIT_ASKPASS`, `GIT_EXEC_PATH` etc. Hooks do usuário não rodam no clone (`core.hooksPath` aponta para uma pasta vazia, mais `--no-verify` no commit e no push), assinatura automática de commit fica desligada e `core.symlinks=false`. Consequência: se o seu git depende de `GIT_ASKPASS`/`GIT_SSH_COMMAND` no ambiente, configure isso no `~/.gitconfig` (gerenciador de credenciais, `core.sshCommand`) ou na chave SSH padrão. O `~/.gitconfig` e o `/etc/gitconfig` continuam valendo (são seus): um `url.<x>.insteadOf` global é respeitado pelo git, e por isso a ferramenta compara a URL **crua** guardada no clone (`git config remote.origin.url`, sem aplicar `insteadOf`) com a URL aprovada, normalizando os dois lados; o envio também não deixa um `insteadOf` global quebrar o segundo `publish`. Um `insteadOf` global pode, é claro, redirecionar o destino: só o seu `~/.gitconfig` faz isso, a ferramenta não o cria nem o desativa.
19
+ 8. **Clone em cache seguro.** Antes de qualquer comando git no clone, a ferramenta confere (com `lstat`) que `repo/` e `repo/.git` são pastas de verdade (`repo/` como link simbólico, junction ou arquivo é **recusado**, sem apagar nada; `.git` como link/arquivo `gitdir:` num clone nosso faz o clone ser **renomeado e recriado, com aviso**) e que o `.git/config` só tem as chaves que o `git clone` cria (`core.*` básicas, `remote.origin.url` e `fetch` padrão, `branch.*`). Qualquer outra chave (`remote.origin.pushurl`, `core.sshCommand`, `core.fsmonitor`/`editor`/`pager`, `url.*.insteadOf`/`pushInsteadOf`, `credential.*`, `include`, filtros, proxy...) significa clone adulterado: ele é renomeado (nunca apagado) e recriado, e nada dele é executado. O `remote.origin.url` cru precisa ser igual ao remoto aprovado depois de normalizar; se você mudar o remoto na configuração, o clone antigo também é recriado. Todos os comandos git usam `--git-dir`/`--work-tree` explícitos (nunca sobem para um repositório numa pasta-mãe) e o `push` vai para a URL aprovada, não para o nome `origin` (assim um `pushurl` nunca desvia o envio). Não passamos `-c core.sshCommand=` vazio nem `-c credential.helper=`: ambos quebrariam o ssh/gerenciador de credenciais que você configurou no `~/.gitconfig` (testado: `core.sshCommand` vazio dá `cannot spawn`); a defesa é a conferência da config LOCAL do clone. O clone e o `.git` precisam ser pastas de verdade; se `metrics.json`/`metrics.svg` forem link simbólico (no disco ou no repositório remoto, modo `120000`) o envio é recusado. A escrita é atômica (arquivo temporário exclusivo + renomear), nunca segue link.
20
+ 9. **Uma execução por vez** por pasta de estado: um `.lock` (pid + hora) evita corrida entre `run` agendado e comando manual. Trava de processo morto, ilegível e antiga, ou com mais de 6 h é recuperada, sem corrida: uma guarda exclusiva (`.lock.reclaim`) serializa a recuperação, a trava é relida dentro dela e renomeada para um nome único antes de ser apagada, então um processo nunca apaga a trava nova do outro. A pasta de estado e os arquivos que a ferramenta grava (`config.json`, `state.json`, `out/metrics.json`, `out/metrics.svg`, `out/avisos.json`) são criados com modo `0700`/`0600` em Linux/macOS (no Windows os modos POSIX não se aplicam: vale a ACL herdada do seu perfil de usuário; não verificado em Linux/macOS aqui); senão a mensagem diz quem a detém e qual arquivo apagar.
21
+ 10. **Registros adversariais ou corrompidos** (arquivos locais podem ser editados por qualquer programa seu): datas só entre 2000-01-01 e amanhã (o resto é descartado com aviso, sem derrubar a execução); tokens só inteiros seguros até 1 bilhão por campo (o resto vira 0) e somas saturadas; arquivo `.jsonl` acima de 512 MiB é ignorado, linha acima de 16 MiB é descartada, `.messages.json` do Cline acima de 64 MiB é ignorado; `messages_path` do Cline só é lido se, resolvido o link simbólico, ficar dentro de `~/.cline` e for arquivo comum; mais de 4000 dias ou 1000 projetos degradam (ficam os mais recentes/ativos) com aviso. **Tetos de entradas distintas** antes desse corte, para um arquivo cheio de ids únicos pequenos não esgotar a memória: até 200 000 ids de resposta e 2 000 000 mensagens por arquivo do Claude Code, 10 000 pastas distintas no total (o excedente vai para "(sem projeto)"), cada caminho de projeto (`cwd`) com no máximo 4096 caracteres (acima disso o valor é descartado, a atividade vai para "(sem projeto)" e há um aviso agregado; nos bancos SQLite o corte é feito na própria consulta, e `aggregate` repete a trava para qualquer adaptador), 500 000 sessões distintas (eventos de sessões novas além disso são ignorados) e 200 000 linhas do catálogo do app do ChatGPT; sempre com aviso e sem derrubar a execução. Linhas de transcrição que não são objetos JSON (`null`, números, textos, listas) são ignoradas. O `avisos.json` (gravado na pasta `out/` do estado, nunca ao lado de `--out`) é lido com sequências ANSI/OSC e caracteres de controle removidos e cada aviso limitado a 300 caracteres. Nomes de pasta mostrados no `report` têm caracteres de controle trocados por `?`.
22
+ 11. **A pasta `repo/` só é mexida se for nossa (marcador de posse).** Quando a ferramenta cria o clone, grava `<state-dir>/repo.owner.json` (`{tool, id aleatório de 128 bits, path real da pasta repo, createdAt}`) e copia o id para `repo/.git/ai-usage-metrics-owner`. Só um clone com marcador de fora válido, **amarrado ao caminho real** (um marcador copiado para outro state-dir não vale) e, se o `.git` é pasta, com a cópia interna igual ao id, pode ser recriado. Sem marcador, a ferramenta **não apaga nem altera nada** e recusa com erro claro pedindo para mover/renomear a pasta ou escolher outro `--state-dir` (vale também no modo automático); só uma pasta `repo/` vazia é aceita (o git clona dentro dela). Recriar um clone nosso divergente **renomeia** a pasta para `repo.velho-<timestamp>-<aleatório>` (com o marcador ao lado, em `repo.velho-….owner.json`) e avisa; são mantidas só as 3 mais recentes, e a poda apaga apenas pastas reais `repo.velho-*` que tenham marcador nosso válido. Clones criados por versões anteriores (sem marcador) também são recusados uma vez: renomeie a pasta `repo` e rode de novo. O `--state-dir` também é validado: raiz de unidade, a pasta pessoal inteira (do sistema e a de `--home`) e pastas que já são repositório git (`.git` no próprio nível) são recusados. Limite conhecido: o marcador protege contra acidente (usar uma pasta `repo` que já existia), não contra quem tem acesso de escrita ao seu state-dir (B5: com esse acesso, forjar o marcador, o `state.json` ou o `.git/config` já seria possível; não é uma fronteira que a ferramenta defenda).
23
+ 13. **`--state-dir` validado sobre o caminho real.** A grafia crua é recusada se usar prefixo de caminho estendido/dispositivo do Windows (`//?/`, e as formas com barras invertidas `?` e `.`), caminho UNC (inclusive o administrativo `localhost` + `c# Segurança e privacidade
24
+
25
+ ## O que a ferramenta lê e o que ela publica
26
+
27
+ - **Lê** (somente leitura) os registros locais de cada fonte (ver `docs/fontes-de-dados.md`). Usa apenas datas, contagens, tokens e o nome da última pasta do projeto. Texto de conversas, código, títulos e ids de sessão são descartados em memória.
28
+ - **Publica** exatamente dois arquivos no repositório de dados que você configurou: `metrics.json` (agregado, esquema v1) e `metrics.svg`.
29
+ - **Nunca** vão para o JSON/SVG: texto de conversa, código, caminhos, nome de usuário do sistema, e-mail, ids de sessão, nomes de modelo.
30
+ - Os bancos SQLite das outras ferramentas (Cline, app do ChatGPT) são abertos com `readOnly: true`; um teste confirma que a opção é respeitada e que o arquivo não muda depois da leitura.
31
+
32
+ ## Travas
33
+
34
+ 1. **Allowlist estrita de campos e formatos** (`src/schema.mjs`): campo extra, texto livre, caminho e e-mail são rejeitados; ids de ferramenta reservados (`constructor`, `__proto__`...) também.
35
+ 2. **Barreira de privacidade** (`src/privacy.mjs`): recusa caminho de disco, pasta pessoal, e-mail e nomes de arquivo de dados. Vale para o JSON, para o **título** (`title` da config e `--title`) e para o **SVG final**, antes de gravar ou enviar. O nome público (alias) também é validado: não pode ser igual ao seu usuário do sistema nem à sua pasta pessoal, nem parecer caminho, e-mail ou arquivo.
36
+ 3. Projetos anonimizados por padrão; nomes públicos só pela lista em `config.json`, conferidos de novo no `publish`. A lista aceita o nome da pasta ou o **caminho completo** (`{"C:\\dev\\app": "app-pessoal"}`) para separar pastas homônimas; se mais de uma pasta distinta resolver para o mesmo nome público, `export`, `publish` (dry-run) e `report` avisam.
37
+ 4. `publish` é dry-run por padrão e só envia com `--yes` ou confirmação interativa. Nunca usa `--force`.
38
+ 5. **Envio automático amarrado ao que você aprovou.** O agendador (`run` sem terminal) só envia com `autoPublish: true` e depois de um `publish` manual confirmado **em terminal interativo** (`publish --yes` sem terminal envia, mas não conta como aprovação). A aprovação guarda, em `state.json`: os nomes públicos, o destino `{remoto normalizado, branch, commitName, commitEmail}` (nome e e-mail EFETIVOS do autor, inclusive o padrão noreply) e os pares `pasta -> nome público`. Se qualquer um mudar, o automático é **bloqueado** com a explicação do que mudou. Para reaprovar: rode `ai-usage-metrics publish` num terminal, confira o dry-run e confirme (vale mesmo quando nada mudou nos números). Estados antigos, sem destino ou sem autor registrado, também bloqueiam até a reaprovação.
39
+ 6. **Remoto restrito.** Só `https://host/caminho` (sem usuário/senha/token), `git@host:caminho` e `ssh://git@host/caminho` (sem senha). A validação olha a string **crua**, antes de o parser de URL normalizá-la: só ASCII imprimível, `%` (codificação percentual) é recusado em qualquer posição do caminho, segmentos `.`/`..` são recusados, e hosts com rótulo `xn--` (punycode) são **recusados** (escolha mais segura: um domínio internacionalizado pode imitar outro; se você realmente usa um, rode o git manualmente). Recusados: `http://`, `git://`, `file://`, caminhos locais e UNC, `ext::`/`xyz::`, nomes começando com `-`, espaços e caracteres de controle. O git roda com `protocol.allow=never` e libera só `https` e `ssh`. Mensagens de erro e saídas nunca repetem a URL fornecida e removem `usuario:senha@` de qualquer texto do git. **Política de host:** só nome DNS público com ponto. São recusados `localhost` e `*.localhost`, nomes sem ponto (`servidor`), sufixos internos (`.local`, `.localdomain`, `.internal`, `.intranet`, `.lan`, `.home`, `.corp`), IPs literais IPv4 em qualquer notação (decimal `2130706433`, hex `0x7f000001`, octal, formato curto `127.1`) e qualquer host com um rótulo só numérico ou começando com `0x` (o `getaddrinfo` do sistema converte esses em IP); IPv6 já era recusado. Um host diferente de `github.com` (por exemplo um GitHub Enterprise seu) **é aceito**, mas o dry-run mostra um aviso destacado com o host; o envio automático continua amarrado ao destino aprovado. **SCP x ssh://:** `git@host:u/r` (caminho relativo ao HOME do servidor) e `ssh://git@host/u/r` (caminho absoluto) são destinos DIFERENTES: trocar de uma forma para a outra conta como mudança (bloqueia o automático até nova aprovação manual e faz o clone ser recriado, com aviso); a forma normalizada guardada em `state.json` é `scp://git@host/u/r`. (`AI_USAGE_METRICS_TEST_ALLOW_LOCAL_REMOTE=1` libera remoto local e é **somente para os testes**: é lida do ambiente do processo, nunca do `config.json`; não a defina no agendador nem no seu shell. Ela também deixa o git receber `GIT_CONFIG_GLOBAL`/`GIT_CONFIG_NOSYSTEM` do ambiente, o que é só para isolar os testes.)
40
+ 7. **Ambiente do git por allowlist.** O `git` recebe só variáveis neutras (PATH, HOME/USERPROFILE, temporários, idioma, `SSH_AUTH_SOCK`...). Não são repassadas `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, `GIT_OBJECT_DIRECTORY`, `GIT_CONFIG_COUNT/KEY_n/VALUE_n`, `GIT_SSH_COMMAND`, `GIT_SSH`, `GIT_ASKPASS`, `GIT_EXEC_PATH` etc. Hooks do usuário não rodam no clone (`core.hooksPath` aponta para uma pasta vazia, mais `--no-verify` no commit e no push), assinatura automática de commit fica desligada e `core.symlinks=false`. Consequência: se o seu git depende de `GIT_ASKPASS`/`GIT_SSH_COMMAND` no ambiente, configure isso no `~/.gitconfig` (gerenciador de credenciais, `core.sshCommand`) ou na chave SSH padrão. O `~/.gitconfig` e o `/etc/gitconfig` continuam valendo (são seus): um `url.<x>.insteadOf` global é respeitado pelo git, e por isso a ferramenta compara a URL **crua** guardada no clone (`git config remote.origin.url`, sem aplicar `insteadOf`) com a URL aprovada, normalizando os dois lados; o envio também não deixa um `insteadOf` global quebrar o segundo `publish`. Um `insteadOf` global pode, é claro, redirecionar o destino: só o seu `~/.gitconfig` faz isso, a ferramenta não o cria nem o desativa.
41
+ 8. **Clone em cache seguro.** Antes de qualquer comando git no clone, a ferramenta confere (com `lstat`) que `repo/` e `repo/.git` são pastas de verdade (`repo/` como link simbólico, junction ou arquivo é **recusado**, sem apagar nada; `.git` como link/arquivo `gitdir:` num clone nosso faz o clone ser **renomeado e recriado, com aviso**) e que o `.git/config` só tem as chaves que o `git clone` cria (`core.*` básicas, `remote.origin.url` e `fetch` padrão, `branch.*`). Qualquer outra chave (`remote.origin.pushurl`, `core.sshCommand`, `core.fsmonitor`/`editor`/`pager`, `url.*.insteadOf`/`pushInsteadOf`, `credential.*`, `include`, filtros, proxy...) significa clone adulterado: ele é renomeado (nunca apagado) e recriado, e nada dele é executado. O `remote.origin.url` cru precisa ser igual ao remoto aprovado depois de normalizar; se você mudar o remoto na configuração, o clone antigo também é recriado. Todos os comandos git usam `--git-dir`/`--work-tree` explícitos (nunca sobem para um repositório numa pasta-mãe) e o `push` vai para a URL aprovada, não para o nome `origin` (assim um `pushurl` nunca desvia o envio). Não passamos `-c core.sshCommand=` vazio nem `-c credential.helper=`: ambos quebrariam o ssh/gerenciador de credenciais que você configurou no `~/.gitconfig` (testado: `core.sshCommand` vazio dá `cannot spawn`); a defesa é a conferência da config LOCAL do clone. O clone e o `.git` precisam ser pastas de verdade; se `metrics.json`/`metrics.svg` forem link simbólico (no disco ou no repositório remoto, modo `120000`) o envio é recusado. A escrita é atômica (arquivo temporário exclusivo + renomear), nunca segue link.
42
+ 9. **Uma execução por vez** por pasta de estado: um `.lock` (pid + hora) evita corrida entre `run` agendado e comando manual. Trava de processo morto, ilegível e antiga, ou com mais de 6 h é recuperada, sem corrida: uma guarda exclusiva (`.lock.reclaim`) serializa a recuperação, a trava é relida dentro dela e renomeada para um nome único antes de ser apagada, então um processo nunca apaga a trava nova do outro. A pasta de estado e os arquivos que a ferramenta grava (`config.json`, `state.json`, `out/metrics.json`, `out/metrics.svg`, `out/avisos.json`) são criados com modo `0700`/`0600` em Linux/macOS (no Windows os modos POSIX não se aplicam: vale a ACL herdada do seu perfil de usuário; não verificado em Linux/macOS aqui); senão a mensagem diz quem a detém e qual arquivo apagar.
43
+ 10. **Registros adversariais ou corrompidos** (arquivos locais podem ser editados por qualquer programa seu): datas só entre 2000-01-01 e amanhã (o resto é descartado com aviso, sem derrubar a execução); tokens só inteiros seguros até 1 bilhão por campo (o resto vira 0) e somas saturadas; arquivo `.jsonl` acima de 512 MiB é ignorado, linha acima de 16 MiB é descartada, `.messages.json` do Cline acima de 64 MiB é ignorado; `messages_path` do Cline só é lido se, resolvido o link simbólico, ficar dentro de `~/.cline` e for arquivo comum; mais de 4000 dias ou 1000 projetos degradam (ficam os mais recentes/ativos) com aviso. **Tetos de entradas distintas** antes desse corte, para um arquivo cheio de ids únicos pequenos não esgotar a memória: até 200 000 ids de resposta e 2 000 000 mensagens por arquivo do Claude Code, 10 000 pastas distintas no total (o excedente vai para "(sem projeto)"), cada caminho de projeto (`cwd`) com no máximo 4096 caracteres (acima disso o valor é descartado, a atividade vai para "(sem projeto)" e há um aviso agregado; nos bancos SQLite o corte é feito na própria consulta, e `aggregate` repete a trava para qualquer adaptador), 500 000 sessões distintas (eventos de sessões novas além disso são ignorados) e 200 000 linhas do catálogo do app do ChatGPT; sempre com aviso e sem derrubar a execução. Linhas de transcrição que não são objetos JSON (`null`, números, textos, listas) são ignoradas. O `avisos.json` (gravado na pasta `out/` do estado, nunca ao lado de `--out`) é lido com sequências ANSI/OSC e caracteres de controle removidos e cada aviso limitado a 300 caracteres. Nomes de pasta mostrados no `report` têm caracteres de controle trocados por `?`.
44
+ 11. **A pasta `repo/` só é mexida se for nossa (marcador de posse).** Quando a ferramenta cria o clone, grava `<state-dir>/repo.owner.json` (`{tool, id aleatório de 128 bits, path real da pasta repo, createdAt}`) e copia o id para `repo/.git/ai-usage-metrics-owner`. Só um clone com marcador de fora válido, **amarrado ao caminho real** (um marcador copiado para outro state-dir não vale) e, se o `.git` é pasta, com a cópia interna igual ao id, pode ser recriado. Sem marcador, a ferramenta **não apaga nem altera nada** e recusa com erro claro pedindo para mover/renomear a pasta ou escolher outro `--state-dir` (vale também no modo automático); só uma pasta `repo/` vazia é aceita (o git clona dentro dela). Recriar um clone nosso divergente **renomeia** a pasta para `repo.velho-<timestamp>-<aleatório>` (com o marcador ao lado, em `repo.velho-….owner.json`) e avisa; são mantidas só as 3 mais recentes, e a poda apaga apenas pastas reais `repo.velho-*` que tenham marcador nosso válido. Clones criados por versões anteriores (sem marcador) também são recusados uma vez: renomeie a pasta `repo` e rode de novo. O `--state-dir` também é validado: raiz de unidade, a pasta pessoal inteira (do sistema e a de `--home`) e pastas que já são repositório git (`.git` no próprio nível) são recusados. Limite conhecido: o marcador protege contra acidente (usar uma pasta `repo` que já existia), não contra quem tem acesso de escrita ao seu state-dir (B5: com esse acesso, forjar o marcador, o `state.json` ou o `.git/config` já seria possível; não é uma fronteira que a ferramenta defenda).
45
+ ) ou, no Windows, nome terminado em ponto ou espaço. Depois a ferramenta resolve o `realpath` do state-dir (ou do ancestral existente mais próximo, acrescentando o resto) e compara com o `realpath` da pasta pessoal do sistema e de `--home`: junction/link para a casa ou para a raiz de uma unidade, e nome 8.3 da casa, são recusados, assim como uma pasta que já é repositório git.
46
+ 14. **O git nunca herda o diretório do processo.** Todo comando git roda com `cwd` explícito (o state-dir ou o clone; o `clone` roda no state-dir) e com `GIT_CEILING_DIRECTORIES` apontando para o pai do state-dir, além de `--git-dir`/`--work-tree` explícitos nos demais comandos: um state-dir dentro de um repositório seu não sobe para esse repositório (config, `insteadOf`, hooks) e ele não é tocado.
47
+ 15. **Poda de `repo.velho-*` só do que é comprovadamente nosso:** exige pasta real, `.owner.json` válido com caminho coerente (`<state-dir>/repo`) **e** a cópia interna `.git/ai-usage-metrics-owner` igual ao id do marcador. Pasta com marcador forjado não é apagada. Se o marcador não puder ser movido ao aposentar um clone, a ferramenta **avisa**: a pasta velha fica sem marcador, nunca é podada e só acumula até você removê-la.
48
+ 12. Sem rede no código da ferramenta; a única rede é o `git` do próprio usuário (clone/fetch/push) depois da confirmação. Sem token em arquivo: as credenciais são as que o seu `git` já usa.
49
+
50
+ ## E-mail do commit (histórico público)
51
+
52
+ O commit enviado ao seu repositório público leva um autor e um committer. A ferramenta **não usa** a identidade global do seu git: usa `commitName` (padrão: `githubUser`) e `commitEmail` (padrão: `<githubUser>@users.noreply.github.com`), passados ao git por `-c user.name/user.email` e pelo ambiente.
53
+
54
+ - O dry-run mostra o autor que será usado.
55
+ - Se o e-mail **não** terminar em `@users.noreply.github.com`, o dry-run avisa em destaque e o envio exige confirmação extra: em terminal, digitar a frase pedida (mesmo com `--yes`); sem terminal, a flag `--accept-public-email`; no modo automático, fica **bloqueado**.
56
+ - O formato com ID numérico também vale, e pode ser o que o GitHub exige da sua conta: `ID+usuario@users.noreply.github.com` (veja o seu em GitHub > Settings > Emails). Exemplo no `config.json`:
57
+ `"commitName": "Seu Nome", "commitEmail": "12345678+seu-usuario@users.noreply.github.com"`.
58
+ - Se a opção "Block command line pushes that expose my email" estiver ligada na sua conta, o GitHub recusa pushes com e-mail privado: use o noreply.
59
+
60
+ ## Publicando uma nova versão (mantenedor)
61
+
62
+ 1. Rode `npm test` e `npm run lint`.
63
+ 2. Rode `npm pack --dry-run` e confira a lista de arquivos (só `bin`, `src`, `docs`, `templates`, `examples`, `LICENSE`, `README.md`, `SECURITY.md` e `package.json`): nada de `.env`, `config.json`, `state.json`, `out/`, `repo/` ou logs.
64
+ 3. Publique com **2FA** ativo na conta do npm. O `--provenance` só é gerado a partir de um CI suportado (por exemplo GitHub Actions com `id-token: write`); de uma máquina local ele falha, e nesse caso publica-se sem ele, com 2FA.
65
+ 4. Atualize `AI_USAGE_METRICS_VERSION` no template do Actions. As ações do template estão fixadas por SHA de commit (resolvidas com `git ls-remote` nas tags `v4.2.2` e `v4.1.0`); ao atualizar uma ação, repita a consulta e troque o SHA.
66
+
67
+ ## Riscos que continuam com você
68
+
69
+ - **Política de host é léxica:** ela olha o texto do nome (sem ponto, `localhost`, `.local`, IP, rótulo numérico...), não resolve DNS. Um domínio público que resolva para 127.0.0.1 ou para a rede interna passa. Confira o host no dry-run.
70
+ - **Um clone nosso pode perder commits locais não enviados** quando é recriado: o commit local fica na cópia `repo.velho-*` (e no reflog dela), mas não no novo clone. Só as 3 cópias mais recentes são mantidas.
71
+ - **O envio agendado falha enquanto houver uma pasta `repo` que não é nossa** (por exemplo, clone de uma versão anterior da ferramenta, sem marcador), sem alterar nada, até um humano renomear/mover essa pasta ou escolher outro `--state-dir`.
72
+ - O `~/.gitconfig` (e o `/etc/gitconfig`) continuam valendo: `url.<x>.insteadOf`/`pushInsteadOf`, `credential.helper`, `core.sshCommand` e afins são seus e a ferramenta não os desativa. O dry-run mostra a URL **aprovada**, mas o git pode reescrevê-la (um `insteadOf` global pode levar o push a outro destino). Confira o seu `git config --global --list` antes do primeiro envio.
73
+ - O histórico de um repositório público é permanente e pode ser clonado. Confira o dry-run antes do primeiro envio.
74
+ - Datas, volume de uso e ranking são informação pública, mesmo com projetos anonimizados. Pouca atividade em um dia pode revelar rotina.
75
+ - O nome público de um projeto pode revelar trabalho confidencial: só inclua o que você já divulga.
76
+ - Os números são autodeclarados e aproximados.
77
+ - O comando `report` mostra nomes reais de projetos no terminal: não cole a saída em lugares públicos.
78
+ - No Windows o log do agendador não existe (a tarefa não grava log); o modo `0600` do log só se aplica a Linux/macOS (`umask 077` no comando de cron impresso, **não validado**). O `schtasks` grava o caminho do Node usado na criação da tarefa: recrie a tarefa se atualizar ou mover o Node.
79
+ - Só foi validado no Windows (o do autor). macOS/Linux não foram testados (inclusive os modos `0700`/`0600`, o `cron` impresso e o `schtasks`/`cron` reais: os comandos são só impressos e nenhuma tarefa agendada foi criada nos testes).
80
+
81
+ ## Reportar um problema de segurança
82
+
83
+ Envie um e-mail para **dev.brenoluiz@gmail.com** com o assunto "ai-usage-metrics: segurança", descrevendo o problema e como reproduzi-lo. **Não publique detalhes de uma falha em uma issue pública** antes de ela ser corrigida.
84
+
85
+ Quando o repositório existir no GitHub, vale também ativar o aviso privado de vulnerabilidade (Settings > Security > "Private vulnerability reporting") como segundo canal.
@@ -0,0 +1,7 @@
1
+ #!/usr/bin/env node
2
+ import { main } from "../src/cli.mjs";
3
+
4
+ main(process.argv.slice(2)).catch((e) => {
5
+ console.error(`Erro: ${e.message}`);
6
+ process.exitCode = 1;
7
+ });
@@ -0,0 +1,53 @@
1
+ # Esquema do JSON agregado (versão 1)
2
+
3
+ Gerado por `ai-usage-metrics export` e validado por `src/schema.mjs` (fonte da verdade; tipos JSDoc em `src/types.mjs`). Mudança incompatível = novo `schemaVersion`.
4
+
5
+ ```jsonc
6
+ {
7
+ "schemaVersion": 1,
8
+ "generatedAt": "2026-06-04T12:00:00.000Z",
9
+ "synthetic": false, // true só em exemplos fictícios
10
+ "period": { "from": "2026-01-05", "to": "2026-06-03" }, // null se não há atividade
11
+ "totals": { "projects": 8, "sessions": 360, "userMessages": 2771, "assistantMessages": 8313,
12
+ "activeDays": 141, "tokens": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0, "total": 0 } },
13
+ "tools": [ { "id": "claude-code", "name": "Claude Code",
14
+ "provides": { "messages": true, "tokens": true }, // false = a fonte não informa
15
+ "sessions": 0, "userMessages": 0, "assistantMessages": 0, "tokens": { /* idem */ },
16
+ "firstActivity": "2026-01-05", "lastActivity": "2026-06-03" } ],
17
+ "projects": [ { "name": "meu-site" /* ou "projeto-privado-1", "sem-projeto" */, "public": true,
18
+ "sessions": 0, "userMessages": 0, "assistantMessages": 0, "tokens": { /* idem */ },
19
+ "firstActivity": "...", "lastActivity": "...",
20
+ "tools": [ { "id": "claude-code", "sessions": 0, "userMessages": 0, "assistantMessages": 0, "tokens": { /* idem */ } } ] } ],
21
+ "timeline": { "granularity": "day", "timezone": "UTC",
22
+ "points": [ { "date": "2026-01-05", "sessions": 0, "userMessages": 0, "assistantMessages": 0, "tokens": 0,
23
+ "byTool": { "claude-code": { "sessions": 0, "userMessages": 0, "tokens": 0 } } } ] }
24
+ }
25
+ ```
26
+
27
+ ## Definições
28
+
29
+ - **sessions** (totais, ferramenta, projeto): sessões distintas. Em `timeline`, é o número de sessões com atividade naquele dia (uma sessão de vários dias conta em cada dia).
30
+ - **userMessages**: mensagens digitadas pelo usuário (sem resultados de ferramenta). **assistantMessages**: respostas distintas da IA.
31
+ - **tokens**: soma dos tokens informados; `total` inclui leitura e escrita de cache (por isso é grande) e precisa bater com a soma dos quatro tipos.
32
+ - `projects` vem ordenado por `userMessages` (desc), depois sessões e tokens. `public: false` significa nome anonimizado (`projeto-privado-N`).
33
+ - Datas em UTC.
34
+
35
+ ## Allowlist estrita (o que o validador aceita)
36
+
37
+ O validador **recusa** qualquer coisa fora disto:
38
+
39
+ - Só as chaves listadas acima, em cada nível, e todas obrigatórias. Campo extra = erro.
40
+ - Números: inteiros de 0 a 1e15. Datas: `AAAA-MM-DD` válidas. `generatedAt`: instante ISO em UTC (`...Z`).
41
+ - `tools[].id` e chaves de `byTool`: `[a-z0-9][a-z0-9-]{0,30}`.
42
+ - Nomes (`tools[].name`, `projects[].name` público): letras, números, espaço e `. _ ( ) + -`, até 60 caracteres. Sem barras, `@`, `:` nem quebras de linha, então caminhos e e-mails não passam.
43
+ - Projeto com `public: false` só pode se chamar `projeto-privado-N`.
44
+
45
+ Na hora do `publish` há checagens adicionais (além do esquema):
46
+
47
+ - `id` e `name` de ferramenta têm de ser exatamente os das fontes registradas no código (nada de texto livre ali);
48
+ - todo projeto com nome público precisa estar na allowlist (`publicProjects`) da sua configuração;
49
+ - a barreira de privacidade recusa caminho de disco, pasta pessoal, e-mail e nome de arquivo de dados.
50
+
51
+ Limite honesto: um nome de projeto público é texto escolhido por você na configuração; o validador só garante o formato (letras, números e poucos símbolos), não o significado. Escolha nomes que você aceite ver publicados.
52
+
53
+ Nunca há: texto de mensagens, código, caminhos, nomes de usuário do sistema, e-mails, títulos de conversa, ids de sessão ou nomes de modelo.
@@ -0,0 +1,23 @@
1
+ # Fontes de dados de uso de IA (descoberta no disco, somente leitura)
2
+
3
+ Levantamento feito em 15/11/2026 num computador Windows. Formatos conferidos em arquivos reais (só estrutura e campos, nunca lendo conversas para guardar). **Os formatos são internos das ferramentas e mudam sem aviso**: se uma fonte parar de aparecer após uma atualização da ferramenta, o adaptador precisa ser revisto.
4
+
5
+ | Ferramenta | Caminho | Formato | O que dá para extrair | Limitações | Status |
6
+ |---|---|---|---|---|---|
7
+ | Claude Code (CLI e extensão do VS Code) | `~/.claude/projects/<pasta>/<sessão>.jsonl` e `<sessão>/subagents/agent-*.jsonl` | JSON Lines; cada linha tem `type` (`user`, `assistant`...), `timestamp`, `cwd`, `sessionId`, `message.usage` (tokens de entrada, saída, leitura e escrita de cache), `message.id`, `isSidechain`, `isMeta` | sessões, mensagens do usuário, respostas, tokens (4 tipos), pasta de trabalho, datas | A mesma resposta aparece em várias linhas (um bloco por linha): deduplicamos por `message.id`. Resultados de ferramenta também são linhas `user` e são ignorados. Sessões apagadas pelo Claude Code somem (há limpeza automática por idade). A transcrição guarda o conteúdo: o adaptador só lê campos numéricos/estruturais. | Suportado |
8
+ | Cline (CLI) | `~/.cline/data/db/sessions.db` (SQLite) + `~/.cline/data/sessions/<id>/<id>.messages.json` | tabela `sessions` (`started_at`, `cwd`, `workspace_root`, `model`, `is_subagent`, `messages_path`); JSON com `messages[]` (`role`, `ts`, `content[]`, `metrics.inputTokens/outputTokens/cacheReadTokens/cacheWriteTokens`) | sessões, mensagens do usuário, tokens, pasta de trabalho | Só o Cline CLI aparece no computador do levantamento. Subagentes entram na sessão-mãe. Mensagens de "usuário" que são só resultado de ferramenta são ignoradas. A extensão Cline do VS Code não está instalada aqui (não há pasta de globalStorage), então não foi verificada. | Suportado |
9
+ | ChatGPT (via catálogo do app desktop Codex) | `~/.codex/sqlite/codex.db`, tabela `local_thread_catalog` (`source_kind = 'chatgpt'`) | SQLite | número de conversas por data de criação | Não há mensagens, tokens nem projeto (`cwd` vem vazio). O título existe na tabela mas **nunca é lido**. Cobre só conversas que o app desktop sincronizou; o uso do ChatGPT no navegador ou no celular que não passou pelo app não aparece. | Suportado (parcial: só sessões por dia) |
10
+ | Codex (CLI/app, threads de código) | `~/.codex/state_5.sqlite`, tabela `threads` | SQLite (tem `cwd`, `tokens_used`, `model`) | seria possível: sessões, tokens, projeto | A tabela está vazia no computador do levantamento, então não há como validar o adaptador com dados reais. | Não suportado ainda (fácil de adicionar quando houver dados) |
11
+ | GitHub Copilot CLI | `~/.copilot/session-state/<id>/` e `~/AppData/Roaming/Code/User/globalStorage/github.copilot-chat/session-store.db` | SQLite / arquivos de sessão | provável: sessões e datas | Não inspecionado a fundo; o formato não foi validado. | Não suportado ainda |
12
+ | Gemini / Antigravity CLI | `~/.gemini/antigravity-cli/brain/<id>/` | arquivos por conversa (Markdown + metadata) | provável: número de conversas e datas | Sem tokens nem projeto claros; formato não validado. | Não suportado ainda |
13
+ | Cursor | (não instalado: sem `AppData/Roaming/Cursor`) | `state.vscdb` (SQLite) em instalações normais | n/a | Não existe no computador do levantamento. | Não suportado |
14
+ | DeepSeek (web/app) | nenhum | n/a | n/a | Sem dados locais. Só seria possível via exportação manual da conta. | Não suportado / só via exportação manual |
15
+ | ChatGPT / Claude no navegador | nenhum (nuvem) | exportação manual de dados da conta (JSON/ZIP) | datas e contagens, se importadas | Exige o usuário baixar a exportação; não implementado. | Não suportado / só via exportação manual |
16
+ | VS Code (`state.vscdb`) | `~/AppData/Roaming/Code/User/...` | SQLite | n/a | Estado genérico do editor, sem métricas de IA confiáveis. | Ignorado |
17
+
18
+ ## Observações
19
+
20
+ - Pastas de trabalho: o `cwd` é reduzido ao último nome de pasta; worktrees (`<repo>/.claude/worktrees/x`) contam para o repositório. Internamente as pastas são separadas pelo caminho completo normalizado (nunca publicado). Duas pastas com o mesmo nome em lugares diferentes só são somadas se o nome público for dado pelo **nome** da pasta (e o `export`/`publish`/`report` avisam); para escolher só uma, use o caminho completo em `publicProjects`.
21
+ - Limites de segurança dos adaptadores: datas só de 2000-01-01 até amanhã, tokens inteiros de até 1 bilhão por campo, `.jsonl` até 512 MiB e linhas até 16 MiB, `.messages.json` do Cline até 64 MiB e só dentro de `~/.cline`, caminho de projeto (`cwd`) até 4096 caracteres (acima disso vira "(sem projeto)"). O que passa do limite é descartado com aviso. Os bancos SQLite são abertos somente para leitura.
22
+ - Datas em UTC.
23
+ - Há registros do Claude Desktop (`~/AppData/Roaming/Claude*`) que não foram avaliados.
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="840" height="440" viewBox="0 0 840 440" role="img" aria-labelledby="ttl desc"><title id="ttl">AI usage (sample)</title><desc id="desc">Period 2026-01-05 - 2026-06-03: 360 sessions, 2771 messages, 141 active days.</desc><style>:root{--bg:#0d1117;--card:#161b22;--line:#30363d;--fg:#e6edf3;--muted:#8b949e;--track:#21262d;}text{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif;fill:var(--fg)}.t{font-size:20px;font-weight:600}.s{font-size:12px;fill:var(--muted)}.n{font-size:26px;font-weight:600}.l{font-size:12px;fill:var(--muted)}.h{font-size:13px;font-weight:600}.v{font-size:11px;fill:var(--muted)}</style><rect width="840" height="440" rx="14" fill="var(--bg)" stroke="var(--line)"/><text class="t" x="20" y="38">AI usage (sample)</text><text class="s" x="20" y="58">Period: 2026-01-05 - 2026-06-03</text><rect x="20" y="76" width="191" height="64" rx="10" fill="var(--card)" stroke="var(--line)"/><text class="n" x="34" y="109">360</text><text class="l" x="34" y="128">Sessions</text><rect x="223" y="76" width="191" height="64" rx="10" fill="var(--card)" stroke="var(--line)"/><text class="n" x="237" y="109">2,771</text><text class="l" x="237" y="128">My messages</text><rect x="426" y="76" width="191" height="64" rx="10" fill="var(--card)" stroke="var(--line)"/><text class="n" x="440" y="109">418.4M</text><text class="l" x="440" y="128">Tokens (with cache)</text><rect x="629" y="76" width="191" height="64" rx="10" fill="var(--card)" stroke="var(--line)"/><text class="n" x="643" y="109">141</text><text class="l" x="643" y="128">Active days</text><text class="h" x="20" y="178">Sessions per month</text><line x1="20" y1="374" x2="400" y2="374" stroke="var(--line)"/><rect x="37.0" y="306.9" width="46.0" height="67.1" fill="#d97757"/><rect x="37.0" y="262.7" width="46.0" height="44.2" fill="#10b981"/><rect x="37.0" y="250.4" width="46.0" height="12.4" fill="#f59e0b"/><text class="v" x="60.0" y="245.4" text-anchor="middle">70</text><text class="v" x="60.0" y="389" text-anchor="middle">Jan 26</text><rect x="97.0" y="296.3" width="46.0" height="77.7" fill="#d97757"/><rect x="97.0" y="262.7" width="46.0" height="33.6" fill="#10b981"/><rect x="97.0" y="248.6" width="46.0" height="14.1" fill="#f59e0b"/><text class="v" x="120.0" y="243.6" text-anchor="middle">71</text><text class="v" x="120.0" y="389" text-anchor="middle">Feb 26</text><rect x="157.0" y="296.3" width="46.0" height="77.7" fill="#d97757"/><rect x="157.0" y="261.0" width="46.0" height="35.3" fill="#10b981"/><rect x="157.0" y="252.1" width="46.0" height="8.8" fill="#f59e0b"/><text class="v" x="180.0" y="247.1" text-anchor="middle">69</text><text class="v" x="180.0" y="389" text-anchor="middle">Mar 26</text><rect x="217.0" y="303.4" width="46.0" height="70.6" fill="#d97757"/><rect x="217.0" y="273.3" width="46.0" height="30.0" fill="#10b981"/><rect x="217.0" y="262.7" width="46.0" height="10.6" fill="#f59e0b"/><text class="v" x="240.0" y="257.7" text-anchor="middle">63</text><text class="v" x="240.0" y="389" text-anchor="middle">Apr 26</text><rect x="277.0" y="303.4" width="46.0" height="70.6" fill="#d97757"/><rect x="277.0" y="252.1" width="46.0" height="51.2" fill="#10b981"/><rect x="277.0" y="238.0" width="46.0" height="14.1" fill="#f59e0b"/><text class="v" x="300.0" y="233.0" text-anchor="middle">77</text><text class="v" x="300.0" y="389" text-anchor="middle">May 26</text><rect x="337.0" y="363.4" width="46.0" height="10.6" fill="#d97757"/><rect x="337.0" y="358.1" width="46.0" height="5.3" fill="#10b981"/><rect x="337.0" y="356.3" width="46.0" height="1.8" fill="#f59e0b"/><text class="v" x="360.0" y="351.3" text-anchor="middle">10</text><text class="v" x="360.0" y="389" text-anchor="middle">Jun 26</text><rect x="20" y="187" width="10" height="10" rx="2" fill="#d97757"/><text class="v" x="35" y="196">Claude Code</text><rect x="110.6" y="187" width="10" height="10" rx="2" fill="#10b981"/><text class="v" x="125.6" y="196">Cline</text><rect x="167.6" y="187" width="10" height="10" rx="2" fill="#f59e0b"/><text class="v" x="182.6" y="196">ChatGPT</text><text class="h" x="436" y="178">Most used projects</text><text class="v" x="436" y="209">meu-site</text><rect x="564" y="198" width="212" height="14" rx="7" fill="var(--track)"/><rect x="564" y="198" width="212.0" height="14" rx="7" fill="#d97757"/><text class="v" x="784" y="209">1,096 msg</text><text class="v" x="436" y="239">app-de-tarefas</text><rect x="564" y="228" width="212" height="14" rx="7" fill="var(--track)"/><rect x="564" y="228" width="118.8" height="14" rx="7" fill="#d97757"/><text class="v" x="784" y="239">614 msg</text><text class="v" x="436" y="269">api-de-pagamentos</text><rect x="564" y="258" width="212" height="14" rx="7" fill="var(--track)"/><rect x="564" y="258" width="70.0" height="14" rx="7" fill="#d97757"/><text class="v" x="784" y="269">362 msg</text><text class="v" x="436" y="299">projeto-privado-1</text><rect x="564" y="288" width="212" height="14" rx="7" fill="var(--track)"/><rect x="564" y="288" width="52.6" height="14" rx="7" fill="#d97757"/><text class="v" x="784" y="299">272 msg</text><text class="v" x="436" y="329">bot-do-discord</text><rect x="564" y="318" width="212" height="14" rx="7" fill="var(--track)"/><rect x="564" y="318" width="29.0" height="14" rx="7" fill="#d97757"/><text class="v" x="784" y="329">150 msg</text><text class="v" x="436" y="359">estudos</text><rect x="564" y="348" width="212" height="14" rx="7" fill="var(--track)"/><rect x="564" y="348" width="27.5" height="14" rx="7" fill="#d97757"/><text class="v" x="784" y="359">142 msg</text><text class="s" x="20" y="424">Generated locally on 2026-06-04 · days in UTC · private projects are anonymized</text></svg>