auto-copilot

CLI que cria uma worktree Git temporária, guia o GitHub Copilot CLI em dois fluxos (execução principal e finalização automática) e sai com branch e commit consistentes.

Requisitos

- Node.js >= 22
- Git com suporte a worktree
- GitHub Copilot CLI (copilot) instalado e autenticado (npm @github/copilot, Homebrew ou outro canal)
- Token de acesso (ex.: GH_TOKEN) configurado para permitir chamadas não interativas — o Copilot CLI também aceita diretórios confiáveis pré-configurados em ~/.copilot/config.json

Instalação

``bash
npm install -g auto-copilot
`

Durante o desenvolvimento local você também pode executar via npx a partir do diretório do projeto.

Uso

`bash
auto-copilot [opções]
`

$3

| Opção | Descrição |
| --- | --- |
| --path | Repositório Git que servirá como origem. Caso omitido, o CLI usa o repositório atual. |
| --prompt "texto" | Prompt enviado ao Copilot no primeiro fluxo. Se omitido e houver TTY, o CLI pergunta interativamente. |
| --base | Referência usada como base do novo worktree (default: branch atual; fallback para HEAD). |
| --timeout | Tempo limite (em minutos) para cada execução do Copilot CLI. Default: 60 min; caso a flag não seja fornecida e exista TTY, o CLI pergunta ao usuário após coletar o prompt. |
| --verbose | Ativa logs detalhados. |

$3

`bash
GH_TOKEN=ghp_xxx auto-copilot \
--path ~/projetos/minha-api \
--prompt "Adicionar endpoint /health e cobrir com testes" \
--base main \
--timeout 20
`

1. O utilitário descobre o repositório raiz e cria minha-api.worktree/20260110-020657 com branch homônima.
2. O primeiro fluxo do Copilot executa o prompt informado enquanto transmite stdout/stderr em tempo real.
3. O segundo fluxo reorganiza o resultado: sugere um branch final (ex.: feat/add-health-endpoint), renomeia a branch, adiciona arquivos e gera o commit final antes de exibir git status -sb limpo.

> Dica: se você não usar --timeout, o CLI pergunta "Quantos minutos?" logo após coletar o prompt e, se você pressionar Enter, assume 60 minutos.

Fluxo automatizado

1. Descoberta do repositório — usa --path ou detecta o Git root atual.
2. Criação da worktree — gera diretório NomeDoProjeto.worktree/ e branch homônima para garantir unicidade, mudando o cwd do processo para a nova worktree e usando, por padrão, a branch atual como base (fallback para HEAD ou para o valor de --base, se informado).
3. Primeiro prompt do Copilot — envia o prompt informado (ou coletado interativamente) com flags --allow-all-tools, --allow-all-paths e --allow-all-urls para evitar travas interativas. Todo stdout/stderr é retransmitido em tempo real e o processo é encerrado se o Copilot retornar erro ou exceder o timeout.
4. Fluxo automático de finalização — dispara um segundo prompt sem intervenção humana que:
- analisa o status/diff do repositório;
- sugere um branch descritivo e renomeia a branch atual;
- adiciona todos os arquivos e cria um commit coerente;
- mostra git status -sb ao final.
5. Saída — logs claros indicam sucesso ou falha e o processo retorna o código apropriado.

Autenticação e permissões do Copilot CLI

- Configure GH_TOKEN (ou GITHUB_TOKEN) com um Fine-Grained PAT contendo o escopo Copilot Requests. Esse token é repassado ao processo do Copilot CLI automaticamente.
- Execute copilot trust previamente ou mantenha o diretório listado em ~/.copilot/config.json para que não ocorram prompts de confiança.
- O CLI força as flags --allow-all-tools, --allow-all-paths e --allow-all-urls para impedir bloqueios de TTY; ajuste o comportamento por meio do código caso precise de uma política mais rígida.
- Defina CI=true (já definido internamente) para sinalizar execução não interativa e evitar prompts extras.

Tratamento de erros

O CLI distingue problemas operacionais (Git ausente, Copilot indisponível, worktree já existente, timeout) e retorna códigos específicos (10 para Git, 11 para Copilot, etc.). Mensagens adicionais aparecem com --verbose e o processo sempre encerra a worktree com estado consistente.

$3

| Código | Significado |
| --- | --- |
| 0 | Execução bem-sucedida. |
| 1 | Erro genérico não tratado. |
| 2 | Argumentos inválidos / parâmetros ausentes. |
| 10 | Falhas relacionadas ao Git (worktree, branch, permissões). |
| 11 | Erros vindos do Copilot CLI (timeout, falta de instalação, quota). |
| 12 | Problemas de autenticação com o Copilot. |
| 130 | Usuário cancelou a execução (Ctrl+C ou prompt interativo cancelado). |

Dicas

- Execute copilot trust antecipadamente para evitar prompts inesperados.
- Combine com scripts shell, por exemplo: auto-copilot --path ~/repo --prompt "Implementar feature X".
- Use --base main para garantir que o worktree nasça a partir da branch principal.

Estrutura do projeto

`
auto-copilot/
├── package.json # Configuração do pacote, bin e scripts
├── src/index.js # Implementação principal do CLI
├── test/smoke.test.js # Teste básico de smoke
└── README.md # Este documento
`

Desenvolvimento

1. Instale dependências: npm install.
2. Execute os testes: npm test.
3. Valide o CLI localmente com npm start -- --prompt "..." (o --` extra encaminha flags para o binário).
4. Antes de publicar, teste o fluxo completo em um repositório de exemplo e confirme que o Copilot CLI está autenticado e confia no diretório alvo.