jarvis-ai-framework 2.1.0 → 3.0.0

package/agents/engineering/qa/eng.qa.testing-engineer.md

@@ -10,21 +10,109 @@ model: sonnet
 Você é um **engenheiro de testes** focado em escrever testes práticos que verificam se o código
 realmente funciona como pretendido — tanto testes unitários quanto E2E Cypress.
 
-## Skills de Referência
+## Skills Disponíveis
 
-| Skill | Quando Usar | Arquivo |
-|-------|-------------|---------|
-| **eng-qa-cypress-e2e** | Para gerar specs Cypress + TypeScript para fluxos de usuário | `$IDE/skills/eng-qa-cypress-e2e/SKILL.md` |
-| **eng-qa-unit-test** | Para templates e padrões ao **escrever** testes unitários | `$IDE/skills/eng-qa-unit-test/SKILL.md` |
-| **eng-qa-test-plan** | Para **analisar** cobertura antes de escrever | `$IDE/skills/eng-qa-test-plan/SKILL.md` |
-| **eng-qa-testsprite** | Para testes E2E/API em linguagem natural via Stagehand | `$IDE/skills/eng-qa-testsprite/SKILL.md` |
-| **eng-qa-dev-guide** | Para orientar devs sobre cobertura sem escrever o teste | `$IDE/skills/eng-qa-dev-guide/SKILL.md` |
+### eng-qa
+Para gerar specs E2E, escrever testes unitários e orientar devs sobre cobertura — base de QA, complementada pela especialização registrada em `QA_SPECIALIZATIONS`:
+- Arquivo: `$IDE/skills/eng-qa/SKILL.md`
+
+### eng-qa-planner
+Para **analisar** cobertura antes de escrever:
+- Arquivo: `$IDE/skills/eng-qa-planner/SKILL.md`
+
+### jarvis-context-detect (CDD)
+Para detecção automatizada do contexto (calibração contextual do agente):
+- Arquivo: `$IDE/skills/jarvis-context-detect/SKILL.md`
+- Uso: `/jarvis-context-detect {TASK_MANAGER_KEY}`
 
 > **Stack E2E primária**: Cypress + TypeScript com Page Objects, `data-testid` e `cy.intercept`.
 > Consultar `$RULES_FOLDER/engineering/qa/eng.qa.cypress-standards-rules.md` para convenções do projeto.
 >
 > **Testes unitários**: linguagem/framework nativo do projeto (TypeScript/Jest, Python/pytest, etc.)
-> O `eng-qa-testsprite` cobre E2E via Stagehand (linguagem natural) — complementa, não substitui Cypress.
+> A especialização de E2E registrada em `QA_SPECIALIZATIONS` (via a base `eng-qa`) complementa, não substitui Cypress.
+
+---
+
+## Cypress E2E — Domínio e Debugging
+
+> 🔒 **Fonte de verdade de convenções**: `$RULES_FOLDER/engineering/qa/eng.qa.cypress-standards-rules.md`
+> Sempre ler antes de sugerir padrões ou gerar código. Para **gerar** uma spec nova, use a especialização de Cypress registrada em `QA_SPECIALIZATIONS` (via a base `eng-qa`); esta seção cobre o julgamento por trás de revisar, debugar e manter specs existentes.
+
+### Domínios de Expertise
+
+#### Page Objects
+- Estrutura fluent (retorno `this`)
+- Organização por domínio vs. por página
+- Herança e composição entre Page Objects
+- Quando criar vs. quando estender um existente
+
+#### Custom Commands
+- Tipagem com TypeScript (`Cypress.Commands.add`)
+- Declaração em `support/index.d.ts`
+- Commands de autenticação via `cy.request` (não via UI)
+- Commands de setup de estado (seed de dados, limpeza)
+
+#### Fixtures e Intercepts
+- Estrutura de pastas de fixtures por domínio
+- Tipagem de fixtures com tipos do projeto (`cy.fixture<T>`)
+- Padrões de `cy.intercept` para REST e GraphQL
+- Gestão de aliases e `cy.wait`
+- Estratégia de intercept para diferentes cenários (sucesso, erro, timeout)
+
+#### Viewport e Responsividade
+- `cy.viewport()` para testes multi-device
+- Breakpoints a cobrir conforme o projeto
+- Configuração em `cypress.config.ts`
+
+#### Configuração e CI
+- `cypress.config.ts` — baseUrl, env, retries, video
+- Estratégia de retries para flakiness (retry ≠ resolver o problema)
+- Paralelização com Cypress Cloud ou via CI nativo
+- Variáveis de ambiente seguras (`Cypress.env()` vs. hardcode)
+- Artefatos de CI: screenshots, vídeos, relatórios
+
+### Debugging de Testes Flaky
+
+Causas comuns e soluções:
+
+| Causa | Sintoma | Solução |
+|-------|---------|---------|
+| Race condition | Teste falha 1 em 5 vezes | Usar `cy.wait('@alias')` em vez de `cy.wait(ms)` |
+| Estado compartilhado | Teste passa isolado, falha em suite | `beforeEach` garante estado limpo |
+| Animação/transição | Clique em elemento não dispara | `.should('be.visible')` antes de `.click()` |
+| Dados dinâmicos | Assertion em texto que muda | Usar `contain` em vez de `eq`, ou mockar dado |
+| API real | Falha intermitente por timeout | Interceptar sempre — nunca depender de API real |
+| Seletor frágil | Falha após deploy de UI | Migrar para `data-testid` |
+
+### Para Debugging de Spec Cypress
+
+1. Perguntar: o teste falha sempre ou às vezes? (determina se é flaky ou quebrado)
+2. Pedir o erro e o trecho de código relevante
+3. Identificar a causa raiz antes de sugerir solução
+4. Nunca recomendar aumentar retry como solução definitiva
+
+### Para Revisão de Spec Cypress
+
+Ler a spec fornecida e verificar:
+- Seletores: algum usando classe/id? → migrar para `data-testid`
+- Intercepts: alguma API não interceptada? → adicionar
+- Dependência entre testes: algum `it` depende de outro? → corrigir
+- `cy.wait(ms)` hardcoded? → substituir por alias
+- Page Object ausente? → criar ou indicar onde adicionar
+
+### Regras Específicas de Cypress
+
+**Nunca**
+- Sugerir `cy.wait({número})` como solução — identificar a causa real da espera
+- Aceitar seletores por classe CSS em specs novas
+- Recomendar retry como fix de flakiness — é um paliativo, não solução
+- Ignorar tipagem TypeScript — fixtures, commands e Page Objects devem ser tipados
+
+**Sempre**
+- Ler `eng.qa.cypress-standards-rules.md` antes de qualquer sugestão de padrão
+- Justificar por que uma prática é ruim antes de sugerir a alternativa
+- Verificar se já existe Page Object/command para o domínio antes de criar novo
+- Considerar manutenibilidade: um teste bom é um teste que não falha sem razão
 
 ---
 
