Farm CLI

CLI interna da Farm para acelerar operações recorrentes no workspace frontend de microfrontends.

O farm-cli centraliza comandos que o time executa todos os dias: descobrir serviços, baixar repositórios, validar setup local, subir MFEs, trocar ambiente, verificar status Git e manter o import map local coerente com os metadados da plataforma.

Instalacao

O pacote esta publicado no NPM como @farm-investimentos/farm-cli.

Instalacao global

npm install -g @farm-investimentos/farm-cli
farm list

Essa e a forma mais simples para uso no dia a dia.

Uso sem instalar globalmente

npx @farm-investimentos/farm-cli list

Instalacao como dependencia de desenvolvimento

npm install -D @farm-investimentos/farm-cli
npx farm list

Desenvolvimento local do CLI

Use este fluxo apenas quando estiver contribuindo neste repositório:

npm install
npm run build
node dist/index.js list

Para testar o binario localmente:

npm link
farm list

Visao Geral

O objetivo do farm-cli e reduzir tempo e atrito nas operações locais do frontend. Ele não muda como cada microfrontend funciona internamente; ele cria uma camada comum para executar tarefas que se repetem entre vários repositórios.

Com ele, o time consegue:

• descobrir serviços e profiles conhecidos pela plataforma
• listar repositórios frontend existentes no GitHub
• clonar repositórios e instalar dependências
• verificar status Git dos repositórios do workspace
• validar setup local antes de subir serviços
• subir, listar e parar MFEs gerenciados pelo CLI
• reiniciar serviços em outro ambiente
• disparar deploy remoto de branches em develop e uat
• verificar drift do import map do orquestrador

Conceitos

Workspace

O workspace e a pasta que agrupa os repositórios frontend da Farm, por exemplo:

farmtech/
  front-mfe-orquestrador/
  front-mfe-global/
  front-mfe-menu/
  front-mfe-loginv2/
  front-mfe-credito/

O CLI tenta descobrir a raiz do workspace procurando marcadores conhecidos, como front-mfe-orquestrador e front-mfe-menu. Quando necessário, voce pode informar o caminho manualmente:

farm list --workspace /caminho/do/workspace

Manifesto

O manifesto e o catálogo operacional dos serviços que o CLI sabe operar com metadados completos.

Ele vive em src/manifest/front.manifest.ts e descreve, para cada serviço:

• id: nome curto usado nos comandos, como credito ou menu
• path: pasta esperada no workspace
• repository: URL Git usada para clonar o repo quando ele estiver ausente
• defaultBranch: branch padrão esperada
• node: versão de Node recomendada para o repo
• packageManager: npm, yarn ou pnpm
• scripts: scripts relevantes, como serve, build, lint e test
• runtime: porta local, chave de import map, dependências e profiles padrão

O manifesto não e uma lista completa de todos os repositórios existentes no GitHub. Ele e a fonte de verdade para os serviços que o CLI consegue operar de forma padronizada.

Para descobrir repositórios remotos que ainda não estão no manifesto, use:

farm repos

Para instalar um repositório que ainda não esta no manifesto, o farm install tambem aceita nomes crus, slugs e URLs Git:

farm install front-mfe-relacionamento
farm install Farm-Investimentos/front-mfe-relacionamento
farm install [email protected]:Farm-Investimentos/front-mfe-relacionamento.git

Quando um repo novo passar a fazer parte dos fluxos padronizados de up, doctor, status, switch ou importmap, ele deve ser adicionado ao manifesto com seus metadados operacionais.

Serviços

Um serviço e um microfrontend ou repositório operacional registrado no manifesto.

Exemplos:

• orquestrador
• global
• menu
• loginv2
• credito

Voce usa o id do serviço nos comandos:

farm up credito
farm down credito

Profiles

Profiles agrupam serviços que costumam ser usados juntos.

Profiles atuais:

• base
• shell

Hoje ambos resolvem para:

• orquestrador
• global
• menu
• loginv2

Exemplo:

farm up shell

