@fc/cli-utils
Pacote privado com funções utilitárias para scripts e ferramentas de linha de comando em Node: execução de comandos sem shell, resolução do pnpm, leitura de .env, argumentos, raiz do workspace e abertura do navegador.
Fronteira do pacote
Só entra o que é genérico de CLI. Quase tudo é exclusivo de Node e declara // @env node; a exceção é mensagemDeErro, isomórfica, que mora aqui porque todos os seus consumidores são scripts. Regras de domínio, apoio de teste e utilidades isomórficas de uso geral ficam fora: as duas últimas pertencem a @fc/test-utils e @fc/utils.
Módulos
Não há barrel: cada função é publicada por subpath, e o consumidor importa o arquivo que a declara.
| Subpath | Conteúdo |
|---|---|
@fc/cli-utils/processos/executarComando | executarComando — spawn sem shell que resolve no close e rejeita com ErroComando, inclusive quando o executável não existe |
@fc/cli-utils/processos/executarPnpm | executarPnpm — pnpm <args> pelo pnpm que iniciou o processo |
@fc/cli-utils/processos/obterComandoPnpm | obterComandoPnpm — executável e argumentos para rodar o pnpm sem shell em qualquer sistema, inclusive Windows |
@fc/cli-utils/processos/executarCli | executarCli — ponto de entrada que traduz ErroCli e prompt cancelado em código de saída, sem pilha |
@fc/cli-utils/erros/ErroCli | ErroCli — falha esperada de um CLI |
@fc/cli-utils/erros/ErroComando | ErroComando — comando filho que falhou, com código e sinal |
@fc/cli-utils/ambiente/lerArquivoEnv | lerArquivoEnv — variáveis de um arquivo .env; {} quando ele não existe |
@fc/cli-utils/workspace/obterRaizMonorepo | obterRaizMonorepo — diretório do pnpm-workspace.yaml mais próximo |
@fc/cli-utils/argumentos/lerArgumento | lerArgumento — valor que segue --opcao |
@fc/cli-utils/argumentos/temFlag | temFlag — presença de --flag |
@fc/cli-utils/navegador/abrirNoNavegador | abrirNoNavegador — abre uma URL no navegador padrão, sem shell e sem prender o processo |
@fc/cli-utils/navegador/montarComandoNavegador | montarComandoNavegador — comando por sistema (open, xdg-open, rundll32) |
@fc/cli-utils/processos/ehExecucaoDireta | ehExecucaoDireta — o módulo é o script invocado na linha de comando (o import.meta.main chega vazio sob o tsx) |
@fc/cli-utils/erros/mensagemDeErro | mensagemDeErro — mensagem de um valor capturado por catch |
@fc/cli-utils/http/consultarUrl | consultarUrl — GET com prazo que nunca lança: { ok, status } ou { ok: false, erro } |
@fc/cli-utils/http/aguardarUrl | aguardarUrl — sonda uma URL até ficar pronta, com prazo, critério, desistência e marcos de progresso |
@fc/cli-utils/workspace/lerManifesto | lerManifesto — package.json de um diretório, undefined quando não existe |
@fc/cli-utils/argumentos/fatiarArgumentos | fatiarArgumentos — lotes que cabem na linha de comando (LIMITE_LINHA_COMANDO em constantes) |
@fc/cli-utils/ambiente/lerInteiroPositivoDoAmbiente | lerInteiroPositivoDoAmbiente — inteiro positivo de uma variável, com padrão e aviso opcional |
@fc/cli-utils/prompts/* | perguntarTexto, perguntarConfirmacao, perguntarSelecao, perguntarMultiSelecao, ehVoltar, VOLTAR — prompts sobre @clack/core que distinguem ESC (voltar) de Ctrl+C (sair) |
@fc/cli-utils/tipos | Tipos públicos: ComandoPnpm, ResultadoHttp, Manifesto, RespostaPrompt, OpcaoPrompt e as opções de cada função |
Por que o pnpm precisa de tratamento
No Windows, o pnpm do PATH é um pnpm.cmd. Um spawn sem shell não o encontra, e executar o .cmd diretamente é recusado pelo Node desde a CVE-2024-27980. Quando o processo foi iniciado pelo pnpm, a variável npm_execpath aponta para o script do próprio pnpm; obterComandoPnpm o executa com o Node corrente, o que funciona em qualquer sistema e mantém a chamada sem shell. Fora do pnpm, ou com o pnpm binário, a função cai no pnpm do PATH.