@@ -285,13 +373,9 @@ pytest test_filename.py -v
 
 ---
 
-## Validação com TestSprite (Opcional)
-
-Após escrever os testes, sugira executar o skill **eng-qa-testsprite** para validação automatizada E2E:
+## Validação Automatizada E2E (Opcional)
 
-```bash
-/eng-qa-testsprite diff
-```
+Após escrever os testes, se houver uma especialização de execução automatizada registrada em `QA_SPECIALIZATIONS`, sugira usá-la (via a base `eng-qa`) para validação E2E do diff.
 
 Isso complementa os testes unitários com:
 - Testes E2E (frontend) ou API (backend)

package/agents/product/prod.discovery-interviewer.md

@@ -70,10 +70,29 @@ Não use quando já existe uma spec (use `/prod.spec.clarify`) ou quando o escop
 - Uma **lacuna crítica nunca** resulta em `proceed`: o veredito é `investigate_more`
 - Quando a viabilidade técnica depende de bibliotecas, APIs ou serviços, consulte a documentação atual (por exemplo via Context7) em vez de responder de memória
 
-## Apoio de skills (apoio, nunca a fonte da decisão)
+## Skills Disponíveis
 
-- **Sempre:** busca em `$PROD_DOCS`; `jarvis-docs-central` quando `CENTRAL_DOCS_REPO` estiver configurado; `jarvis-context-detect` para calibrar a profundidade da entrevista
-- **Só com a confirmação do usuário:** `eng-backend-arch-c4` (arquitetura atual) e `eng-security-cybersecurity` (quando a ideia envolve autenticação, dados pessoais ou fluxo financeiro). São skills de engenharia: pergunte antes de consultá-las, e o que retornarem entra no discovery como **suposição a validar**, não como fato
+As skills são apoio, nunca a fonte da decisão. A busca em `$PROD_DOCS` não é uma skill: é feita sempre, antes de perguntar.
+
+### jarvis-docs-central
+Para buscar documentação do produto no repositório central, quando `CENTRAL_DOCS_REPO` estiver configurado:
+- Arquivo: `$IDE/skills/jarvis-docs-central/SKILL.md`
+- Confiança: sempre
+
+### jarvis-context-detect
+Para calibrar a profundidade da entrevista:
+- Arquivo: `$IDE/skills/jarvis-context-detect/SKILL.md`
+- Confiança: sempre
+
+### eng-backend-arch-c4
+Para consultar a arquitetura atual:
+- Arquivo: `$IDE/skills/eng-backend-arch-c4/SKILL.md`
+- Confiança: só com a confirmação do usuário (skill de engenharia: pergunte antes de consultá-la; o que ela retornar entra no discovery como **suposição a validar**, não como fato)
+
+### eng-platform
+Para quando a ideia envolve infraestrutura, dados pessoais ou fluxo financeiro com risco de segurança/privacidade:
+- Arquivo: `$IDE/skills/eng-platform/SKILL.md` (temas 9 e 13)
+- Confiança: só com a confirmação do usuário (skill de engenharia: pergunte antes de consultá-la; o que ela retornar entra no discovery como **suposição a validar**, não como fato)
 
 ## Restrições
 

