@pathbit/agentdevkit 0.0.0-stage → 0.0.6

package/.pbai4devs/external-skills/CATALOG.json

@@ -0,0 +1,121 @@
+{
+  "schemaVersion": 1,
+  "allowlist": [
+    "vercel-labs/skills",
+    "vercel-labs/agent-skills",
+    "cloudflare/skills",
+    "microsoft/skills",
+    "oracle/skills",
+    "anthropics/skills",
+    "openai/skills",
+    "tech-leads-club/agent-skills"
+  ],
+  "skills": [
+    {
+      "id": "vercel-writing-guidelines",
+      "repository": "vercel-labs/agent-skills",
+      "commit": "1a2c79d4e6c4a2283dc2c614b6538cbe1ed5ca62",
+      "path": "skills/writing-guidelines/SKILL.md",
+      "name": "writing-guidelines",
+      "license": "MIT",
+      "use": "Revisar textos e documentação quando a tarefa pedir orientação editorial.",
+      "status": "reviewed",
+      "notes": "Licença declarada no README da origem. O pin não congela regras buscadas em main. Aplicar somente princípios editoriais compatíveis; Markdown, Node, autoria Git e demais regras locais prevalecem sobre recomendações de MDX/TypeScript ou atribuição de agentes.",
+      "licenseSource": "https://github.com/vercel-labs/agent-skills/blob/1a2c79d4e6c4a2283dc2c614b6538cbe1ed5ca62/README.md#license"
+    },
+    {
+      "id": "cloudflare-web-perf",
+      "repository": "cloudflare/skills",
+      "commit": "cbf893b954222276bf1af57e5f23379231e0efb9",
+      "path": "skills/web-perf/SKILL.md",
+      "name": "web-perf",
+      "license": "Apache-2.0",
+      "use": "Investigar desempenho web com medições reais quando houver página e ferramenta disponíveis.",
+      "status": "reviewed",
+      "notes": "Depende das ferramentas de navegador necessárias à investigação. Salvar evidências em .agent-tests e informar medições não executadas.",
+      "licenseSource": "https://github.com/cloudflare/skills/blob/cbf893b954222276bf1af57e5f23379231e0efb9/LICENSE"
+    },
+    {
+      "id": "anthropic-frontend-design",
+      "repository": "anthropics/skills",
+      "commit": "2c5958ecac7cee2b583967a2c4981d0f4a75c579",
+      "path": "skills/frontend-design/SKILL.md",
+      "name": "frontend-design",
+      "license": "Apache-2.0",
+      "use": "Apoiar implementação visual após decisões de produto e design.",
+      "status": "reviewed",
+      "notes": "LICENSE.txt presente na pasta. Aplicar às interfaces solicitadas, respeitando o design aprovado e a stack do projeto.",
+      "licenseSource": "https://github.com/anthropics/skills/blob/2c5958ecac7cee2b583967a2c4981d0f4a75c579/skills/frontend-design/LICENSE.txt"
+    },
+    {
+      "id": "openai-security-best-practices",
+      "repository": "openai/skills",
+      "commit": "49f948faa9258a0c61caceaf225e179651397431",
+      "path": "skills/.curated/security-best-practices/SKILL.md",
+      "name": "security-best-practices",
+      "license": "Apache-2.0",
+      "use": "Revisar práticas de segurança quando solicitado explicitamente.",
+      "status": "reviewed",
+      "notes": "LICENSE.txt e referências devem ser preservados. Suporte orientado a Python, JavaScript/TypeScript e Go; sem auditoria automática fora do escopo.",
+      "licenseSource": "https://github.com/openai/skills/blob/49f948faa9258a0c61caceaf225e179651397431/skills/.curated/security-best-practices/LICENSE.txt"
+    },
+    {
+      "id": "microsoft-frontend-review",
+      "repository": "microsoft/skills",
+      "commit": "4cfa010138972d45a7bb92edea90094f4f443da8",
+      "path": ".github/skills/frontend-design-review/SKILL.md",
+      "name": "frontend-design-review",
+      "license": "MIT",
+      "use": "Revisar uma interface existente quando essa revisão fizer parte da tarefa.",
+      "status": "reviewed",
+      "notes": "Licença MIT na raiz da origem. Respeitar a revisão pedida e complementar recomendações com validação real no navegador.",
+      "licenseSource": "https://github.com/microsoft/skills/blob/4cfa010138972d45a7bb92edea90094f4f443da8/LICENSE"
+    },
+    {
+      "id": "vercel-react-best-practices",
+      "repository": "vercel-labs/agent-skills",
+      "commit": "1a2c79d4e6c4a2283dc2c614b6538cbe1ed5ca62",
+      "path": "skills/react-best-practices/SKILL.md",
+      "name": "vercel-react-best-practices",
+      "license": "MIT",
+      "use": "Revisar React/Next.js quando essa stack tiver sido aprovada.",
+      "status": "candidate",
+      "notes": "Adoção depende da stack e da revisão da pasta. Não define a tecnologia do produto.",
+      "licenseSource": "https://github.com/vercel-labs/agent-skills/blob/1a2c79d4e6c4a2283dc2c614b6538cbe1ed5ca62/README.md#license"
+    },
+    {
+      "id": "cloudflare-workers-best-practices",
+      "repository": "cloudflare/skills",
+      "commit": "cbf893b954222276bf1af57e5f23379231e0efb9",
+      "path": "skills/workers-best-practices/SKILL.md",
+      "name": "workers-best-practices",
+      "license": "Apache-2.0",
+      "use": "Revisar Workers quando a arquitetura utilizar Cloudflare.",
+      "status": "candidate",
+      "notes": "Consultar versão e documentação atual; não criar infraestrutura nem fazer deploy por iniciativa própria.",
+      "licenseSource": "https://github.com/cloudflare/skills/blob/cbf893b954222276bf1af57e5f23379231e0efb9/LICENSE"
+    },
+    {
+      "id": "oracle-database",
+      "repository": "oracle/skills",
+      "commit": "0779f030fdee393ee418a3a76f6a4b09bf1408db",
+      "path": "db/SKILL.md",
+      "name": "db",
+      "license": "UPL-1.0",
+      "use": "Trabalhar com Oracle Database se escolhido no design.",
+      "status": "candidate",
+      "notes": "Pode chamar SQLcl/MCP e operações de banco. Exige revisão do escopo, licença e ferramentas; não faz parte da configuração base."
+    },
+    {
+      "id": "community-spec-driven-eval",
+      "repository": "tech-leads-club/agent-skills",
+      "commit": "e74dc8a7e8d59bb36f267afd089580e0858e224a",
+      "path": "packages/skills-catalog/skills/(development)/spec-driven-eval/SKILL.md",
+      "name": "spec-driven-eval",
+      "license": "CC-BY-4.0",
+      "use": "Avaliar implementação contra critérios de aceite.",
+      "status": "candidate",
+      "notes": "Fonte comunitária com atribuição. Revisar licença e adaptar destino de relatórios para .agent-tests; a origem grava junto da spec."
+    }
+  ]
+}

