diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index fa6222e2..bf5a15f7 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -53,6 +53,7 @@ Title convention — Conventional Commits, in English: - [ ] Tests pass locally - [ ] Lint clean (`npm run lint`) - [ ] Typecheck clean (`npm run typecheck`) +- [ ] Cookbooks synchronized (`npm run docs:check-cookbook`) - [ ] Secret scan clean (`npm run secret-scan`) - [ ] No new dependencies without justification - [ ] No secrets or credentials committed diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9b37f912..50973d39 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -359,3 +359,5 @@ jobs: run: npm run docs:lint - name: Changelog structure run: npm run docs:check-changelog + - name: Cookbook parity + run: npm run docs:check-cookbook diff --git a/AGENTS.global.md b/AGENTS.global.md index 36db47b2..d9b46837 100644 --- a/AGENTS.global.md +++ b/AGENTS.global.md @@ -1,7 +1,7 @@ - + # Pantheon Agent System — OpenCode diff --git a/AGENTS.md b/AGENTS.md index 28f250f9..3827c1cc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,7 @@ - + # Pantheon — Repository Setup @@ -32,5 +32,5 @@ Validate global installation AS A REAL USER in the sandbox `~/pantheon-sandbox/` - Stronger gates (auth, security, data-integrity, coverage) are canonical in the global `Test Economy` section - Async/await on all I/O - Type hints on all functions -- PRs always update the README: document new features, behaviors, env vars, and commands before opening. +- PRs update README + Cookbooks: document features, env vars, commands (`npm run docs:check-cookbook`). diff --git a/docs/guides/cookbook.md b/docs/guides/cookbook.md index 611d35be..a7fb2abd 100644 --- a/docs/guides/cookbook.md +++ b/docs/guides/cookbook.md @@ -1,8 +1,26 @@ + # Pantheon Cookbook: Everyday Practical Recipes > 🇧🇷 **Versão em Português disponível:** [Leia em Português](../pt-BR/guides/cookbook.md) -This practical cookbook aggregates the most common everyday development workflows with Pantheon, showcasing exact prompts, tool dispatches, and which specialist to call for each scenario. +This practical cookbook gathers copy-paste recipes for everyday development in **Pantheon `v2.2.0` (`OpenCode 2.x` native)** — covering zero-init setup, the **14 specialist agents**, **30 native in-process tools**, **9 server commands**, and **5 interactive TUI surfaces**. + +--- + +## Recipe 0: Zero-Init Setup & Safe Updates (`OpenCode 2.x`) + +**Scenario:** Enable Pantheon across any project or git worktree without committing extra framework files to git. + +**Command:** +```bash +opencode plugin add pantheon-opencode@2.2.0 +# or update later: +opencode plugin update pantheon-opencode +``` + +**Why this works:** +- All **14 agents**, **9 server commands**, global instructions, and **30 native TypeScript tools** load directly in memory. +- Inside the TUI, run `/pantheon-updates` to check registry updates or clean stale npm plugin caches cleanly. --- @@ -16,165 +34,212 @@ This practical cookbook aggregates the most common everyday development workflow ``` **Workflow:** -1. `@zeus` analyzes scope and delegates planning to `@athena`. -2. `@athena` defines phases and acceptance criteria; trade-offs are presented via the native `question` dialog. -3. Upon approval, `@hermes` writes failing tests (RED) and implements until green (GREEN). -4. `@themis` runs linters, security scans, and confirms coverage. +1. `@zeus` analyzes scope, optionally runs `detect_stack`, and delegates planning to `@athena`. +2. `@athena` defines phases and acceptance criteria; ambiguities use OpenCode's native `question` dialog. +3. `@hermes` executes steps tracked in `pantheon_step_ledger` (including isolated `execute_step` sub-sessions when appropriate) — RED tests first, then GREEN implementation with post-edit LSP diagnostics (`tsc` / `pyright` / stdio / pooled TCP). +4. `@themis` runs linters, security scans, and emits a structured verdict via `pantheon_review_verdict`. --- -## Recipe 2: 1-Turn Express Hotfix (Bugs & Typos) +## Recipe 2: Express 1-Turn Fix (`@talos`) -**Scenario:** Fix a CSS styling bug, a typo, or a missing import that does not require architectural ceremony. +**Scenario:** Fix a CSS styling bug, a typo, or a missing import without planning ceremony. **Prompt:** ```text -@talos Update the login submit button background from blue to emerald green in login.css +@talos Update the login submit button background from blue to emerald green in login.css using hashline_edit ``` **Why use @talos?** -`@talos` is Pantheon's fast lane. It operates without subagents, skips Deepwork planning ceremonies, executes surgical single-turn edits, and finishes immediately. +`@talos` is Pantheon's fast lane: zero subagent overhead, surgical edits via `hashline_edit` (confined to the workspace root), and immediate verification. --- -## Recipe 3: Database Migrations & Query Optimization +## Recipe 3: Bugfix TDD with Mechanical `RED` Gate & Auto-Rollback -**Scenario:** Add a new table or column with proper indexing and foreign key constraints without N+1 query pitfalls. +**Scenario:** Fix a verified production regression without letting agents skip failure reproduction or leave a broken tree behind. **Prompt:** ```text -@demeter Create an Alembic migration adding the 'user_preferences' table with a foreign key to 'users' and an index on 'created_at'. +@zeus Fix the off-by-one tax rounding bug in src/billing/calc.ts. Enforce a failing reproduction test first before editing production code. ``` -**Why use @demeter?** -`@demeter` is Pantheon's persistence specialist. It enforces SQLAlchemy, Prisma, Alembic, and PostgreSQL best practices, ensuring referential integrity and optimized indexes. +**Workflow (`pantheon_step_ledger`):** +1. `@zeus` initializes a `bugfix` step (`init_step`) capturing a non-invasive `GIT_INDEX_FILE` `baselineTree` snapshot without touching `.git/index`. +2. `tool.execute.before` blocks edits (`edit`, `write`, `hashline_edit`, `ast_rewrite`) on production files by `@hermes` / `@talos` while allowing edits to test files. +3. Once a failing test is recorded via `record_reproduction` (`exitCode !== 0`), production edits unlock automatically. +4. If verification fails repeatedly and `ThemisReflexController` escalates, `pantheon_step_ledger` rolls back cleanly to `baselineTree` (`rollback_step` is also available manually). --- -## Recipe 4: Visual Refactoring from a Screenshot +## Recipe 4: Structural AST Search & Refactoring (`ast_search` / `ast_rewrite`) -**Scenario:** Rebuild or polish a frontend component to match a mockup. +**Scenario:** Rename or migrate a function call pattern safely across dozens of TypeScript/JavaScript files without matching string literals or comments. **Prompt:** -*(Paste screenshot with Ctrl+V / Cmd+V into chat)* ```text -@aphrodite Refactor this metrics card component to match the visual styling, spacing, and typography in the pasted screenshot. +@hermes Use ast_search to find all calls to legacyFetch($URL, $$$ARGS) across src/ and preview an ast_rewrite with dryRun=true before applying. ``` -**Workflow:** -1. Pantheon Vision processes the screenshot silently via `session.context`. -2. `@aphrodite` inspects colors, layout hierarchy, and typography, updating React and CSS components with WCAG AA compliance. +**Why use `ast_search` / `ast_rewrite`?** +- Ignores comments and strings automatically, supporting `$VAR` single-node and `$$$ARGS` variadic captures. +- Enforces strict workspace symlink confinement and post-write LSP + diff-scoped lint diagnostics (`[LSP-Diagnostics]`) in the exact same turn. --- -## Recipe 5: Safe Codebase Investigation (Read-Only) +## Recipe 5: Database Migrations & Query Optimization -**Scenario:** Understand complex logic across multiple files without risking unintended modifications. +**Scenario:** Add a new table or column with proper indexing and foreign key constraints without N+1 query pitfalls. **Prompt:** ```text -@apollo Search the repository and trace how authentication tokens are validated in incoming WebSocket connections. +@demeter Create an Alembic migration adding the 'user_preferences' table with a foreign key to 'users' and an index on 'created_at'. ``` -**Why use @apollo?** -`@apollo` is strictly read-only (`edit: deny`, `bash: deny`). It performs fast parallel exploration, returning structured findings with exact file paths and line ranges. +**Why use @demeter?** +`@demeter` enforces SQLAlchemy, Prisma, Alembic, and PostgreSQL best practices, referential integrity, and index coverage. --- -## Recipe 6: Pre-PR Quality & Security Audit +## Recipe 6: Visual Refactoring & Multimodal Diagnostics (`/pantheon-vision`) -**Scenario:** Review all changes on the current branch before opening a pull request. +**Scenario:** Rebuild or inspect UI components from a screenshot or verify multimodal vision status. **Prompt:** +*(Paste screenshot with Ctrl+V / Cmd+V into chat, or run `/pantheon-vision` to check vision configuration)* ```text -@themis Audit all changes on this branch against OWASP Top 10 security standards, run Biome and test suites, and generate a quality verdict. +@aphrodite Refactor this metrics card component to match the spacing, typography, and contrast in the pasted screenshot. ``` -**Why use @themis?** -`@themis` has read-only audit permissions (`edit: deny`). It never modifies code directly; it runs test suites, checks linting rules, and issues clear compliance verdicts (`PASS`, `PASS_WITH_NOTES`, `BLOCK`). +**Workflow:** +1. `/pantheon-vision` shows configured multimodal vision providers and gateway status. +2. Pantheon Vision extracts structured visual tokens once via `vision_describe` / `session.context`, avoiding repeated image bytes in prompts. +3. `@aphrodite` updates the UI components with WCAG AA contrast compliance. --- -## Recipe 7: AI Pipelines and RAG Tooling +## Recipe 7: Safe Read-Only Exploration (`@apollo`) -**Scenario:** Implement a semantic search service with vector embeddings. +**Scenario:** Trace authentication, data flows, or symbol callers across files with zero risk of edits. **Prompt:** ```text -@hephaestus Implement a vector search pipeline using LangChain and pgvector for document chunk retrieval. +@apollo Map where incoming WebSocket tokens are validated using code_index, code_query, and code_neighbors. ``` -**Why use @hephaestus?** -`@hephaestus` specializes in embeddings, vector stores, prompt chaining, and AI model integrations. +**Why use @apollo?** +`@apollo` is strictly read-only (`edit: deny`, `bash: deny`, `ast_rewrite: deny`). Combining `code_index`, `code_query`, and `code_neighbors` avoids broad recursive globs and auto-prunes deleted files. --- -## Recipe 8: Docker & CI/CD Pipelines +## Recipe 8: Security Audit & Typed Verdict Remediation (`/pantheon-audit` + `@themis`) -**Scenario:** Create a multi-stage Dockerfile and a GitHub Actions workflow. +**Scenario:** Audit branch changes before merging and auto-trigger fixes on blocker findings. -**Prompt:** +**Prompts:** ```text -@prometheus Create a multi-stage Dockerfile for our Node.js application and a GitHub Actions CI workflow to run tests on pull requests. +/pantheon-audit +``` +or directly: +```text +@themis Audit changes on this branch against OWASP Top 10, verify tests/lint, and record the final pantheon_review_verdict. ``` -**Why use @prometheus?** -`@prometheus` owns containerization, GitHub Actions, build automation, and infrastructure configurations. +**Workflow:** +- `/pantheon-audit` runs zero-token static heuristics followed by `@themis`'s 3-layer review. +- `@themis` calls `pantheon_review_verdict` with structured verdicts: `APPROVE`, `APPROVE_WITH_NOTES`, or `BLOCK`. +- When `BLOCK` is emitted, Pantheon automatically dispatches up to 2 remediation turns into the parent orchestration session with actionable findings. --- -## Recipe 9: Council Synthesis for Architecture Decisions (`/pantheon`) +## Recipe 9: AI Pipelines, Containers & CI/CD -**Scenario:** Arbitrate a technical trade-off across multiple architecture domains. +**Scenarios:** Build vector RAG retrieval pipelines or multi-stage container builds & GitHub Actions workflows. -**Prompt:** +**Prompts:** ```text -/pantheon Should we use Server-Sent Events (SSE) or WebSockets for live status updates in our dashboard? +@hephaestus Implement a vector search pipeline using embeddings and pgvector with batched ingestion. +``` +```text +@prometheus Create a multi-stage Dockerfile for this service and a GitHub Actions PR workflow. ``` - -**Why use /pantheon?** -Dispatches 2-3 specialists in parallel (`@athena` for architecture, `@hermes` for backend scalability, `@themis` for security and connection limits). Divergences are synthesized into a decisive recommendation with domain authority precedence. --- -## Recipe 10: Multi-Phase Project with Persistent Checkpoints (`/pantheon-deepwork`) +## Recipe 10: Council Arbitration & Strategic Deepwork (`/pantheon`, `/pantheon-deepwork`, `pantheon_worktree`) -**Scenario:** Refactor a core system subsystem across multiple sessions without losing context. +**Scenarios:** Arbitrate high-stakes design trade-offs or execute multi-phase refactors safely in isolated git worktrees. -**Prompt:** +**Council prompt:** ```text -/pantheon-deepwork Migrate user session management from server-side memory to encrypted JWT cookies with redis blacklist. +/pantheon Should we use Server-Sent Events (SSE) or WebSockets for live status updates in our dashboard? ``` -**Workflow:** -1. Progress is written to `.pantheon/deepwork//` (`plan.json`, `PLAN.md`, checkpoints). -2. Parallel tasks execute in isolated git worktrees (`.pantheon-worktrees/`). -3. Each phase boundary requires a PASS verdict from `@themis` before progressing. +**Deepwork + Worktree prompt:** +```text +/pantheon-deepwork Migrate session authentication to rotating refresh tokens using pantheon_worktree isolation and Deepwork checkpoints. +``` + +**How it runs:** +- Parallel tasks isolate cleanly inside `/.pantheon-worktrees//` via `pantheon_worktree` and `ctx.worktree.transform`. +- Linked git worktrees automatically share the primary repository's `.pantheon/` knowledge store (`PANTHEON_ISOLATE_WORKTREE_MEMORY=1` opts out). +- Plan artifacts save to `.pantheon/deepwork//PLAN.md` and remain clickable directly from the Home/Sidebar links. --- -## Recipe 11: Interactive Question Gate in Complex Planning +## Recipe 11: Persistent Memory, Focus & Cross-Repo Federation (`/pantheon-focus`, `/pantheon-consolidate`) -**Scenario:** Clarify architectural ambiguities and design trade-offs interactively before code generation starts. +**Scenario:** Keep goals sharp across compactions and search architectural decisions stored in peer repositories. -**Workflow:** -When `@athena` designs a system with multiple valid approaches, `@zeus` presents the choices via OpenCode's native `question` tool: -- The UI displays structured options with clear trade-offs. -- A marked `(Recommended)` choice highlights the best-practice path. -- The developer selects their preferred option, and execution proceeds automatically without textual back-and-forth. +**Commands & Tools:** +- **`/pantheon-focus`** — inspect or update durable session goals (`goal_create`, `goal_get`, `goal_update`, `goal_done`). +- **`/pantheon-consolidate`** — compact, deduplicate, and merge local `node:sqlite` FTS5 memory entries. +- **`memory_search` with federation** — set `PANTHEON_FEDERATED_REPOS` or `~/.pantheon/federation.json` so `memory_search(federated=true)` queries peer `.pantheon/memory/memory.db` stores strictly read-only. --- -## Recipe 12: Health Validation & Drift Detection (`doctor`) +## Recipe 12: Custom Stack Specialists, Model Overrides & Pruning (`/pantheon-forge`, `/pantheon-model`, `/pantheon-optimize`) -**Scenario:** Verify that local MCP servers, plugins, and configurations are synchronized and healthy. +**Scenario:** Tailor project agents to your exact stack (`Node`, `Python`, `Rust`, `Go`), tune per-agent models, or prune stale artifacts. -**Command:** -```bash -npx pantheon-opencode doctor -``` +**Commands:** +- **`/pantheon-forge`** — runs `detect_stack` (`package.json`, `pyproject.toml`, `requirements.txt`, `Cargo.toml`, `go.mod`) and scaffolds specialized agents into `.opencode/agents/` via `pantheon_agent_forge`. +- **`/pantheon-model`** — inspect or configure per-agent model overrides cleanly in `active-preset.json`. +- **`/pantheon-optimize`** — analyze and prune stale Deepwork artifacts, leftover worktrees, and context overhead. + +--- + +## Recipe 13: Real-Time Terminal Mission Control (`/pantheon-cockpit`, `/pantheon-artifacts`, `/pantheon-whats-new`) + +**Scenario:** Monitor active subagents, gates, Step-Ledger state, Mermaid plans, and release updates without leaving OpenCode. + +![Pantheon Mission Control Cockpit Flightdeck tab](../assets/tui/cockpit-flightdeck.png) + +- **`/pantheon-cockpit`** (or `/cockpit`) — opens the 3-tab Mission Control dashboard: + - `1 Overview`: token velocity, context meter, runtime health (`Native Tools (30)`), and topology map. + - `2 Swarm`: subagent concurrency Gantt timeline and per-agent cost breakdown. + - `3 Flightdeck`: `GATE` safety/guardrail matrix, `Step-Ledger` states, live cross-process event stream, and **`x` Export Replay Trace** to `.pantheon/reports/`. +- **`/pantheon-artifacts`** (or `/artifacts`) — browse project plans/reports and inspect `flowchart`, `sequenceDiagram`, and `stateDiagram` Mermaid diagrams rendered natively as Unicode terminal boxes. +- **`/pantheon-whats-new`** — review curated release highlights cleanly inside OpenCode. + +--- + +## Recipe 14: Configuration, Legacy Cache Cleanup & Health Checks (`/pantheon-settings`, `/pantheon-updates`, `doctor`) + +**Scenario:** Inspect active gates/autonomy presets, purge outdated plugin caches, or diagnose host integration issues. + +- **`/pantheon-settings`** — opens the interactive 10-tab configuration panel (`Gates`, `Decision`, `Preset`, `TUI`, `Autonomy`, `J1 Safety`, `Updates`, `Changelog`, `Doctor`, `About`). +- **`/pantheon-updates`** — opens directly on **Updates & Cleanup**, checking npm for newer Pantheon releases and removing stale coexisting `~/.cache/opencode/npm/pantheon-opencode*` caches. +- **CLI diagnostics:** + ```bash + npx pantheon-opencode doctor + ``` + +--- + +## Quick Reference: All Commands -**When to run:** -- After git branch switches or pulling remote updates. -- When upgrading Node.js or OpenCode. -- If an MCP tool reports connection failures or missing dependencies. +| Surface | Commands | +|---|---| +| **Server Commands** | `/pantheon`, `/pantheon-deepwork`, `/pantheon-audit`, `/pantheon-consolidate`, `/pantheon-focus`, `/pantheon-forge`, `/pantheon-model`, `/pantheon-optimize`, `/pantheon-vision` | +| **TUI Commands** | `/pantheon-cockpit`, `/pantheon-artifacts`, `/pantheon-settings`, `/pantheon-updates`, `/pantheon-whats-new` | diff --git a/docs/pt-BR/guides/cookbook.md b/docs/pt-BR/guides/cookbook.md index 38fd4977..a6cf41db 100644 --- a/docs/pt-BR/guides/cookbook.md +++ b/docs/pt-BR/guides/cookbook.md @@ -1,14 +1,32 @@ -# Livro de Receitas do Pantheon: Casos Práticos do Dia a Dia + +# Livro de Receitas do Pantheon: Fluxos Práticos do Dia a Dia > 🇺🇸 **English version available:** [Read in English](../../guides/cookbook.md) -Este livro de receitas reúne os fluxos de trabalho mais comuns no desenvolvimento diário com o Pantheon, apresentando os prompts exatos, ferramentas utilizadas e qual especialista acionar em cada cenário. +Este livro de receitas reúne fluxos práticos prontos para copiar e colar no **Pantheon `v2.2.0` (`OpenCode 2.x` nativo)** — cobrindo onboarding Zero-Init, os **14 agentes especialistas**, as **30 ferramentas TypeScript nativas**, os **9 comandos de servidor** e as **5 superfícies interativas de TUI**. + +--- + +## Receita 0: Setup Zero-Init e Atualização Segura (`OpenCode 2.x`) + +**Cenário:** Habilitar o Pantheon em qualquer projeto ou worktree Git sem sujar o repositório com arquivos copiados. + +**Comando:** +```bash +opencode plugin add pantheon-opencode@2.2.0 +# ou para atualizar uma instalação existente: +opencode plugin update pantheon-opencode +``` + +**Por que funciona melhor:** +- Todos os **14 agentes**, **9 comandos de servidor**, instruções globais e **30 ferramentas nativas** carregam direto em memória. +- Na TUI, use `/pantheon-updates` para verificar atualizações no npm e limpar caches obsoletos automaticamente. --- ## Receita 1: Funcionalidade Full-Stack com TDD e Portão de Qualidade -**Cenário:** Implementar uma nova funcionalidade de ponta a ponta (ex: endpoint de exportação de relatórios em CSV com validação de schema e testes). +**Cenário:** Implementar uma funcionalidade completa (ex.: endpoint de exportação CSV com validação de schema e testes). **Prompt:** ```text @@ -16,165 +34,212 @@ Este livro de receitas reúne os fluxos de trabalho mais comuns no desenvolvimen ``` **Fluxo de Execução:** -1. O `@zeus` analisa o escopo e delega o planejamento para a `@athena`. -2. A `@athena` estrutura as fases e critérios de aceite; dúvidas de design são apresentadas pela ferramenta interativa nativa `question`. -3. Após aprovação, o `@hermes` escreve testes que falham (RED) e implementa até passarem (GREEN). -4. A `@themis` roda linters, auditoria de segurança e valida a cobertura de testes antes da conclusão. +1. `@zeus` analisa o escopo, opcionalmente executa `detect_stack`, e delega o planejamento à `@athena`. +2. `@athena` estrutura fases e critérios de aceite; ambiguidades usam o diálogo nativo `question`. +3. `@hermes` executa as etapas rastreadas no `pantheon_step_ledger` (inclusive com sub-sessões isoladas via `execute_step` quando necessário) — testes RED primeiro, depois código GREEN com diagnósticos LSP pós-edição (`tsc` / `pyright` / stdio / TCP pool). +4. `@themis` executa linters, auditoria de segurança e emite o parecer estruturado via `pantheon_review_verdict`. --- -## Receita 2: Hotfix em 1 Turno (Bugs e Correções Pontuais) +## Receita 2: Correção Expressa em 1 Turno (`@talos`) -**Cenário:** Corrigir um erro visual de CSS, um erro de digitação ou um import quebrado sem cerimônia de planejamento. +**Cenário:** Corrigir um estilo CSS, typo ou import ausente sem cerimônia de planejamento. **Prompt:** ```text -@talos Altere a cor de fundo do botão de login de azul para verde esmeralda no arquivo login.css +@talos Altere a cor de fundo do botão de login para verde esmeralda em login.css usando hashline_edit ``` -**Por que usar o @talos?** -O `@talos` é a faixa expressa do Pantheon. Ele opera sem subagentes, pula rituais de planejamento Deepwork, realiza edições cirúrgicas em um único turno e finaliza imediatamente. +**Por que usar `@talos`?** +`@talos` é a via rápida do Pantheon: zero sobrecarga de subagentes, edições cirúrgicas via `hashline_edit` (confinado à raiz do projeto) e verificação imediata. --- -## Receita 3: Migrações de Banco de Dados e Otimização de Consultas +## Receita 3: Bugfix TDD com Portão Mecânico `RED` e Rollback Atômico -**Cenário:** Criar uma nova tabela ou coluna com índices adequados e integridade referencial. +**Cenário:** Corrigir um bug confirmado em produção impedindo que o agente pule o teste de reprodução ou deixe o working tree sujo em caso de falha. **Prompt:** ```text -@demeter Crie uma migration Alembic adicionando a tabela 'user_preferences' com chave estrangeira para 'users' e índice em 'created_at'. +@zeus Corrija o bug de arredondamento de imposto em src/billing/calc.ts exigindo primeiro um teste de reprodução falhando antes de editar o código de produção. ``` -**Por que usar o @demeter?** -O `@demeter` é o especialista em persistência do Pantheon. Ele domina SQLAlchemy, Prisma, Alembic e PostgreSQL, prevenindo problemas clássicos de consultas N+1 e índices ausentes. +**Fluxo (`pantheon_step_ledger`):** +1. `@zeus` inicia um step `bugfix` (`init_step`), gravando um snapshot `baselineTree` isolado via `GIT_INDEX_FILE` sem mexer no `.git/index` do usuário. +2. O hook `tool.execute.before` bloqueia edições (`edit`, `write`, `hashline_edit`, `ast_rewrite`) em arquivos de produção por `@hermes` / `@talos`, mantendo escrita livre em arquivos de teste. +3. Assim que um teste falhando é registrado via `record_reproduction` (`exitCode !== 0`), a edição em produção é liberada automaticamente. +4. Se as tentativas de validação esgotarem e `ThemisReflexController` escalar, o `pantheon_step_ledger` restaura o `baselineTree` automaticamente (`rollback_step` também pode ser chamado sob demanda). --- -## Receita 4: Refatoração Visual Baseada em Captura de Tela (Screenshot) +## Receita 4: Busca e Refatoração Estrutural via AST (`ast_search` / `ast_rewrite`) -**Cenário:** Reconstruir ou refinar um componente frontend para corresponder a um mockup. +**Cenário:** Migrar chamadas de API em dezenas de arquivos TypeScript/JavaScript sem risco de alterar strings ou comentários. **Prompt:** -*(Cole a imagem da área de transferência com Ctrl+V / Cmd+V no chat)* ```text -@aphrodite Refatore este card de métricas para refletir fielmente o espaçamento, tipografia e cores da captura colada. +@hermes Use ast_search para localizar todas as chamadas a legacyFetch($URL, $$$ARGS) em src/ e faça uma prévia com ast_rewrite usando dryRun=true antes de aplicar. ``` -**Fluxo de Execução:** -1. O Pantheon Vision processa a imagem silenciosamente via contexto de sistema (`session.context`). -2. A `@aphrodite` analisa a hierarquia visual, espaçamentos e acessibilidade WCAG AA, atualizando os componentes React/Tailwind. +**Por que usar `ast_search` / `ast_rewrite`?** +- Ignora comentários e strings literais automaticamente, suportando capturas `$VAR` e variádicas `$$$ARGS`. +- Garante confinamento por symlink dentro do workspace e retorna `[LSP-Diagnostics]` + lint por diff no mesmo turno. --- -## Receita 5: Investigação Segura da Base de Código (Somente Leitura) +## Receita 5: Migrações de Banco de Dados e Otimização de Consultas -**Cenário:** Compreender uma lógica complexa espalhada por vários arquivos sem risco de edições indesejadas. +**Cenário:** Adicionar nova tabela ou coluna com chaves estrangeiras e índices otimizados sem gargalos N+1. **Prompt:** ```text -@apollo Rastreie o repositório e explique como os tokens de autenticação são validados em conexões WebSocket ativas. +@demeter Crie uma migration Alembic adicionando a tabela 'user_preferences' com chave estrangeira para 'users' e índice em 'created_at'. ``` -**Por que usar o @apollo?** -O `@apollo` opera em modo estritamente somente leitura (`edit: deny`, `bash: deny`). Ele realiza buscas rápidas e paralelas, retornando caminhos exatos de arquivos e intervalos de linhas relevantes. +**Por que usar `@demeter`?** +`@demeter` aplica boas práticas de SQLAlchemy, Prisma, Alembic e PostgreSQL, garantindo integridade referencial e índices eficientes. --- -## Receita 6: Auditoria de Segurança e Qualidade Pré-PR +## Receita 6: Refatoração Visual e Diagnóstico Multimodal (`/pantheon-vision`) -**Cenário:** Fazer uma revisão completa de todas as alterações feitas na branch antes de abrir um Pull Request. +**Cenário:** Ajustar componentes frontend com base em um screenshot ou inspecionar o status do gateway de visão. **Prompt:** +*(Cole o screenshot com Ctrl+V / Cmd+V no chat, ou execute `/pantheon-vision` para conferir a configuração)* ```text -@themis Audite as mudanças desta branch contra o OWASP Top 10, execute os testes e o linter Biome, e emita o veredicto de qualidade. +@aphrodite Refatore este card de métricas para corresponder ao espaçamento, tipografia e contraste do screenshot colado. ``` -**Por que usar a @themis?** -A `@themis` atua como auditora independente em modo read-only. Ela nunca altera código diretamente; executa suítes de teste, analisa regras estáticas e emite pareceres formais (`PASS`, `PASS_WITH_NOTES`, `BLOCK`). +**Fluxo:** +1. `/pantheon-vision` exibe os provedores multimodais configurados e o status do gateway. +2. O Pantheon Vision extrai tokens visuais uma única vez via `vision_describe` / `session.context`, evitando reenviar bytes de imagem no histórico. +3. `@aphrodite` atualiza os componentes com contraste acessível WCAG AA. --- -## Receita 7: Inteligência Artificial e Pipelines de RAG +## Receita 7: Investigação Segura Somente Leitura (`@apollo`) -**Cenário:** Implementar busca semântica com embeddings vetoriais. +**Cenário:** Mapear autenticação, fluxos de dados ou quem chama determinado símbolo sem risco de edição acidental. **Prompt:** ```text -@hephaestus Crie um pipeline de busca vetorial usando LangChain e pgvector para recuperação semântica de trechos de documentos. +@apollo Rastreie onde os tokens WebSocket são validados usando code_index, code_query e code_neighbors. ``` -**Por que usar o @hephaestus?** -O `@hephaestus` é especialista em embeddings, bancos de dados vetoriais, orquestração de LLMs e ferramentas de inteligência artificial. +**Por que usar `@apollo`?** +`@apollo` opera estritamente em modo somente leitura (`edit: deny`, `bash: deny`, `ast_rewrite: deny`). O uso de `code_index`, `code_query` e `code_neighbors` evita globs recursivos pesados e poda automaticamente arquivos removidos. --- -## Receita 8: Docker e Automação de CI/CD +## Receita 8: Auditoria de Segurança e Remediação por Veredito (`/pantheon-audit` + `@themis`) -**Cenário:** Criar Dockerfile multi-stage e workflow do GitHub Actions. +**Cenário:** Auditar alterações da branch antes de abrir PR e acionar correções automáticas se houver bloqueios. -**Prompt:** +**Prompts:** ```text -@prometheus Crie um Dockerfile multi-stage otimizado para produção em Node.js e um workflow do GitHub Actions para testar PRs. +/pantheon-audit +``` +ou diretamente: +```text +@themis Audite as alterações desta branch contra o OWASP Top 10, valide testes e lint e registre o veredito final com pantheon_review_verdict. ``` -**Por que usar o @prometheus?** -O `@prometheus` é o especialista em DevOps, contêineres, pipelines de integração contínua e scripts de infraestrutura. +**Fluxo:** +- `/pantheon-audit` executa análise estática zero-token seguida da revisão em 3 camadas da `@themis`. +- `@themis` registra o veredito estruturado via `pantheon_review_verdict`: `APPROVE`, `APPROVE_WITH_NOTES` ou `BLOCK`. +- Ao emitir `BLOCK`, o Pantheon injeta automaticamente até 2 turnos de remediação na sessão pai com os achados estruturados. --- -## Receita 9: Síntese de Conselho para Decisões de Arquitetura (`/pantheon`) +## Receita 9: Pipelines de IA, Containers e CI/CD -**Cenário:** Decidir entre duas soluções arquiteturais com múltiplos prós e contras técnicos. +**Cenários:** Construir pipelines vetoriais RAG ou Dockerfiles multi-stage e workflows GitHub Actions. -**Prompt:** +**Prompts:** ```text -/pantheon Devemos utilizar Server-Sent Events (SSE) ou WebSockets para o feed de notificações em tempo real do dashboard? +@hephaestus Implemente um pipeline de busca semântica com embeddings e pgvector com ingestão em lotes. +``` +```text +@prometheus Crie um Dockerfile multi-stage para este serviço e um workflow do GitHub Actions para rodar testes em PRs. ``` - -**Por que usar /pantheon?** -Dispara 2 ou 3 especialistas em paralelo (`@athena` para modularidade, `@hermes` para vazão/APIs, `@themis` para limites de conexões e segurança) e sintetiza uma decisão unificada com precedência de domínio. --- -## Receita 10: Projeto Multidisciplinar com Checkpoints (`/pantheon-deepwork`) +## Receita 10: Conselho de Arquitetura e Deepwork em Worktrees (`/pantheon`, `/pantheon-deepwork`, `pantheon_worktree`) -**Cenário:** Migrar ou refatorar subsistemas complexos que levam múltiplos turnos e dias de trabalho. +**Cenários:** Arbitrar trade-offs arquiteturais críticos ou executar refatorações multifase em worktrees isolados. -**Prompt:** +**Prompt de Conselho:** ```text -/pantheon-deepwork Migre o armazenamento de sessões de usuário de memória para cookies JWT criptografados com lista de revogação no Redis. +/pantheon Devemos usar Server-Sent Events (SSE) ou WebSockets para atualizações ao vivo no dashboard? ``` -**Fluxo de Execução:** -1. O plano e o progresso são salvos em `.pantheon/deepwork//` (`plan.json`, `PLAN.md`, logs). -2. Especialistas trabalham concorrentemente em git worktrees isolados (`.pantheon-worktrees/`). -3. Cada fase concluída passa pelo portão de aprovação da `@themis` antes do avanço. +**Prompt de Deepwork + Worktree:** +```text +/pantheon-deepwork Migre a autenticação de sessões para refresh tokens rotativos usando isolamento via pantheon_worktree e checkpoints do Deepwork. +``` + +**Como funciona:** +- Tarefas paralelas são isoladas em `/.pantheon-worktrees//` por meio de `pantheon_worktree` e `ctx.worktree.transform`. +- Worktrees ligados compartilham automaticamente o `.pantheon/` do repositório principal (`PANTHEON_ISOLATE_WORKTREE_MEMORY=1` permite isolar por worktree). +- Planos são salvos em `.pantheon/deepwork//PLAN.md` e abrem diretamente pelos links clicáveis da Home e Sidebar. --- -## Receita 11: Tomada de Decisão Interativa via Portão de Perguntas +## Receita 11: Memória Persistente, Foco e Federação Cross-Repo (`/pantheon-focus`, `/pantheon-consolidate`) -**Cenário:** Resolver trade-offs técnicos durante o planejamento de forma dinâmica e interativa. +**Cenário:** Preservar metas entre compactações de contexto e consultar decisões salvas em repositórios pares. -**Fluxo de Execução:** -Quando a `@athena` elabora um plano com caminhos técnicos alternativos, o `@zeus` aciona a ferramenta nativa `question` do OpenCode: -- A interface exibe caixas interativas com opções claras. -- A alternativa mais alinhada às boas práticas vem marcada como `(Recomendado)`. -- O desenvolvedor clica na opção preferida e a orquestração prossegue imediatamente sem atrito de digitação no chat. +**Comandos e Ferramentas:** +- **`/pantheon-focus`** — consultar ou atualizar metas duráveis da sessão (`goal_create`, `goal_get`, `goal_update`, `goal_done`). +- **`/pantheon-consolidate`** — compactar, deduplicar e consolidar entradas no banco `node:sqlite` FTS5 local. +- **`memory_search` federado** — configure `PANTHEON_FEDERATED_REPOS` ou `~/.pantheon/federation.json` para que `memory_search(federated=true)` pesquise bancos `.pantheon/memory/memory.db` de outros repositórios em modo estritamente somente leitura. --- -## Receita 12: Diagnóstico de Saúde e Detecção de Drift (`doctor`) +## Receita 12: Especialistas Sob Medida, Modelos e Limpeza (`/pantheon-forge`, `/pantheon-model`, `/pantheon-optimize`) -**Cenário:** Verificar a saúde dos servidores MCP locais, permissões e integridade de arquivos do Pantheon. +**Cenário:** Adaptar agentes à stack exata do projeto (`Node`, `Python`, `Rust`, `Go`), ajustar modelos por agente ou limpar artefatos antigos. -**Comando:** -```bash -npx pantheon-opencode doctor -``` +**Comandos:** +- **`/pantheon-forge`** — executa `detect_stack` (`package.json`, `pyproject.toml`, `requirements.txt`, `Cargo.toml`, `go.mod`) e cria agentes customizados em `.opencode/agents/` via `pantheon_agent_forge`. +- **`/pantheon-model`** — inspeciona ou configura overrides de modelo por agente em `active-preset.json`. +- **`/pantheon-optimize`** — analisa e remove artefatos Deepwork antigos, worktrees órfãos e excessos de contexto. + +--- + +## Receita 13: Observabilidade em Tempo Real no Terminal (`/pantheon-cockpit`, `/pantheon-artifacts`, `/pantheon-whats-new`) + +**Cenário:** Acompanhar subagentes, portões, Step-Ledger, diagramas Mermaid e novidades da versão direto na TUI. + +![Aba Flightdeck do Pantheon Mission Control Cockpit](../../assets/tui/cockpit-flightdeck.png) + +- **`/pantheon-cockpit`** (ou `/cockpit`) — abre o Mission Control Cockpit em 3 abas: + - `1 Overview`: velocidade de tokens, medidor de contexto, saúde das superfícies (`Native Tools (30)`) e mapa de topologia. + - `2 Swarm`: linha do tempo Gantt concorrente e custo por subagente. + - `3 Flightdeck`: matriz `GATE`, estados do `Step-Ledger`, stream de eventos cross-process e atalho **`x` (`Export Replay Trace`)** para `.pantheon/reports/`. +- **`/pantheon-artifacts`** (ou `/artifacts`) — navegue por planos/relatórios e visualize diagramas `flowchart`, `sequenceDiagram` e `stateDiagram` renderizados em caixas Unicode no terminal. +- **`/pantheon-whats-new`** — visualize o resumo curado de novidades da versão instalada. + +--- + +## Receita 14: Configurações, Limpeza de Caches Legados e Diagnóstico (`/pantheon-settings`, `/pantheon-updates`, `doctor`) + +**Cenário:** Ajustar presets de autonomia/portões, remover caches antigos de npm ou validar a integração com o OpenCode. + +- **`/pantheon-settings`** — abre o painel interativo de 10 abas (`Gates`, `Decisão`, `Preset`, `TUI`, `Autonomia`, `Segurança J1`, `Atualizações`, `Changelog`, `Doctor`, `Sobre`). +- **`/pantheon-updates`** — abre direto na aba **Atualizações & Limpeza**, verificando novas versões no npm e limpando caches obsoletos coexistentes em `~/.cache/opencode/npm/pantheon-opencode*`. +- **Diagnóstico via CLI:** + ```bash + npx pantheon-opencode doctor + ``` + +--- + +## Referência Rápida: Todos os Comandos -**Quando Executar:** -- Após alternar entre branches git ou sincronizar atualizações do repositório remoto. -- Ao atualizar o Node.js ou o OpenCode. -- Caso alguma ferramenta MCP relate falhas de conexão ou dependências ausentes. +| Superfície | Comandos | +|---|---| +| **Comandos de Servidor** | `/pantheon`, `/pantheon-deepwork`, `/pantheon-audit`, `/pantheon-consolidate`, `/pantheon-focus`, `/pantheon-forge`, `/pantheon-model`, `/pantheon-optimize`, `/pantheon-vision` | +| **Comandos TUI** | `/pantheon-cockpit`, `/pantheon-artifacts`, `/pantheon-settings`, `/pantheon-updates`, `/pantheon-whats-new` | diff --git a/package.json b/package.json index 42b04be1..5513579d 100644 --- a/package.json +++ b/package.json @@ -50,6 +50,7 @@ "docs:lint": "node scripts/docs-link-check.mjs", "docs:media": "node scripts/docs-media.mjs", "docs:check-changelog": "node scripts/docs-check-changelog.mjs", + "docs:check-cookbook": "node scripts/docs-check-cookbook.mjs", "typecheck": "tsc --noEmit", "audit": "npm audit --audit-level=critical", "secret-scan": "node scripts/secret-scan.mjs", diff --git a/scripts/build-agents-md.mjs b/scripts/build-agents-md.mjs index 07a54f18..9921daa8 100644 --- a/scripts/build-agents-md.mjs +++ b/scripts/build-agents-md.mjs @@ -157,7 +157,7 @@ Validate global installation AS A REAL USER in the sandbox \`~/pantheon-sandbox/ - Stronger gates (auth, security, data-integrity, coverage) are canonical in the global \`Test Economy\` section - Async/await on all I/O - Type hints on all functions -- PRs always update the README: document new features, behaviors, env vars, and commands before opening. +- PRs update README + Cookbooks: document features, env vars, commands (\`npm run docs:check-cookbook\`). ` const INSTRUCTIONS_PREAMBLE = `--- diff --git a/scripts/docs-check-cookbook.mjs b/scripts/docs-check-cookbook.mjs new file mode 100644 index 00000000..545d0ad5 --- /dev/null +++ b/scripts/docs-check-cookbook.mjs @@ -0,0 +1,158 @@ +#!/usr/bin/env node +/** + * docs-check-cookbook.mjs — enforce parity between Pantheon's shipped + * commands, TUI surfaces, core native workflows, package minor version, + * and both Practical Cookbooks (docs/guides/cookbook.md & docs/pt-BR/guides/cookbook.md). + * + * Exits 1 when either cookbook drifts behind code or version bumps. + */ + +import { existsSync, readFileSync } from 'node:fs' +import { dirname, join, resolve } from 'node:path' +import { fileURLToPath, pathToFileURL } from 'node:url' + +const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..') + +export const REQUIRED_CORE_MARKERS = [ + 'ast_search', + 'ast_rewrite', + 'hashline_edit', + 'pantheon_step_ledger', + 'pantheon_worktree', + 'pantheon_review_verdict', + 'detect_stack', + 'pantheon_agent_forge', + 'memory_search', + 'APPROVE', + 'APPROVE_WITH_NOTES', + 'BLOCK', +] + +export const STALE_COOKBOOK_PATTERNS = [ + { + pattern: /\bPASS_WITH_NOTES\b/, + reason: 'obsolete verdict label PASS_WITH_NOTES (use APPROVE / APPROVE_WITH_NOTES / BLOCK)', + }, +] + +function extractServerCommands(pluginSource) { + const blockMatch = /const CANONICAL_SLASH_COMMANDS[^=]*=\s*\[([\s\S]*?)\n\]/.exec(pluginSource) + if (!blockMatch) return [] + return [...blockMatch[1].matchAll(/\bname:\s*['"]([a-z0-9-]+)['"]/g)].map((m) => m[1]) +} + +function extractTuiCommands(tuiIndexSource) { + const start = tuiIndexSource.indexOf('function PantheonSettingsCommandLayer') + if (start === -1) return [] + const slice = tuiIndexSource.slice(start, start + 2500) + return [...slice.matchAll(/slash:\s*\{\s*name:\s*['"]([a-z0-9-]+)['"]/g)].map((m) => m[1]) +} + +function expectedMinorTag(version) { + const match = /^(\d+)\.(\d+)\./.exec(String(version ?? '').trim()) + return match ? `v${match[1]}.${match[2]}` : null +} + +function escapeRegExp(value) { + return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') +} + +function checkCookbookDocument(label, content, { expectedTag, commands, coreMarkers }) { + const findings = [] + if (!expectedTag) { + findings.push(`${label}: could not determine package.json major.minor version`) + } else { + const tagMarker = `` + if (!content.includes(tagMarker)) { + findings.push( + `${label}: missing current minor sync marker '${tagMarker}' — review and update recipes for ${expectedTag}`, + ) + } + } + + for (const cmd of commands) { + const cmdRe = new RegExp(`/${escapeRegExp(cmd)}(?![a-z0-9-])`) + if (!cmdRe.test(content)) { + findings.push(`${label}: missing documented command /${cmd}`) + } + } + + for (const marker of coreMarkers) { + const markerRe = new RegExp(`\\b${escapeRegExp(marker)}\\b`) + if (!markerRe.test(content)) { + findings.push(`${label}: missing v2.2+ core workflow/tool marker '${marker}'`) + } + } + + for (const rule of STALE_COOKBOOK_PATTERNS) { + if (rule.pattern.test(content)) { + findings.push(`${label}: contains ${rule.reason}`) + } + } + + return findings +} + +export function checkCookbookParity(rootDir = ROOT) { + const findings = [] + const pkgPath = join(rootDir, 'package.json') + const pluginPath = join(rootDir, 'src', 'plugin.ts') + const tuiPath = join(rootDir, 'src', 'plugins', 'tui', 'src', 'index.tsx') + const enPath = join(rootDir, 'docs', 'guides', 'cookbook.md') + const ptPath = join(rootDir, 'docs', 'pt-BR', 'guides', 'cookbook.md') + + if (!existsSync(pkgPath)) { + return { findings: ['package.json missing'], discoveredCommands: [], expectedTag: null } + } + const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) + const expectedTag = expectedMinorTag(pkg.version) + + const serverCommands = existsSync(pluginPath) + ? extractServerCommands(readFileSync(pluginPath, 'utf8')) + : [] + const tuiCommands = existsSync(tuiPath) ? extractTuiCommands(readFileSync(tuiPath, 'utf8')) : [] + const discoveredCommands = [...new Set([...serverCommands, ...tuiCommands])] + + if (discoveredCommands.length === 0) { + findings.push( + 'Unable to discover any canonical slash commands in src/plugin.ts or TUI index.tsx', + ) + } + + for (const [label, filePath] of [ + ['docs/guides/cookbook.md', enPath], + ['docs/pt-BR/guides/cookbook.md', ptPath], + ]) { + if (!existsSync(filePath)) { + findings.push(`${label}: file missing`) + continue + } + const content = readFileSync(filePath, 'utf8') + findings.push( + ...checkCookbookDocument(label, content, { + expectedTag, + commands: discoveredCommands, + coreMarkers: REQUIRED_CORE_MARKERS, + }), + ) + } + + return { findings, discoveredCommands, expectedTag } +} + +const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href + +if (isDirectRun) { + const { findings, discoveredCommands, expectedTag } = checkCookbookParity(ROOT) + if (findings.length > 0) { + console.error(`docs:check-cookbook failed (${findings.length} finding(s)):`) + for (const finding of findings) { + console.error(` - ${finding}`) + } + process.exitCode = 1 + } else { + console.log( + `docs:check-cookbook OK — EN + pt-BR cookbooks match ${expectedTag} (${discoveredCommands.length} commands, ${REQUIRED_CORE_MARKERS.length} core markers).`, + ) + } +} diff --git a/scripts/release-gates.mjs b/scripts/release-gates.mjs index 8f373b18..725f840d 100755 --- a/scripts/release-gates.mjs +++ b/scripts/release-gates.mjs @@ -541,6 +541,9 @@ function metadataGate(options) { run('version-manifests', 'node', ['scripts/version-check.mjs']), run('node-engine-policy', 'node', ['scripts/validate-node-engine-policy.mjs']), ] + if (!options.recovery) { + checks.push(run('cookbook-parity', 'node', ['scripts/docs-check-cookbook.mjs'])) + } return { checks, details: { diff --git a/tests/docs-cookbook.test.mjs b/tests/docs-cookbook.test.mjs new file mode 100644 index 00000000..9d941c11 --- /dev/null +++ b/tests/docs-cookbook.test.mjs @@ -0,0 +1,108 @@ +import assert from 'node:assert/strict' +import { execFileSync } from 'node:child_process' +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { afterEach, describe, test } from 'node:test' +import { fileURLToPath } from 'node:url' + +const ROOT = fileURLToPath(new URL('..', import.meta.url)) +const SCRIPT = join(ROOT, 'scripts/docs-check-cookbook.mjs') +const tempDirs = [] + +function makeTempRepo({ + version = '2.2.0', + serverCommands = ['pantheon', 'pantheon-forge'], + tuiCommands = ['pantheon-cockpit'], + cookbookEn = '', + cookbookPt = '', +} = {}) { + const dir = mkdtempSync(join(tmpdir(), 'pantheon-cookbook-check-')) + tempDirs.push(dir) + mkdirSync(join(dir, 'src/plugins/tui/src'), { recursive: true }) + mkdirSync(join(dir, 'docs/guides'), { recursive: true }) + mkdirSync(join(dir, 'docs/pt-BR/guides'), { recursive: true }) + + writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'pantheon-opencode', version })) + writeFileSync( + join(dir, 'src/plugin.ts'), + `const CANONICAL_SLASH_COMMANDS = [\n${serverCommands + .map((name) => ` { name: '${name}', description: 'desc' },`) + .join('\n')}\n]\n`, + ) + writeFileSync( + join(dir, 'src/plugins/tui/src/index.tsx'), + `function PantheonSettingsCommandLayer() {\n const cmds = [\n${tuiCommands + .map((name) => ` { slash: { name: '${name}' } },`) + .join('\n')}\n ]\n}\n`, + ) + writeFileSync(join(dir, 'docs/guides/cookbook.md'), cookbookEn) + writeFileSync(join(dir, 'docs/pt-BR/guides/cookbook.md'), cookbookPt) + return dir +} + +const VALID_BODY = ` + +Uses /pantheon, /pantheon-forge, /pantheon-cockpit, +ast_search, ast_rewrite, hashline_edit, pantheon_step_ledger, +pantheon_worktree, pantheon_review_verdict, detect_stack, +pantheon_agent_forge, memory_search, APPROVE, APPROVE_WITH_NOTES, BLOCK. +` + +afterEach(() => { + while (tempDirs.length > 0) { + rmSync(tempDirs.pop(), { recursive: true, force: true }) + } +}) + +describe('scripts/docs-check-cookbook.mjs', () => { + test('passes on synchronized EN and pt-BR cookbooks', async () => { + const { checkCookbookParity } = await import(SCRIPT) + const dir = makeTempRepo({ cookbookEn: VALID_BODY, cookbookPt: VALID_BODY }) + const result = checkCookbookParity(dir) + assert.deepEqual(result.findings, []) + assert.deepEqual(result.discoveredCommands.sort(), [ + 'pantheon', + 'pantheon-cockpit', + 'pantheon-forge', + ]) + }) + + test('fails when package.json minor version advances without cookbook version bump', async () => { + const { checkCookbookParity } = await import(SCRIPT) + const dir = makeTempRepo({ + version: '2.3.0', + cookbookEn: VALID_BODY, + cookbookPt: VALID_BODY, + }) + const result = checkCookbookParity(dir) + assert.ok(result.findings.some((f) => /cookbook-version v2\.3/.test(f))) + }) + + test('fails when a new server or TUI slash command is missing from either cookbook', async () => { + const { checkCookbookParity } = await import(SCRIPT) + const dir = makeTempRepo({ + serverCommands: ['pantheon', 'pantheon-forge', 'pantheon-new-cmd'], + tuiCommands: ['pantheon-cockpit'], + cookbookEn: `${VALID_BODY}\n/pantheon-new-cmd`, + cookbookPt: VALID_BODY, + }) + const result = checkCookbookParity(dir) + assert.ok(result.findings.some((f) => f.includes('pt-BR') && f.includes('/pantheon-new-cmd'))) + }) + + test('fails when obsolete PASS_WITH_NOTES verdict marker appears', async () => { + const { checkCookbookParity } = await import(SCRIPT) + const dir = makeTempRepo({ + cookbookEn: `${VALID_BODY}\nVerdict: PASS_WITH_NOTES`, + cookbookPt: VALID_BODY, + }) + const result = checkCookbookParity(dir) + assert.ok(result.findings.some((f) => f.includes('PASS_WITH_NOTES'))) + }) + + test('repository cookbooks satisfy full CI parity check', () => { + const output = execFileSync(process.execPath, [SCRIPT], { cwd: ROOT, encoding: 'utf8' }) + assert.match(output, /docs:check-cookbook OK/) + }) +})