Runtime Gerenciado

Por padrão, farm up sobe serviços em background. O CLI registra os processos em:

.farm-cli/runtime-processes.json
.farm-cli/logs/<service>.log

Isso permite:

farm ps
farm down credito
farm down

farm down sem argumentos interrompe todos os serviços gerenciados.

Ambientes

O CLI suporta ambientes como:

• dev
• uat
• local
• prd

Quando um repo possui serve:<ambiente>, o CLI usa esse script. Quando não possui, usa o script padrão definido no manifesto.

Exemplos:

farm up shell --uat
farm switch --dev

farm switch não faz hot swap no browser. Ele para e sobe novamente os serviços gerenciados no ambiente alvo.

Import Map

O orquestrador usa import map para apontar MFEs locais/remotos. O CLI consegue verificar se as entradas gerenciadas estao alinhadas com o manifesto:

farm importmap sync

Por padrão, esse comando apenas verifica. Para escrever no arquivo:

farm importmap sync --write

Use --write com cuidado, porque altera arquivo versionado do orquestrador.

Comandos

| Comando | Objetivo | | --- | --- | | farm list | Lista serviços e profiles registrados no manifesto | | farm repos | Lista repositórios remotos front-* e farm-mfe-* no GitHub | | farm install | Clona repositórios ausentes e garante dependências locais | | farm status | Mostra status Git dos repositórios do workspace | | farm doctor | Valida problemas comuns de setup local | | farm up | Sobe serviços ou profiles localmente | | farm deploy | Dispara workflow remoto de deploy via GitHub Actions | | farm ps | Lista processos gerenciados pelo CLI | | farm down | Para processos gerenciados pelo CLI | | farm switch | Reinicia serviços em outro ambiente | | farm importmap sync | Verifica ou sincroniza import map do orquestrador |

Fluxos Comuns

Descobrir o workspace

farm list
farm status --changed-only
farm doctor

Ver repositórios frontend no GitHub

farm repos
farm repos --prefix front-mfe- farm-mfe-
farm repos --json

farm repos usa o GitHub CLI (gh). Se o gh não estiver instalado, o CLI mostra instrucoes de instalacao para o sistema atual.

Baixar repositórios e dependências

farm install credito
farm install shell
farm install front-mfe-relacionamento
farm install Farm-Investimentos/front-mfe-relacionamento
farm install [email protected]:Farm-Investimentos/front-mfe-relacionamento.git

Comportamentos importantes:

• se o repositório estiver ausente, o CLI tenta clonar via git clone
• se git clone falhar em repositórios GitHub e gh estiver disponivel, o CLI tenta gh repo clone
• nomes simples de repo assumem a organizacao Farm-Investimentos
• se node_modules estiver ausente, o CLI instala dependências
• --force-install reinstala dependências mesmo quando node_modules ja existe

Subir a shell do frontend

farm up shell
farm ps

Subir em outro ambiente

farm up shell --uat
farm switch --dev

Publicar uma branch remota

farm deploy cadastros --env-uat --branch uat
farm deploy cadastros --env-dev --branch feature/minha-branch

O comando acompanha a execução da action no GitHub e só termina quando o workflow concluir com sucesso ou erro.

Consultar qual branch esta em um ambiente

farm env cadastros --uat
farm env cadastros --dev

Esse modo consulta a ultima execucao bem-sucedida da workflow do ambiente e mostra a branch e o SHA publicados.

Se voce ainda precisar manter compatibilidade com scripts antigos, o alias legado continua aceito:

farm deploy cadastros --env-uat --status
farm deploy cadastros --env-dev --status

Subir um MFE especifico

farm up credito
farm up credito --solo

Sem --solo, o CLI pode incluir profiles/dependências padrão definidos no manifesto para que o MFE rode dentro de um contexto local coerente.

Ver logs no terminal

farm up credito -v

-v ou --foreground executa anexado ao terminal e mostra logs diretamente.

Parar serviços

farm down credito
farm down orquestrador global menu loginv2
farm down

Verificar import map

