✨ Add gitea plugin

Ports dirigent's gitea scripts into a self-contained reliquary plugin. Scripts run via uv with PEP 723 inline deps — no project venv needed. Gitea connection inferred from `git remote get-url origin` with env-var overrides; only GITEA_TOKEN is mandatory. Workpad path and tickets directory are parameterized so the plugin works in any project. Label set externalized to labels.default.json with project-level override via .gitea-labels.json. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-19 19:52:02 +02:00
parent c5b189a73c
commit 68c112d2c8
15 changed files with 1154 additions and 0 deletions
@@ -0,0 +1,63 @@
+# gitea plugin
+
+Claude Code plugin for working with Gitea issues from any project. Ships a single skill (`gitea`) and a set of self-contained PEP 723 scripts that need no project-level Python setup — `uv run` builds an isolated env per script on first invocation.
+
+## What it can do
+
+| Task | Script |
+|------|--------|
+| Verify connectivity | `ping.py` |
+| Fetch a ticket as markdown | `fetch_ticket.py` |
+| Create an issue (inline or from a goal file) | `create_ticket.py` |
+| Post a markdown file as a comment | `post_comment.py` |
+| Start work on a ticket (branch + context) | `start_ticket.py` |
+| List/search issues | `list_tickets.py` |
+| Close issues | `close_ticket.py` |
+| Scaffold standard labels in a new repo | `setup_labels.py` |
+
+## Prerequisites
+
+- [uv](https://docs.astral.sh/uv/) on PATH.
+- A Gitea instance with API access and an API token.
+- The project you're working in is a git clone of the Gitea repo (so the remote URL is parseable). If not, you can set `GITEA_URL`/`GITEA_OWNER`/`GITEA_REPO` explicitly.
+
+## Gitea setup
+
+1. Log into Gitea, go to **Settings → Applications → Manage Access Tokens**.
+2. Generate a token with scopes:
+   - `issue` — Read and Write
+   - `repository` — Read and Write
+3. Add it to a `.env` file in your project root (gitignored):
+
+```env
+GITEA_TOKEN=your_token_here
+```
+
+`GITEA_URL`, `GITEA_OWNER`, and `GITEA_REPO` are inferred from `git remote get-url origin`. Set them in `.env` only if you need to override the inferred values (mirrors, separate API host, etc.).
+
+## Verify
+
+```bash
+uv run ${CLAUDE_PLUGIN_ROOT}/skills/gitea/scripts/ping.py
+```
+
+Should print the resolved URL/repo and `Connection: OK`.
+
+## Bootstrap labels (optional)
+
+```bash
+uv run ${CLAUDE_PLUGIN_ROOT}/skills/gitea/scripts/setup_labels.py
+```
+
+Creates a default emoji-prefixed label set. Override per-project by placing `.gitea-labels.json` in the project root — its contents fully replace the default set.
+
+## Architecture notes
+
+- All scripts use **CWD-relative paths** for git, `.env`, and workpad lookups. The plugin directory is only consulted for shipped resources (like `labels.default.json`).
+- Imports are **flat sibling imports** (`from client import …`) — scripts are run as files, not as a package.
+- Each CLI entrypoint carries a PEP 723 `# /// script` header listing its own dependencies, so no shared environment, lockfile, or `pyproject.toml` is needed.
+
+## See also
+
+- The `gitea` skill's `SKILL.md` is the agent-facing reference. Read that to understand how Claude uses these scripts.
+- A future sibling plugin will layer workflow glue (kanban, ticket-to-implementation flows) on top of this thin API surface.