Setup do Ambiente de Desenvolvimento

O desenvolvimento do Cactus V2 e gerenciado pelo workspace front-dev, que usa o FECA CLI (Front-End Cactus CLI) — ferramenta interna que centraliza setup, dev servers e gestao de repos.

Pre-requisitos

• Node.js >=24.14.1
• pnpm >=10.0.0 (obrigatorio — nao use npm ou yarn)
• Git

node --version   # >= 24.14.1
pnpm --version   # >= 10.0.0

Setup inicial (workspace front-dev)

# 1. Clonar o workspace
git clone git@github.com:cactus-agents/front-dev.git
cd front-dev

# 2. Rodar o setup interativo
pnpm start
# ou: ./setup.sh

O script de setup faz tudo automaticamente:

1. Verifica pre-requisitos (Node, pnpm)
2. Instala o FECA CLI em bin/feca
3. Solicita o GitHub PAT para acesso ao registry privado
4. Salva o token em repos/front-web-base/.npmrc (local ao projeto, nunca commitado)
5. Clona os repos (front-web-base, front-cactus-core, front-cactus-docs, front-ops)
6. Instala dependencias em todos os repos
7. Copia arquivos .env.example como .dev.vars e .env pre-preenchidos

Ao final, o ambiente esta pronto para usar.

Gerando o GitHub PAT

O setup vai solicitar um Personal Access Token com permissao de leitura no GitHub Packages.

1. Acesse github.com/settings/tokens → Generate new token (classic)
2. De um nome (ex: cactus-local) e defina uma expiracao
3. Marque o escopo read:packages
4. Clique em Generate token e copie o valor — ele so aparece uma vez

O token e salvo em repos/front-web-base/.npmrc (local ao projeto) e nunca deve ser commitado.

Usando o FECA CLI

Apos o setup, use o FECA CLI para o dia a dia:

feca          # abre a TUI interativa
feca --help   # lista todos os comandos

Comandos principais no dia-a-dia:

feca dev                         # base: auto (source/registry)
feca dev:base                    # alias de `feca dev`
feca dev:docs                    # docs: sobe Docusaurus em localhost:3000
feca dev --registry              # base com pacotes publicados
feca dev --pb-bet                # ativa brand (copia .dev.vars.pb-bet → .dev.vars)
feca dev --pb-bet --registry     # brand + registry (testa pacote publicado da brand)
feca update                      # pnpm update -i --latest no base (interativo)
feca update "@cactus-agents/*"   # update filtrado por pattern
feca install                     # pnpm install em TODOS os repos clonados
feca sync --install              # git pull workspace+repos + pnpm install (one-shot)
feca kill                        # lista e mata listeners zumbis em 5173-5180
feca status / sync / clone       # git status / pull / clone em todos os repos

TUI interativa

A interface TUI e a forma principal de trabalhar com o workspace:

Tela	O que faz
Dev	Seleciona repos + modo (core local / core registry) e inicia o dashboard
Status	Tabela com branch e status (clean/dirty) de cada repo
Sync	Puxa ultimas alteracoes de todos os repos
Exec	Executa qualquer comando em todos os repos
Reset	Cleanup: limpar builds, remover repos ou full reset

Dev Dashboard

A tela Dev oferece duas opcoes para front-web-base (radio):

• core local — pnpm dev: resolve @cactus-agents/* direto do source do front-cactus-core clonado (HMR sub-segundo). Fallback automatico pro registry se o core nao estiver clonado.
• core registry — pnpm dev --registry: forca pacotes publicados, ignora o core local. Use pra validar release.

E um checkbox independente para front-cactus-docs. Nao aparecem opcoes para front-cactus-core ou front-ops porque eles nao tem dev server — o core e auto-linkado do source, ops e so CI.

Cada processo ativo ocupa um painel com largura total do terminal, empilhados verticalmente. Quando rodando em registry mode, um badge amarelo REGISTRY aparece no topo.

Atalhos no dashboard:

Tecla	Acao
tab	Alternar entre paineis
r	Reiniciar processo ativo
i	Rodar pnpm install no painel ativo
c	Limpar logs
s	Pausar auto-scroll (navegar com ↑/↓)
q	Sair

Rodando repos individualmente

Quando precisar de mais controle, entre no repo especifico:

Template (front-web-base)

cd repos/front-web-base
pnpm dev               # auto: source do core se clonado, senao registry
pnpm dev --registry    # forca registry (pacotes publicados)
pnpm dev --local       # exige core clonado (fail-fast)
pnpm typecheck         # tsc via tsconfig.json (source paths + node_modules fallback)
pnpm test              # vitest com mesmo resolver

O .dev.vars ja vem pre-preenchido pelo setup.sh. Ajuste os valores conforme necessario para apontar para o ambiente correto.

SDK (front-cactus-core)

No fluxo atual, raramente precisa rodar o dev do core em paralelo — o pnpm dev do base le direto do src/*.ts do core. Use pnpm build/pnpm test quando precisar validar o pacote isoladamente ou antes de publicar.

cd repos/front-cactus-core
pnpm build    # build todos os pacotes (tsup ESM + CJS + .d.ts)
pnpm test     # rodar testes
pnpm dev      # tsup --watch (raramente necessario no novo fluxo)

Documentacao (front-cactus-docs)

cd repos/front-cactus-docs
pnpm start    # dev server em localhost:3000
pnpm build    # build estatico

GitHub Packages (auth para @cactus-agents/*)

O .npmrc configurado pelo setup ja cuida da autenticacao automaticamente. Se precisar configurar manualmente em outro projeto:

# repos/front-web-base/.npmrc  (local ao projeto)
@cactus-agents:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=ghp_SEU_TOKEN_AQUI

cuidado

O .npmrc com token e local ao projeto — nao use ~/.npmrc global para evitar expor o token. O .gitignore ja inclui .npmrc.

Para mais detalhes, veja GitHub Packages.

IDEs

VS Code

Extensoes recomendadas:

• Biome (biomejs.biome) — lint + format
• Tailwind CSS IntelliSense — autocomplete de classes
• Pretty TypeScript Errors — erros TS mais legiveis

Configuracao

O Biome substitui ESLint + Prettier. Configure o VS Code para formatar com Biome:

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true
}