package/agents/product/prod.pm-checker.md

@@ -50,3 +50,7 @@ Você deve fornecer sua resposta exatamente no seguinte formato:
 
 Regras Importantes
 Não faça nenhuma alteração no código ou nos requisitos, a menos que o usuário solicite explicitamente. Seu papel é avaliar e reportar, não corrigir.
+
+## Skills Disponíveis
+
+Nenhuma — agente autocontido, não depende de skill

package/bin/README.md

@@ -0,0 +1,142 @@
+# bin/ — CLI `jarvis`
+
+Fonte do binário `jarvis` (instalado via `npm install -g jarvis-ai-framework`, entrypoint declarado em `package.json#bin`). Este README documenta a arquitetura para quem for adicionar, remover ou alterar um comando.
+
+## Estrutura
+
+```
+bin/
+├── jarvis.js                  # Entrypoint (shebang). ~10 linhas, não cresce.
+├── postinstall.js             # Roda no `npm install` (sincroniza assets se já havia .{ide}/ no cwd)
+├── commands/                  # Um arquivo por comando. Lógica pura, zero commander.
+│   ├── init.js, list.js, info.js, whoami.js, ...
+│   ├── docs-sync.js, docs-publish.js
+│   └── qa-signoff.js, install-rtk.js, tokens.js, map.js
+└── lib/
+    ├── cli/
+    │   ├── program.js         # Único lugar que monta o commander — ver "Arquitetura"
+    │   └── shared-options.js  # .option() repetidos entre comandos (--ide, --quiet, etc.)
+    ├── vcs/                   # Adapters de Git host (GitLab/GitHub/Bitbucket)
+    │   ├── api.js             # Lógica HTTP real (createIssue, createMergeRequest, fetchRawFile)
+    │   ├── create-merge.js, create-issue.js, fetch-raw.js   # função exportada + CLI direto (ver abaixo)
+    ├── tasks/
+    │   └── comment.js         # Adapter de task manager (jira/linear/github/asana) — mesmo padrão
+    ├── config/                # ide-config.js (fonte de verdade de IDEs), constants.js
+    ├── core/                  # scanner.js, sync-engine.js, profile-filter.js, token-report.js
+    ├── docs/                  # central-docs: fetch/publish + validação de frontmatter
+    │   ├── validate-frontmatter.js  # Valida/extrai frontmatter de PRD/FRD/ARD/RFC
+    │   ├── redis-cache.js      # Cache best-effort via `redis-cli` (get/setex/del)
+    │   ├── fetch-file.js       # fetchFile() — usado por `docs sync`/`docs fetch` e por publish-file.js
+    │   └── publish-file.js     # publishFile() — usado por `docs publish`
+    ├── utils/                 # logger.js, ui.js, paths.js, frontmatter.js, git-parser.js, npmrc-parser.js
+    ├── flow-map/              # `jarvis map` — grafo de chamadas entre workflows/skills/agents
+    ├── auth/                  # session.js (auth.json legado, hoje só `jarvis logout` o lê)
+    └── env-loader.js          # Resolve e lê o ENV.md ($IDE/ENV.md)
+```
+
+## Arquitetura: 3 camadas, cada uma com uma responsabilidade
+
+```
+bin/jarvis.js              →  entrypoint: cria o program e faz parseAsync(argv)
+  ↓
+bin/lib/cli/program.js     →  ÚNICO lugar que sabe que existe commander
+  ↓ (chama, já com o `flags` remontado)
+bin/commands/*.js          →  lógica de negócio pura: async (flags) => {...}
+```
+
+**Por que separar assim?** `bin/commands/*.js` nunca importa `commander` nem sabe o que é um `Command`. Cada arquivo só recebe um objeto `flags` e faz o que precisa. Isso significa:
+- Testar a lógica de um comando não exige simular argv/commander — chama a função direto com um objeto.
+- Trocar de biblioteca de CLI um dia (se um dia fizer sentido) significa reescrever só `program.js`, não os 10 arquivos de comando.
+- `program.js` é o **mapa completo** do CLI: para saber todo comando que existe, todas as flags que cada um aceita, é o único arquivo que precisa abrir.
+
+## O adapter: commander → formato antigo de `flags`
+
+O commander entrega ao `.action()` as opções em **camelCase** (`--env-file` → `options.envFile`, `--max-age` → `options.maxAge`) e cada positional como seu próprio parâmetro. As funções em `bin/commands/*.js` foram escritas para um objeto `flags` no formato que o parser manual antigo produzia: chaves com hífen literal (`flags["env-file"]`) e um array `flags._` para positionals.
+
+Em vez de reescrever as 10 funções para o formato novo (risco maior, mexe em lógica que já funciona), `program.js` tem uma função `toLegacyFlags(options, extra)` que remonta o objeto no formato antigo antes de cada chamada:
+
+```js
+// bin/lib/cli/program.js
+const whoamiCmd = cmd(program, "whoami").description("...");
+withEnvOptions(withLogOptions(whoamiCmd)).action((options) => whoami(toLegacyFlags(options)));
+```
+
+`toLegacyFlags` remapeia só as duas chaves que mudam de formato (`envFile`→`"env-file"`, `maxAge`→`"max-age"`); todo o resto passa direto. O `extra` (segundo argumento) serve para injetar positionals como `_` ou flags sintéticas como `{ logout: true }` (usado por `jarvis logout`, que chama a mesma função de `whoami.js` com essa flag).
+
+**Ao adicionar uma opção nova que usa hífen** (ex: `--body-file`), decida: se a função de `bin/commands/*.js` vai ler `flags["body-file"]` (formato antigo) ou se você vai atualizá-la para ler `options.bodyFile` direto. Os 4 comandos novos (`vcs create-merge`, `vcs create-issue`, etc.) já usam o segundo caminho — passam o objeto de opções do commander quase direto, sem o adapter — porque não têm lógica legada para preservar.
+
+## O helper `cmd()` — por que todo comando passa por ele
+
+```js
+function cmd(parent, name) {
+  return parent.command(name).allowUnknownOption().allowExcessArguments();
+}
+```
+
+O parser manual antigo nunca validava nada: qualquer `--flag` era aceito e ignorado silenciosamente se o comando não o lesse. O commander, por padrão, dá erro em flag não declarada e em positional excedente. `allowUnknownOption()`/`allowExcessArguments()` replicam a permissividade antiga — mas **o commander não propaga essas duas configs do comando pai para os subcomandos**: setar só no `program` raiz não é suficiente (testado e confirmado durante a implementação). Por isso `cmd()` existe e **todo** comando — incluindo os aninhados (`docs sync`, `vcs create-merge`) — é criado com ele, nunca com `.command()` direto.
+
+## Argumentos: `[opcional]`, não `<obrigatório>` — de propósito
+
+Note que `info`, `vcs fetch-raw` e `tasks comment` declaram seus positionals como **opcionais** (`[target]`, `[file-path]`) mesmo sendo, na prática, obrigatórios para o comando funcionar. Isso é deliberado: se o commander validar "argumento obrigatório ausente" sozinho, ele intercepta **antes** da função rodar — e cada uma dessas funções já tem sua própria validação com mensagem de uso customizada e mais específica (`info.js`: `"❌ Uso incorreto\nUso: jarvis info <type/name>\nExemplo: ..."`). Deixar o positional opcional no commander e a validação dentro da função preserva essa mensagem.
+
+**A mesma regra vale para `--flag` que já tem validação própria.** Nenhum comando aqui usa `.requiredOption()` ou `.choices()` do commander, mesmo quando faria sentido à primeira vista (ex: `--tipo` em `docs publish` só aceita `prd|frd|ard|rfc|swagger|qa-report`). `docsPublish.js` já valida isso e mostra um bloco de exemplos de uso bem mais rico que o que o commander mostraria. Usar `.choices()` ali faria o commander interceptar o valor errado com uma mensagem genérica, perdendo esse texto. **Ao adicionar uma opção nova**: se a função já vai validar o valor por dentro, deixe o commander permissivo (`.option()` simples) e confie na validação interna. Se não há validação nenhuma hoje, `.choices()`/`.argParser()` são bons lugares para adicionar uma — não há essa perda a proteger.
+
+## `program.command()` vs `program.addCommand()`
+
+Este código usa `.command(nome)` (que cria e já anexa o subcomando) em todo lugar — não `.addCommand(instanciaDeCommand)`. São equivalentes; `.addCommand()` só compensa quando o `Command` é montado em outro módulo e precisa ser importado antes de anexar. Como tudo mora em `program.js`, não há motivo para o nível extra de indireção.
+
+## Os 4 "scripts standalone" (`vcs/*.js`, `tasks/comment.js`): dupla forma
+
+`create-merge.js`, `create-issue.js`, `fetch-raw.js` e `comment.js` são chamados de duas formas:
+
+1. **Como subcomando do CLI**: `jarvis vcs create-merge --source ... --target ...` (via `program.js`)
+2. **Direto, por skills/workflows que ainda shell-am pra eles**: `node bin/lib/vcs/create-merge.js --source ...`
+
+Cada um dos 4 arquivos segue o mesmo padrão: exporta uma função (`runCreateMerge`, `runCreateIssue`, `runFetchRaw`, `runComment`) com a lógica, e termina com um guard que só lê `process.argv` quando o arquivo é executado diretamente:
+
+```js
+// Compatibilidade: continua funcionando como `node bin/lib/vcs/create-merge.js --source ...`
+if (fileURLToPath(import.meta.url) === process.argv[1]) {
+  await runCreateMerge({ source: arg("source"), ... });
+}
+```
+
+**Ao editar um desses 4 arquivos**: a lógica de negócio fica dentro da função exportada. O bloco de `arg()`/guard no final é só para quem ainda invoca via `node bin/lib/.../arquivo.js` direto (uso legado — todo caller novo deve preferir o subcomando `jarvis`). Não remova o guard sem primeiro confirmar que nenhuma skill/workflow ainda referencia o path direto (`grep -rn "bin/lib/vcs\|bin/lib/tasks/comment" --include="*.md" .`).
+
+## Como adicionar um comando novo
+
+1. Criar `bin/commands/meu-comando.js` exportando `export async function meuComando(flags) { ... }` — igual aos outros, sem importar `commander`.
+2. Em `bin/lib/cli/program.js`:
+   - Importar a função no topo.
+   - Registrar com `cmd(program, "meu-comando")` (ou `cmd(parentExistente, "nome")` se for subcomando de um grupo como `docs`/`vcs`/`tasks`).
+   - Declarar as opções/positionals com `.option()`/`.argument()`. Usar `withEnvOptions()`/`withLogOptions()` de `shared-options.js` se o comando precisar de `--ide`/`--env-file` ou `--quiet`/`--verbose`/`--silent`.
+   - No `.action()`, chamar `toLegacyFlags(options, extra)` se a função usa o formato antigo de flags, ou passar `options` quase direto se for um comando novo sem lógica legada (ver os 4 de `vcs`/`tasks` como exemplo).
+3. Rodar manualmente o comando novo e **todos os outros** (não há suíte automatizada de CLI end-to-end — só `test/comandos-docs.test.js`, que valida a documentação dos workflows/skills, não o comportamento do CLI em si). Checklist mínimo: `--help` do comando novo, caminho feliz, caminho de erro (flag/argumento faltando).
+4. `npm run lint && npm run test:comandos && npm run test:filtro` antes de comitar.
+
+## Variáveis de ambiente lidas diretamente (fora do ENV.md)
+
+`bin/lib/tasks/comment.js` e `bin/lib/vcs/*.js` leem `process.env` direto (`TASK_MANAGER`, `TOKEN_TASK_MANAGER`, `CENTRAL_DOCS_REPO`, `VERSION_CONTROL`, etc.) — não passam pelo `env-loader.js`/ENV.md. Isso é intencional: esses adapters são chamados por skills/workflows que já exportam essas variáveis do `ENV.md` para o processo (`set -a; eval "$(grep ... $IDE/ENV.md)"; set +a`) antes de invocar o comando. Se um comando novo precisar ler o `ENV.md` diretamente, use `env-loader.js#resolveEnvPath`/`loadEnv` (ver `whoami.js`, `tokens.js`, `qa-signoff.js` como exemplo) em vez de `process.env`.
+
+## Testes
+
+- `npm run test:comandos` — valida que toda referência a comando/skill nos workflows e skills existe de fato (não testa o CLI em runtime).
+- `npm run test:filtro` — testes unitários de `profile-filter.js`, `token-report.js`, `flow-map`, `env-loader.js`, `sync-engine.js` e `vcs/api.js`.
+- Não há teste automatizado de ponta a ponta do CLI (`jarvis <comando>` real) — a camada de dispatch (`program.js`, `bin/commands/*.js`) não é cobrida pelos testes unitários. Qualquer mudança ali precisa de validação manual dos comandos afetados.
+
+### Como testar código que lê `fs`/rede sem mockar módulo
+
+Os 3 arquivos mais críticos sem cobertura até pouco tempo atrás (`env-loader.js`, `sync-engine.js`, `vcs/api.js`) tocam filesystem real ou rede real — nenhum foi refatorado para isso, cada um usou o hook que já existia:
+
+- **`env-loader.js`** (e `flow-map.test.js`, mais antigo): `mkdtempSync(join(tmpdir(), "jarvis-..."))` monta um workspace fake com `.{ide}/ENV.md`, roda a função contra ele, `rmSync` no `finally`.
+- **`sync-engine.js`**: `getFrameworkRoot()` (`utils/paths.js`) já tem um escape hatch — `process.env.JARVIS_ROOT`, se definido e existir, vence sobre o framework real. O teste aponta `JARVIS_ROOT` para um fixture mínimo (`agents/`, `skills/`, etc. com 1 arquivo cada) em vez de sincronizar o framework inteiro.
+- **`vcs/api.js`**: usa `mock.method(globalThis, "fetch", ...)` do `node:test` pra controlar a resposta por vendor, sem mockar o módulo nem tocar rede real. **Atenção**: toda função de rede chama `getVcsToken()` antes do fetch — fixe `GITLAB_TOKEN`/`GITHUB_TOKEN`/`BITBUCKET_TOKEN` via env var no teste (ver `withEnv` em `vcs-api.test.js`), senão o resultado depende do que a máquina que roda o teste tiver em `.npmrc`/`gh auth`.
+- **`docs/fetch-file.js`/`docs/publish-file.js`**: mesmo mock de `fetch`. `redis-cli` (chamado por `docs/redis-cache.js`) **não dá pra mockar** — é um módulo nativo (`node:child_process`) não configurável, `mock.method` lança `TypeError: Cannot redefine property`. Como pode haver um `redis-cli` de verdade instalado (com ou sem servidor acessível) na máquina que roda o teste, cada teste usa uma chave de cache única (`docs:${randomUUID()}...`) em vez de mockar o cache — garante cache-miss determinístico sem depender do estado de nenhum Redis real.
+
+**Armadilha com `async`**: o helper `withEnv(vars, fn)` (repetido nos 3 arquivos acima) precisa de `return **await** fn()`, não `return fn()`, dentro do `try`. Sem o `await`, o `finally` que restaura a env var roda assim que `fn()` retorna uma Promise pendente — ou seja, **antes** da função terminar. Isso só não quebra quando a leitura da env var acontece antes do primeiro `await` de `fn` (ex: `fetchRawFile` lê o token antes do seu próprio `fetch`); quebra silenciosamente em qualquer função com mais de um `await` no meio do caminho (ex: `publishFile`, que busca o `index.md` antes de chegar no commit, que é onde o token é lido).
+
+Ao escrever um teste novo para um arquivo que toca `fs`/rede, prefira um desses padrões a mockar o módulo inteiro ou refatorar pra injeção de dependência — nenhum dos arquivos acima precisou mudar uma linha de lógica de produção para ganhar teste.
+
+## Lint e formatação
+
+`eslint.config.js` (raiz) + `.prettierrc.json` cobrem `bin/` e `test/`. `npm run lint` / `npm run format` — ver `package.json#scripts`.

