CODESPOT CLI (Retro Review)

Este projeto fornece um console retrô para code review com suporte a UI estilo MS-DOS e modo headless via CLI.

Segredos e Configuração

• Não versione segredos. O arquivo .env está ignorado via .gitignore e serve apenas para uso local.
• Precedência: variáveis do sistema têm prioridade sobre .env. Se definir OPENAI_API_KEY no sistema, o valor do .env será ignorado.
• Em ambientes versionados (repositório público/privado), prefira variáveis de ambiente do sistema (ou gerenciadores de segredos) em vez de .env.

Azure DevOps (Repos e Pipelines)

Se seus repositórios estão no Azure DevOps, o ideal é usar Secrets via Library (Variable Groups) ou integrar com Azure Key Vault.

Opção A: Library → Variable Groups

1. Em Azure DevOps, acesse: Pipelines → Library → + Variable group.
2. Crie um grupo (ex.: codespot-secrets) e adicione:
   • OPENAI_API_KEY (marque como Secret)
   • Opcional: OPENAI_MODEL
3. Salve e restrinja acesso conforme necessário.

YAML (Windows agent):

trigger:
  - main

pool:
  vmImage: 'windows-latest'

variables:
  - group: codespot-secrets

steps:
  - task: UsePythonVersion@0
    inputs:
      versionSpec: '3.x'

  - script: |
      python -m pip install --upgrade pip
      python -m pip install .
      python -m codespot_cli.app review "$(Build.SourcesDirectory)" --out "codespot-review.txt"
    env:
      OPENAI_API_KEY: $(OPENAI_API_KEY)
      OPENAI_MODEL: $(OPENAI_MODEL)
    displayName: Run Codespot Review

  - task: PublishBuildArtifacts@1
    inputs:
      PathtoPublish: 'codespot-review.txt'
      ArtifactName: 'codespot-review'

YAML (Linux agent):

pool:
  vmImage: 'ubuntu-latest'

variables:
  - group: codespot-secrets

steps:
  - task: UsePythonVersion@0
    inputs:
      versionSpec: '3.x'

  - script: |
      python -m pip install --upgrade pip
      python -m pip install .
      python -m codespot_cli.app review "$(Build.SourcesDirectory)" --out "codespot-review.txt"
    env:
      OPENAI_API_KEY: $(OPENAI_API_KEY)
      OPENAI_MODEL: $(OPENAI_MODEL)
    displayName: Run Codespot Review

  - task: PublishBuildArtifacts@1
    inputs:
      PathtoPublish: 'codespot-review.txt'
      ArtifactName: 'codespot-review'

Opção B: Azure Key Vault

1. Configure um Service Connection (Azure Resource Manager) com acesso ao seu Key Vault.
2. Adicione os segredos no Key Vault (OPENAI_API_KEY, OPENAI_MODEL).
3. No pipeline, use a task AzureKeyVault@2 para importar os segredos para variáveis de pipeline.

Exemplo (Windows/Linux):

steps:
  - task: AzureKeyVault@2
    inputs:
      azureSubscription: 'nome-da-service-connection'
      KeyVaultName: 'nome-do-keyvault'
      SecretsFilter: 'OPENAI_API_KEY,OPENAI_MODEL'
      RunAsPreJob: false

  - script: |
      python -m pip install --upgrade pip
      python -m pip install .
      python -m codespot_cli.app review "$(Build.SourcesDirectory)" --out "codespot-review.txt"
    env:
      OPENAI_API_KEY: $(OPENAI_API_KEY)
      OPENAI_MODEL: $(OPENAI_MODEL)
    displayName: Run Codespot Review

Boas práticas no Azure DevOps

• Nunca imprima o valor dos segredos nos logs.
• Restrinja acesso a Variable Groups e Service Connections.
• Rode o review em agentes que não persistam artefatos sensíveis.
• Publique apenas o relatório (codespot-review.txt) como artefato.

Windows (local)

• Persistir para o usuário atual:
  • setx OPENAI_API_KEY "SEU_TOKEN_AQUI"
  • Feche e reabra o terminal para surtir efeito.
• Sessão atual apenas:
  • PowerShell: $env:OPENAI_API_KEY = "SEU_TOKEN_AQUI"
• Opcional: defina OPENAI_MODEL do mesmo modo.

CI/CD (GitHub Actions)

• Vá em Settings → Secrets and variables → Actions → New repository secret e adicione OPENAI_API_KEY.
• No workflow, referencie:

  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

