spec-first-copilot 0.8.0-beta.1 → 0.8.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-first-copilot",
-  "version": "0.8.0-beta.1",
+  "version": "0.8.0-beta.2",
   "description": "Spec-first workflow kit for GitHub Copilot — AI-driven development with specs, not guesswork",
   "bin": {
     "spec-first-copilot": "bin/cli.js"

package/templates/.github/CHANGELOG.md

@@ -8,6 +8,23 @@
 
 ---
 
+## 0.8.0-beta.2 (2026-05-11) — Auth check pré-clone
+
+`/sf-onboard` agora verifica autenticação git **antes** de tentar clonar,
+detectando SSH vs HTTPS e testando ssh-agent / credential helper / GH CLI.
+Falha cedo com mensagem específica em vez de erro genérico do `git clone`.
+
+### Adicionado
+
+- Passo 0 do `/sf-onboard`: verificação proativa de auth
+  - SSH: `ssh-add -l` (agent vazio?) + `ssh -T git@<host>` (chave autorizada?)
+  - HTTPS: `git config credential.helper` + `gh auth status` + `git ls-remote`
+- 6 mensagens de erro específicas (ssh-agent off, agent vazio, chave não
+  autorizada, sem helper nem GH CLI, GH CLI deslogado, falha desconhecida)
+- Nota Windows/PowerShell sobre ssh-agent + alternativas (GH CLI, PAT)
+
+---
+
 ## 0.8.0-beta.1 (2026-05-11) — Brownfield onboarding
 
 Skill nova `/sf-onboard` pra assumir aplicações **já existentes**. Lê o

package/templates/.github/skills/sf-onboard/SKILL.md

@@ -52,11 +52,77 @@ execução adiciona uma entry em `projetos.yaml` e merge aditivo no TRD.
 | # | Validação | Se falhar |
 |---|-----------|-----------|
 | 1 | `<git-url>` informado | Parar → "Informe a URL do repositório. Ex: /sf-onboard https://github.com/org/app.git" |
-| 2 | `git` instalado no PATH | Parar → "Git não encontrado no PATH" |
-| 3 | URL acessível (auth do user) | Parar → "Falha ao clonar. Configure SSH/PAT antes de rodar /sf-onboard" |
+| 2 | `git` instalado no PATH (`git --version`) | Parar → "Git não encontrado no PATH" |
+| 3 | **Auth git pré-verificada** (ver passo 0) | Parar com instrução específica conforme tipo de URL |
 | 4 | `--branch` e `--tag` não usados juntos | Parar → "Use --branch OU --tag, não ambos" |
 | 5 | Scope `onboard_<repo>` não está em `analyzing` | Se sim → "Onboarding anterior incompleto. Rode novamente pra retomar" |
 
+### Passo 0 — Verificar autenticação ANTES de clonar
+
+Detectar tipo de URL e testar auth proativamente. Falhar cedo com mensagem
+clara é melhor que esperar o `git clone` quebrar sem contexto.
+
+**Detectar tipo de URL**:
+
+| Padrão | Tipo |
+|--------|------|
+| `git@<host>:<org>/<repo>.git` | SSH |
+| `ssh://git@<host>/...` | SSH |
+| `https://<host>/...` | HTTPS |
+
+**Se SSH** — testar agente + conectividade:
+
+```bash
+# 1. ssh-agent rodando com chave carregada?
+ssh-add -l
+#    Saída esperada: linha(s) com fingerprint. Se "The agent has no identities",
+#    user precisa rodar `ssh-add ~/.ssh/id_ed25519` (ou similar).
+#    Se "Could not open a connection to your authentication agent",
+#    user precisa iniciar o ssh-agent.
+
+# 2. Host autenticável? (extrair host da URL, ex: github.com)
+ssh -T -o StrictHostKeyChecking=accept-new -o BatchMode=yes git@<host>
+#    GitHub retorna exit 1 com "Hi <user>! You've successfully authenticated"
+#    GitLab/Bitbucket têm mensagens análogas.
+#    Exit 255 ou "Permission denied (publickey)" → chave não autorizada.
+```
+
+**Se HTTPS** — testar credential helper ou GH CLI:
+
+```bash
+# 1. Git credential helper configurado?
+git config --get credential.helper
+#    Vazio → user usa GH CLI ou vai ser perguntado credencial no clone.
+
+# 2. (Se host = github.com) GH CLI autenticado?
+gh auth status --hostname github.com
+#    Exit 0 + "Logged in to github.com" → ok
+#    Exit 1 → não logado
+
+# 3. Alternativa: tentar ls-remote sem clonar (mais leve que clone)
+GIT_TERMINAL_PROMPT=0 git ls-remote --heads <git-url> HEAD
+#    Exit 0 → auth ok
+#    Exit ≠ 0 + "Authentication failed" → credencial ausente/inválida
+#    Exit ≠ 0 + "could not read Username" → terminal prompt bloqueado, sem credential helper
+```
+
+**Mensagens de erro específicas**:
+
+| Cenário | Mensagem |
+|---------|----------|
+| SSH sem ssh-agent | "ssh-agent não está rodando. Inicie com `eval $(ssh-agent)` (Linux/Mac) ou `Start-Service ssh-agent` (Windows)" |
+| SSH agent vazio | "Nenhuma chave SSH carregada. Rode `ssh-add ~/.ssh/id_ed25519` (ajuste o nome se diferente)" |
+| SSH host nega | "Chave SSH não autorizada em `<host>`. Verifique se a chave pública está cadastrada em `<host>/settings/keys` (GitHub) ou equivalente" |
+| HTTPS sem helper nem GH CLI | "Credencial HTTPS não configurada. Opções: (1) `gh auth login` se host=github.com; (2) configurar credential helper (`git config --global credential.helper manager`); (3) usar URL SSH (`git@<host>:...`)" |
+| HTTPS GH CLI deslogado | "GH CLI não autenticado. Rode `gh auth login` e tente novamente" |
+| `ls-remote` falha por motivo desconhecido | "Falha ao acessar o repo: `<stderr do ls-remote>`. Verifique a URL e suas credenciais" |
+
+**Sucesso**: log breve "Auth OK ({tipo})" e prosseguir para o Passo 1.
+
+> **Nota Windows/PowerShell**: comandos `ssh-add`, `ssh -T`, `gh`, `git`
+> assumem disponíveis no PATH. Em ambientes sem ssh-agent nativo (Windows
+> antigo), instruir uso do GH CLI ou HTTPS+PAT.
+
 ## Passos
 
 ### 1. Resolver nome do scope e path
@@ -343,7 +409,8 @@ Se `--name` diferentes → scopes separados (raro, mas suportado).
 
 | Erro | Ação |
 |------|------|
-| URL não acessível | Parar, sugerir checar SSH/PAT |
+| Auth falha (capturado no Passo 0) | Parar com mensagem específica conforme cenário (ver tabela do Passo 0) |
+| Clone falha mesmo com auth OK | Reportar `stderr` do git; verificar se a URL e branch existem |
 | Repo vazio | Parar — "Nada a onboardar" |
 | Nenhum reader produziu fragmento (stack desconhecida) | Parar — "Stack não reconhecida. Detalhe TRD manualmente ou peça suporte" |
 | `projetos/<repo-name>/` já existe e NÃO é clone do mesmo URL | Parar — "Path já em uso por outro repo. Use --name pra dar outro nome" |