Alest CozinhaOS SDK

CLI/SDK para preparar a cozinha de trabalho da Alest com os repositórios certos para cada tipo de iniciativa.

Ao rodar o CozinhaOS, a pessoa escolhe entre duas trilhas:

• Implementação: clona implementation-spec-engine e implementation-loop-engine.
• Modernização: clona modernization-planning-template e modernization-spec-driven-dev-guide.

O objetivo é que alguém leigo consiga entrar em um repositório de cliente ou em uma pasta de trabalho, rodar um comando npm, escolher a trilha e receber a base correta na raiz do projeto.

Uso Rápido

Depois de publicado no npm, a experiência esperada em qualquer máquina é:

npm exec alest-cozinhaos-sdk@latest

Também funciona com npx:

npx alest-cozinhaos-sdk@latest

Esses comandos abrem o menu interativo diretamente. A máquina só precisa ter Node 22+, npm e Git.

Para publicar esse pacote e habilitar essa experiência, veja PUBLISHING.md.

Os repositórios clonados pela Alest são privados por compliance. Por isso, antes de escolher uma trilha, a máquina precisa ter acesso GitHub configurado:

gh auth login -h github.com -s repo
gh auth setup-git

Com SSH:

ssh -T [email protected]
npm exec alest-cozinhaos-sdk@latest -- --ssh

Se o npm não inferir o binário automaticamente em alguma versão específica, use a forma explícita:

npm exec --package alest-cozinhaos-sdk@latest -- cozinhaos

Dentro deste pacote, para desenvolvimento:

npm start

Ou, depois de linkar localmente para testar como comando global:

npm link
cozinhaos

Também existe o alias:

alest-cozinhaos-sdk
cozinhaos-sdk
alest-cozinhaos

Menu

Rodando sem argumentos, o CLI abre o menu interativo:

cozinhaos

Ele mostra o título Alest CozinhaOS, lista as duas trilhas e pergunta onde clonar os repositórios.

Por padrão, o destino é:

1. A raiz Git do diretório atual, quando o comando está dentro de um repositório.
2. O diretório atual, quando não existe raiz Git detectável.

Comandos Diretos

Instalar a stack de implementação:

cozinhaos install implementation

Instalar a stack de modernização:

cozinhaos install modernization

Escolher um destino explícito:

cozinhaos install implementation --target /caminho/do/repo

Ver o que aconteceria sem clonar:

cozinhaos install modernization --dry-run

Usar SSH em vez de HTTPS:

cozinhaos install implementation --ssh

Pular a checagem de acesso antes do clone:

cozinhaos install implementation --skip-access-check

Atualizar repositórios já existentes com git pull --ff-only:

cozinhaos install implementation --update-existing

Trilhas

Implementação

Clona na raiz alvo:

• implementation-spec-engine
• implementation-loop-engine

Essa trilha serve para qualquer tipo de implementação da empresa: feature nova, bugfix, ajuste, refatoração, integração com SaaS/API, POC, hotfix, criação do zero, processos não codificados, BI/dados, infra e documentação operacional.

Modernização

Clona na raiz alvo:

• modernization-planning-template
• modernization-spec-driven-dev-guide

Essa trilha serve para iniciativas específicas de modernização, mantendo o planejamento e a execução spec-driven separados, mas complementares.

Segurança Operacional

O CozinhaOS não apaga pastas existentes.

Quando uma pasta de destino já existe:

• Sem flags extras, ele pula a pasta.
• Com --update-existing, ele roda apenas git pull --ff-only se a pasta for um repositório Git.
• Se a pasta existir mas não for Git, ele bloqueia a atualização.

JSON Para Automação

Todos os comandos principais aceitam --json:

cozinhaos list --json
cozinhaos doctor --json
cozinhaos install implementation --dry-run --json

Formato de sucesso:

{
  "ok": true,
  "install": {
    "stack": "implementation",
    "targetRoot": "/repo",
    "protocol": "https",
    "dryRun": true,
    "accessCheck": true,
    "results": []
  }
}

Doctor

Verifica Node, Git, raiz alvo, permissão de escrita e presença dos repositórios:

cozinhaos doctor

Para testar também se a máquina consegue acessar os quatro repositórios privados da Alest antes de clonar:

cozinhaos doctor --check-access

Esse preflight usa git ls-remote --heads em cada repo. Ele não clona nada; só confirma se o Git/GitHub está pronto para o clone.

Com SSH:

cozinhaos doctor --check-access --ssh

Com JSON:

cozinhaos doctor --check-access --json

Desenvolvimento

npm run check
npm test
npm run validate

Smoke test sem clonar:

node ./bin/cozinhaos.js install implementation --dry-run --target /tmp/cozinhaos-smoke

Teste de autenticação GitHub para um repo privado:

git ls-remote --heads https://github.com/alest-github/implementation-loop-engine.git

API SDK

O pacote também exporta funções para uso programático:

import { installStack, listStacks, doctor } from "alest-cozinhaos-sdk";

console.log(listStacks());

await installStack("implementation", {
	target: "/caminho/do/repo",
	dryRun: true,
});

console.log(await doctor());