package/.pbai4devs/external-skills/README.md

@@ -0,0 +1,48 @@
+---
+description: Catálogo revisado e cópias locais de skills externas.
+---
+
+# Skills externas
+
+[CATALOG.json](CATALOG.json) registra origem, commit imutável, arquivo,
+nome, licença, finalidade e revisão local. `reviewed` indica curadoria para o
+uso descrito. As instruções do usuário e as regras do projeto prevalecem.
+
+Use o [gerenciador](../scripts/gerenciar-skills-externas/README.md) para listar,
+descobrir, instalar, verificar ou ler uma entrada. Instale antes o CLI `skills`
+pelo gerenciador de ferramentas. Node.js 24+ é o runtime comum.
+
+As cópias completas ficam em `.local/<id>/`, com referências e licenças
+incluídas pela origem. O CLI oficial faz o download e a cópia; nenhuma skill
+é espelhada em `.pbai4devs/skills/`, pastas de clientes ou diretórios globais.
+Somente catálogo, guias e automações próprias são versionados.
+`licenseSource` aponta para a declaração de licença no mesmo commit, inclusive
+quando ela fica na raiz do repositório e não vem junto da pasta da skill.
+
+Atualizações exigem revisar e registrar um novo SHA no catálogo. Ler uma
+skill não executa suas instruções: aplique-a somente à tarefa pertinente.
+Evidências ficam em `.agent-tests/`; publicação, instalação global e fluxos
+externos que alteram o projeto dependem do pedido correspondente. Spec Kit e
+OpenSpec seguem seus próprios fluxos e não são iniciados por este catálogo.
+
+As notas de cada entrada registram dependências e conteúdo remoto adicional.
+O pin congela os arquivos copiados; regras buscadas depois em `main` precisam
+de nova leitura antes de uso.
+
+## Outras fontes e fluxos
+
+| Fonte | Aplicação |
+| --- | --- |
+| [Vercel](https://vercel.com/docs/agent-resources/skills), [CLI skills](https://github.com/vercel-labs/skills) | Descoberta e download pelo CLI já preparado. |
+| [Cloudflare](https://github.com/cloudflare/skills), [APIs de skills](https://developers.cloudflare.com/agents/tools/skills/) | Catálogo local e APIs do runtime são recursos distintos. |
+| [Microsoft](https://github.com/microsoft/skills), [Anthropic](https://github.com/anthropics/skills), [OpenAI](https://github.com/openai/skills) | Referências por tarefa; confira licença e dependências de cada pasta. |
+| [Oracle](https://github.com/oracle/skills) | Candidatas para banco e Graal; uso depende da stack. |
+| [Tech Leads Club](https://github.com/tech-leads-club/agent-skills) | Fonte comunitária; revisar licença e destinos de evidências. |
+| [Spec Kit](https://github.github.com/spec-kit/), [código](https://github.com/github/spec-kit) | Aproveitar fases, artefatos e convergência; o CLI Python/uv fica fora do runtime Node adotado. |
+| [OpenSpec](https://openspec.dev/), [código](https://github.com/Fission-AI/OpenSpec) | Fluxo próprio de proposal/design/tasks/verify; `init` depende de decisão explícita porque altera o projeto. |
+| [Dotcontext](https://github.com/vinilana/dotcontext), antigo [AI Coders Context](https://www.npmjs.com/package/@ai-coders/context) | Avaliar manualmente o fluxo PREVC e `.context`; CLI, MCP, harness e hooks opcionais podem alterar destinos. |
+
+As entradas revisadas de Microsoft, Anthropic e OpenAI estão identificadas no
+catálogo. Vercel Writing Guidelines deve contribuir apenas com princípios
+editoriais compatíveis: seus padrões de MDX/TypeScript e atribuição de agentes
+não substituem os padrões locais de Markdown, Node e autoria Git.

package/.pbai4devs/rules/README.md

@@ -0,0 +1,18 @@
+---
+description: Finalidade e criação das regras compartilhadas.
+---
+
+# Regras
+
+Orientam contextos recorrentes. Use `criar-regra` quando uma convenção precisar
+valer em várias tarefas; salve em `<nome>/RULE.md` e defina seu escopo.
+
+- [Estrutura](estrutura/RULE.md): organização, concisão e sincronização.
+- [Qualidade](qualidade/RULE.md): testes, evidências e Markdown.
+- [Git](git/RULE.md): commits, autoria e publicação.
+- [Ambiente local](ambiente-local/RULE.md): estrutura, Docker e comandos reais.
+- [Documentação](documentacao/RULE.md): revisão após toda implementação.
+- [Próximos passos](proximos-passos/RULE.md): continuidade explícita por etapa.
+
+O Cursor usa regras `.mdc`; se o espelho não for carregado automaticamente,
+peça leitura explícita. Preserve o escopo nos formatos nativos disponíveis.

package/.pbai4devs/rules/ambiente-local/RULE.md

@@ -0,0 +1,33 @@
+---
+trigger: always_on
+description: Estrutura mínima e ambiente local dos projetos com Docker Compose.
+---
+
+# Ambiente local
+
+Na configuração técnica de projetos novos, mantenha `.pbai4devs/` e gere apenas
+os clientes selecionados. Configure `.vscode/` quando esse editor for adotado.
+Para a aplicação, crie `src/`, `tests/` e `infra/compose/compose.local.yml`.
+São obrigatórios `.gitignore`, `.gitattributes`, `.editorconfig`,
+`.dockerignore`, `Makefile` e `README.md`; `scripts/` é opcional para automações
+da aplicação. Em projetos existentes, preserve a organização até uma
+padronização autorizada; preparar a máquina não implica migrar o projeto.
+
+Execute o ambiente local em Docker Compose. Esclareça serviços e versões,
+bancos, cache, filas, integrações, recursos, segredos, portas e dados existentes.
+Pergunte a porta de entrada; se o usuário não souber, escolha uma livre e
+registre-a. Publique somente o necessário em localhost, com healthchecks e
+persistência explícita. Preserve volumes; não execute `down -v` como rotina.
+
+Traefik é opcional para compartilhar a porta de entrada entre aplicações com
+hosts distintos. Use configuração de arquivo ou proxy restrito para descoberta;
+não exponha dashboard nem acesso irrestrito ao socket Docker.
+
+O Makefile deve oferecer `help`, `doctor`, `setup`, `up`, `down`, `logs`,
+`test`, `lint` e `build`, com comandos reais da stack. Etapas ainda indefinidas
+devem falhar com mensagem útil; não simule sucesso. Documente os comandos,
+dependências e URL/porta no README; valide Compose e saúde antes de concluir.
+
+Use o [modelo de ambiente](../../templates/ambiente-local/TEMPLATE.md) para
+perguntas e arquivos-base. Versões da aplicação seguem as decisões do projeto;
+atualização de ferramentas locais não atualiza bancos ou dependências da stack.

package/.pbai4devs/rules/ambiente-local/cursor.yaml

@@ -0,0 +1,4 @@
+---
+description: Estrutura mínima e ambiente local com Docker Compose.
+alwaysApply: true
+---

package/.pbai4devs/rules/documentacao/RULE.md

@@ -0,0 +1,11 @@
+---
+trigger: always_on
+description: Documentação e revisão fazem parte de toda entrega implementada.
+---
+
+# Documentação da entrega
+
+Após implementar, siga `atualizar-documentacao` e o comando `revisar-entrega`
+antes de commit ou merge. Use os modelos da fase atual; registre decisões sem
+impacto com justificativa e resolva os achados da revisão independente.
+Uma mudança sem spec também precisa de critérios e evidências verificáveis.

package/.pbai4devs/rules/documentacao/cursor.yaml

@@ -0,0 +1,4 @@
+---
+description: Documentação e revisão fazem parte de toda entrega implementada.
+alwaysApply: true
+---

package/.pbai4devs/rules/estrutura/RULE.md

@@ -0,0 +1,33 @@
+---
+trigger: always_on
+description: Organização, concisão e sincronização dos recursos compartilhados.
+---
+
+# Estrutura
+
+Use a skill específica ou `criar-recurso`. Reutilize antes de criar. Mantenha
+uma origem por recurso, uma pasta por nome e um arquivo principal por tipo.
+Escreva instruções curtas; carregue detalhes opcionais só quando necessários.
+
+Após criar, alterar, renomear ou remover recursos do hub, execute
+`sincronizar-agentes` e seu `--check`. Registre clientes agênticos nos templates
+em `.pbai4devs/templates/clients/`, sem tratar tools como destinos.
+Documentos de produto fora do hub seguem seus próprios índices; alterá-los
+não exige sincronizar os agentes. Os espelhos contêm metadados e apontamentos.
+Espelhe apenas os principais `SKILL.md`, `AGENT.md`, `COMMAND.md` e `RULE.md`.
+Não replique templates, scripts, tools, estado, testes, docs ou guias.
+Repare com `--force` quando necessário: os destinos gerenciados podem ser
+sobrescritos e limpos; preserve a origem e os arquivos nativos fora desse escopo.
+Cada pasta de primeiro nível de `.pbai4devs` tem um README curto sobre seu uso.
+Cada pasta criada em `docs/`, incluindo ancestrais necessários, tem um README
+conciso sobre finalidade e público; preserve os arquivos existentes.
+Guias `README.md` e `INSTRUCTIONS.md` ficam só em `.pbai4devs`, sem espelhamento.
+Automações seguem `executar-script`: identifique SO, runtimes e conectores;
+reutilize scripts e ferramentas instaladas antes de gerar código na conversa.
+Enquanto configurar os agentes, mantenha os documentos de produto como modelos.
+Testes compartilhados ficam junto de cada script em `tests/`; testes do
+próprio AgentDevKit ficam em `tests/`, na raiz. Em tools, versione fontes;
+downloads e registros ficam em `<nome>/.local/`, cache em `.cache/`, launchers em
+`bin/`. Não duplique o instalador nem espelhe esses recursos nas ferramentas.
+Mantenha os derivados locais e ignorados pelo sincronizador. Novas fontes
+precisam continuar versionáveis; confira o resultado com Git.

package/.pbai4devs/rules/estrutura/cursor.yaml

@@ -0,0 +1,4 @@
+---
+description: Organização e sincronização dos recursos compartilhados.
+alwaysApply: true
+---

package/.pbai4devs/rules/git/RULE.md

@@ -0,0 +1,18 @@
+---
+trigger: model_decision
+description: Aplique ao preparar, integrar ou publicar alterações Git.
+---
+
+# Regras Git
+
+Use Conventional Commits (`tipo(escopo): descrição`, escopo opcional), inclusive
+em checkpoints e merges; destaque mudanças incompatíveis com `!` ou
+`BREAKING CHANGE:`. Autor e committer devem ser o usuário, nunca um agente;
+confira as identidades efetivas e não adicione coautoria ou identificação de
+agente. Se a identidade do usuário não estiver clara, pergunte. Não altere a
+configuração ou a assinatura criptográfica automaticamente e não reescreva
+autores humanos existentes.
+
+Antes de publicar, confira o conteúdo, as verificações e o estado remoto; não
+envie tarefas incompletas nem use push forçado. Consulte a skill correspondente
+em `.pbai4devs/skills/git/`.

package/.pbai4devs/rules/git/cursor.yaml

@@ -0,0 +1,4 @@
+---
+description: Convenções de Git e autoria dos commits do projeto.
+alwaysApply: true
+---

package/.pbai4devs/rules/proximos-passos/RULE.md

@@ -0,0 +1,14 @@
+---
+trigger: always_on
+description: Mantém os próximos passos explícitos após cada etapa do trabalho.
+---
+
+# Próximos passos
+
+Conclua respostas sobre trabalho com resultado, pendências e próxima ação
+aplicável, usando o idioma escolhido no projeto. No chat ou tela, termine com
+**[ Próximo passo ]** e a ação/comando; use **[ Next step ]** em inglês ou
+**[ Próximo paso ]** em espanhol. Use a skill
+[proximos-passos](../../skills/projeto/proximos-passos/SKILL.md) quando precisar
+determinar a fase ou seus pré-requisitos. Não repita etapas concluídas nem
+confunda instalação de instruções com aprovação de produto ou execução de testes.

package/.pbai4devs/rules/qualidade/RULE.md

@@ -0,0 +1,32 @@
+---
+trigger: always_on
+description: Padrões de testes, evidências e Markdown do projeto.
+---
+
+# Qualidade
+
+Versione código de testes e fixtures em `tests/`; testes da infraestrutura de
+agentes ficam em `.pbai4devs/scripts/<nome>/tests/`. Não versione
+resultados, relatórios, capturas ou artefatos temporários: use `.agent-tests/`,
+diretórios ignorados ou uma pasta temporária fora do repositório. Informe as
+verificações necessárias que não puder executar.
+
+Use `verificar-trabalho` para provar as mudanças. Alterações web exigem testar
+o fluxo real no navegador; desktop exige abrir e testar a aplicação. Código
+revisado, build ou fixture isolada não substituem essa prova funcional.
+
+Comece arquivos Markdown com frontmatter YAML adequado ao tipo e título H1;
+preserve os metadados exigidos pela ferramenta.
+
+Ao criar ou atualizar `.gitignore`, mantenha o bloco do
+[modelo de gitignore](../../templates/gitignore/TEMPLATE.md)
+como última seção CUSTOM IGNORE e acrescente os padrões específicos ali.
+As políticas vêm desse modelo. `.pbai4devs/.gitignore` controla o hub; o gerador
+protege os derivados externos no Git local. Sem Git, uma proteção temporária
+na raiz evita versioná-los ao iniciar o repositório.
+Confira com Git tanto os arquivos permitidos quanto os artefatos ignorados.
+Scripts compartilhados devem ser versionados; resultados locais, ignorados.
+Ignore o conteúdo baixado de tools, preservando `TOOL.json`, scripts próprios
+e guias. Não esconda scripts, fixtures ou templates por nome genérico ou
+extensão. Qualquer arquivo ou pasta `.playwright*` fica ignorado, em qualquer
+caixa, inclusive `.playwright-mcp`.

package/.pbai4devs/rules/qualidade/cursor.yaml

@@ -0,0 +1,4 @@
+---
+description: Testes, evidências e Markdown do projeto.
+alwaysApply: true
+---

package/.pbai4devs/scripts/README.md

@@ -0,0 +1,69 @@
+---
+description: Seleção e uso das automações compartilhadas.
+---
+
+# Scripts
+
+Pré-requisito: [Node.js 24+ com npm](https://nodejs.org/en/download),
+preferencialmente uma versão LTS. Automações próprias usam `.mjs` e o mesmo
+comando em macOS, Linux e Windows. Bun não faz parte do contrato validado.
+Versione scripts e testes; salve somente resultados em `.agent-tests/`.
+Prepare ferramentas locais com `preparar-ferramentas`, sem instalações globais.
+O runtime da aplicação será decidido no design doc; este requisito é dos agentes.
+Com Node 18+, use o [bootstrap JavaScript](preparar-ferramentas/BOOTSTRAP.md)
+com `--runtime-only` para preparar Node 24+ e continuar a operação.
+Sem Node/npm, o agente instala primeiro pelo mecanismo do sistema operacional.
+Não há inicializadores `.sh` ou `.ps1` no kit.
+
+Na raiz do repositório, use o seletor (adicione `--plan` antes do nome para
+consultar sem executar):
+
+```sh
+node .pbai4devs/scripts/executar-script/SCRIPT.mjs diagnosticar-ambiente
+```
+
+| Nome | Finalidade |
+| --- | --- |
+| `diagnosticar-ambiente` | Runtimes, pacotes e navegadores disponíveis |
+| `inspecionar-projeto` | Detecta manifests, comandos e estrutura |
+| `preparar-ferramentas` | Instala/atualiza ferramentas locais |
+| `gerenciar-skills-externas` | Instala/check/read de skills curadas locais |
+| `revisar-entrega` | Confere documentação, revisão e provas da mudança |
+| `sincronizar-agentes` | Repara com `--force`; `--check` só confere |
+| `verificar-recursos` | Estrutura Markdown, links e espelhos |
+| `testar-infraestrutura` | Executa `tests/TEST.mjs` com Node |
+| `testar-maturidade` | Gera e executa cenários em `examples/generated/` |
+| `testar-navegador` | Cenários via conector Playwright; veja a [referência](testar-navegador/REFERENCE.md) |
+
+Cada [ferramenta](../tools/README.md) tem `TOOL.json` e um `SCRIPT.mjs`,
+com ações `install`, `update`, `check`, `info` e `run`.
+Esses scripts delegam ao mesmo instalador; downloads ficam em `.local/`.
+`preparar-ferramentas setup` instala e verifica todos os CLIs compatíveis.
+Para um grupo, use `setup base`, `install base` ou `update base`;
+`check base` não instala nem consulta novas versões.
+
+O teste `preparar-ferramentas/tests/SMOKE_VERCEL.mjs` verifica CLIs opcionais
+instaladas com fixtures locais. Execute com Node; resultados ficam em
+`.agent-tests/vercel-labs/`. A suíte comum permanece independente desses downloads.
+
+O seletor aceita nome ou caminho JavaScript, repassa os argumentos e preserva
+o código de saída. Ele não procura outros interpretadores após uma falha.
+`playwright-mcp` exige o conector: seu `SCRIPT.js` é código para uma página,
+não um programa Node. Novas automações usam `.mjs`; `.bun` não é necessário.
+Os testes de cada script ficam em `<nome>/tests/`; resultados e capturas em
+`.agent-tests/`. Scripts, modelos e ferramentas não têm cópias nos agentes.
+
+Os layouts vêm de `templates/clients/ADAPTERS.json` no hub. O manifesto local
+`espelhos.conf` é gerado dessa fonte. Os metadados nativos ficam ao lado dos
+recursos, com frontmatter YAML sem corpo. Caminhos são relativos à raiz.
+Somente os quatro arquivos principais são fontes; não registre documentos.
+Use `gitignore|pasta` para gerar apenas o `.gitignore`, como em `.vscode`.
+
+`sincronizar-agentes --force` reconstrói os destinos e limpa auxiliares,
+preservando configurações e workflows fora do escopo gerenciado. Conteúdo
+próprio substituído recebe backup em `.agent-tests/`; `--check` não altera nada.
+O sincronizador também gera o catálogo completo e os índices auxiliares a partir
+das fontes. Helpers e testes constam como suporte, sem fingir comandos próprios.
+Ele protege os derivados contra versionamento e preserva regras humanas.
+As políticas vêm dos modelos de gitignore; o estado e os índices são locais.
+Os exemplos de maturidade usam cópias locais, sem downloads ou estado pessoal.

package/.pbai4devs/scripts/diagnosticar-ambiente/SCRIPT.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { ToolManager } from '../preparar-ferramentas/SCRIPT.mjs';
+import { findExecutable, isMain, projectRoot, requireNode } from '../lib/runtime.mjs';
+
+export function diagnose({ root = projectRoot, environment = process.env, probe = spawnSync } = {}) {
+  requireNode();
+  const manager = new ToolManager({ root });
+  const docker = findExecutable('docker', environment);
+  const execute = args => docker ? probe(docker, args, { encoding: 'utf8', timeout: 5000, windowsHide: true }).status === 0 : false;
+  const browserCandidates = [
+    environment.AGENT_BROWSER_EXECUTABLE_PATH,
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    environment.PROGRAMFILES && join(environment.PROGRAMFILES, 'Google/Chrome/Application/chrome.exe'),
+    environment['PROGRAMFILES(X86)'] && join(environment['PROGRAMFILES(X86)'], 'Google/Chrome/Application/chrome.exe'),
+    environment.LOCALAPPDATA && join(environment.LOCALAPPDATA, 'Google/Chrome/Application/chrome.exe'),
+    environment.LOCALAPPDATA && join(environment.LOCALAPPDATA, 'Chromium/Application/chrome.exe'),
+    'google-chrome', 'chromium', 'chromium-browser',
+  ].filter(Boolean);
+  return {
+    platform: process.platform,
+    arch: process.arch,
+    runtime: { name: 'node', version: process.version, executable: process.execPath },
+    npm: findExecutable('npm', environment),
+    git: findExecutable('git', environment),
+    docker: { executable: docker, compose: execute(['compose', 'version']), daemon: execute(['info', '--format', '{{.ServerVersion}}']) },
+    browsers: [...new Set(browserCandidates.map(name => findExecutable(name, environment)).filter(Boolean))],
+    tools: Object.keys(manager.catalog).map(name => {
+      const info = manager.info(name);
+      return { name, installed: info.installed?.version || null, supported: info.supported, ...(info.issue ? { issue: info.issue } : {}) };
+    }),
+    playwrightMcp: 'discover-through-agent-tools',
+  };
+}
+
+if (isMain(import.meta.url)) {
+  try { console.log(JSON.stringify(diagnose(), null, 2)); }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/.pbai4devs/scripts/diagnosticar-ambiente/tests/TEST.mjs

@@ -0,0 +1,30 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { diagnose } from '../SCRIPT.mjs';
+import { findExecutable, projectRoot, requireNode } from '../../lib/runtime.mjs';
+
+test('diagnostico funciona so com Node e informa dependencias opcionais ausentes', t => {
+  const output = join(projectRoot, '.agent-tests'); mkdirSync(output, { recursive: true });
+  const root = mkdtempSync(join(output, 'diagnose-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const report = diagnose({ root, environment: { PATH: '' }, probe: () => { throw new Error('Nenhum processo opcional esperado.'); } });
+  assert.equal(report.runtime.name, 'node'); assert.equal(report.runtime.executable, process.execPath);
+  assert.equal(report.npm, null); assert.equal(report.git, null);
+  assert.equal(report.docker.executable, null); assert.equal(report.docker.compose, false);
+  assert.deepEqual(report.tools, []); assert.equal(existsSync(join(root, '.pbai4devs')), false);
+});
+
+test('requisito comum recusa Node antigo e procura executaveis sem shell', t => {
+  assert.throws(() => requireNode(24, '22.22.0'), /Node.js >=24/);
+  assert.doesNotThrow(() => requireNode(24, '24.13.0'));
+  const output = join(projectRoot, '.agent-tests'); mkdirSync(output, { recursive: true });
+  const root = mkdtempSync(join(output, 'runtime-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const file = join(root, process.platform === 'win32' ? 'fixture.exe' : 'fixture');
+  writeFileSync(file, 'fixture'); chmodSync(file, 0o755);
+  assert.equal(findExecutable(file), file);
+  assert.equal(findExecutable('fixture', { PATH: dirname(file) }), file);
+  assert.equal(findExecutable('missing', { PATH: dirname(file) }), null);
+});

package/.pbai4devs/scripts/executar-script/README.md

@@ -0,0 +1,28 @@
+---
+description: Executor comum dos scripts Node do projeto.
+---
+
+# Executar script
+
+Use Node 24+ com o nome de uma pasta em `.pbai4devs/scripts/`, uma pasta do
+repositório ou o caminho de um arquivo `.mjs`. O comando funciona nos três SOs:
+
+```console
+node .pbai4devs/scripts/executar-script/SCRIPT.mjs --plan preparar-ferramentas
+node .pbai4devs/scripts/executar-script/SCRIPT.mjs preparar-ferramentas list
+```
+
+`--plan` mostra o arquivo sem executá-lo. Os argumentos e o código de saída
+são preservados; falhas não tentam outro runtime. Scripts shell/Python e links
+simbólicos são recusados. Arquivos `.js`/`.cjs` existentes usam o mesmo Node.
+
+Com Node 18+, o [bootstrap JavaScript](../preparar-ferramentas/BOOTSTRAP.md)
+aceita `--runtime-only` e prepara Node 24+ antes da operação solicitada.
+Sem Node/npm, o agente instala primeiro o runtime pelo mecanismo do SO.
+O modo padrão do bootstrap prepara também as ferramentas; reserve-o ao setup.
+
+`testar-navegador` mantém o executor Playwright indicado em `SCRIPT.conf`;
+sem `--plan`, retorna 69 para o agente usar o conector, sem executar o arquivo.
+Quando presente, `SCRIPT.conf` exige uma única entrada `executor=node` ou
+`executor=playwright-mcp`; comentários `#` são permitidos. Configurações vazias,
+desconhecidas ou duplicadas falham antes de executar qualquer script.

package/.pbai4devs/scripts/executar-script/SCRIPT.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { isMain, projectRoot, requireNode } from '../lib/runtime.mjs';
+import { parseScriptConfig } from '../lib/script-config.mjs';
+
+const fail = message => { throw Object.assign(new Error(message), { exitCode: 2 }); };
+const within = (root, path) => { const part = relative(root, path); return !isAbsolute(part) && part !== '..' && !part.startsWith(`..${sep}`); };
+
+function checkedPath(root, path) {
+  if (!within(root, path)) fail('Script fora do repositorio.');
+  let current = root;
+  for (const part of relative(root, path).split(sep).filter(Boolean)) {
+    current = join(current, part);
+    let stat;
+    try { stat = lstatSync(current); } catch { fail(`Script ausente: ${path}`); }
+    if (stat.isSymbolicLink()) fail('Link simbolico nao permitido em scripts.');
+  }
+  if (!within(root, realpathSync(path))) fail('Script fora do repositorio.');
+  return path;
+}
+
+function configuredExecutor(root, config) {
+  checkedPath(root, config);
+  if (!lstatSync(config).isFile()) fail('SCRIPT.conf deve ser um arquivo.');
+  try { return parseScriptConfig(readFileSync(config, 'utf8')); }
+  catch (error) { fail(error.message); }
+}
+
+export function resolveScript(input, { root = projectRoot } = {}) {
+  if (typeof input !== 'string' || !input || input.includes('\0')) fail('Informe o nome ou caminho de um script.');
+  root = realpathSync(root);
+  let path = resolve(root, input);
+  if (!within(root, path)) fail('Script fora do repositorio.');
+  if (!existsSync(path)) path = resolve(root, '.pbai4devs/scripts', input);
+  checkedPath(root, path);
+  const directory = lstatSync(path).isDirectory() ? path : dirname(path);
+  if (!lstatSync(path).isDirectory() && !['.mjs', '.js', '.cjs'].includes(extname(path))) fail('Use um script JavaScript Node (.mjs, .js ou .cjs).');
+  const config = join(directory, 'SCRIPT.conf');
+  if (lstatSync(config, { throwIfNoEntry: false })) {
+    if (configuredExecutor(root, config) === 'playwright-mcp') {
+      const file = checkedPath(root, join(directory, 'SCRIPT.js'));
+      if (!lstatSync(file).isFile()) fail('SCRIPT.js do conector deve ser um arquivo.');
+      if (!lstatSync(path).isDirectory() && path !== file) fail('O executor Playwright exige o arquivo SCRIPT.js configurado.');
+      return { root, file, executor: 'playwright-mcp' };
+    }
+  }
+  if (lstatSync(path).isDirectory()) {
+    path = ['SCRIPT.mjs', 'SCRIPT.cjs', 'SCRIPT.js'].map(name => join(directory, name)).find(existsSync);
+    if (!path) fail('Nenhum SCRIPT.mjs encontrado; scripts shell e Python nao sao executados.');
+    checkedPath(root, path);
+  }
+  if (!lstatSync(path).isFile()) fail('O caminho nao e um arquivo de script.');
+  return { root, file: path, executor: 'node' };
+}
+
+export function main(input = process.argv.slice(2), options = {}) {
+  requireNode();
+  const args = [...input]; const plan = args[0] === '--plan'; if (plan) args.shift();
+  if (['--help', '-h'].includes(args[0])) { console.log('Uso: node SCRIPT.mjs [--plan] <nome-ou-caminho> [argumentos]'); return 0; }
+  if (!args.length) fail('Uso: node SCRIPT.mjs [--plan] <nome-ou-caminho> [argumentos]');
+  const selected = resolveScript(args.shift(), options);
+  console.log(`${selected.executor === 'node' ? 'runtime=node' : 'executor=playwright-mcp'}\nfile=${relative(selected.root, selected.file).split(sep).join('/')}`);
+  if (plan) return 0;
+  if (selected.executor === 'playwright-mcp') {
+    console.error('Use o conector Playwright pelo agente; este script nao e um programa Node.');
+    return 69;
+  }
+  const result = spawnSync(process.execPath, [selected.file, ...args], { cwd: selected.root, stdio: 'inherit', windowsHide: true });
+  if (result.error) throw result.error;
+  return result.status ?? 1;
+}
+
+if (isMain(import.meta.url)) {
+  try { process.exitCode = main(); }
+  catch (error) { console.error(error.message); process.exitCode = error.exitCode || 1; }
+}