Utilidades CLI en TypeScript: de la idea a la herramienta lista en una hora

¿Por qué TypeScript es el lenguaje ideal para utilidades CLI?

Si escribes en Python y de repente piensas en crear una utilidad de consola, lo más probable es que tu primer impulso sea usar argparse o click. Y tiene sentido. Pero ¿y si te digo que TypeScript puede darle una ventaja a cualquier herramienta de Python en el mundo de las CLI? Sí, no has oído mal.

TypeScript no es solo "JavaScript con tipos". Es un lenguaje que convierte el desarrollo de utilidades CLI en un proceso predecible y seguro. Nada más de "¿por qué tengo undefined en lugar de una cadena?" o "pasé un número y se convirtió en cadena". La tipificación estricta elimina toda una clase de errores ya en la etapa de compilación.

Pero la principal ventaja es el ecosistema. Node.js permite ejecutar código TypeScript en cualquier lugar: en el servidor, en Docker, en una Raspberry Pi. Y npm hace que publicar una utilidad sea cuestión de cinco minutos. Hoy recorreremos todo el camino: desde una carpeta vacía hasta una utilidad CLI lista que se pueda instalar con el comando npm install -g.

¿Qué vamos a construir?

Imagina: trabajas frecuentemente con archivos JSON y necesitas contar rápidamente la cantidad de campos, verificar la validez o convertir a CSV. Escribiremos la utilidad json-toolkit, que hace tres cosas:

\n
• validate — verifica si el JSON es válido;
\n
• count — cuenta la cantidad de claves de nivel superior;
\n
• to-csv — convierte un array de objetos a CSV.
\n

¿Suena simple? Sí. Pero con este ejemplo dominarás todas las técnicas clave: manejo de argumentos, trabajo con el sistema de archivos, colores en la terminal y manejo de errores.

Paso 1. Configuración del proyecto

Primero, creamos una carpeta e inicializamos el proyecto:

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

Ahora instalamos TypeScript y los paquetes necesarios:

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

\n
• commander — biblioteca para analizar argumentos de línea de comandos (similar al argparse de Python, pero más cómodo);
\n
• chalk — colorea la salida en la terminal;
\n
• @types/node — tipos para Node.js.
\n

Creamos 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}

Observa: outDir es la carpeta donde se compilará el código, y rootDir son los archivos fuente. Esta es una práctica estándar para proyectos TypeScript.

Paso 2. Escribimos el núcleo de la utilidad

Creamos la carpeta src y el archivo src/index.ts. Empezamos con las importaciones y la configuración de 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('Utilidad para trabajar con archivos JSON')\n  .version('1.0.0');\n\nprogram\n  .command('validate')\n  .argument('<file>', 'ruta al archivo JSON')\n  .description('Verificar la validez del 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('✗ Error:'), (err as Error).message);\n    }\n  });\n\nprogram\n  .command('count')\n  .argument('<file>', 'ruta al archivo JSON')\n  .description('Contar la cantidad de claves de nivel superior')\n  .action((file: string) => {\n    if (!existsSync(file)) {\n      console.error(chalk.red('¡Archivo no encontrado!'));\n      return;\n    }\n    const content = readFileSync(file, 'utf-8');\n    const data = JSON.parse(content);\n    const keys = Object