Criando sua próxima CLI

Se você não está familiarizado com CLIs, vamos fazer uma breve revisão. CLI significa Interface de Linha de Comando e é uma ferramenta que utiliza uma interface baseada em texto, geralmente acessível em um aplicativo semelhante a um terminal ou em um ambiente semelhante a um shell.

Os leitores assíduos sabem que já temos uma CLI, que usamos como alternativa ao Painel. Ela permite que você gerencie sua Account da Vonage e usar os produtos da Vonage a partir da linha de comando. Temos essa ferramenta há cerca de 4 anos, e ela foi escrita em Node.js. Ela utiliza o framework commander.js e cresceu bastante à medida que fomos adicionando funcionalidades ao longo do tempo.

Como a ferramenta ficou bastante grande, chegamos aos limites da estrutura que estamos usando. O Commander tem uma maneira específica de lidar com comandos de alias e um limite rígido para o número de aliases que um comando pode ter. Por exemplo, nexmo app:list, nexmo apps:list, nexmo apps e nexmo al, todos listam suas Applications da Vonage. Mas, para conseguir isso com o Commander, tivemos que duplicar parte do código. Criamos dois comandos, cada um com um alias, e ambos precisam ser mantidos. Isso aumentou a dificuldade para as pessoas contribuírem. Também aumenta a chance de alguém (principalmente eu) se esquecer de atualizar o menu de ajuda para ambos antes de um lançamento.

O Commander é ótimo para desenvolver interfaces de linha de comando (CLI) menores, mas, à medida que a CLI cresceu em escopo e funcionalidades, ele não conseguiu mais atender a algumas de nossas necessidades. Quando atualizamos nossa API de Applications para oferecer suporte a vários recursos na mesma Application, achamos que as pessoas não deveriam ter que se lembrar de nove sinalizadores para um comando. Por isso, aprimoramos a experiência do desenvolvedor na CLI, adicionando um prompt interativo que orienta os usuários durante o processo de criação da Application. Como Commander não oferece suporte a um modo interativo, também incorporamos o o Inquirer.js como dependência.

Você provavelmente já está percebendo onde quero chegar. As soluções alternativas que temos usado para contornar as limitações do framework tornaram mais difícil manter e atualizar nossa CLI. A CLI é algo que todos nós usamos diariamente, por isso é bastante essencial, e estamos dedicando tempo para reescrevê-la. Pensei em compartilhar o processo que estamos usando para trabalhar em nosso próximo aplicativo CLI, caso você se interesse ou venha a ter um projeto como esse algum dia.

Retrospectiva

Antes de mergulharmos de cabeça em um novo projeto de código, reservamos um tempo para garantir que tivéssemos uma estrutura clara. Demos início ao processo com uma retrospectiva da CLI atual. Listamos alguns pontos sobre a CLI atual: “coisas que estamos fazendo bem”, “coisas que devemos melhorar" e "coisas que devemos parar de fazer". Aqui estão alguns exemplos do que sugerimos para todas essas colunas.

O que estamos fazendo bem:

• Nossa CLI é um produto de primeira linha, comparável aos nossos SDKs de servidor.

• A CLI oferece mais de uma maneira de realizar certas tarefas (como a listagem de Applications que mencionei anteriormente).

Coisas que devemos melhorar:

• Modo interativo na maioria dos comandos.

• Formatações para CSV, JSON e saída padrão.

• Suporte ao preenchimento automático de comandos.

• Plug-ins de suporte.

• Reduzir nossas dependências.

Coisas que devemos parar de fazer:

• Pare de se esforçar tanto com essa base de código antiga. 😅

Dá para ver que tínhamos muito mais itens listados na categoria “deveríamos melhorar”. Essa retrospectiva foi realmente útil para identificar uma lista de requisitos.

Levantamento de Requisitos

Em seguida, elaboramos uma lista dos casos de uso que queríamos incluir na CLI. Nós os definimos com base nos casos de uso atualmente suportados pela CLI e nas solicitações de recursos que queríamos implementar. Alguns deles teriam um custo muito alto com a estrutura existente (por exemplo, suporte a plug-ins). Dividimos esses casos em requisitos voltados para o usuário, como “Os usuários devem poder listar suas applications." e requisitos não voltados para o usuário, como "Serão oferecidos vários formatos de saída (tabelas ASCII, CSV, JSON).”.

Como você pode imaginar, acabamos tendo uma longa lista de casos de uso. Embora esperemos implementar todos eles, percebemos que fazer isso de uma só vez seria contraproducente e levaria muito tempo. Por isso, dividimos esses casos em funcionalidades essenciais e itens para os quais devemos desenvolver plug-ins. Para torná-los ainda mais fáceis de gerenciar, definimos versões-alvo para todos eles. Por exemplo, a maioria dos casos de uso de autenticação será implementada na V1, com alguns sendo transferidos para a V2. "O envio de SMS” será um dos primeiros plug-ins que implementaremos.

Exemplos de comandos

Depois de dividirmos os requisitos em versões gerenciáveis, elaboramos um conjunto de padrões para a CLI. Estamos usando exemplos para garantir que criemos uma experiência de desenvolvedor muito consistente em nossa nova ferramenta. Aqui está a lista de padrões que definimos:

• A nomenclatura dos comandos deve se basear na ação do usuário, e não nos nomes da nossa API. Ou seja, nexmo number format --number=012345678 --country=GB em vez de nexmo insight basic --format --number=12345678 --country=GB.

• Os nomes dos comandos são substantivos no singular. Ou seja, nexmo app ou nexmo number.

• A segunda parte do comando deve ser um verbo na forma ativa. Ou seja, nexmo app create ou nexmo number list.

• Os sinalizadores são preferíveis aos argumentos posicionais. Ou seja, nexmo app update --name MyBetterNamedApp.

• Os sinalizadores podem ter versões abreviadas. Ou seja, nexmo app update -n MyBetterNamedApp.

• As bandeiras universais devem incluir --help, --silent, --verbose, --debug, --format, --non-interactive e --color.

• Os comandos paginados usarão --limit e --offset, independentemente do mecanismo de paginação subjacente às nossas diversas APIs.

E agora?

A criação de uma nova CLI começa com uma reflexão sobre a antiga, caso você tenha uma, reunindo os requisitos e determinando quais são os mais importantes para a experiência do usuário. Com uma compreensão melhor do que queríamos para a próxima iteração da CLI, começamos a identificar frameworks de desenvolvimento de CLI e a compará-los com nossos requisitos. Abordarei esse processo com mais detalhes na próxima postagem do blog.

Até lá, estamos trabalhando para aprimorar nossa CLI, e você pode acompanhar nosso progresso em https://github.com/nexmo/nexmo-cli. Se você tiver alguma sugestão ou problema, sinta-se à vontade para relatá-los no GitHub ou no nosso Slack da comunidade.