Aprenda a crear herramientas de automatización CLI con Node.js

Bienvenido, soy Miguel y aquí les traigo otro nuevo artículo.

Cree una herramienta CLI de seguimiento de peso con oclif en Node

¡A los desarrolladores les encantan las herramientas CLI! Tanto es así que estoy seguro de que aprovecharíamos la oportunidad de hacer todo en una computadora con la comodidad de una línea de comandos.

¿Y por qué no hacer eso? Con la ayuda de bibliotecas y marcos modernos, construir nuestra propia CLI es cuestión de unas pocas horas o incluso minutos. Especialmente en Node, puede crear fácilmente interesantes interfaces de línea de comandos utilizando el marco oclif.

En este artículo, crearemos una herramienta CLI simple para ayudarnos a rastrear nuestro peso a lo largo del tiempo. Tiene características simples como agregar un nuevo registro de peso y mostrar registros anteriores.

Dado que usamos oclif para completar fácilmente esta tarea, intentemos comprender exactamente qué es.

¿Qué es Oclif?

Oclif es un marco que se utiliza para crear herramientas CLI en Node. Admite implementaciones de JavaScript y TypeScript. Oclif proporciona un amplio conjunto de funciones para diseñar e implementar programas de línea de comandos que se pueden ampliar fácilmente con plugins y hooks.

Comando único frente a comando múltiple

Podemos crear dos tipos de herramientas de línea de comandos en Oclif: comando único y comando múltiple. Las CLI de un solo comando proporcionan solo una opción de comando (similar a los comandos ls y curl en Linux).

Los programas de comandos múltiples admiten subcomandos que proceden del comando principal. git y npm son buenos ejemplos de herramientas de múltiples comandos.

En este tutorial, estamos construyendo un programa de múltiples comandos que admite subcomandos como add y show para agregar nuevos registros de peso y mostrar registros antiguos.

Inicializar el proyecto

Podemos inicializar el proyecto usando un comando simple:

npx oclif multi [project name]

Aquí, usamos npx, el corredor de paquetes npm, para inicializar el proyecto con oclif. El comando multi especifica que nuestro proyecto es una CLI de múltiples comandos.

Cuando ejecute este comando, se le pedirá que ingrese varios detalles sobre el proyecto que ayudarán a oclif a crear los archivos del proyecto inicial, incluido el package.json.

Dado que estamos usando JavaScript en este proyecto, asegúrese de ingresar «No» en el campo TypeScript.

Cuando se complete este paso, verá que oclif ha creado un nuevo directorio para nuestro proyecto con los siguientes subdirectorios:

├── README.md
├── bin
│ ├── run
│ └── run.cmd
├── package.json
├── node_modules
├── src
│ ├── commands
│ │ └── hello.js
│ └── index.js
├── test
│ ├── commands
│ │ └── hello.test.js
│ └── mocha.opts
└── package-lock.json

Esta es la CLI inicial que oclif crea para nosotros. Podemos agregar nuevos comandos para convertirlo al programa que necesitamos.

Como puede ver, nuestro proyecto ya tiene un comando predefinido llamado hello. Podemos usar la línea de comando para ejecutar este comando:

./bin/run hello

Si desea acceder a esta aplicación desde un alcance global usando el comando oclif_cli (que es el nombre del proyecto de nuestra CLI), use el comando npm link:

npm link

Ahora, podemos ejecutar nuestra aplicación en la línea de comando usando el oclif_cli comando:

Agregar nuevos comandos a nuestra aplicación

Como mencioné anteriormente, nuestra herramienta de seguimiento de peso tiene dos comandos principales: agregar y mostrar. El comando add nos permite agregar nuevos registros de weight y el comando show muestra weight registros pasados .

Al crear estos comandos, se encontrará con términos como banderas y argumentos. Primero aclaremos qué significan estos términos.

Banderas y argumentos

Si tiene algo de experiencia trabajando con programas de línea de comandos, es posible que ya sepa qué son las banderas y los argumentos.

Los indicadores proporcionan una forma de especificar opciones para ejecutar un comando en particular. Por ejemplo, considere el siguiente comando:

npm install -g oclif