.env.example

• Inclui apenas placeholders. Copie para .env localmente se desejar, mas não commite segredos.
• O projeto carrega .env automaticamente se existir, porém variáveis do sistema têm prioridade.

Uso

• UI retrô: cs init (ou cs ui)
• Review headless: cs review <path> --out <arquivo>
• Caminho único: cs <path> (atalho para review)

Get Started (instalação via npm)

• Instale o Codespot CLI via npm:
  • npm install codespotcli (ou npm install -g codespotcli para acesso global)
• Encerrar sessão (se houver credenciais antigas):
  • cs signout (alias: cs logout)
• Fazer login no serviço Codespot (SaaS):
  • cs login --token SEU_TOKEN --url https://api.seuservico.com
• Ver estado de autenticação:
  • cs whoami
• Opções de executável e PATH:
  • cs setup mostra instruções para gerar .exe e incluir no PATH
  • Alternativa: gerar executável com powershell ./build_exe.ps1
• Executar o review:
  • cs review <path> --out codespot-review.txt
  • UI retrô: cs init ou cs ui

Nota

• A distribuição via npm usa um wrapper que expõe o comando cs. Em ambientes corporativos, prefira instalar globalmente (-g) para que o comando esteja disponível no sistema.

Publicação no npm

• Login no npm:
  • npm login (use a conta da organização)
• Versionamento:
  • npm version patch (ou minor/major conforme necessidade)
• Publicar pacote:
  • npm publish --access public
• Nome do pacote:
  • codespotcli (já configurado em package.json)
• Requisitos em tempo de execução:
  • Deve haver Python disponível no PATH (py, python ou python3). O wrapper detecta automaticamente nesta ordem.
• O pacote inclui o código Python do CLI (codespot_cli/*) e usa python_entry.py para invocar codespot_cli.app:cli_main.

Modo SaaS (recomendado para distribuição)

• O CLI pode usar seu backend Codespot em vez de falar direto com a API.
• Primeiro, faça login e salve as credenciais:
  • cs login --token SEU_TOKEN --url https://api.seuservico.com
• Depois, rode normalmente:
  • cs review <path> --out codespot-review.txt
• Em CI/CD, defina variáveis de pipeline:
  • CODESPOT_TOKEN e CODESPOT_BASE_URL
  • O CLI detecta automaticamente e envia os chunks para o seu backend.

Rodar o backend localmente (dev)

• Pré‑requisitos: Python 3.9+, e definir OPENAI_API_KEY no ambiente do servidor.
• Ajuste o .env do backend (use backend/.env.example como base):
  • OPENAI_API_KEY, OPENAI_MODEL (opcional), CODESPOT_BACKEND_TOKEN.
• Instale dependências e rode:
  • powershell ./backend/run_local.ps1 -Port 8000
• Faça login no CLI apontando para seu backend local:
  • cs login --token SEU_TOKEN --url http://localhost:8000
• Execute o review:
  • cs review <path> --out codespot-review.txt

UI retrô em Windows (opcional)

• A UI depende de curses. Em Windows, instale o extra opcional:
  • pip install .[ui]
  • ou pip install windows-curses
• Em CI/CD (pipeline), o modo headless é usado e não requer windows-curses.

Precedência de variáveis

• Pipeline/Agente: env: OPENAI_API_KEY: $(OPENAI_API_KEY) tem prioridade.
• Local: variáveis do sistema > .env.

Boas Práticas

• Armazene segredos no ambiente do sistema ou em um secret manager (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager) e injete via variáveis.
• Se acidentalmente commitar um .env com segredos:
  • Remova do histórico (use git filter-repo/git filter-branch) e revogue a chave.
  • Garanta que .env esteja no .gitignore.

Notas

• Dependências principais: openai, python-dotenv (para .env local).
• Dependência opcional para UI em Windows: windows-curses (instale com pip install .[ui]).
• Extra opcional para armazenamento seguro de credenciais: pip install .[secure] (usa keyring).
• O CLI salva saída formatada com --out; a UI mostra banners e bullets no estilo retrô.

Backend (API)

• Endpoint: POST /api/review
• Autenticação: header Authorization: Bearer <token> (definido via CODESPOT_BACKEND_TOKEN no servidor).
• Request JSON: { "chunks": ["--- FILE: a.py ---\n...", "..."] }
• Response JSON: { "review": "texto do code review" }