Setup do Ambiente de Desenvolvimento

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

Pré-requisitos

Node.js 24.14.1 (versão pinada no .nvmrc do workspace)
pnpm >=10.0.0 (obrigatório — não use npm ou yarn)
Git com chave SSH configurada no GitHub
Um GitHub PAT com read:packages

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

:::info .nvmrc vs engines O engines.node dos repos declara >=24.0.0 (um piso), mas o .nvmrc do workspace pina 24.14.1. Use a do .nvmrc. :::

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
pnpm start
# ou: ./setup.sh
# ou, não-interativo: GITHUB_TOKEN=<pat> ./setup.sh --non-interactive

O script faz:

Verifica pré-requisitos (Node, pnpm)
Instala o FECA CLI em bin/feca
Obtém o GitHub PAT — do env GITHUB_TOKEN se estiver setado (modo não-interativo auto-detectado), senão via prompt oculto
Escreve repos/front-web-base/.npmrc (local ao projeto, gitignored) com o registry e o token
Clona os repos: feca clone --tag initial
Instala dependências: feca exec "pnpm install" --tag initial
Copia .env.example como .dev.vars / .env pré-preenchidos

:::caution O token nunca vai pelo chat Se você está pedindo ajuda a uma IA no setup, exporte GITHUB_TOKEN no seu shell e rode o script — nunca cole o valor do PAT numa conversa. :::

Repos clonados pelo setup

--tag initial cobre cinco repos:

Repo	Tags
`front-web-base`	`frontend`, `base`, `initial`
`front-cactus-core`	`frontend`, `core`, `initial`
`front-cactus-docs`	`frontend`, `docs`, `initial`
`front-ops`	`ops`, `initial`
`front-tests-e2e`	`e2e`, `tests`, `initial`

Os outros quatro repos do workspace ficam de fora e são clonados por tag quando necessário:

feca clone --tag service   # front-service-api, -dev-proxy, -warmup
feca clone --tag admin     # fecadm
feca clone --tag ops       # front-ops + os service workers + fecadm

A fonte de verdade da lista e das tags é o feca.yaml na raiz do workspace. Ver Serviços de infraestrutura e fecadm.

Gerando o GitHub PAT

Acesse github.com/settings/tokens → Generate new token (classic)
Dê um nome (ex: cactus-local) e defina uma expiração
Marque o escopo read:packages
Generate token e copie o valor — ele só aparece uma vez

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

Usando o FECA CLI

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

Comandos principais no dia-a-dia:

feca dev                         # base: auto (source do core / registry)
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
feca test                        # E2E Playwright (seleção interativa de brand + env)
feca update                      # update interativo (default: @cactus-agents/*)
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
feca kill                        # mata listeners zumbis nas portas de dev
feca status / sync / clone       # git status / pull / clone em todos os repos
feca code                        # abre o workspace na IDE
feca purge --brand DOMAIN        # purge de cache emergencial

Porta do dev server — não assuma 5173

O Vite do base usa DEV_PORT do .env.local (gitignored), com fallback para 5173, e roda com strictPort: true — se a porta estiver ocupada ele falha em vez de cair silenciosamente pra outra.

# repos/front-web-base/.env.local
DEV_PORT=5193

Isso existe para rodar workspaces paralelos (front-dev, front-dev-claude, front-dev-codex, …) sem colidir. Antes de um smoke test, leia o .env.local do seu workspace em vez de chutar a porta:

grep DEV_PORT repos/front-web-base/.env.local
curl -sI http://localhost:<porta>/

`feca kill`

O range default é 5170-5199 — cobre tanto o 5173 do Vite quanto a faixa dos workspaces paralelos.

feca kill                       # range default 5170-5199, interativo
feca kill --range 5170-5199     # explícito
feca kill --include-docs        # inclui a porta do Docusaurus
feca kill -y                    # sem confirmação

:::caution O --help está errado sobre o range O texto do feca --help (e a TUI) dizem "default 5173-5180". O código (lib/commands/kill.sh) usa 5170-5199. O range real é o do código; o texto de ajuda é um bug conhecido, já reportado. :::

TUI interativa

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 últimas alterações 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 opções para front-web-base (radio):

core local — pnpm dev: resolve @cactus-agents/* direto do source do front-cactus-core clonado (HMR sub-segundo). Fallback automático pro registry se o core não estiver clonado.
core registry — pnpm dev --registry: força pacotes publicados, ignora o core local. Use pra validar release.

E um checkbox independente para front-cactus-docs. Não aparecem opções para front-cactus-core nem front-ops porque eles não têm dev server.

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

Atalhos:

Tecla	Ação
`tab`	Alternar entre painéis
`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

Template (front-web-base)

cd repos/front-web-base
pnpm dev               # auto: source do core se clonado, senão registry
pnpm dev --registry    # força registry (pacotes publicados)
pnpm dev --local       # exige core clonado (fail-fast)
pnpm typecheck         # tsc via tsconfig.json (source paths + node_modules fallback)
pnpm typecheck:ci      # tsc via tsconfig.ci.json (só node_modules) — o que o CI roda
pnpm test              # vitest com o mesmo resolver
pnpm quality           # lint + check + check:dev-vars + typecheck + test
pnpm build             # produção (sempre resolve do registry)

O .dev.vars já vem pré-preenchido pelo setup.sh. Ajuste os valores conforme necessário.

SDK (front-cactus-core)

No fluxo atual, raramente precisa rodar o dev do core em paralelo — o pnpm dev do base lê direto do src/*.ts do core.

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

:::caution Pacote novo no core Depois de criar um pacote novo, rode node scripts/regen-tsconfig-paths.mjs no base para atualizar tsconfig.json e tsconfig.ci.json. :::

Documentação (front-cactus-docs)

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

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

O .npmrc configurado pelo setup já cuida da autenticação. Se precisar configurar manualmente:

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

cuidado

O .npmrc com token é local ao projeto — não use ~/.npmrc global para evitar expor o token para todos os projetos da máquina. O .gitignore já inclui .npmrc.

Para mais detalhes, veja GitHub Packages.

Falhas comuns no setup

Sintoma	Causa	Correção
`Permission denied (publickey)` no clone	SSH não configurado no GitHub	Adicionar a chave em GitHub → Settings → SSH keys
`401 Unauthorized` no `pnpm install`	PAT ausente/expirado ou sem `read:packages`	Regenerar o PAT e recriar o `.npmrc`
`GITHUB_TOKEN não está setado no env`	`--non-interactive` sem o export	`export GITHUB_TOKEN=<pat>` antes de rodar
Vite falha com porta ocupada	`strictPort: true` + porta em uso	`feca kill`, ou setar outro `DEV_PORT` no `.env.local`
`curl` no `localhost:5173` não responde	O workspace usa outra porta	`grep DEV_PORT repos/front-web-base/.env.local`

IDEs

VS Code

Extensões recomendadas:

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

O Biome substitui ESLint + Prettier:

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

Pré-requisitos​

Setup inicial (workspace front-dev)​

Repos clonados pelo setup​

Gerando o GitHub PAT​

Usando o FECA CLI​

Porta do dev server — não assuma 5173​

feca kill​

TUI interativa​

Dev Dashboard​

Rodando repos individualmente​

Template (front-web-base)​

SDK (front-cactus-core)​

Documentação (front-cactus-docs)​

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

Falhas comuns no setup​

IDEs​

VS Code​