Aquí, usamos la bandera -g para especificar que necesitamos instalar oclif globalmente. Pero no es necesario incluir esta bandera con cada comando. Solo tienes que usar una bandera si quieres activar la opción que representa.

Crea el primer comando de la aplicación

Podemos usar el siguiente comando para agregar nuevos comandos a nuestro programa:

npx oclif command [command-name]

Crea todos los archivos necesarios para el nuevo comando y actualiza el archivo README.

Agregaremos nuestro primer comando add, siguiendo este formato:

npx oclif command add

Agregar un nuevo comando a la CLI es tan simple como eso. Ahora, el comando oclif_cli add está listo para usarse. Sin embargo, todavía tenemos que implementar su lógica interna.

Para lograr esto, debemos cambiar el archivo add.js ya creado dentro del directorio src.

El comando add completamente implementado debería poder aceptar un argumento que especifique el peso del usuario y registrarlo con una marca de tiempo.

Por lo tanto, el código debería poder leer un argumento weight y guardarlo en un archivo con la fecha y hora en que se agregó el registro.

Para ello, cambiamos la clase AddCommand (que ya está definida por oclif) para incluir la siguiente implementación:

Aquí, hemos dado una descripción al comando add y definió el argumento que acepta. Declaramos el nombre del argumento (weight) y agregue una descripción para dar instrucciones a los usuarios sobre cómo pasar el argumento.

Como hemos definido el argumento como «obligatorio», los usuarios no podrán ejecutar el comando oclif_cli add sin proporcionar un valor de peso.

La parte más importante de la implementación es el código dentro del asincrónico función run. Se llama cada vez que el usuario ejecuta el mando add.

Lee el argumento pasado con el comando y usa el método add del Weightclass (que implementaremos más adelante) para guardar los datos en un archivo. Una vez que el guardado se completa con éxito, registra un mensaje de éxito en la consola.

Crear el comando show

Ahora, vamos a crear el segundo mandato de nuestro programa: show. Se utiliza para mostrar los datos de peso ya guardados en el archivo en la línea de comando.

Podemos crear el comando show de la misma manera que creamos el comando add:

npx oclif command show

Implementemos el comando show como lo hicimos antes. La única diferencia aquí es que el comando show acepta una bandera opcional. Esta marca opcional permite a los usuarios especificar cuántos registros anteriores quieren ver.

Podemos definir la bandera (nombrada count) así:

ShowCommand.flags = {
count: flags.string({char: 'c', description: 'count of past records to be displayed'}),
help: flags.help({char: 'h'})
}

Con la función flags.string que crea nuestra nueva bandera, podemos pasar un carácter para usar para la bandera y una descripción. Cuando se utiliza la función de cadena para crear una bandera, los usuarios pueden pasar un argumento con ella.

Para nuestro programa, hemos declarado este argumento como requerido. Entonces, este argumento es esencial cuando se usa la bandera count.

Puede obtener más información sobre los diferentes tipos de banderas de oclif y las opciones aceptadas en la documentación oficial.

También estamos creando una bandera de ayuda usando la función incorporada de oclif flags.help para que los usuarios puedan obtener ayuda con el uso del comando.

La clase showCommand completa de nuestro programa se ve así:

Nuevamente, dentro de la función run, definimos qué sucede cuando el usuario ejecuta este comando. Analiza las banderas que hemos pasado (si las hay) y lee el argumento pasado con la bandera count.

Invoca el método show de la clase Weight para recuperar el número necesario de registros pasados. Por último, registra los datos recuperados en la consola en orden descendente según el tiempo de creación del registro.

Implementar la clase de peso

Usamos dos métodos de la clase Weight en nuestro programa en implementaciones anteriores. Ahora crearemos esta clase dentro de un nuevo directorio llamado api en el directorio src.

Dentro del directorio api, también creamos una carpeta llamada weightTracker para guardar el archivo JSON en el que estamos almacenando nuestros registros de peso. El archivo JSON recibe el nombre weights.json.

No entraré en demasiados detalles sobre cómo se implementa esta clase. En términos abstractos, lo que hemos hecho aquí es esto:

Pruebe nuestra herramienta CLI de seguimiento de peso

Ahora hemos implementado completamente nuestro programa. Todo lo que queda por hacer es jugar con él y ver cómo funciona todo junto:

Gracias por leer este artículo.