# GitHub Posting Reference

How to post review comments to a GitHub pull request via the REST API. Read this
only when the user has **explicitly opted in** to posting comments online (see the
Output Format section in `SKILL.md`).

Replace the placeholders below with your own values:

- `<owner>` — repository owner (user or org), e.g. `your-org`
- `<repo>` — repository name, e.g. `your-repo`
- `<pull_number>` — the pull request number (the number in the PR URL)
- Auth token comes from the `GITHUB_TOKEN` env var (a review-bot access token /
  fine-grained PAT with "Pull requests: Read and write").

All requests use these headers:

```
Authorization: Bearer $GITHUB_TOKEN
Accept: application/vnd.github+json
X-GitHub-Api-Version: 2026-03-10
```

## Handling the token safely

`GITHUB_TOKEN` is a secret that can act on the user's behalf. Treat it as
write-only from your perspective: you may confirm it's present and report its
length, but its value must never leave the process. This is enforced by the
skill's `PreToolUse` hook (`scripts/protect-token.sh`), which blocks any Bash
command that would expose the value.

**Allowed** — confirm it's configured without revealing it. This uses only the
length form `${#GITHUB_TOKEN}`, so presence is derived from length and the value
is never expanded:

```bash
if [ "${#GITHUB_TOKEN}" -gt 0 ]; then
  echo "GITHUB_TOKEN is set (length: ${#GITHUB_TOKEN})"
else
  echo "GITHUB_TOKEN is not set"
fi
```

**Never do any of these** (the hook will deny them):

- `echo "$GITHUB_TOKEN"`, `printf` it, or `cat` a file/heredoc containing it.
- Print it to chat, write it to a file, or include it in a commit.
- `printenv GITHUB_TOKEN`, or dump the environment (`env`, `set`, `export -p`).
- Inline the literal token in a command (it lands in shell history/logs) — always
  reference `$GITHUB_TOKEN`.
- Use `curl -v` / `--verbose` / `--trace*`, which echo the `Authorization` header.

When sharing command output for debugging, redact the `Authorization:` header line.

## Comment Format

- Line comments: `[Flutter Code Review Bot]: <feedback>`
- Summary (optional): `[Flutter Code Review Bot] Summary: <overall feedback>`

## API Usage (Essentials)

GitHub distinguishes three kinds of comments:

| Goal | Endpoint |
|---|---|
| General PR comment (not tied to a line) | `POST /repos/<owner>/<repo>/issues/<pull_number>/comments` |
| Single inline comment on a diff line | `POST /repos/<owner>/<repo>/pulls/<pull_number>/comments` |
| Batch review (many inline + verdict/approval) | `POST /repos/<owner>/<repo>/pulls/<pull_number>/reviews` |

