hyprcrd/public/plugins/gitea/TODO.md

gitea plugin — roadmap

Status: scaffold. Phase 1 = accounts CRUD + connection test only. The gitea-issue-client/ Python tool in the project root is the reference for the full feature surface that needs to be ported.

Phase 1 — done ✅

• GiteaClient.php cURL wrapper with testConnection(), searchIssues(), listRepoIssues(), getIssue(), listIssueComments()
• gitea_accounts table with encrypted token (vault key, same as email)
• Routes: GET/POST/PATCH/DELETE /api/gitea/accounts + POST .../test
• Settings tab via hyprcrd.settings.registerTab
• Header button "gitea"
• Welcome view + accounts management form
• Connection test against /api/v1/user

Phase 2 — issue reader (next)

• Issue list view in the overlay: - Search box (q parameter) - State filter (open/closed/all) - Owner/team filter (optional dropdown) - Pagination (reuse pattern from email plugin) - Each row: title, repo path, state badge, labels, author, age
• Issue detail view (right pane): - Subject + state + labels + assignees + milestone - Body (markdown rendered with the existing core renderer) - Comments list (each with author + timestamp) - "Open on Gitea" link button
• Extract → card: - Card title = issue title - Card body = markdown with metadata header + body + comments + #gitea #issue tags - Optionally store backref (account_id, owner, repo, index) in a gitea_issue_links table for later sync

Phase 3 — write operations

• Add comment from the detail view
• Close / reopen issue
• Edit title / body (only for the issue creator)
• Set labels (need to fetch repo labels, multi-select UI)
• Set assignees (typeahead from repo collaborators)
• Set milestone
• Set due date

Phase 4 — create issues

• "new issue" button in the overlay
• Create from card: a card → push as new gitea issue, store the backref so future edits can sync both ways
• Pre-fill template from a repo's .gitea/ISSUE_TEMPLATE.md if available

Phase 5 — bidirectional sync (the killer feature)

• When a card has a gitea backref, an "issue" badge appears
• Edit the card body in hyprcrd → "push to gitea" button
• "pull from gitea" button refreshes the card from the live issue
• Conflict detection via updated_at timestamps
• This replaces the Python tool's gir push workflow

Phase 6 — multi-instance + ergonomics

• Account selector remembers last-used account in localStorage
• Per-account default filters (e.g. always show assigned=true)
• Org/repo browsing tree on the left
• Label browser per repo
• Milestone view
• Search across multiple accounts

Hardening

• Rate limiting on test endpoint
• Better error messages (currently raw HTTP body leaks through)
• Cert pinning option for self-hosted gitea instances
• Connection caching (currently every request opens a new cURL handle)
• Map common errors (401 → "token expired", 403 → "no access", etc.)

Mapping from the Python tool

Python feature	hyprcrd plan
gi search	overlay issue list with q filter
gi list --owner --repo	overlay with owner/repo filter
gi get	overlay detail pane
gi create	Phase 4 "new issue" button
gi edit	Phase 3 detail-pane edit buttons
gi comment	Phase 3 comment box in detail pane
gi comments	Phase 2 comments rendering
gir fetch → markdown files	Phase 2 extract-as-card (no files needed)
gir push → sync local edits	Phase 5 bidirectional sync
gir new --push	Phase 4 create-from-card
gir clean	not needed (cards are managed via the UI)
_valid-metadata.md per repo	label/milestone dropdowns at edit time
templates/gir-new-issue.md	configurable issue template per account

Once Phase 2–4 are done, the entire gitea-issue-client/ Python tool can be removed from the project root.