httpdr-setup

Configure, distribua e mantenha uma camada de engenharia para agentes de IA — em um único comando.

O httpdr-setup instala skills, regras, comandos e recursos cross-harness para Claude Code, Codex e GitHub Copilot. Ele cria uma configuração reproduzível no projeto, preserva conteúdo humano e funciona offline a partir do pacote publicado.

Instalação

Requer Node.js 20 ou superior.

npx httpdr-setup@latest init

Para aceitar as recomendações padrão sem perguntas:

npx httpdr-setup@latest init --yes

Primeiros passos

Dentro da pasta do seu projeto:

npx httpdr-setup init

O assistente detecta a stack e os harnesses, recomenda um perfil, mostra um preview, pede confirmação, grava manifesto/lock/state, instala a camada e executa uma verificação final.

Em CI ou ambientes sem TTY, use --yes. Sem essa flag, o comando encerra com código 2 para evitar alterações não confirmadas.

O que é instalado

Dependendo do perfil escolhido, o projeto pode receber:

• AGENTS.md e CLAUDE.md;
• .codex/AGENTS.md e configurações do Codex;
• .github/copilot-instructions.md e prompts do Copilot;
• .ai-harness/ com inventário, regras, comandos e catálogo;
• skills compatíveis com Claude Code, Codex e Copilot;
• snapshot local dos recursos ECC, quando habilitado.

Arquivos gerenciados são marcados com BEGIN AI-HARNESS / END AI-HARNESS. Conteúdo humano fora desses blocos não é sobrescrito silenciosamente.

Comandos principais

# Configuração guiada
npx httpdr-setup init
npx httpdr-setup init --yes --no-ecc

# Configuração explícita e previsível
npx httpdr-setup setup --target . --harness all --dry-run
npx httpdr-setup setup --target . --harness all

# Atualizar somente recursos ECC
npx httpdr-setup ecc-sync --target . --harness all

# Consultar o catálogo empacotado, sem rede
npx httpdr-setup search react
npx httpdr-setup info react-best-practices
npx httpdr-setup list --json

# Diagnóstico e validação
npx httpdr-setup validate
npx httpdr-setup doctor
npx httpdr-setup doctor --deep

Use --json em automações. Mensagens humanas vão para stderr e stdout permanece JSON válido.

| Flag | Função | |---|---| | --target <path> | Define o projeto alvo. O padrão é o diretório atual. | | --scope project\|global | Escolhe instalação no projeto ou no perfil do usuário. | | --harness <id\|all> | Seleciona claude, codex, copilot ou todos. | | --yes | Aprova o preview sem interação. | | --dry-run | Mostra o plano sem escrever arquivos. | | --json | Emite resultado estruturado. | | --force | Permite substituir arquivos gerenciados alterados localmente. |

Manifesto e lockfile

Uma configuração de projeto usa .httpdr-setup.yml:

schemaVersion: 1
scope: project
harnesses:
  - codex
skills:
  - react-best-practices
options:
  includeEcc: false

O httpdr-setup.lock.json registra resolução, versões, checksums, harnesses e arquivos gerenciados. Ambos podem ser versionados para reproduzir o setup.

Instalação global

npx httpdr-setup setup --target /caminho/do/projeto --scope project --harness all
npx httpdr-setup setup --scope global --harness all

No Windows, use um caminho PowerShell como C:\Projetos\minha-app.

Desenvolvimento local

git clone https://github.com/pedronazarito98/skills_PT-BR.git
cd skills_PT-BR
npm ci
npm run ci

O gate executa build das distribuições, check estático, encoding UTF-8, validação de skills, verificação do catálogo e a suíte de testes.

Para testar a CLI sem instalar o pacote:

node bin/httpdr-setup.mjs --help
node bin/httpdr-setup.mjs list --json

Publicação e releases

main é a fonte de releases: toda mudança aprovada e incorporada em main deve receber uma nova versão no package.json, passar por npm run ci e ser publicada no npm como uma atualização do httpdr-setup.

O workflow de CI valida cada push em main. A publicação exige credencial/trusted publishing do npm e é o passo de release após a validação; nunca publique novamente uma versão já existente.

Segurança e previsibilidade

• O planner calcula operações antes de alterar o disco.
• Paths absolutos e traversal são rejeitados.
• Arquivos humanos não gerenciados não são apagados.
• Falhas parciais usam rollback/journal.
• Catálogo e snapshot ECC são empacotados; a instalação não depende de rede.

Estrutura

apps/cli/          entrada e apresentação da CLI
packages/          schemas, core, catálogo, installer e adapters
skills/            fonte canônica das skills
vendor/ecc/        snapshot vendorizado do ECC
distributions/     saídas derivadas por harness
catalog/           catálogo JSON/Markdown versionado
tests/             testes unitários, integração e smoke

Contribuindo

1. Crie uma branch a partir de main.
2. Faça a alteração e adicione testes para o comportamento novo.
3. Rode npm run ci.
4. Abra um pull request descrevendo impacto, riscos e validação.

Licença

O código do projeto é MIT. Cada skill declara sua própria licença e origem; consulte THIRD_PARTY_NOTICES.md para os créditos de terceiros.