# Como um agente de IA usa o dsgit (Claude Code, CLI)

Vale depois que o usuário rodou o `entrar` (ver `LEIAME.md`). Instância: Forgejo 17.0.1 em `https://dsgit.dsmarketing.com.br` (`$DSGIT_URL`). Git só por HTTPS. Marcas: [medido] = rodado em 18/11/2026 no PC do administrador contra `<dono>/<repo>`.

## Regras para o agente
- **Nunca** leia, imprima nem grave o token. Não rode `git credential fill` nem abra a configuração da `tea`. Use os três caminhos abaixo: eles buscam o token no cofre sozinhos.
- O agente age **como o usuário** dono do token. O token do dia a dia não é admin e não cria repositório (403) [medido].
- Em Actions, o número que a API usa é o **id da execução** (o `#N` de `dsgit runs`, campo `id`), que **não é** o número da URL da tela (`index_in_repo`) [medido: id 5 = `/actions/runs/1`].
- Escolha: **MCP** para ler/escrever PR, issue, arquivo, release; **`dsgit`** para log de etapa e reexecução (o MCP 2.30.2 não tem essas duas); **API direta** para o resto.

## 1. MCP (servidor `dsgit`, 128 ferramentas [medido])
No Claude Code as ferramentas aparecem como `mcp__dsgit__<nome>`. Conferir: `claude mcp get dsgit` → *Connected*. Fora do Claude Code a mesma ferramenta roda pelo terminal: `dsgit mcp --cli <nome> --args '<json>'` (`dsgit mcp --cli list` lista todas; `--help` mostra os parâmetros).

| Tarefa | Ferramenta | Argumentos |
|---|---|---|
| Listar PRs | `list_repo_pull_requests` | `{"owner":"<dono>","repo":"<repo>","state":"open"}` |
| Abrir PR | `create_pull_request` | `{"owner":"…","repo":"…","head":"minha-branch","base":"main","title":"…","body":"…"}` |
| Ver diff / arquivos do PR | `get_pull_request_diff`, `list_pull_request_files` | `{"owner":"…","repo":"…","index":3}` |
| Revisar / mesclar | `create_pull_review`, `merge_pull_request` | ver `--help` |
| Ver execuções | `list_workflow_runs` | `{"owner":"…","repo":"…","status":"failure"}` (filtros: `status`, `event`, `head_sha`) |
| Detalhe de uma execução | `get_workflow_run` | `{"owner":"…","repo":"…","run_id":5}` |
| Disparar workflow manual | `dispatch_workflow` | `{"owner":"…","repo":"…","workflow":"ola.yml","ref":"main"}` (o workflow precisa de `workflow_dispatch`) |
| Log de etapa / reexecutar | **não há no MCP** | use a seção 2 ou 3 |

[medido] `create_pull_request` abriu o PR 3; `list_repo_pull_requests`, `list_workflow_runs` e `get_workflow_run` responderam. `dispatch_workflow`, revisão e merge: só escritos.

## 2. CLI
```bash
dsgit prs  <dono>/<repo>           # PRs abertos (sem argumento: repo da pasta atual)        [medido]
dsgit runs <dono>/<repo>           # execuções; anote o #N                                    [medido]
dsgit log  5 <dono>/<repo>         # jobs, etapas e o log inteiro de cada job                 [medido]
dsgit log  5 <dono>/<repo> 1       # só a etapa 1 (a numeração aparece no cabeçalho do job)   [medido]
dsgit rerun 5 <dono>/<repo>        # reexecuta (só execução terminada)                        [medido]
tea pulls create --login dsgit --repo <dono>/<repo> --head minha-branch --base main \
    --title "Título" --description "Texto"   # abrir PR                                                 [medido]
tea pulls ls --login dsgit --repo <dono/repo> ; tea issues ls ; tea repos ls                            # [medido: pulls e repos]
```
No PowerShell os nomes são os mesmos (`dsgit`, `dsgit-prs`, `dsgit-runs`, `dsgit-log`, `dsgit-rerun`, `dsgit-api`).
**Não use** `tea actions runs view|logs`: falha com o Forgejo 17 (`cannot unmarshal array…`) [medido]; `tea actions runs ls` vem com colunas vazias.

## 3. API direta (`dsgit api <caminho> [opções do curl]`)
Base `/api/v1`; o cabeçalho de autenticação é posto pelo comando. Erro HTTP = saída diferente de zero, com o corpo da resposta.
```bash
R=<dono>/<repo>
dsgit api "/repos/$R/pulls?state=open"                                   # listar PRs               [medido]
dsgit api "/repos/$R/pulls" -X POST -H 'Content-Type: application/json' \
  -d '{"head":"minha-branch","base":"main","title":"Título","body":"Texto"}'   # abrir PR           [medido]
dsgit api "/repos/$R/actions/runs?limit=10&status=failure"               # execuções (id, status, event, prettyref) [medido]
dsgit api "/repos/$R/actions/runs/5/jobs"                                # jobs da execução (id de cada job)        [medido]
dsgit api "/repos/$R/actions/jobs/21"                                    # um job, com a lista de etapas            [medido]
dsgit api "/repos/$R/actions/jobs/21/logs?step=1"                        # log de UMA etapa (texto)                 [medido]
dsgit api "/repos/$R/actions/jobs/21/logs"                               # log inteiro do job                       [medido]
dsgit api "/repos/$R/actions/runs/5/rerun" -X POST                       # reexecutar a execução (204)              [medido]
dsgit api "/repos/$R/actions/jobs/21/rerun" -X POST                      # reexecutar só um job e dependentes       [só escrito]
dsgit api "/repos/$R/actions/runs/5/cancel" -X POST                      # cancelar                                 [só escrito]
dsgit api "/repos/$R/actions/runs/5/logs" -o logs.zip                    # ZIP com o log de todos os jobs           [só escrito]
```
Parâmetros de log (API 17): `step` (número da etapa), `attempt`, `q`/`qi` (filtro de texto), `format=text|ndjson`.

## Fluxo típico: "o CI do meu PR falhou"
1. `dsgit runs` → pegue o `#N` com `Status: failure`.
2. `dsgit log N` → veja qual job/etapa falhou; `dsgit log N "" <etapa>` para ler só ela (o `""` mantém o repo da pasta atual).
3. Corrija, `git push`. Se a falha foi do runner, `dsgit rerun N`.
4. Comente no PR pelo MCP (`create_issue_comment`, com `index` = número do PR).

## Limites conhecidos
- Sem `jq` no Git for Windows: o `dsgit` lê o JSON com `grep/sed` e depende do formato da API 17.x. Para tratar JSON de verdade, use o MCP (`dsgit mcp --cli … --output=json`).
- Runners: rótulos `p`, `m`, `g` (`runs-on`). Workflow com `uses:` depende do estado dos runners (em 18/11 a prova `piloto/hello-runners` falhava no *Set up job*; um workflow só com `run:` no rótulo `p` passou [medido]).
- Se o 2FA global for ligado, a senha deixa de valer na API: só token (o kit já usa token).
