starter-kits-cli

CLI para criar projetos e instalar kits de projeto (PostgreSQL, Docker, JWT, etc.).

Não confundir com os kits de skills do repositório pai (universal/, frontend/, …) — esses são para agentes de IA; este CLI gera código e configuração de projeto.

Requisitos

• Node.js 22+

Setup para o time (instalar no terminal)

| Modo | Guia | |------|------| | npm / npx (sem clone) | npx @heap-eng/starter-kits-cli@latest init — ver CLI-SETUP.md | | Clone + npm link (dev) | CLI-SETUP.md | | Publicar no npm (maintainers) | PUBLISH-NPM.md |

# Após publicação no npm
npx @heap-eng/starter-kits-cli@latest list-agent-kits

# Desenvolvimento no monorepo
git clone [email protected]:heap-eng/starter-kits.git
cd starter-kits/starter-kits-cli
npm install && npm run build && npm link

Desenvolvimento (monorepo starter-kits)

cd starter-kits-cli
npm install
npm run validate   # build + test + smoke

Executar localmente:

node dist/index.js list-kits
node dist/index.js list-agent-kits    # só dentro do monorepo
node dist/index.js init backend-nestjs --name my-api --kits db-postgres,docker

Ou após npm link:

starter-kits-cli init
starter-kits-cli list-kits
starter-kits-cli list-agent-kits
starter-kits-cli install-kit docker

Comandos

| Comando | Descrição | |---------|-----------| | init [type] | Novo projeto (interativo ou --name / --kits) | | import-kits / add-kits | Só importa kits no diretório atual (sem scaffold) | | init --kits-only | Atalho para import-kits no cwd | | list-kits | Lista kits de projeto (--category, --json) | | list-agent-kits | Lista kits de skills via kits/manifest.json (monorepo) | | install-kit <kit> | Aplica um kit no diretório atual |

Importar kits em projeto existente

cd meu-projeto

# Só agent kits (Cursor)
starter-kits-cli import-kits --agent-kits universal,planning,quality-security

# Só capacidades (templates Docker, DB, …)
starter-kits-cli import-kits --kits docker,ci-github

# Os dois
starter-kits-cli import-kits --agent-kits software-dev -k db-postgres

# Abre o seletor Ink de agent kits direto (sem boilerplate)
starter-kits-cli import-kits
starter-kits-cli init --kits-only

# Só capacidades (seletor de templates)
starter-kits-cli init --kits-only --pick capabilities

# Os dois seletores em sequência
starter-kits-cli init --kits-only --pick both

Tipos de projeto

• monorepo-turborepo, monorepo-nx
• frontend-nextjs, frontend-vite
• backend-nestjs, backend-go

Cada tipo gera um scaffold mínimo em src/generators/scaffolds/; skills adicionam arquivos em kits/<id>/, .github/, Docker, etc.

No init interativo, a seleção de skills usa um TUI (Ink, inspirado em agent-skills): categorias fechadas por padrão, Espaço para expandir/recolher, Espaço na skill para marcar, Enter para confirmar.

Publicação npm

npm run bundle      # vendor/heap-starter-kits ← skills do monorepo
npm run pack:check  # build + bundle + tarball dry-run

Detalhes: docs/PUBLISH-NPM.md.

Validação

| Escopo | Comando | O que valida | |--------|---------|----------------| | Só o CLI | npm run validate | tsc, vitest (registry + init + manifest), smoke (scripts/smoke-cli.mjs) | | Antes de publicar | npm run pack:check | build + bundle agent kits + npm pack --dry-run | | Monorepo inteiro | bash scripts/validate-repo.sh (raiz) | manifest de skills, shared skills, depois npm run build && npm test no CLI |

CI (.github/workflows/ci.yml) — job Validate em todo push/PR; Publish npm após validate OK na main.

Estrutura

src/
├── commands/       # init, list-kits, list-agent-kits, install-kit
├── generators/
│   ├── scaffolds/  # por project type
│   └── kits/       # por kit de projeto
├── lib/            # repo-root, agent-manifest, progress
└── registry/       # KIT_REGISTRY, PROJECT_TYPES