CodeGen CLI

CLI interativa (TUI com Ink/React) para se conectar a um agente CodeGen via HTTP/WebSocket.

• Execução da CLI
• Configuração do backend
  • Endpoints esperados
• Rodando a CLI em modo de desenvolvimento
• Problemas comuns
• Conventional Commits
• Release Workflow

Execução da CLI

Pré‑requisitos

• Node.js (versão LTS recomendada > 22.x)
• Pnpm - Gerenciador de dependências
• Backend HTTP/WebSocket compatível com o protocolo do CodeGen CLI, exposto (por padrão) em http://localhost:8000

[!NOTE] Dica: este repositório não inclui o backend; ele precisa estar rodando em outro processo/máquina caso deseje executar toda a stack localmente.

• Instale o pnpm globalmente:

npm -g install pnpm
## Confira se foi instalado com pnpm --version, caso contrário, adicione-o nas variáveis de ambiente do seu sistema

• Clone o repositório e entre na pasta do projeto:

git clone https://github.com/stack-spot/codegen-channels

• Instale as dependências para a configuração inicial (commit lint):

pnpm install

• Navegue até a pasta do projeto da CLI:

  cd cli_executor

• Instale as dependências:

  pnpm install

• Caso deseje executar a CLI localmente, mas apontando para o backend em dev, basta executar:

pnpm dev

Passos para executar localmente (apontando para backend local)

Configuração do backend

A CLI depende do backend para:

• Criar/retomar sessões de conversa (HTTP + WebSocket)
• Verificar a versão do CLI (version check obrigatório na inicialização)

Verifique o arquivo das variáveis de ambiente, nesse caso em específico o de dev: .env.dev

Endpoints esperados

O backend deve expor pelo menos:

1. Version check (obrigatório na inicialização):

   • Método: GET

   • URL: ${CLI_BACKEND_URL}/v1/cli/version

   • Resposta esperada:

     {
       "version": "1.0.1"
     }

   O valor deve estar sincronizado com:

   • version em package.json
   • config.CURRENT_VERSION em src/config.ts

   Se a versão retornada for diferente, o CLI tentará um auto‑update via npm install -g cli_executor-<version>.tgz.

2. Criação de sessão:

   • Método: POST

   • URL: ${CLI_BACKEND_URL}/v1/tasks

   • Corpo mínimo esperado (do lado do CLI):

     {
       "prompt": "New interactive session"
     }

   • Resposta esperada:

     {
       "id": "<SESSION_ID>"
     }

3. WebSocket da sessão:

   • URL: ${CLI_BACKEND_URL}/v1/ws/session/start_or_resume/<SESSION_ID>
   • Protocolo de mensagens em JSON (handshake + mensagens do agente + comandos de ferramenta).

Importante: inicie o backend antes de rodar a CLI, caso contrário o version check e a criação de sessão vão falhar.

Rodando a CLI em modo desenvolvimento

O fluxo mais simples para compilar e executar a CLI é usar o script local:

pnpm local

Esse comando executa:

1. pnpm build – compila o código TypeScript em dist/
2. node dist/cli.js – roda o binário da CLI (entrypoint src/cli.tsx) usando o arquivo .env.local como referência

Ou, se quiser usar o bin definido no package.json (stk-codegen) de forma global:

# dentro do diretório do projeto
pnpm link

# em qualquer lugar
stk-codegen

[!NOTE] Lembrando que o comando de link acima, irá instalar a versão atual da lib na store global do pnpm, caso deseje alterar, será necessário a remoção do pacote com o comando: pnpm rm -g stk-codegen

Para mais detalhes e visualizar outros comandos disponíveis, vá até o arquivo: package.json especificamente na seção "scripts".

Problemas comuns

• Falha ao tentar executar a tool SearchText (ripgrep / rg)

  • Em ambientes corporativos não é comum o download/execução do ripgrep falhar (ex.: problemas de proxy/certificado como unable to get local issuer certificate).

  • O CLI possui fallback em Node.js (sem binário externo). Para forçar o fallback, defina:

    export CLI_DISABLE_RIPGREP=true

  • Opcionalmente, você pode definir o diretório base de trabalho das tools com:

    export CLI_WORKSPACE_DIR=/caminho/do/projeto

• Erro de versão / auto‑update falhando

  • Verifique se o endpoint /v1/cli/version está acessível e retornando JSON válido.
  • Confirme se a versão bate com a do package.json e de src/config.ts.

• Falha ao criar sessão (/v1/tasks)

  • Cheque se o backend está rodando e se a CLI_BACKEND_URL está configurada corretamente.
  • Veja logs do backend para entender o erro.

• WebSocket não conecta / desconecta imediatamente

  • Confirme se a URL de WebSocket está correta (/v1/ws/session/start_or_resume/{sessionId}).
  • Verifique se não há firewall/bloqueio de rede entre o CLI e o backend.

Para mais detalhes sobre arquitetura, padrões e decisões do projeto, consulte o arquivo CODEGEN.md.

Conventional Commits

Este projeto utiliza o padrão Conventional Commits para padronizar as mensagens de commit seguindo as melhores práticas da comunidade. Em resumo, você deve usar um dos seguintes padrões ao escrever mensagens de commit:

feat: implementação de novas funcionalidades
refactor: alterações comuns, não adiciona nada novo
fix: correções de bugs
chore: tarefas rotineiras relacionadas a build, workflows, etc
...

Para mais exemplos e detalhes, consulte a documentação oficial.

Release / npm publish

A publicação de uma nova release é feita através de um workflow do GitHub Actions, para entender como o processo funciona, leia o arquivo Release Please Workflow