A PR is also an issue, so the **PR number is the issue number** for general comments.
Inline comments need `commit_id` (the head SHA), `path`, and `line` (the line in the
file's diff). For added lines use `side=RIGHT`; for removed lines use `side=LEFT`.
For multi-line comments add `start_line` (+ `start_side`).

## Example (General PR Comment)

[Issues / Comments API](https://docs.github.com/en/rest/issues/comments?apiVersion=2026-03-10)

```bash
curl --request POST \
  --header "Authorization: Bearer $GITHUB_TOKEN" \
  --header "Accept: application/vnd.github+json" \
  --header "X-GitHub-Api-Version: 2026-03-10" \
  --url "https://api.github.com/repos/<owner>/<repo>/issues/<pull_number>/comments" \
  --data '{"body":"[Flutter Code Review Bot]: This is a general comment on the PR."}'
```

### Inline Diff Comment (Minimal Example)

[Pulls / Review comments API](https://docs.github.com/en/rest/pulls/comments?apiVersion=2026-03-10)

```bash
curl -s -X POST \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  "https://api.github.com/repos/<owner>/<repo>/pulls/<pull_number>/comments" \
  --data '{
    "body": "[Flutter Code Review Bot]: Feedback",
    "commit_id": "<head_sha>",
    "path": "lib/.../file.dart",
    "line": 42,
    "side": "RIGHT"
  }'
```

Fetch the head SHA (useful when running locally):

```bash
curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/<owner>/<repo>/pulls/<pull_number>" \
  | grep -A 3 '"head"'
```

### Fast Checklist

1. Get the head SHA (`commit_id`) from the PR JSON.
2. Confirm the line number exists in the diff for that file and `side`.
3. POST with `commit_id`, `path`, `line`, `side`; verify the response contains an
   `"id"` and `"path"`.

Failure quick-fix: 422 Unprocessable => line not part of the diff or wrong `side`;
404 => wrong owner/repo/number or token lacks PR access; 401 => bad/expired token.

## Batch Review + Approval

Prefer a single **review** when posting many inline comments plus a verdict — it
groups them and sets approval in one call. Use `event=APPROVE` ONLY after verdict =
APPROVED and: no blocking notes, all comments resolved/visible, bot not already
approved, checks not failing. Other events: `REQUEST_CHANGES`, `COMMENT`.

```bash
curl -s -X POST \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  "https://api.github.com/repos/<owner>/<repo>/pulls/<pull_number>/reviews" \
  --data '{
    "commit_id": "<head_sha>",
    "body": "[Flutter Code Review Bot] Summary: Looks good.",
    "event": "APPROVE",
    "comments": [
      {"path": "lib/.../file.dart", "line": 42, "side": "RIGHT",
       "body": "[Flutter Code Review Bot]: Feedback"}
    ]
  }'
```

# GitLab Posting Reference

How to post review comments to a GitLab merge request via the API. Read this only
when the user has **explicitly opted in** to posting comments online (see the
Output Format section in `SKILL.md`).

Replace the placeholders below with your own values:

- `<your-gitlab-host>` — your GitLab host, e.g. `git.example.com`
- `<project_id>` — your project's numeric ID
- `<iid>` — the merge request's internal ID (the number in the MR URL)
- Auth token comes from the `GITLAB_TOKEN` env var (a review-bot access token).

## Handling the token safely

`GITLAB_TOKEN` is a secret that can act on the user's behalf. Treat it as
write-only from your perspective: you may confirm it's present and report its
length, but its value must never leave the process. This is enforced by the
skill's `PreToolUse` hook (`scripts/protect-token.sh`), which blocks any Bash
command that would expose the value.

**Allowed** — confirm it's configured without revealing it. This uses only the
length form `${#GITLAB_TOKEN}`, so presence is derived from length and the value
is never expanded:

```bash
if [ "${#GITLAB_TOKEN}" -gt 0 ]; then
  echo "GITLAB_TOKEN is set (length: ${#GITLAB_TOKEN})"
else
  echo "GITLAB_TOKEN is not set"
fi
```

**Never do any of these** (the hook will deny them):

- `echo "$GITLAB_TOKEN"`, `printf` it, or `cat` a file/heredoc containing it.
- Print it to chat, write it to a file, or include it in a commit.
- `printenv GITLAB_TOKEN`, or dump the environment (`env`, `set`, `export -p`).
- Inline the literal token in a command (it lands in shell history/logs) — always
  reference `$GITLAB_TOKEN`.
- Use `curl -v` / `--verbose` / `--trace*`, which echo the `PRIVATE-TOKEN` header.

When sharing command output for debugging, redact the `PRIVATE-TOKEN:` header line.

## Comment Format

- Line comments: `[Flutter Code Review Bot]: <feedback>`
- Summary (optional): `[Flutter Code Review Bot] Summary: <overall feedback>`

## API Usage (Essentials)

GitLab Discussions API: `POST /projects/:id/merge_requests/:iid/discussions`.
Required `position[...]` fields for inline notes (added lines):
`position_type=text`, `base_sha`, `start_sha`, `head_sha`, `new_path`, `new_line`.
Removed lines: use `old_path` + `old_line` instead of new.
Missing `position_type` => GitLab error and no comment.
Auth: `PRIVATE-TOKEN` from the `GITLAB_TOKEN` env var.

## Example (General MR Comment)

```bash
curl --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  --url "https://<your-gitlab-host>/api/v4/projects/<project_id>/merge_requests/<iid>/discussions" \
  --form "body=[Flutter Code Review Bot]: This is a general comment on the MR."
```

**Important Note:** Use the exact curl format shown above
(`--request POST --header ... --url ... --form ...`) for posting comments to avoid
401 Unauthorized errors. Alternative formats like `-X POST -H ...` may not
authenticate properly with the API.

### Inline Diff Comment (Minimal Example)

```bash
curl -s -X POST \
  -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://<your-gitlab-host>/api/v4/projects/<project_id>/merge_requests/<iid>/discussions" \
  --form "body=[Flutter Code Review Bot]: Feedback" \
  --form "position[position_type]=text" \
  --form "position[base_sha]=<base>" \
  --form "position[start_sha]=<start>" \
  --form "position[head_sha]=<head>" \
  --form "position[new_path]=lib/.../file.dart" \
  --form "position[new_line]=42"
```

Fetch `diff_refs` (useful when running locally):

```bash
curl -s -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://<your-gitlab-host>/api/v4/projects/<project_id>/merge_requests/<iid>" \
  | grep -A 6 '"diff_refs"'
```

### Fast Checklist

1. Get `diff_refs` (base/start/head) from MR JSON.
2. Confirm absolute line number in current file (`nl -ba file | grep context`).
3. POST with all required fields; verify response contains `"type":"DiffNote"`.

Failure quick-fix: missing note => check `position_type`; invisible => wrong line;
400/error => refresh SHAs.

## Automated Approval

Use ONLY after verdict = APPROVED and: no blocking notes, all inline comments
visible, bot not already approved, pipeline not failing.

Approve:

```bash
curl -s -X POST -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://<your-gitlab-host>/api/v4/projects/<project_id>/merge_requests/<iid>/approve"
```

#!/usr/bin/env bash
#
# PreToolUse hook for the code-review skill.
#
# Goal: the agent may confirm a review-bot token is configured and report its
# LENGTH, but must never reveal the token VALUE. This hook enforces that
# deterministically in the harness rather than relying on instructions alone.
#
# Allowed:  existence/length checks via ${#GITLAB_TOKEN} / ${#GITHUB_TOKEN},
#           and passing the token to curl as an auth header.
# Blocked:  echo/printf/cat/tee of the token value, environment dumps, and
#           curl -v/--verbose/--trace (which print the auth header).
#
# The hook reads the PreToolUse event JSON on stdin and, to block a call, prints
# a permissionDecision=deny object (see code.claude.com/docs/en/hooks). Any other
# Bash command falls through (exit 0) to the normal permission flow.

input="$(cat)"

# Extract the Bash command. If jq is unavailable, scan the raw event instead so
# enforcement still applies (it just may be slightly more conservative).
if command -v jq >/dev/null 2>&1; then
  cmd="$(printf '%s' "$input" | jq -r '.tool_input.command // ""' 2>/dev/null)"
else
  cmd="$input"
fi

deny() {
  # Reasons must contain no double quotes or backslashes (kept JSON-safe inline).
  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' "$1"
  exit 0
}

names='GITLAB_TOKEN|GITHUB_TOKEN'

# 1) curl with verbose/trace prints the Authorization / PRIVATE-TOKEN header.
if printf '%s' "$cmd" | grep -Eq 'curl' \
   && printf '%s' "$cmd" | grep -Eq '(^|[[:space:]])(-v|--verbose|--trace[^[:space:]]*)([[:space:]]|$)'; then
  deny "curl -v/--verbose/--trace prints the auth header, which exposes the token. Re-run the request without verbose/trace flags."
fi

# 2) Environment dumps that would include the token.
if printf '%s' "$cmd" | grep -Eq "printenv[[:space:]]+($names)([[:space:]]|$)"; then
  deny "Printing the token with printenv is not allowed. Confirm it is set and how long it is with the length form instead."
fi
if printf '%s' "$cmd" | grep -Eq '(^|[|;&]|[[:space:]])(printenv|env|set|export[[:space:]]+-p|declare[[:space:]]+-p)[[:space:]]*(\||$)'; then
  deny "Dumping the whole environment can expose the token. Reference a specific variable length instead."
fi

# 3) Token VALUE passed to a printing/writing command. The length form is allowed
#    because the regex requires the value form ($NAME or ${NAME...}), and ${#NAME}
#    does not match it.
if printf '%s' "$cmd" | grep -Eq "(echo|printf|print|cat|tee)[[:space:]][^|;&]*[\$][{]?($names)"; then
  deny "Refusing to print the token value. Verify existence/length with the length form, but never echo/printf/cat the value itself."
fi

exit 0