Utilitários CLI em TypeScript: da ideia à ferramenta pronta em uma hora

Por que o TypeScript é a linguagem ideal para utilitários CLI?

Se você programa em Python e de repente pensou em criar um utilitário de console, provavelmente seu primeiro impulso é usar argparse ou click. E isso é lógico. Mas e se eu lhe dissesse que o TypeScript pode superar qualquer ferramenta Python no mundo CLI? Sim, você não ouviu errado.

TypeScript não é apenas "JavaScript com tipos". É uma linguagem que transforma o desenvolvimento de utilitários CLI em um processo previsível e seguro. Chega de "por que tenho undefined em vez de string?" ou "passei um número e ele virou string". A tipagem forte elimina toda uma classe de erros já na fase de compilação.

Mas a principal vantagem é o ecossistema. O Node.js permite executar código TypeScript em qualquer lugar: no servidor, no Docker, no Raspberry Pi. E o npm torna a publicação do utilitário uma questão de cinco minutos. Hoje percorreremos todo o caminho: de uma pasta vazia até um utilitário CLI pronto, que pode ser instalado com o comando npm install -g.

O que vamos construir?

Imagine: você trabalha frequentemente com arquivos JSON e precisa contar rapidamente o número de campos, verificar a validade ou converter para CSV. Escreveremos o utilitário json-toolkit, que faz três coisas:

\n
• validate — verifica se o JSON é válido;
\n
• count — conta o número de chaves de primeiro nível;
\n
• to-csv — converte um array de objetos para CSV.
\n

Parece simples? Sim. Mas com este exemplo você aprenderá todas as técnicas principais: processamento de argumentos, trabalho com sistema de arquivos, cores no terminal e tratamento de erros.

Passo 1. Configuração do projeto

Primeiro, criamos uma pasta e inicializamos o projeto:

mkdir json-toolkit\ncd json-toolkit\nnpm init -y

Agora instalamos o TypeScript e os pacotes necessários:

npm install -D typescript @types/node\nnpm install commander chalk

\n
• commander — biblioteca para análise de argumentos de linha de comando (similar ao argparse do Python, mas mais conveniente);
\n
• chalk — coloriza a saída no terminal;
\n
• @types/node — tipos para Node.js.
\n

Criamos o tsconfig.json:

{\n  "compilerOptions": {\n    "target": "ES2020",\n    "module": "commonjs",\n    "outDir": "./dist",\n    "rootDir": "./src",\n    "strict": true,\n    "esModuleInterop": true,\n    "declaration": true\n  },\n  "include": ["src/**/*"]\n}

Observe: outDir é a pasta onde o código será compilado, e rootDir são os arquivos fonte. Esta é uma prática padrão para projetos TypeScript.

Passo 2. Escrevendo o núcleo do utilitário

Criamos a pasta src e o arquivo src/index.ts. Começamos com as importações e configuração do commander:

import { Command } from 'commander';\nimport { readFileSync, existsSync } from 'fs';\nimport chalk from 'chalk';\n\nconst program = new Command();\n\nprogram\n  .name('json-toolkit')\n  .description('Utilitário para trabalhar com arquivos JSON')\n  .version('1.0.0');\n\nprogram\n  .command('validate')\n  .argument('<file>', 'caminho para o arquivo JSON')\n  .description('Verificar validade do JSON')\n  .action((file: string) => {\n    try {\n      const content = readFileSync(file, 'utf-8');\n      JSON.parse(content);\n      console.log(chalk.green('✓ JSON válido!'));\n    } catch (err) {\n      console.error(chalk.red('✗ Erro:'), (err as Error).message);\n    }\n  });\n\nprogram\n  .command('count')\n  .argument('<file>', 'caminho para o arquivo JSON')\n  .description('Contar o número de chaves de primeiro nível')\n  .action((file: string) => {\n    if (!existsSync(file)) {\n      console.error(chalk.red('Arquivo não encontrado!'));\n      return;\n    }\n    const content = readFileSync(file, 'utf-8');\n    const data = JSON.parse(content);\n    const keys = Object