Rockfeller CLI

CLI oficial para criar e manter a base de projetos Rockfeller. O pacote publicado é @rockdev/cli e o binário é rock.

Use a CLI para iniciar projetos web, api e monolith. Ela centraliza a estrutura inicial, ferramentas de qualidade, documentação de agentes, arquivos de ambiente e opções de infraestrutura; não copie manualmente outro repositório para substituir o scaffold.

O que a CLI oferece

• rock new: cria projetos a partir dos templates web, api e monolith;
• rock status: verifica a saúde básica de um projeto existente;
• rock env example: cria .env.example sem expor valores locais;
• rock env check: compara as chaves de .env e .env.example;
• rock db migrate: localiza e executa uma migration existente do projeto;
• rock setup: prepara globalmente skills, RTK, Claude Code e Codex;
• rock update (ou rock upgrade): procura e instala uma release mais nova da CLI.

Todos os templates incluem .github/CODEOWNERS, Dependabot e renovate.json com as politicas padrao da Rockfeller. Durante o scaffold, escolha os workflows desejados: Quality (lint, typecheck, testes e build), CodeQL e Dependency Review. Os templates tambem podem incluir Biome, Lefthook, Commitlint, Dockerfile, Docker Compose, ORM, Better Auth, bases visuais e skills recomendadas conforme o tipo de projeto.

Instalação e uso

Instalação global:

npm install -g @rockdev/cli

Ou execute sem instalar globalmente:

npx @rockdev/cli new

Exemplos:

rock new web minha-landing
rock new api minha-api
rock new monolith plataforma-interna
rock status
rock env example
rock env check
rock db migrate
rock setup
rock update

rock new também funciona de modo interativo e permite escolher gerenciador de pacotes, extras, ORM, provedores de autenticação, bases web e skills.

rock setup instala globalmente as skills oficiais Rockfeller para Claude Code e Codex, oferece skills recomendadas de terceiros, instala e valida o RTK e configura seus agentes. Use rock setup --dry-run para visualizar as alterações, rock setup --yes para executar sem prompts ou rock setup --json para obter um relatório estruturado.

rock db migrate procura arquivos .env* e todos os package.json do projeto, sugere scripts de migration conhecidos, permite escolher o arquivo e a variável de conexão e sempre pede confirmação antes de executar. A saída é sanitizada para não exibir credenciais do ambiente.

Escolha de template

| Template | Use quando | Exemplos | | --- | --- | --- | | web | A aplicação é somente frontend. | Landing page, campanha, shell de dashboard. | | api | O produto é dono de um backend ou integração. | API de produto, adapter de provider. | | monolith | Web, API e dados fazem parte do mesmo produto. | Admin, área de membros, produto operacional. |

Defina produto, usuário, fluxo crítico, dados, autenticação, integrações e deploy antes de executar o scaffold. A CLI acelera a estrutura; ela não substitui decisões de domínio.

Arquitetura do repositório

src/
  index.ts                    Entrada do binário `rock`
  app.ts                      Registro e configuração dos comandos
  commands/                   Interface de cada comando da CLI
  scaffold/                   Criação de projetos, templates e assets
  shared/                     Ambiente, filesystem, processos, status e update
tsdown.config.mjs             Configura bundle, tipos e assets de templates no build
.github/workflows/
  ci.yml                      Qualidade em push e pull request
  release-publish.yml         Validação de release e publicação no npm

Os arquivos em src/scaffold/templates/ definem o que os projetos gerados recebem. Alterações nesses templates são alterações de contrato: atualize os testes de scaffold no mesmo ciclo.

Desenvolvimento local

Pré-requisitos:

• Bun 1.3.12;
• Node.js 22 para build, publicação e consistência com a CI.

bun install --frozen-lockfile
bun run dev

Comandos de qualidade:

| Comando | Finalidade | | --- | --- | | bun run lint | Executa as verificações do Biome. | | bun run typecheck | Verifica os tipos sem gerar saída. | | bun run test | Executa os testes com Bun. | | bun run build | Compila TypeScript e copia os assets de template. | | bun run check | Executa lint, typecheck e testes. | | bun run format | Formata os arquivos com Biome. |

Antes de abrir um PR, execute:

bun run check
bun run build
git diff --check

Variáveis de ambiente

A CLI não exige variáveis de ambiente para desenvolver, testar ou publicar no ambiente local. O arquivo .env.example documenta esse contrato.

Não versione .env. Quando uma nova configuração for necessária, declare apenas o nome sem segredo em .env.example, documente sua finalidade e mantenha os comandos rock env example e rock env check compatíveis com o formato.

Publicação no npm

O workflow release-publish.yml publica @rockdev/cli quando uma release do GitHub é publicada. Para permitir a publicação, devem coincidir:

• nome do pacote: @rockdev/cli;
• versão em package.json: por exemplo, 0.2.2;
• tag da release: v0.2.2;
• nome da release: v0.2.2.

O workflow executa lint, typecheck, build e testes antes de npm publish. Não publique manualmente ignorando esse fluxo nem exponha o token NPM_TOKEN fora dos secrets do GitHub.

Contribuição

Leia AGENTS.md antes de alterar código ou templates. CLAUDE.md e CONTRIBUTING.md são links simbólicos para o mesmo guia.

Ao modificar uma feature:

1. mantenha a alteração mínima e preserve compatibilidade de comandos e templates publicados;
2. adicione ou atualize testes para comportamento observável;
3. execute as validações relevantes;
4. descreva impacto em projetos novos ou existentes no PR.

Segurança

Não inclua credenciais, URLs privadas, dados pessoais ou valores de .env em código, fixtures, documentação ou logs. Para reportar uma vulnerabilidade, use um canal privado com o time responsável em vez de abrir uma issue pública com detalhes exploráveis.