A construção de recursos CLI geralmente se resume a:

• Lançar novos endpoints de API.
• Crie novas ações CLI que precisem de alterações na API.
• Perceba que erros foram cometidos na API que você acabou de lançar.
• Tente corrigir a API desse recurso sem criar mais problemas no futuro.
• Tente lembrar o que você estava tentando alcançar na CLI e então realmente conseguir.  
• GOTO: perceba que erros foram cometidos.

Cada etapa requer a anterior e, opa, reinventamos o gerenciamento de projetos em cascata. Você fica desgastado pela dor ao tentar superar os erros com elegância até mancar para o funcional, mas desiste bem antes do excepcional. E não me fale sobre a manutenção do conjunto resultante de “correções” e verrugas ad-hoc.

Já estive lá, fiz isso. Sabíamos que precisávamos superar a abordagem em cascata.

Aqui está a história de como chegamos lá e algumas das ferramentas que ajudaram ao longo do caminho.

Começando de forma incompleta

Queríamos uma iteração rápida e barata até entendermos o recurso e só então nos comprometermos com uma implementação cara e suporte de longo prazo. Como uma equipe pequena, muitas vezes eu fazia esse processo de ponta a ponta e queria me concentrar em cada parte por vez. Queríamos falsificar peças de implementação até nos sentirmos confiantes o suficiente para fazê-lo.

Voltando ao processo, ele começa com a proposta de funcionalidades. Queríamos sair do abstrato, mas não se isso significasse uma implementação incompleta. Nós falsificamos isso com "esboços", inspirados na abordagem de esboço CLI do Google Docs que o Github descreve aqui.

Infelizmente, os esboços estáticos não nos deram o feedback que queríamos. Nossa CLI muda a saída ao longo do tempo, mais como uma animação do que como um desenho. Para obter maior fidelidade, escrevi pequenos programas Ruby para receber entradas básicas e responder imprimindo respostas prontas apropriadas.

Desde então, encontramos uma maneira ainda melhor de capturar a saída CLI animada, mas explicar isso requer um pequeno desvio.

Você ao menos testa?

À medida que começamos a desenvolver nossa CLI, também queríamos testar casos extremos e detectar regressões. Pesquisei CLIs públicas baseadas em cobra/bubbletea em busca de ideias e encontrei poucos testes frustrantes. Então nos deparamos com o teste do Charm, que nos deu um ponto de partida.

O Teatest se concentra em testes de ouro, capturando um resultado conhecido e bom e, em seguida, afirmando que os resultados futuros continuam a corresponder a ele. O que nos trouxe de volta, mais uma vez, à captura de alta fidelidade de saídas CLI animadas. Teatest nos deu a ótima ideia de uma solução baseada em molduras, como um flipbook, na qual desenvolvemos:

─── SigninHeader ───────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
─── SigninInput --──────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
    ? What is your username?
    ? user
─── SigninInput ────────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
    * Signing in to your CLI account… ⠋
─── SigninInput ────────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
    * Signed in to your CLI account: [email protected]

Este exemplo simplificado mostra como seria uma saída dourada para um comando de autorização básico. As linhas horizontais delineiam os quadros, com rótulos indicando o modelo ativo. Juntos, obtemos uma captura de saída de alta fidelidade, mesmo quando linhas são adicionadas, removidas ou substituídas.

Usamos um sinalizador em nosso conjunto de testes para atualizar arquivos com as saídas douradas e, caso contrário, os testes falharão se a saída não corresponder aos arquivos. Isso nos mantém cientes das mudanças nos resultados e facilita as revisões de relações públicas, permitindo-nos entender como o resultado deve ser e se ele mudou. Gostamos tanto que planejamos substituir nossos programas de esboço por saída de estilo dourado no Google Docs estilo Github para que possamos capturar ideias de animação e estilo.

Com nossos esboços antigos e futuros em mãos, vamos voltar aos primeiros passos com novos endpoints de API.

Projetando API e CLI juntos

Trabalhamos na API e na CLI simultaneamente, porque os melhores designs para elas surgem de uma forte integração. Somos capazes de fazer isso, evitando os perigos da cascata, iterando projetos em contextos mais baratos e esperando para implementar até que os requisitos se solidifiquem. Para nossas APIs, isso significa esboçar com OpenAPI:

openapi: 3.1.0
info:
  contact:
    email: [email protected]
  description: An example API.
  title: Example API
  version: 0.0.1
servers:
  - url: https://api.example.com
tags:
  - description: account operations
    name: account
paths:
  '/v0/auth/signin':
    post:
      description: Signin to CLI.
      operationId: auth_signin
      responses:
        '200':
          content:
            'application/json':
              schema:
                additionalProperties: false
                properties:
                  email:
                    description: Email address for authenticated user.
                    example: [email protected]
                    type: string
                required:
                  - email
                type: object
          description: Successful signin.
      summary: Signin to CLI.
      tags:
        - account

Este exemplo simplificado mostra a aparência de um esquema para um comando de autorização básico. Usamos o linter espectral para simplificar o trabalho nesses arquivos.

Com um esboço em mãos, usamos o prisma como um servidor API simulado enquanto implementamos a CLI. Quando inevitavelmente percebemos que foram cometidos erros, podemos apenas ajustar as especificações e voltar à nossa iteração CLI. Trabalhar neste alto nível nos permite evoluir a API e a CLI juntas e adiar implementações dispendiosas até que tenhamos um melhor conhecimento.

Implementando APIs

Também nos baseamos em nossas especificações OpenAPI para nos manter honestos durante a implementação usando o comitê. assert_schema_conform testa o alinhamento e o middleware nos notifica sobre quaisquer discrepâncias em tempo real. Eles se combinam para permitir a implementação do vermelho verde, ao mesmo tempo que nos protegem de regressões.

Teste com simulações e proxies

Para completar, nosso conjunto de testes usa sinalizadores para executar o prisma no modo simulado ou proxy. Ao usar sinalizadores podemos nos concentrar em escrever apenas um tipo de teste, embora isso signifique pular alguns testes em um modo ou outro. Usamos testes simulados para sua velocidade e no Windows e macOS, onde nossa pilha completa não roda em CI. Nossos testes de proxy nos permitem executar testes em toda a nossa pilha apenas adicionando um sinalizador, facilitando a execução de testes de ponta a ponta sempre que considerarmos necessário.

Juntando tudo

Esboços e especificações nos ajudam a superar o abstrato sem ter que nos preocupar com a implementação. Então, simulações e proxies nos ajudam a garantir que as implementações correspondam aos esboços. Ao continuar a iterar nosso processo, cada recurso causa menos problemas, o que apreciamos profundamente ao construir a experiência de equipe que entregaremos no final deste mês.

Continuaremos iterando nosso processo, espero que você tenha aprendido algo com ele e adoraria aprender com você. O que você tentou, onde você está orgulhoso e o que continua frustrante?