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
• rodar revisoes de seguranca frontend orientadas a OWASP e supply-chain

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 | | farm security check | Executa revisao automatizada OWASP/supply-chain de um frontend | | farm security review | Executa revisao completa e gera relatorio Markdown automaticamente |

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

Rodar check de seguranca frontend

farm security review credito
farm security check credito
farm security check credito --output credito.md
farm security check credito --report
farm security check ./front-mfe-credito --audit --output credito.md
farm security check credito --github-security --report
farm security pentest credito --fail-on high --output credito.md

O comando faz uma revisao local orientada a OWASP Top 10 para frontend. Ele procura padroes como HTML dinamico, execucao de codigo, secrets hardcoded, storage de token, dependencias nao pinadas, scripts npm sensiveis, URLs dinamicas, source maps e pontos que exigem confirmacao humana.

Para o fluxo completo do dia a dia, prefira:

farm security review credito

Esse comando roda scan OWASP local, nosso npm supply-chain detector, npm audit, GitHub Security e gera um Markdown na raiz atual. Se quiser desligar alguma etapa:

farm security review credito --no-supply-chain
farm security review credito --no-audit
farm security review credito --no-github-security

Opcoes principais:

• --output <path> salva relatorio em .md, .txt ou .json
• --report gera automaticamente um Markdown na raiz atual
• --format md|txt|json define o formato quando a extensao nao for suficiente
• --supply-chain executa o detector local @otaviomarcal/npm-supply-chain-detector
• --audit roda npm audit --json quando houver package-lock.json
• --github-security consulta Dependabot, Code Scanning e Secret Scanning via GitHub CLI (gh)
• --github-repo owner/repo informa manualmente o repositorio quando o remote local nao for suficiente
• --external-script executa scripts/security/frontend-owasp-check.sh quando existir
• --fail-on high faz o comando falhar quando encontrar severidade igual ou maior que o limite

farm security pentest e alias de farm security check. O nome check e preferido porque o comando faz revisao automatizada local; ele nao substitui um pentest manual ou teste exploratorio autenticado.

Quando --github-security estiver ativo, o CLI tenta consultar:

• Dependabot alerts
• Code scanning alerts
• Secret scanning alerts

Se o gh nao estiver instalado, nao estiver autenticado ou o usuario nao tiver permissao nos endpoints de seguranca, o relatorio continua sendo gerado e registra essa indisponibilidade na secao GitHub Security.

No farm security review, o detector de supply-chain roda por padrao. No farm security check, ele roda apenas quando voce passar --supply-chain.

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
• farm security check nao altera arquivos do projeto analisado; apenas imprime resultado e, se solicitado, grava relatorio

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 security check credito --output credito.md

Este repositório inclui referencias operacionais para agentes:

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

Codex

Instalacao sugerida da skill:

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

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
ln -s "$(pwd)/.claude/skills/frontend-owasp-review" ~/.claude/skills/frontend-owasp-review

Estrutura Do Projeto

farm-cli/
  src/
    commands/
    manifest/
    services/
    utils/
  skills/
    farm-front-workspace/
      SKILL.md
      agents/openai.yaml
      references/commands.md
    frontend-owasp-review/
      SKILL.md
      agents/openai.yaml
  .claude/
    skills/
      farm-front-workspace/
        SKILL.md
        references/commands.md
      frontend-owasp-review/
        SKILL.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