@neetru/cli 2.29.0 → 2.31.0

package/CHANGELOG.md

@@ -4,6 +4,58 @@ Convenção: [Keep a Changelog](https://keepachangelog.com/) + [SemVer](https://
 
 ## [Unreleased]
 
+### Corrigido
+
+- **`neetru dev up` voltou a subir o banco.** O compose gerado tinha um serviço `agent` com `build: dockerfile: Dockerfile.agent`, mas o comando só gravava o compose — o `Dockerfile.agent` nunca era escrito no projeto (a função que o copiaria não era chamada). O `docker compose up` falhava no build e nem o banco subia. Mesmo com o arquivo, o agente não rodaria: o entrypoint chamava `node` num executável `pkg` (não é JS), dependia de um `NEETRU_DEV_MODE` que o agente não implementa, e o container montava o `docker.sock` do host. Agora o `dev up` sobe **só o banco** do engine do projeto e imprime a conexão para o `.env.local` (`postgresql://postgres:neetru_dev@localhost:5432/app` etc.); o app roda com `npm run dev`. As mensagens deixaram de anunciar "App SaaS" e "Agente: conectado ao Core". O agente local volta quando o próprio agente tiver modo dev. Templates mortos removidos: `templates/dev/{Dockerfile.agent,agent-entrypoint.sh,docker-compose.dev.yml}`.
+- README e `--help`: a seção de dev local descrevia flags do `dev up` que não existem (`--import`, `--export-on-exit`, `--skip-core`) e o tratava como "emulador completo, 100% offline". Agora descreve o que roda de fato na máquina do dev de produto. `dev exec` documentado como ferramenta do CI do Core (exige o `firebase.json` do Core).
+
+## [2.31.0] — 2026-10-03 (docs do produto: `neetru docs init|new|check|sync`)
+
+Implementa a parte de ferramenta do **protocolo de documentação dos produtos SaaS** (Core, `docs/sistema/contrib/PROTOCOLO_DOCS_PRODUTOS_SAAS.md` v1, com a taxonomia de `PROTOCOLO_WIKI_INTERNA.md` §5–§7). Decisões do dono de 2026-10-03: o deploy **só avisa** sobre docs (nunca bloqueia); publicar no Core é **opcional** — opt-in `docs.publishOnDeploy` no deploy de produção ou manual com `neetru docs sync`; `--migrar` não move nem renomeia nada.
+
+### Adicionado
+
+- **`neetru docs init [--com-api] [--migrar] [--dry-run] [--json]`** — cria o mínimo do primeiro dia (§7): pastas do §3 (com `.gitkeep` nas vazias), `docs/index.md`, `docs/produto/VISAO_DO_PRODUTO.md`, `docs/arquitetura/ARQUITETURA.md` (com a seção "Integração com o Core"), `docs/runbooks/RUNBOOK_DEPLOY.md`, `README.md` (3 seções) e `CHANGELOG.md` (Keep a Changelog PT-BR, versão do `package.json`), cada doc com frontmatter preenchido (`product`, datas de hoje, `status: draft`, `owner: produto`, `audience` da pasta) e um `<!-- o que escrever aqui -->` por seção. **Idempotente**: nunca sobrescreve; informa o que criou e o que pulou. `API_V1.md` só com `--com-api` (grava `docs.api: true`) ou quando o produto declara app móvel (`.neetru/mobile.json`) ou integração. Acrescenta a chave `docs` no `neetru.config.json` sem mexer no resto (preserva indentação, fim de linha e a quebra final).
+  - **`--migrar`** (repo que já tem docs): acrescenta frontmatter inferido **só** nos `.md` que não têm — `title` do H1, `description` da primeira frase útil, `type`/`category` pela pasta (inclusive as legadas: `architecture/`, `design/`, `guia-do-usuario/`, `_review/`, `deploy/`…) e pelo prefixo ou palavra-chave do nome, `status` pela família, `date`/`updated` pelo primeiro/último commit (ou `_revisado: AAAA-MM-DD_` do corpo), `tags: [migrado]`. **Não move, não renomeia e não altera o corpo** (o arquivo vira exatamente frontmatter + linha em branco + conteúdo original; BOM e CRLF preservados); quem já tem frontmatter fica intocado. Gera `docs/_nomes-legados.json` (só se não existir — a lista só diminui) e o relatório `docs/_audit/MIGRACAO_DOCS_<data>.md` com cada inferência, a origem e a confiança, as sugestões de destino pelo protocolo e o que falta do mínimo do primeiro dia (que **não** é criado no `--migrar`: vem depois de mover, com `docs init`).
+- **`neetru docs new <tipo> "<título>" [--categoria] [--subcategoria] [--audience] [--descricao] [--data] [--dry-run] [--json]`** — doc a partir de modelo embutido, na pasta do §3 e com o nome do §6/§8 (sem acento, MAIÚSCULAS, prefixo do tipo — `AUDITORIA_`/`PROTOCOLO_` quando o título já começa assim —, data no fim nos registros, próximo `ADR-NNNN_` livre). Tipos: `guia`, `referencia`, `arquitetura`, `adr`, `runbook`, `norma`, `plano`, `relatorio`, `incidente`, `ata`, e os modelos-base do zelo: `rfc`/`spec` (viram `plano`), `politica` (vira `norma`), `ameacas` (modelo de ameaças, `referencia` em `seguranca/`). Nunca sobrescreve.
+- **`neetru docs check [--changed] [--strict] [--offline] [--json]`** — validador **offline** com os mesmos códigos do Core (FM001–FM013, TI001–TI008, NM001–NM002, LK001–LK002, PB001, LC001–LC002) mais PR001 (`product` ausente ou diferente do slug), PR002 (mínimo do primeiro dia e seções do README; os itens "do primeiro mês" saem como **sugestão**, que nunca falha), PR003 (categoria só do Core) e PR004 (CHANGELOG sem a versão do `package.json`). `_archive/` e `_audit/` com as regras reduzidas do §9.4. `--changed` = catraca contra a branch principal (commits + staged + não commitados + não rastreados; sem git, avisa e checa tudo). `--strict` = aviso também falha. Sai 1 com erro.
+  - **Taxonomia embutida** (`src/lib/product-docs/taxonomy.ts`) idêntica ao bloco JSON do §5.2 do protocolo — teste confere contra a fixture copiada do protocolo e, quando há checkout do Core (`NEETRU_CORE_DIR`), contra o próprio markdown. Online, usa `GET /api/cli/v1/docs/taxonomy` do Core (outra frente cria a rota) e cai na embutida em 404, falha de rede ou formato inválido; avisa quando a do Core é mais nova.
+- **`neetru docs sync [--dry-run] [--offline] [--json]`** — publica `docs/` no registro de docs por produto do Core, contra o contrato **proposto** em `PROJ_PRODUCT_DOCS` §4.2 (`GET`/`POST /api/cli/v1/products/{productId}/docs`, corpo `{slug, content, frontmatter, visibility}`). Só sobem docs **sem erro** no check (fora `_archive/` e `_audit/`); `visibility: public` só com `audience: publico` + `status: active`; doc igual ao do Core (sha256 do conteúdo + título + status + visibilidade) não é reenviado; **nada é apagado** — doc que só existe no Core é listado como órfão. Limite local de 200 docs / 10 MB (D-05). **Capacidade**: se o Core responde 404 (sem `product_not_found`), 405 ou 501, mostra "O Core ainda não aceita docs de produto" e sai **0**. `docs.publish: false` desliga.
+- **`neetru init` e `neetru new` chamam `docs init`** depois do scaffold (`--sem-docs` pula; falha nos docs vira aviso, não derruba o init).
+- **`neetru deploy`** roda `docs check` (taxonomia embutida, sem rede extra) e **só avisa** — em produção, lista o que falta do mínimo do primeiro dia. Com `docs.publishOnDeploy: true`, o deploy de **produção** bem-sucedido chama o sync no fim (VM, workspace e cloud-run); falha do sync vira aviso e o deploy continua com exit 0. Em `--json`, a saída ganha `docs: { check, sync }`. `--sem-docs` pula as duas coisas.
+- `neetru.config.json`: bloco `docs` (`protocolVersion`, `root`, `publish`, `publishOnDeploy`, `api`) no schema.
+
+### Corrigido (ensaio real nos 3 produtos e alinhamento com o servidor do Core)
+
+- Datas no fuso de Brasília: depois das 21h BRT, docs, CHANGELOG, relatório e `gerado_em` saíam com o dia seguinte (UTC).
+- `suggestedName` preserva a data ISO com hífens (`…_2026-06-30.md`); antes virava `_2026_06_30` e reprovava o NM002.
+- CHANGELOG do `docs init` em produto maduro: entrada da versão atual, sem "Primeira versão do produto." inventada.
+- `index.md` gerado lista tudo o que existe (inclusive `superpowers/`, `_review/`, pastas fora do padrão e docs da raiz), marcando o que está fora do padrão.
+- Monorepo: o `neetru.config.json` é procurado subindo pastas até a raiz do git; `docs.root` pode apontar acima do config, mas nunca para fora do repositório.
+- `--migrar`: inferências de tipo/destino melhores (`DESIGN*` não vira plano; doc solto na raiz recebe tipo coerente com o destino sugerido; `deploy/README.md` não vira índice; destinos do §10).
+- `resolveTaxonomy` aceita o formato real do Core (`categories` como lista + `subcategories` como mapa); a cópia embutida passa a esconder `superpowers/`, como o protocolo.
+- `docs sync`: espaça os envios (janela de 25 por minuto) e respeita `Retry-After` no 429; compara também os metadados com o Core; confere localmente o limite de 2 MB por doc e os caracteres aceitos no caminho (acento/espaço/`__` são recusados antes do envio); a dica de órfão não cita mais um comando que não existe.
+
+### Dependência no Core
+
+- `GET /api/cli/v1/docs/taxonomy` (Core PR #565) e `GET`/`POST /api/cli/v1/products/{productId}/docs` (Core PR #571). Sem eles no ar, a CLI funciona igual (taxonomia embutida; o sync informa e sai 0).
+
+## [2.30.0] — 2026-10-03 (varredura de segredo no pacote público antes do deploy)
+
+### Adicionado
+
+- **`neetru deploy` bloqueia segredo no pacote PÚBLICO** (decisão do dono 2026-10-03: a credencial `nrt_` do produto é **só de servidor**; produtos hoje carregam a chave no navegador via `NEXT_PUBLIC_NEETRU_API_KEY`/`NEXT_PUBLIC_NEETRU_PUBLIC_KEY`).
+  - Novo `src/lib/public-secret-scan.ts` (sem dependências): lê o `.tar.gz` de deploy em **streaming** (zlib + parser ustar/GNU `@LongLink`/pax `path=`) e varre só o que é servido ao navegador — `.next/static/**` (em qualquer profundidade), `public/**`, `out/**`, `dist/**`, `build/**`; na stack `static`, o pacote inteiro; `node_modules/**` nunca; binários (imagem/fonte/mídia/wasm) e arquivos > 25 MB pulados (o grande é avisado).
+  - Padrões: `nrt_[A-Za-z0-9_-]{20,}`, `npk_[A-Za-z0-9_-]{20,}`, `-----BEGIN … PRIVATE KEY-----` seguido do material base64 da chave (só o cabeçalho, comum em código de biblioteca, não conta) e o **valor** de envs públicas (`NEXT_PUBLIC_*`, `EXPO_PUBLIC_*`, `VITE_*`, `REACT_APP_*`, `PUBLIC_*`) com `KEY`/`SECRET`/`TOKEN` no nome — lidas de `.env`, `.env.production`, `.env.local`, `.env.production.local` (que **não** viajam no tarball), `--env-file` e `process.env`. Valores públicos por desenho (Stripe `pk_live_`/`pk_test_`, Google/Firebase `AIza…`, reCAPTCHA `6L…`) e valores com menos de 12 caracteres são ignorados.
+  - Roda **antes do upload** (fluxo build→upload e `--artifact <arquivo>`; também com `--local-artifact`). Em `target=cloud-run` sem `--image`, varre as pastas públicas do disco antes de buildar a imagem.
+  - Achou → **falha FECHADO**: exit 1, `public_secret_in_bundle` (em `--json`, a linha `{ok:false,error,message}`), mensagem PT-BR com arquivo + tipo + como corrigir. **Nunca imprime o segredo**: no máximo os 8 primeiros caracteres (e nunca mais que 1/4 do valor), mascarados. Pacote ilegível → `public_secret_scan_failed` (também fechado).
+  - **`--allow-public-secret "<motivo>"`** — override de emergência. Motivo obrigatório (≥ 10 caracteres, validado antes de build/upload; senão `invalid_override_reason`). Segue com aviso alto ("trate a chave como VAZADA") e **registra no deploy**: `publicSecretOverride: { reason, findings: [{ file, pattern }], at }` no corpo do `POST /api/cli/v1/deploy` (só caminho + tipo, nunca o valor) e `publicSecretScan` na saída `--json`.
+  - Não varridos (com aviso): `--artifact-url` (pacote remoto) e `--image` (imagem pronta).
+
+### Dependência no Core
+
+- O `deployRequestSchema` do Core faz *strip* de chaves desconhecidas: hoje o `publicSecretOverride` chega no corpo cru mas **não é persistido**. Para o registro valer de ponta a ponta, o Core precisa ler `publicSecretOverride` do corpo cru (mesmo padrão do `prodDirectOverride`) e gravar em `deployments/{id}` + auditoria. Até lá o registro fica na saída do CLI.
+
 ## [2.29.0] — 2026-10-01 (status live_unverified, db move decommission no contrato real, servers pgbouncer sync-userlist, TUI do code sob demanda)
 
 ### Adicionado

package/README.md

@@ -51,7 +51,11 @@ Cria produto + workspace + scaffold local Next.js 15 + instala deps + abre cockp
 | `neetru new <slug>` | Criar produto completo (registry + workspace + scaffold) |
 | `neetru init <name>` | Só scaffold local Next.js + Firebase |
 | `neetru add <feature>` | Adicionar features ao scaffold (auth, billing, etc) |
-| `neetru deploy` | Pipeline de deploy interativo (cloud-run / vm / workspace) |
+| `neetru deploy` | Pipeline de deploy interativo (cloud-run / vm / workspace) — roda `docs check` e só avisa |
+| `neetru docs init [--com-api] [--migrar]` | Mínimo do primeiro dia do `docs/` do produto (idempotente); `--migrar` só acrescenta frontmatter + relatório |
+| `neetru docs new <tipo> "<título>"` | Doc novo a partir do modelo, na pasta e com o nome do protocolo |
+| `neetru docs check [--changed] [--strict]` | Valida os docs do produto offline (códigos FM/TI/NM/LK/PB/LC + PR001–PR004) |
+| `neetru docs sync [--dry-run]` | Publica os docs do produto no Core (só os sem erro; nada é apagado) |
 | `neetru build [--stack ...] [--target-env dev\|workspace\|prod] [--env-file ...] [--no-cache] [--no-install]` | Empacotar produto em tarball pra deploy |
 | `neetru smoke [--base-url ...] [--prod ...] [--health-path ...] [--routes csv] [--json]` | Percorrer as páginas do produto **local** antes do deploy (alcance + login + DB) + smoke de prod opcional |
 | `neetru promote` | Promover dev → staging → prod |
@@ -63,8 +67,8 @@ Cria produto + workspace + scaffold local Next.js 15 + instala deps + abre cockp
 | `neetru admin database engines` | Listar engines suportados (`firestore-instance`, `cloud-sql-postgres`, `cloud-sql-mysql`, `vm-postgres-single`, `vm-mysql-single`, `nosql-vm`, …) |
 | `neetru db init / apply / migrations` | Banco por produto no fluxo dev (registra + schema + migrations) |
 | `neetru dev` | Banco Docker local + watch de schema (`salvar = aplicado`) |
-| `neetru dev up` | **Emulador local completo** — Firebase Emulators + Core, 100% offline |
-| `neetru dev exec <script>` | Roda `<script>` com emuladores ativos (CI sem credencial cloud) |
+| `neetru dev up` | Banco do produto em container (Docker Compose) + URL de conexão pro `.env.local` |
+| `neetru dev exec <script>` | Roda `<script>` com os emuladores Firebase do **Core** (exige o repo do Core; CI do Core) |
 | `neetru cloud-run pause/resume/delete <service>` | Controle Cloud Run |
 | `neetru products list/create/update` | Registry de produtos |
 | `neetru workspaces create/list/get/advance` | Instâncias por cliente |
@@ -91,24 +95,44 @@ Cria produto + workspace + scaffold local Next.js 15 + instala deps + abre cockp
 
 40+ subcomandos. Quase todos suportam `--json` pra automação.
 
-## Dev local — emulador (`neetru dev up`)
+## Docs do produto (`neetru docs init|new|check|sync`) — 2.31.0
 
-Ambiente de desenvolvimento **100% offline**, estilo Firebase Emulator Suite — sem tocar GCP/staging:
+Padrão: `PROTOCOLO_DOCS_PRODUTOS_SAAS.md` do Core (versão 1). O `docs/` de cada produto segue a mesma taxonomia da wiki do Core (categoria + subcategoria por assunto, `type` à parte) e nomes `MAIÚSCULO_COM_UNDERLINE`.
 
 ```bash
-# Na raiz do Core (onde tem firebase.json):
-neetru dev up
-#  → sobe Firebase Emulators (Firestore :8080, Auth :9099, Functions :5001)
-#  → sobe o Core Next.js (:9003) apontando pros emuladores
-#  → Ctrl-C encerra os dois em cascata
+neetru docs init                 # README, CHANGELOG, docs/index.md, visão, arquitetura, runbook de deploy
+neetru docs init --com-api       # + docs/api/API_V1.md (o produto expõe /api/v1)
+neetru docs init --migrar        # repo que já tem docs: frontmatter inferido + relatório em docs/_audit/
+neetru docs new adr "Usar Postgres para vendas"
+neetru docs new relatorio "Auditoria de UX da tela de caixa"
+neetru docs check --changed      # catraca: só o que mudou contra a branch principal
+neetru docs sync --dry-run       # o que subiria para o Core
+```
+
+- `neetru init` e `neetru new` já rodam `docs init` (`--sem-docs` pula).
+- `neetru deploy` roda `docs check` e **só avisa** — nunca bloqueia. Com `"docs": { "publishOnDeploy": true }` no `neetru.config.json`, o deploy de **produção** publica os docs no fim; falha na publicação não derruba o deploy. `--sem-docs` pula as duas coisas.
+- A taxonomia vem embutida na CLI (funciona offline); quando o Core expõe `GET /api/cli/v1/docs/taxonomy`, o `check` usa a do Core e avisa se a embutida estiver velha.
 
-# Seed portátil (compartilhe o estado entre devs via git):
-neetru dev up --import .neetru-dev/seed --export-on-exit .neetru-dev/seed
+## Dev local (`neetru dev`, `neetru dev up`)
 
-# Só os emuladores (sem o Core):
-neetru dev up --skip-core
+O que roda na máquina do dev de produto hoje:
+
+| Peça | Como |
+|---|---|
+| SDK sem conta Neetru | `NEETRU_ENV=dev` → mocks em memória (login fixture, uso zerado, banco em memória). `neetru mocks reset` limpa as fixtures. |
+| Banco real do produto | `neetru dev` (container + reaplica `db/schema.ts` a cada save) **ou** `neetru dev up` (só sobe o container e imprime a URL de conexão). Engine vem do projeto. |
+| App | `npm run dev`, fora de container. |
+| Agente / Core locais | **Ainda não existem** para produto. Deploy e migração pelo agente só acontecem na VM. |
 
-# CI / teste de integração sem credencial cloud (propaga o exit code do script):
+```bash
+# Na raiz do produto (com database.engine no neetru.config.json):
+neetru dev up
+#  → gera neetru-compose.dev.yml e sobe o banco (docker compose up -d --wait)
+#  → imprime a conexão, ex. postgresql://postgres:neetru_dev@localhost:5432/app
+docker compose -f neetru-compose.dev.yml down   # para
+
+# CI do Core (na raiz do Core, onde tem firebase.json): roda o script com os
+# emuladores Firebase e propaga o exit code.
 neetru dev exec "npm run test:integration"
 ```
 
@@ -121,7 +145,7 @@ neetru dev use --product meu-produto --sync
 # Protótipo local ainda não cadastrado no Core:
 neetru dev use --prototype meu-rascunho
 
-# Ver o contexto efetivo que dev up/dev exec vão usar:
+# Ver o contexto dev-local efetivo:
 neetru dev status
 
 # Sincronizar bancos dev-local do Core para .neetru/db.json:
@@ -129,7 +153,7 @@ neetru dev sync --write-db
 ```
 
 > `neetru dev` (sem subcomando) mantém o modo legado: banco Docker local + watch de schema.
-> Flags: `--only firestore,auth,functions`, `--core-port 9003`, `--core-path <dir>`.
+> Flags: `dev up --core-port <n>` (porta do app nas instruções, default 3000); `dev exec --only firestore,auth,functions --core-path <dir>`.
 > O arquivo `.neetru/dev.json` guarda o contexto local: produto Core ou protótipo, Core path e emuladores padrão.
 
 ## Build — env do bundle (`NEXT_PUBLIC_NEETRU_ENV`)
@@ -145,6 +169,26 @@ Isso existe porque o Next.js carrega `.env.local` (arquivo do disco do dev, nunc
 
 Se o produto envolver `next.config.mjs` com `withNeetruBuildGuard` (`@neetru/sdk/build-guard`, `@neetru/sdk >= 3.1.15`), `neetru build` confere pós-build que o env realmente compilado bate com o esperado — e **recusa empacotar o tarball** se divergir, em vez de deployar um bundle quebrado silenciosamente.
 
+## Segredo no pacote público bloqueia o deploy (2.30.0)
+
+A credencial `nrt_` do produto é **só de servidor**. Antes de enviar o pacote, `neetru deploy` varre o que é servido ao navegador — `.next/static/**`, `public/**`, `out/**`, `dist/**`, `build/**` (na stack `static`, o pacote inteiro; `node_modules` nunca) — procurando:
+
+- `nrt_…` e `npk_…` (credenciais Neetru);
+- `-----BEGIN … PRIVATE KEY-----` com o material da chave (só o cabeçalho não conta);
+- o **valor** de envs públicas (`NEXT_PUBLIC_*`, `EXPO_PUBLIC_*`, `VITE_*`, `REACT_APP_*`, `PUBLIC_*`) cujo nome contém `KEY`/`SECRET`/`TOKEN` (lidas de `.env`, `.env.production`, `.env.local`, `.env.production.local`, `--env-file` e do ambiente). Valores públicos por desenho do provedor (Stripe `pk_live_`/`pk_test_`, chave web Google/Firebase `AIza…`, reCAPTCHA `6L…`) são ignorados.
+
+Achou → **o deploy falha** (exit 1, `public_secret_in_bundle`) mostrando arquivo e tipo — **nunca o segredo** (no máximo 8 caracteres iniciais, mascarados). Pacote ilegível também falha (`public_secret_scan_failed`).
+
+Correção: tire a chave do código do navegador/app; o navegador/app chama a API do seu produto com o token do usuário e o backend usa `@neetru/sdk` com `NEETRU_API_KEY` (ver `verifyAccessToken` no SDK ≥ 3.8.0).
+
+Emergência (fica registrado no deploy — só caminho e tipo, nunca o valor):
+
+```bash
+neetru deploy --allow-public-secret "chave antiga já revogada, ticket #123"
+```
+
+Limites: `--artifact-url` (pacote remoto) e `--image` (imagem pronta, cloud-run) não passam pelo CLI e **não são varridos** — o deploy avisa. Em `target=cloud-run` sem `--image`, a varredura é nas pastas públicas do disco antes do build da imagem.
+
 ## Smoke local antes do deploy (`neetru smoke`)
 
 Roda contra o servidor **dev local** (`next dev` / `neetru dev up`) e percorre as páginas do produto **antes** de `neetru build` + `neetru deploy` — pega página quebrada, login que não renderiza ou banco fora do ar sem subir nada em produção.

package/dist/commands/deploy.d.ts

@@ -1,3 +1,4 @@
+import { type PublicSecretOverrideRecord } from '../lib/public-secret-scan.js';
 /**
  * bug_a5786e03 (2026-05-31): o Core/agente só conhecem os stacks canônicos
  * `node|docker|php-apache|static` (PRODUCT_STACKS). `nextjs` é um alias de
@@ -88,7 +89,51 @@ export interface DeployOptions {
      * pra prod (auditoria cli/v1 2026-09-29, M7). Ignorado em dev/staging.
      */
     mfaToken?: string;
+    /**
+     * 2.30.0 — `--allow-public-secret "<motivo>"`: override de EMERGÊNCIA da
+     * varredura de segredo no pacote público. Motivo obrigatório (≥10 chars);
+     * fica registrado no deploy (`publicSecretOverride` no corpo enviado ao Core
+     * e na saída --json) — só caminho + tipo de padrão, nunca o valor.
+     */
+    allowPublicSecret?: string;
+    /**
+     * Protocolo de docs de produto v1: pula a checagem dos docs (que só avisa)
+     * e a publicação automática no fim do deploy de produção (`docs.publishOnDeploy`).
+     */
+    semDocs?: boolean;
+}
+/** Resultado da varredura de segredo, anexado ao deploy. */
+export interface PublicSecretGateResult {
+    /** `false` quando não deu pra varrer (artefato remoto / imagem pronta). */
+    scanned: boolean;
+    scannedFiles?: number;
+    reason?: string;
+    override?: PublicSecretOverrideRecord;
 }
+/**
+ * Valida o motivo do `--allow-public-secret` ANTES de qualquer build/upload.
+ * `undefined` = flag não passada.
+ */
+export declare function validateAllowPublicSecretReason(raw: string | undefined, json?: boolean): string | undefined;
+/**
+ * 2.30.0 — gate de segredo no pacote PÚBLICO (decisão do dono 2026-10-03: a
+ * credencial nrt_ é SÓ DE SERVIDOR). Roda ANTES do upload. Achou → falha
+ * FECHADO (exit 1, `public_secret_in_bundle`), a não ser que haja override com
+ * motivo — aí segue com aviso alto e devolve o registro pro corpo do deploy.
+ */
+export declare function runPublicSecretGate(source: {
+    kind: 'tar';
+    path: string;
+} | {
+    kind: 'dir';
+    root: string;
+}, ctx: {
+    cwd: string;
+    envFile?: string;
+    stack?: string;
+    allowReason?: string;
+    json?: boolean;
+}): Promise<PublicSecretGateResult>;
 /** `true` pra `prod`/`production` (o Core normaliza `production`→`prod`). */
 export declare function isProdEnv(envName: string | undefined): boolean;
 /**

package/dist/commands/deploy.js

@@ -33,6 +33,7 @@ import { formatDeployConsole, isDeployUnverified, deployStatusLabel } from './de
 import { readDbJson, schemaFingerprint } from '../lib/db-local/index.js';
 // bug_863ae5: pre-flight IAM check.
 import { assertIamReady } from '../lib/iam-preflight.js';
+import { ALLOW_PUBLIC_SECRET_FLAG, MIN_OVERRIDE_REASON_LENGTH, buildOverrideRecord, collectPublicEnvSecrets, formatFindingsMessage, scanDirectoryForPublicSecrets, scanTarballForPublicSecrets, } from '../lib/public-secret-scan.js';
 import { getActiveTokenSync } from '../lib/token-resolver.js';
 import { safeExit } from '../utils/safe-exit.js';
 /**
@@ -86,6 +87,57 @@ export function resolveDeployVersion(manifestVersion, explicitVersion, json) {
     }
     return version;
 }
+/**
+ * Valida o motivo do `--allow-public-secret` ANTES de qualquer build/upload.
+ * `undefined` = flag não passada.
+ */
+export function validateAllowPublicSecretReason(raw, json) {
+    if (raw === undefined)
+        return undefined;
+    const reason = String(raw).trim();
+    if (reason.length < MIN_OVERRIDE_REASON_LENGTH) {
+        deployFail(json, 'invalid_override_reason', `${ALLOW_PUBLIC_SECRET_FLAG} exige um motivo de verdade (mínimo ${MIN_OVERRIDE_REASON_LENGTH} caracteres) — ` +
+            'ele fica registrado no deploy. Ex.: --allow-public-secret "rotação da chave em andamento, ticket #123".');
+    }
+    return reason;
+}
+/**
+ * 2.30.0 — gate de segredo no pacote PÚBLICO (decisão do dono 2026-10-03: a
+ * credencial nrt_ é SÓ DE SERVIDOR). Roda ANTES do upload. Achou → falha
+ * FECHADO (exit 1, `public_secret_in_bundle`), a não ser que haja override com
+ * motivo — aí segue com aviso alto e devolve o registro pro corpo do deploy.
+ */
+export async function runPublicSecretGate(source, ctx) {
+    const lg = scopedLog(ctx.json);
+    const envSecrets = await collectPublicEnvSecrets(ctx.cwd, ctx.envFile);
+    let result;
+    try {
+        result =
+            source.kind === 'tar'
+                ? await scanTarballForPublicSecrets(source.path, { stack: ctx.stack, envSecrets })
+                : await scanDirectoryForPublicSecrets(source.root, { stack: ctx.stack, envSecrets });
+    }
+    catch (err) {
+        // Não conseguir LER o pacote é falha fechada também (não dá pra afirmar que está limpo).
+        deployFail(ctx.json, 'public_secret_scan_failed', `Não consegui varrer o pacote em busca de segredos: ${err.message}`);
+    }
+    if (result.skippedLarge.length > 0) {
+        lg.warn(`Varredura de segredo: ${result.skippedLarge.length} arquivo(s) público(s) grande(s) demais não foram varridos ` +
+            `(ex.: ${result.skippedLarge[0]}).`);
+    }
+    if (result.findings.length === 0) {
+        lg.dim(`  Varredura de segredo no pacote público: ok (${result.scannedFiles} arquivo(s)).`);
+        return { scanned: true, scannedFiles: result.scannedFiles };
+    }
+    if (!ctx.allowReason) {
+        deployFail(ctx.json, 'public_secret_in_bundle', formatFindingsMessage(result.findings));
+    }
+    const override = buildOverrideRecord(ctx.allowReason, result.findings);
+    lg.warn(formatFindingsMessage(result.findings).split('\n')[0].replace('Deploy BLOQUEADO.', 'Deploy LIBERADO por override.'));
+    lg.warn(`OVERRIDE ${ALLOW_PUBLIC_SECRET_FLAG} — motivo registrado no deploy: "${ctx.allowReason}". ` +
+        'Trate a chave exposta como VAZADA: rotacione-a assim que possível.');
+    return { scanned: true, scannedFiles: result.scannedFiles, override };
+}
 /** `true` pra `prod`/`production` (o Core normaliza `production`→`prod`). */
 export function isProdEnv(envName) {
     const e = (envName ?? '').trim().toLowerCase();
@@ -566,7 +618,15 @@ async function uploadArtifactToGcs(tarballAbs, productSlug, envName, sizeBytes,
 async function resolveArtifact(opts, productSlug, envName, cwd) {
     // Caso 1: caller já fez upload e passou URL+sha pronta.
     if (opts.artifactUrl && opts.artifactSha256) {
-        return { artifactUrl: opts.artifactUrl, artifactSha256: opts.artifactSha256 };
+        // 2.30.0: artefato remoto não passa pelo CLI — não dá pra varrer. Avisa (o
+        // gate vale pro fluxo padrão build→upload e pro --artifact local).
+        scopedLog(opts.json).warn('Varredura de segredo NÃO feita: --artifact-url aponta um pacote remoto. ' +
+            'Prefira `neetru deploy` com build local ou --artifact <arquivo> (que são varridos).');
+        return {
+            artifactUrl: opts.artifactUrl,
+            artifactSha256: opts.artifactSha256,
+            publicSecretScan: { scanned: false, reason: 'remote_artifact' },
+        };
     }
     // Decide se vamos fazer upload pra GCS ou manter file://.
     const keepLocal = shouldKeepLocalArtifact(opts);
@@ -584,12 +644,15 @@ async function resolveArtifact(opts, productSlug, envName, cwd) {
             hash.update(chunk);
         const stat = await fsp.stat(abs);
         const sha256 = hash.digest('hex');
+        // 2.30.0: varredura de segredo ANTES de qualquer envio.
+        const publicSecretScan = await runPublicSecretGate({ kind: 'tar', path: abs }, { cwd, envFile: opts.envFile, stack: opts.stack, allowReason: opts.allowPublicSecret, json: opts.json });
         if (keepLocal) {
             lg.warn('Modo --local-artifact: mandando file:// pro Core. Só funciona se o agent compartilha FS com este CLI.');
             return {
                 artifactUrl: `file://${abs.replace(/\\/g, '/')}`,
                 artifactSha256: sha256,
                 artifactSizeBytes: stat.size,
+                publicSecretScan,
             };
         }
         const uploaded = await uploadArtifactToGcs(abs, productSlug, envName, stat.size, opts.json);
@@ -598,6 +661,7 @@ async function resolveArtifact(opts, productSlug, envName, cwd) {
             artifactSha256: sha256,
             artifactSizeBytes: stat.size,
             deployId: uploaded.deployId,
+            publicSecretScan,
         };
     }
     // Caso 3: procura manifest existente, senão chama runBuild.
@@ -638,6 +702,14 @@ async function resolveArtifact(opts, productSlug, envName, cwd) {
         });
     }
     const tarAbs = path.resolve(cwd, manifest.tarball);
+    // 2.30.0: varredura de segredo no pacote que VAI ser enviado, antes do upload.
+    const publicSecretScan = await runPublicSecretGate({ kind: 'tar', path: tarAbs }, {
+        cwd,
+        envFile: opts.envFile,
+        stack: manifest.stack ?? opts.stack,
+        allowReason: opts.allowPublicSecret,
+        json: opts.json,
+    });
     if (keepLocal) {
         lg.warn('Modo --local-artifact: mandando file:// pro Core. Só funciona se o agent compartilha FS com este CLI.');
         return {
@@ -645,6 +717,7 @@ async function resolveArtifact(opts, productSlug, envName, cwd) {
             artifactSha256: manifest.sha256,
             artifactSizeBytes: manifest.sizeBytes,
             manifest,
+            publicSecretScan,
         };
     }
     const uploaded = await uploadArtifactToGcs(tarAbs, productSlug, envName, manifest.sizeBytes, opts.json);
@@ -654,6 +727,7 @@ async function resolveArtifact(opts, productSlug, envName, cwd) {
         artifactSizeBytes: manifest.sizeBytes,
         manifest,
         deployId: uploaded.deployId,
+        publicSecretScan,
     };
 }
 async function pollDeploymentStatus(deploymentId, json) {
@@ -1033,9 +1107,11 @@ async function runWorkspaceDeploy(opts, productSlug, envName, cwd, nonInteractiv
     }
     if (resp.status === 'live') {
         spinner.succeed(`Deploy ${chalk.bold('live')} · ${resp.deploymentId}`);
+        const docsSync = await postDeployDocs(opts, cwd, envName);
         if (opts.json) {
             console.log(JSON.stringify({
                 ok: true,
+                ...(docsSync ? { docs: { sync: docsSync } } : {}),
                 status: 'live',
                 target: 'workspace',
                 deploymentId: resp.deploymentId,
@@ -1053,9 +1129,11 @@ async function runWorkspaceDeploy(opts, productSlug, envName, cwd, nonInteractiv
         // aplicou o deploy mas ainda não confirmou saúde. Sucesso COM AVISO — não
         // tratamos como falha nem fingimos "Live" confirmado.
         spinner.warn(`Deploy aplicado — ${deployStatusLabel(resp.status)} · ${resp.deploymentId}`);
+        const docsSync = await postDeployDocs(opts, cwd, envName);
         if (opts.json) {
             console.log(JSON.stringify({
                 ok: true,
+                ...(docsSync ? { docs: { sync: docsSync } } : {}),
                 status: resp.status,
                 verified: false,
                 target: 'workspace',
@@ -1387,6 +1465,16 @@ async function runCloudRunDeploy(opts, productSlug, envName, cwd, nonInteractive
     if (deployToken) {
         await assertIamReady(deployToken, 'deploy.cloud-run', opts.json);
     }
+    // 2.30.0: varredura de segredo nas pastas públicas ANTES de buildar a imagem.
+    // Com --image (imagem pronta) não há o que varrer aqui — avisa.
+    let publicSecretScan;
+    if (opts.image) {
+        scopedLog(opts.json).warn('Varredura de segredo NÃO feita: --image aponta uma imagem já buildada (o CLI não vê o conteúdo).');
+        publicSecretScan = { scanned: false, reason: 'prebuilt_image' };
+    }
+    else {
+        publicSecretScan = await runPublicSecretGate({ kind: 'dir', root: cwd }, { cwd, envFile: opts.envFile, stack: opts.stack, allowReason: opts.allowPublicSecret, json: opts.json });
+    }
     const imageUrl = await resolveCloudRunImage(opts, productSlug, envName, cwd);
     let envVars;
     if (opts.envFile) {
@@ -1421,6 +1509,7 @@ async function runCloudRunDeploy(opts, productSlug, envName, cwd, nonInteractive
                 imageUrl,
                 ...(opts.port ? { port: opts.port } : {}),
                 ...(envVars && Object.keys(envVars).length > 0 ? { envVars } : {}),
+                ...(publicSecretScan.override ? { publicSecretOverride: publicSecretScan.override } : {}),
             },
         });
     }
@@ -1430,9 +1519,11 @@ async function runCloudRunDeploy(opts, productSlug, envName, cwd, nonInteractive
     }
     if (resp.status === 'live') {
         spinner.succeed(`Deploy ${chalk.bold('live')} · ${resp.deploymentId}`);
+        const docsSync = await postDeployDocs(opts, cwd, envName);
         if (opts.json) {
             console.log(JSON.stringify({
                 ok: true,
+                ...(docsSync ? { docs: { sync: docsSync } } : {}),
                 status: 'live',
                 target: 'cloud-run',
                 deploymentId: resp.deploymentId,
@@ -1454,9 +1545,11 @@ async function runCloudRunDeploy(opts, productSlug, envName, cwd, nonInteractive
         // aplicou o deploy mas ainda não confirmou saúde. Sucesso COM AVISO — não
         // tratamos como falha nem fingimos "Live" confirmado.
         spinner.warn(`Deploy aplicado — ${deployStatusLabel(resp.status)} · ${resp.deploymentId}`);
+        const docsSync = await postDeployDocs(opts, cwd, envName);
         if (opts.json) {
             console.log(JSON.stringify({
                 ok: true,
+                ...(docsSync ? { docs: { sync: docsSync } } : {}),
                 status: resp.status,
                 verified: false,
                 target: 'cloud-run',
@@ -1562,17 +1655,48 @@ async function checkSchemaGate(cwd, opts) {
     }
     return true;
 }
+/**
+ * Protocolo de docs v1 (decisão do dono 2026-10-03): depois de um deploy bem
+ * sucedido, publica os docs no Core SÓ se for produção e `docs.publishOnDeploy`
+ * estiver ligado. Nunca lança — falha do sync não derruba o deploy.
+ */
+async function postDeployDocs(opts, cwd, envName) {
+    if (opts.semDocs)
+        return undefined;
+    try {
+        const { deployDocsPostSync } = await import('./docs-produto.js');
+        const r = await deployDocsPostSync(cwd, envName, opts.json);
+        return r.attempted ? r : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function runDeploy(opts) {
     if (!opts.json)
         log.banner();
     const cwd = process.cwd();
     const nonInteractive = ensureNonInteractive(opts);
+    // 2.30.0: motivo do override validado ANTES de build/upload.
+    opts = { ...opts, allowPublicSecret: validateAllowPublicSecretReason(opts.allowPublicSecret, opts.json) };
     const productSlug = await pickProduct(opts, nonInteractive, cwd);
     // GAP-M1-5 — gate de schema: detecta drift antes de prosseguir.
     const canDeploy = await checkSchemaGate(cwd, opts);
     if (!canDeploy) {
         safeExit(1);
     }
+    // Protocolo de docs v1 (decisão do dono 2026-10-03): `docs check` antes do
+    // deploy SÓ AVISA — nunca bloqueia, em nenhum ambiente.
+    let docsCheck;
+    if (!opts.semDocs) {
+        try {
+            const { deployDocsPrecheck } = await import('./docs-produto.js');
+            docsCheck = await deployDocsPrecheck(cwd, (opts.env ?? 'dev').toLowerCase(), opts.json);
+        }
+        catch {
+            docsCheck = undefined;
+        }
+    }
     const target = await pickTarget(opts, nonInteractive);
     // Caminho workspace (Fase 1 do Fluxo de Ambientes) — sem server/tar/upload.
     if (target === 'workspace') {
@@ -1671,6 +1795,10 @@ export async function runDeploy(opts) {
         body.domain = domain;
     if (envVars && Object.keys(envVars).length > 0)
         body.envVars = envVars;
+    // 2.30.0: override da varredura de segredo vai NO deploy (só caminho + tipo
+    // de padrão, nunca o valor). O Core lê do corpo cru (como prodDirectOverride).
+    if (artifact.publicSecretScan.override)
+        body.publicSecretOverride = artifact.publicSecretScan.override;
     const mfaHeaders = await resolveDeployStepUpHeaders(opts, envName, nonInteractive);
     let deploy;
     const dispatchSpinner = ora({ text: 'Enviando comando ao Core…', color: 'blue' }).start();
@@ -1707,6 +1835,9 @@ export async function runDeploy(opts) {
         }
         safeExit(1);
     }
+    // Docs no Core (opt-in `docs.publishOnDeploy`, só produção). O pipeline já
+    // aplicou a versão; falha aqui só vira aviso.
+    const docsSync = await postDeployDocs(opts, cwd, envName);
     // ── Fase 0 #1: probe de saúde INDEPENDENTE antes de declarar "Live" ────────
     // O pipeline pode reportar `success` com o site quebrado (outage PDV
     // 2026-09-07). Só declaramos "Live" se um GET real ao domínio confirmar 200 +
@@ -1724,6 +1855,8 @@ export async function runDeploy(opts) {
         url: final.domain ? `https://${final.domain}` : null,
         artifactUrl: artifact.artifactUrl,
         steps: final.steps,
+        publicSecretScan: artifact.publicSecretScan,
+        ...(docsCheck || docsSync ? { docs: { check: docsCheck ?? null, sync: docsSync ?? null } } : {}),
     };
     if (opts.skipHealthProbe) {
         if (opts.json) {