Creación de la próxima CLI

Si no estás familiarizado con las CLI, hagamos un breve repaso. CLI significa Command-Line Interface (Interfaz de Línea de Comandos) y es una herramienta que utiliza una interfaz basada en texto, generalmente accesible dentro de una aplicación tipo Terminal o un entorno tipo shell.

Los lectores habituales sabrán que ya tenemos una CLIque utilizamos como alternativa al Dashboard. Te permite administrar tu cuenta de Vonage y usar los productos de Vonage desde la línea de comandos. Hemos tenido esta herramienta durante aproximadamente 4 años, y está escrita en Node.js. Utiliza el archivo commander.js y ha crecido bastante a medida que hemos ido añadiendo funcionalidades.

Debido a que la herramienta se ha hecho bastante grande, nos hemos topado con las limitaciones del framework que estamos utilizando. Commander tiene una forma específica de manejar los comandos de alias y un límite duro en el número de alias que un comando puede tener. Por ejemplo, nexmo app:list, nexmo apps:list, nexmo apps y nexmo allistan todas tus aplicaciones de Vonage. Pero para lograr eso con Commander, tuvimos que duplicar algo de código. Creamos dos comandos, cada uno con un alias, que ambos necesitan ser mantenidos. Esto ha aumentado la barrera para que la gente contribuya. También aumenta la posibilidad de que alguien (principalmente yo) se olvide de actualizar el menú de ayuda para ambos antes de un lanzamiento.

Commander es estupendo para crear CLI más pequeñas, pero a medida que la CLI ha ido creciendo en alcance y funciones, no ha podido hacer frente a algunos de nuestros requisitos. Cuando actualizamos nuestra API de Applications para soportar múltiples capacidades en la misma Aplicación, pensamos que la gente no debería tener que recordar 9 banderas para un comando. Así que mejoramos la experiencia del desarrollador para la CLI, añadiendo un aviso interactivo que guía a la gente a través del proceso de creación de Aplicaciones. Dado que Commander no soporta un modo interactivo, también incorporamos Inquirer.js como dependencia.

Probablemente estés viendo a dónde quiero llegar con esto. Las soluciones que hemos estado utilizando para compensar las limitaciones del framework han hecho más difícil mantener y actualizar nuestra CLI. La CLI es algo que todos usamos a diario, por lo que es bastante esencial, y estamos invirtiendo tiempo en reescribirla. Pensé en compartir el proceso que estamos utilizando para trabajar en nuestra próxima aplicación CLI, en caso de que estés interesado o tengas un proyecto como este tú mismo algún día.

Retrospectiva

Antes de lanzarnos directamente a un nuevo proyecto de código, nos tomamos el tiempo necesario para asegurarnos de que teníamos una estructura clara. Iniciamos el proceso con una retrospectiva de la CLI actual. Hicimos una lista de algunas cosas sobre la CLI actual: "cosas que hacemos bien", "cosas que deberíamos hacer mejor"y "cosas que deberíamos dejar de hacer". He aquí algunos ejemplos de cosas que se nos han ocurrido para todas esas columnas.

Cosas que estamos haciendo bien:

• Nuestra CLI es un producto de primera clase, a la altura de nuestros SDK de servidor.

• La CLI ofrece más de una manera de hacer algunas cosas (como el listado de Applications que mencioné antes).

Cosas que deberíamos hacer mejor:

• Modo interactivo en la mayoría de los comandos.

• Formateadores para CSV, JSON y salida estándar.

• Soporte para autocompletar comandos.

• Soporta plugins.

• Reducir nuestras dependencias.

Cosas que deberíamos dejar de hacer:

• Deja de azotar ese viejo código base. 😅

Se puede ver que teníamos muchas más cosas en la categoría "debería mejorar". Esa retrospectiva fue muy útil para identificar una lista de requisitos.

Recopilación de requisitos

A continuación, elaboramos una lista de casos de uso que queríamos para la CLI. Nos basamos en los casos de uso actuales que admite la CLI. Y las peticiones de funciones que queríamos implementar. Algunas de ellas habrían sido demasiado costosas con el marco existente (por ejemplo, la compatibilidad con plugins). Las dividimos en requisitos de cara al usuario como "Los usuarios deben poder listar sus Applications.". Y requisitos no relacionados con el usuario, como "Se ofrecerán múltiples formatos de salida (tablas ASCII, CSV, JSON).".

Como puedes imaginar, acabamos teniendo una larga lista de casos de uso. Aunque esperamos implementarlos todos, pensamos que hacerlo de una sola vez sería contraproducente y nos llevaría mucho tiempo. Así que los hemos dividido en funciones básicas y funciones para las que deberíamos crear plugins. Para hacerlas aún más manejables, hemos asignado versiones objetivo para todas ellas. Por ejemplo, la mayoría de los casos de autenticación se implementarán en la V1, mientras que unos pocos pasarán a la V2".Envío de SMS"será uno de los primeros plugins que implementemos.

Ejemplos de comandos

Después de desglosar los requisitos en versiones manejables, elaboramos un conjunto de normas para la CLI. Estamos utilizando ejemplos para asegurarnos de que creamos una experiencia de desarrollador muy coherente en nuestra nueva herramienta. Esta es la lista de normas a la que hemos llegado:

• La nomenclatura de los comandos debe referirse a la acción del usuario, no a los nombres de nuestra API, es decir nexmo number format --number=012345678 --country=GB en lugar de nexmo insight basic --format --number=12345678 --country=GB.

• Los nombres de mando son un sustantivo singular, es decir nexmo app o nexmo number.

• La segunda parte de la orden debe ser un verbo activo, es decir nexmo app create o nexmo number list.

• Se prefieren las banderas a los argumentos posicionales. es decir. nexmo app update --name MyBetterNamedApp.

• Los indicadores pueden tener versiones abreviadas, por ejemplo nexmo app update -n MyBetterNamedApp.

• Las banderas universales deben incluir --help, --silent, --verbose, --debug, --format, --non-interactive y --color.

• Los comandos paginados utilizarán --limit y --offsetindependientemente del mecanismo de paginación subyacente de nuestras distintas API.

¿Y ahora qué?

La creación de una nueva CLI comienza con la reflexión sobre la antigua, si la tiene, la recopilación de requisitos y la determinación de cuáles son los más importantes para la experiencia del usuario. Con una mejor comprensión de lo que queríamos de la próxima iteración de la CLI, hemos comenzado la identificación de marcos de construcción CLI y compararlos con nuestros requisitos. Voy a cubrir este proceso con más detalle en la próxima entrada del blog.

Hasta entonces, estamos trabajando en la mejora de nuestra CLI, y usted puede seguir nuestro progreso en https://github.com/nexmo/nexmo-cli. Si tienes alguna sugerencia o problema, no dudes en plantearlo en GitHub o en nuestra comunidad slack.