live: heartbeat sync 2026-10-18T16:47:59-07:00 (Refs #11)

agent/managed-skills/gitea-api-pr-operations/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: gitea-api-pr-operations
+description: "Open, list, merge, and verify pull requests (and diagnose issue-API scope failures) on the Dankclaw Gitea via its REST API from a workstation, keeping the token out of argv (curl -K config file, mode 600) — includes the credential-store extraction one-liner, the merge endpoint's Do-field law and Content-Type-header trap, the suggested-URL-is-not-a-PR gotcha, and the insufficient-token-scope trap."
+---
+
+# Gitea API PR operations (Dankclaw)
+
+`git push` on this fleet prints `Create a new pull request for ...` — that is a
+**suggestion, not a PR**. Verify (`GET /pulls?state=open` → expect `[]`) before
+claiming a PR "should exist"; create it via the API when asked.
+
+## Endpoint + auth
+- API base: `http://192.168.0.143:3000/api/v1/repos/dank/<repo>`
+- Token lives in the git credential store configured by
+  `git config --get credential.helper` → `store --file ~/.config/secrets/gitea`,
+  line format `http://user:TOKEN@192.168.0.143:3000`.
+- The repo-local `.env` `GITEA_TOKEN` (main checkout, gitignored) carries
+  **`read:issue` too** (measured 2026-10-18): filing issues needs THAT token,
+  the credential-store one 403s on issues.
+
+Extract the token (the `http://` scheme contains a colon — scheme-stripping
+awk regexes silently grab the port instead; use this anchored sed):
+
+```bash
+tok=$(sed -nE 's#^http://[^:/@]+:([^@]+)@192\.168\.0\.143.*#\1#p' ~/.config/secrets/gitea | head -1)
+[ -n "$tok" ] && echo "token-extracted(len=${#tok})"   # length check, never echo the value
+```
+
+## Keep the token out of argv (repo secret law)
+`curl -H "Authorization: token $tok"` is world-readable in `/proc/<pid>/cmdline`.
+Use a mode-600 config file:
+
+```bash
+cfg=$(mktemp); chmod 600 "$cfg"
+printf 'header = "Authorization: token %s"\n' "$tok" > "$cfg"
+```
+
+- POST JSON needs a second header line: `header = "Content-Type: application/json"`.
+  There IS NO `content-type` config option — curl rejects the file.
+- `rm -f "$cfg"` when done (a mode-600 token file left in /tmp is its own leak).
+
+## Operations
+```bash
+# list open PRs
+curl -sS -K "$cfg" ".../pulls?state=open" | jq -r '.[] | [.number,.head.name,.base.name,.title] | @tsv'
+# create (build the payload as a FILE, see below)
+curl -sS -K "$cfg" -o /tmp/pr.json -w '%{http_code}\n' -X POST -d @/tmp/pr-payload.json ".../pulls"
+# verify: 201 is not enough — check mergeable
+curl -sS -K "$cfg" ".../pulls/1" | jq '{number,state,merged,mergeable,base:.base.ref,head:.head.ref,url:.html_url}'
+```
+
+## Merging: the field is `Do`, and it is a STRING naming the strategy
+
+Measured 2026-10-18 on Gitea at 192.168.0.143:3000 (`POST .../pulls/<n>/merge`).
+`MergePullRequestOption` is `{From, To, When, Do}` — **there is no `DoMerge` and
+no `merge_method`**. Every wrong shape is a 422 with a distinct message, so read it:
+
+|body sent|http|message|
+|---|---|---|
+|`{"DoMerge":true,"merge_method":"merge"}`|422|`[Do]: Required`|
+|`{"Do":true,"merge_method":"merge"}`|422|`[]: json: cannot unmarshal JSON boolean into Go string within "/Do"`|
+|`{"Do":"true"}`|422|`[Do]: In…` (validation: not a strategy name)|
+|form body `Do=true&merge_method=merge`|422|`[Do]: Required` (the value must be a strategy name)|
+|`{"Do":"merge"}`|**200**|merged|
+
+```bash
+curl -sS -K "$cfg" -H 'Content-Type: application/json' -X POST -d '{"Do":"merge"}' ".../pulls/4/merge"
+# then prove it: .merged true, .state closed, .merge_commit_sha set, and origin/main moved
+curl -sS ".../pulls/4" | jq -c '{number,state,merged,merge_commit_sha}'
+```
+
+Strategy names: `merge`, `rebase`, `rebase-merge`, `squash`, `manually` — a
+strategy the repo does not allow is rejected too.
+
+**Merge trap (measured 2026-10-18):** on `POST /merge` the `Content-Type` header
+must go on the **command line** (`-H 'Content-Type: application/json'`). Same
+curl that succeeds on `POST /pulls` with Content-Type supplied only via the `-K`
+config file returns **405 with an EMPTY body** on `/merge`. A 405 there is this
+trap (or a base-moved mergeability recheck — GET the PR, see `mergeable:true`,
+then retry with `-H`), NOT a permission problem.
+
+## Building issue/PR bodies without quote carnage
+Hand-written `jq -n --arg t "..." '{title:$t, body:"..."}'` one-liners with long
+markdown bodies WILL break on a stray quote (and the broken quoting can swallow
+the following commands). Build bodies as files (heredoc or write tool), then:
+```bash
+b=$(jq -Rs . body.md)
+jq -n --arg t "$title" --argjson b "$b" '{title:$t, body:$b, head:"<branch>", base:"main"}' > payload.json
+curl ... -d @payload.json
+```
+
+## Gotchas measured 2026-10-14 / 2026-10-17 / 2026-10-18
+- Unauthenticated/bad token → HTTP 401 body `{"message":"not found"}`; `jq '.[]|[.number,..]'` then fails with *cannot index "not found"* — that is an auth failure, not a missing repo.
+- **Insufficient token scope ≠ missing data.** The credential-store token
+  (measured 2026-10-17) carries only `write:repository,write:user`; the issues
+  API answers HTTP 403 `{"message":"token does not have at least one of required
+  scope(s), required=[read:issue], token scope=write:repository,write:user"}`.
+  jq surfaces that JSON as the *cannot index* error — do NOT conclude the issue
+  list is empty, and note POSTs under this token create NOTHING (verify, don't
+  assume retry safety). Filing issues needs a fresh token minted in the Gitea
+  web UI with `read:issue`+`write:issue` (Frank-class credential action; ask) —
+  OR use the main-checkout `.env` `GITEA_TOKEN`, which already has issue scope.
+  PR endpoints work fine with either token (`pulls` POST/GET/merge all 200/201).
+- On the created-PR response `.head.name` can be null; verify with the `GET /pulls/<n>` and use `.head.ref`.
+- **Swagger JSON is disabled on this instance** — `/api/swagger.v1.json`, `/api/swagger.json` and `/api/v1/swagger.json` all 404. Do not go looking for the schema there; the 422 messages name the field and its Go type, which is the faster instrument.