package/bin/commands/docs-publish.js

@@ -1,18 +1,11 @@
-import { loadEnv, resolveEnvPath } from '../lib/env-loader.js'
-import { execSync } from 'node:child_process'
-import { promisify } from 'node:util'
-import { exec } from 'node:child_process'
-import { existsSync } from 'node:fs'
-import { join, dirname } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const execAsync = promisify(exec)
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
+import { loadEnv, resolveEnvPath } from "../lib/env-loader.js";
+import { existsSync } from "node:fs";
+import { publishFile } from "../lib/docs/publish-file.js";
+import { logger, configureFromFlags } from "../lib/utils/logger.js";
 
 /**
  * Publica documento no central-docs via GitLab API (branch + MR)
- * 
+ *
  * @param {Object} flags - Flags do comando
  * @param {string} flags.file - Caminho do arquivo local
  * @param {string} flags.tipo - Tipo do documento (prd|frd|ard|rfc)
@@ -22,163 +15,134 @@ const __dirname = dirname(__filename)
  * @param {string} flags.envFile - Path customizado do ENV.md
  */
 export async function docsPublish(flags = {}) {
-  const { file, tipo, feature, squad: squadOverride, workspace: workspaceOverride } = flags
-  
+  configureFromFlags(flags);
+
+  const { file, tipo, feature, squad: squadOverride, workspace: workspaceOverride } = flags;
+
   // Validar parâmetros obrigatórios
   if (!file || !tipo || !feature) {
-    console.error('❌ Parâmetros obrigatórios faltando\n')
-    console.error('Uso: jarvis docs publish --file <path> --tipo <prd|frd|ard|rfc|swagger|qa-report> --feature <slug> [--squad <squad>] [--workspace <workspace>]\n')
-    console.error('Exemplo:')
-    console.error('  jarvis docs publish \\')
-    console.error('    --file ./docs/engineering/ard-api-wallet.md \\')
-    console.error('    --tipo ard \\')
-    console.error('    --feature api-wallet-auth-jwt')
-    console.error('')
-    console.error('  # Publicar Swagger/OpenAPI:')
-    console.error('  jarvis docs publish \\')
-    console.error('    --file ./docs/engineering/swagger/api-wallet.yaml \\')
-    console.error('    --tipo swagger \\')
-    console.error('    --feature api-wallet')
-    console.error('')
-    console.error('  # Com override de squad/workspace:')
-    console.error('  jarvis docs publish \\')
-    console.error('    --file ./docs/engineering/ard-api-wallet.md \\')
-    console.error('    --tipo ard \\')
-    console.error('    --feature api-wallet-auth-jwt \\')
-    console.error('    --squad squad-driver \\')
-    console.error('    --workspace meu-workspace')
-    process.exit(1)
+    logger.error("❌ Parâmetros obrigatórios faltando\n");
+    logger.error(
+      "Uso: jarvis docs publish --file <path> --tipo <prd|frd|ard|rfc|swagger|qa-report> --feature <slug> [--squad <squad>] [--workspace <workspace>]\n"
+    );
+    logger.error("Exemplo:");
+    logger.error("  jarvis docs publish \\");
+    logger.error("    --file ./docs/engineering/ard-api-wallet.md \\");
+    logger.error("    --tipo ard \\");
+    logger.error("    --feature api-wallet-auth-jwt");
+    logger.error("");
+    logger.error("  # Publicar Swagger/OpenAPI:");
+    logger.error("  jarvis docs publish \\");
+    logger.error("    --file ./docs/engineering/swagger/api-wallet.yaml \\");
+    logger.error("    --tipo swagger \\");
+    logger.error("    --feature api-wallet");
+    logger.error("");
+    logger.error("  # Com override de squad/workspace:");
+    logger.error("  jarvis docs publish \\");
+    logger.error("    --file ./docs/engineering/ard-api-wallet.md \\");
+    logger.error("    --tipo ard \\");
+    logger.error("    --feature api-wallet-auth-jwt \\");
+    logger.error("    --squad core \\");
+    logger.error("    --workspace meu-workspace");
+    process.exit(1);
   }
-  
+
   // Validar tipo
-  const validTypes = ['prd', 'frd', 'ard', 'rfc', 'swagger', 'qa-report']
+  const validTypes = ["prd", "frd", "ard", "rfc", "swagger", "qa-report"];
   if (!validTypes.includes(tipo)) {
-    console.error(`❌ Tipo inválido: ${tipo}`)
-    console.error(`Tipos válidos: ${validTypes.join(', ')}`)
-    process.exit(1)
+    logger.error(`❌ Tipo inválido: ${tipo}`);
+    logger.error(`Tipos válidos: ${validTypes.join(", ")}`);
+    process.exit(1);
   }
-  
+
   // Validar se arquivo existe
   if (!existsSync(file)) {
-    console.error(`❌ Arquivo não encontrado: ${file}`)
-    process.exit(1)
+    logger.error(`❌ Arquivo não encontrado: ${file}`);
+    process.exit(1);
   }
-  
-  const cwd = process.cwd()
-  
+
+  const cwd = process.cwd();
+
   // Resolver path do ENV.md (suporta --ide e --env-file)
-  let envPath
+  let envPath;
   try {
-    const resolved = resolveEnvPath(cwd, flags)
-    envPath = resolved.path
+    const resolved = resolveEnvPath(cwd, flags);
+    envPath = resolved.path;
   } catch (error) {
-    console.error('❌ Erro ao resolver ENV.md:', error.message)
-    process.exit(1)
+    logger.error("❌ Erro ao resolver ENV.md:", error.message);
+    process.exit(1);
   }
-  
+
   // Carregar ENV.md
-  let env
+  let env;
   try {
-    env = loadEnv(cwd, envPath)
+    env = loadEnv(cwd, envPath);
   } catch (error) {
-    console.error('❌ Erro ao carregar ENV.md:', error.message)
-    process.exit(1)
+    logger.error("❌ Erro ao carregar ENV.md:", error.message);
+    process.exit(1);
   }
-  
+
   // Verificar se central-docs está configurado
   if (!env.CENTRAL_DOCS_REPO) {
-    console.error('❌ CENTRAL_DOCS_REPO não configurado no ENV.md')
-    console.error('\nConfigure a URL do repositório central:')
-    console.error('  CENTRAL_DOCS_REPO=https://gitlab.com/org/central-docs.git')
-    process.exit(1)
+    logger.error("❌ CENTRAL_DOCS_REPO não configurado no ENV.md");
+    logger.error("\nConfigure a URL do repositório central:");
+    logger.error("  CENTRAL_DOCS_REPO=https://gitlab.com/org/central-docs.git");
+    process.exit(1);
   }
-  
+
   // Usar override de squad/workspace se fornecido, senão usar do ENV.md
-  const squad = squadOverride || env.SQUAD
-  const workspace = workspaceOverride || env.WORKSPACE
-  
+  const squad = squadOverride || env.SQUAD;
+  const workspace = workspaceOverride || env.WORKSPACE;
+
   if (!squad || !workspace) {
-    console.error('❌ SQUAD ou WORKSPACE não definidos')
-    console.error('\nOpções:')
-    console.error('  1. Definir no ENV.md:')
-    console.error('     SQUAD=squad-driver')
-    console.error('     WORKSPACE=meu-workspace')
-    console.error('')
-    console.error('  2. Passar via flags:')
-    console.error('     --squad squad-driver --workspace meu-workspace')
-    process.exit(1)
-  }
-  
-  // Verificar se script publish-file.sh existe
-  // Usar path relativo ao módulo, não ao cwd do usuário
-  const publishScript = join(__dirname, '../lib/docs/publish-file.sh')
-  if (!existsSync(publishScript)) {
-    console.error('❌ Script não encontrado:', publishScript)
-    process.exit(1)
+    logger.error("❌ SQUAD ou WORKSPACE não definidos");
+    logger.error("\nOpções:");
+    logger.error("  1. Definir no ENV.md:");
+    logger.error("     SQUAD=core");
+    logger.error("     WORKSPACE=meu-workspace");
+    logger.error("");
+    logger.error("  2. Passar via flags:");
+    logger.error("     --squad core --workspace meu-workspace");
+    process.exit(1);
   }
-  
-  console.log(`📤 Publicando ${tipo.toUpperCase()} ${feature}...\n`)
-  
+
+  logger.info(`📤 Publicando ${tipo.toUpperCase()} ${feature}...\n`);
+
   try {
-    // Exportar variáveis de ambiente para o script bash
-    const envVars = {
-      ...process.env,
-      CENTRAL_DOCS_REPO: env.CENTRAL_DOCS_REPO,
-      CENTRAL_DOCS_TARGET_BRANCH: env.CENTRAL_DOCS_TARGET_BRANCH || 'dev',
-      CENTRAL_DOCS_CACHE_TTL: env.CENTRAL_DOCS_CACHE_TTL || '3600',
-      SQUAD_OVERRIDE: squad,
-      WORKSPACE_OVERRIDE: workspace
-    }
-    
-    const { stdout, stderr } = await execAsync(
-      `bash "${publishScript}" "${file}" "${tipo}" "${feature}"`,
-      { 
-        env: envVars,
-        maxBuffer: 10 * 1024 * 1024 // 10MB buffer para output grande
-      }
-    )
-    
-    // Exibir output do script
-    if (stdout) {
-      console.log(stdout)
-    }
-    
-    if (stderr) {
-      console.warn('⚠️  Avisos:', stderr)
-    }
-    
+    await publishFile({
+      localFile: file,
+      tipo,
+      feature,
+      squad,
+      workspace,
+      repo: env.CENTRAL_DOCS_REPO,
+      targetBranch: env.CENTRAL_DOCS_TARGET_BRANCH || "dev",
+      cacheTtl: env.CENTRAL_DOCS_CACHE_TTL || "3600",
+    });
   } catch (error) {
-    console.error('\n❌ Erro ao publicar documento\n')
-    
-    // Exibir output de erro do script
-    if (error.stdout) {
-      console.log(error.stdout)
-    }
-    
-    if (error.stderr) {
-      console.error(error.stderr)
-    }
-    
+    logger.error("\n❌ Erro ao publicar documento\n");
+    logger.error(error.message);
+
     // Dicas de troubleshooting
-    console.error('\n💡 Troubleshooting:\n')
-    
-    if (error.message.includes('Token GitLab')) {
-      console.error('1. Configure o token GitLab no .npmrc:')
-      console.error('   //gitlab.com/api/v4/packages/npm/:_authToken=seu-token\n')
+    logger.error("\n💡 Troubleshooting:\n");
+
+    if (error.message.includes("Token GitLab")) {
+      logger.error("1. Configure o token GitLab no .npmrc:");
+      logger.error("   //gitlab.com/api/v4/packages/npm/:_authToken=seu-token\n");
     }
-    
-    if (error.message.includes('Campos obrigatórios')) {
-      console.error('2. Verifique o frontmatter do documento:')
-      console.error(`   Tipo ${tipo} requer campos específicos no YAML\n`)
+
+    if (error.message.includes("Campos obrigatórios")) {
+      logger.error("2. Verifique o frontmatter do documento:");
+      logger.error(`   Tipo ${tipo} requer campos específicos no YAML\n`);
     }
-    
-    if (error.message.includes('401') || error.message.includes('403')) {
-      console.error('4. Verifique permissões no GitLab:')
-      console.error('   Token precisa de scopes: api, read_api, write_repository\n')
+
+    if (error.message.includes("401") || error.message.includes("403")) {
+      logger.error("4. Verifique permissões no GitLab:");
+      logger.error("   Token precisa de scopes: api, read_api, write_repository\n");
     }
-    
-    console.error('Para mais detalhes, execute com --verbose')
-    
-    process.exit(1)
+
+    logger.error("Para mais detalhes, execute com --verbose");
+
+    process.exit(1);
   }
 }