112 lines
3.0 KiB
Markdown
112 lines
3.0 KiB
Markdown
---
|
|
name: gitea-pr-review-cli
|
|
description: Use when an agent needs to fetch a single Gitea PR and produce or consume the project's review document format with strict version checks.
|
|
---
|
|
|
|
# gitea-pr-review CLI
|
|
|
|
## Overview
|
|
Use this skill when you need PR review context from Gitea in a stable document format for LLM workflows.
|
|
|
|
The CLI supports two output formats (`markdown`, `json`) and one strict schema version (`v1`). Version mismatch must be treated as a hard failure.
|
|
|
|
## When to Use
|
|
|
|
Use this skill when:
|
|
- You need to fetch one PR and convert it into LLM-friendly review documents.
|
|
- You need to re-render Markdown from a previously generated JSON file.
|
|
- You need deterministic output rules (numbering/version/header fields).
|
|
|
|
Do not use this skill when:
|
|
- You need cross-PR aggregation.
|
|
- You need full patch/diff bodies (this tool intentionally focuses on review context + diff stat).
|
|
|
|
## Required Inputs
|
|
|
|
For `fetch`, these environment variables are required:
|
|
- `GITEA_PR_CLI_API_TOKEN`
|
|
- `GITEA_PR_CLI_URL`
|
|
- `GITEA_PR_CLI_REPO`
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 0) load env
|
|
source .local/env.sh
|
|
|
|
# 1) sanity check CLI document version contract
|
|
gitea-pr-review version
|
|
# expected: v1
|
|
|
|
# 2) fetch markdown to stdout (default)
|
|
gitea-pr-review fetch <pr-index>
|
|
|
|
# 3) fetch json to file
|
|
gitea-pr-review fetch <pr-index> --format json --out pr.json
|
|
|
|
# 4) render markdown from json
|
|
gitea-pr-review render-md --in pr.json --out pr.md
|
|
```
|
|
|
|
## Command Reference
|
|
|
|
### `fetch <pr-index>`
|
|
Fetch PR data from Gitea and output review document.
|
|
|
|
Options:
|
|
- `--format markdown|json` (default `markdown`)
|
|
- `--out <path>` (if omitted, write to stdout)
|
|
|
|
### `render-md --in <json_path>`
|
|
Render Markdown from existing JSON document.
|
|
|
|
Options:
|
|
- `--out <path>` (if omitted, write to stdout)
|
|
|
|
Important:
|
|
- Input JSON must have `version == "v1"`.
|
|
- If version mismatches, command exits non-zero.
|
|
|
|
### `version`
|
|
Print current document version string.
|
|
|
|
Expected output:
|
|
- `v1`
|
|
|
|
## Output Contract (v1)
|
|
|
|
Markdown header contains:
|
|
- Title line: `# <repo> #<pr> <title>`
|
|
- Numbering rule block
|
|
- `version: v1`
|
|
- `fetched at: <rfc3339>`
|
|
- PR description
|
|
|
|
JSON contains:
|
|
- Top-level `version: "v1"`
|
|
- `meta.fetched_at` (RFC3339 string)
|
|
|
|
Numbering hierarchy:
|
|
- Review: `<pr>.<review>`
|
|
- Comment: `<pr>.<review>.<comment>`
|
|
- Reply: `<pr>.<review>.<comment>.<reply>`
|
|
|
|
## Failure Handling
|
|
|
|
If `fetch` fails:
|
|
1. Check all required env vars are set.
|
|
2. Re-run with same env using a small PR index to isolate auth/connectivity issues.
|
|
3. Confirm repo slug format is `<owner>/<repo>`.
|
|
|
|
If `render-md` fails:
|
|
1. Validate JSON is generated by this CLI.
|
|
2. Validate `version` is exactly `v1`.
|
|
3. Check JSON is complete (`meta`, `reviews`, `threads`, `diff_stat`).
|
|
|
|
## Common Mistakes
|
|
|
|
- Running `fetch` without sourcing env file.
|
|
- Assuming schema compatibility across versions.
|
|
- Editing JSON `version` manually and expecting `render-md` to work.
|
|
- Treating position-only comments as lacking location; this CLI maps available position data to a displayed line when possible.
|