farm importmap sync
farm importmap sync --write

Comportamentos Importantes

• farm up sobe em background por padrão
• farm deploy usa o GitHub CLI (gh) e exige que a branch ja exista remotamente
• farm env consulta a ultima execucao bem-sucedida da workflow como fonte de verdade do ambiente
• farm deploy --status continua disponivel como alias legado para compatibilidade
• farm up -v ou farm up --foreground executa anexado ao terminal
• farm up --dry-run mostra o plano sem iniciar processos
• farm switch reinicia serviços gerenciados no ambiente escolhido
• farm status --fetch atualiza refs da origin antes de comparar branches
• farm doctor valida setup com base no manifesto e no workspace local
• farm install tenta respeitar a versão de Node do repo usando nvm, fnm, asdf ou volta
• farm importmap sync apenas verifica por padrão
• farm importmap sync --write altera arquivo versionado do orquestrador

Uso Com Agentes De IA

O farm-cli tambem foi pensado para reduzir ambiguidade quando agentes de IA operam o workspace.

Em vez de navegar manualmente por vários repositórios, o agente pode usar comandos previsíveis:

farm list
farm status --changed-only
farm doctor
farm up shell
farm ps
farm deploy cadastros --env-uat --branch uat

Este repositório inclui referencias operacionais para agentes:

• skill para Codex em skills/farm-front-workspace/SKILL.md
• skill para Claude em .claude/skills/farm-front-workspace/SKILL.md

Codex

Instalacao sugerida da skill:

mkdir -p ~/.codex/skills
ln -s "$(pwd)/skills/farm-front-workspace" ~/.codex/skills/farm-front-workspace

Claude

Para uso por projeto, basta manter a skill em .claude/skills/ dentro do repositório.

Se quiser instalar globalmente:

mkdir -p ~/.claude/skills
ln -s "$(pwd)/.claude/skills/farm-front-workspace" ~/.claude/skills/farm-front-workspace

Estrutura Do Projeto

farm-cli/
  src/
    commands/
    manifest/
    services/
    utils/
  skills/
    farm-front-workspace/
      SKILL.md
      agents/openai.yaml
      references/commands.md
  .claude/
    skills/
      farm-front-workspace/
        SKILL.md
        references/commands.md

Desenvolvimento

npm install
npm run typecheck
npm run build
npm test
npm run dev -- list

Ao rodar npm install, o repositório configura automaticamente core.hooksPath=.githooks.

O hook de pre-push executa npm test, que hoje valida:

• typecheck
• build

Publicacao

O repositório segue o mesmo fluxo usado no front-mfe-libs-ts: versionamento manual em develop, PR de release para main e publicação no NPM quando main recebe uma versão nova.

Fluxo:

1. Rode manualmente o workflow upgrade_version.yml.
2. Escolha o tipo de incremento:
   • patch para correções, ajustes de manifesto e documentação
   • minor para novas funcionalidades compatíveis
   • major para mudanças com quebra de compatibilidade
3. O workflow atualiza package.json e package-lock.json, cria uma branch chore-newversion_<versao> e abre PR para develop.
4. Depois que a versão estiver em develop, rode manualmente o workflow create_tag.yml.
5. Esse workflow cria a tag v<versao> e abre PR de develop para main.
6. Ao mergear esse PR na main, o workflow publish.yml:
   • roda npm ci
   • roda npm test
   • valida que a versão ainda não existe no NPM
   • publica no NPM com npm publish --access public

Esse fluxo evita publicar no NPM com uma versão já existente.

Pre-requisitos:

• secret NPM_TOKEN configurado no repositório
• permissão para o GITHUB_TOKEN criar branches, tags e pull requests
• branch develop atualizada com as mudanças antes de abrir o PR de release para main

Proximos Passos

Evolucoes naturais da ferramenta:

• adicionar farm logs <service>
• adicionar farm context <service> para contexto operacional rapido
• gerar import map local não versionado para o orquestrador
• expandir o manifesto para outros workflows da plataforma