Mortdecai
134 lines
5.6 KiB
Markdown
134 lines
5.6 KiB
Markdown
# Gitea Connector for Claude Code — Design Spec
|
|
|
|
**Date:** 2026-04-01
|
|
**Status:** Approved
|
|
**Author:** Seth + Claude
|
|
|
|
## Overview
|
|
|
|
A Claude Code plugin that lets collaborators connect to Seth's Gitea instance (`git.sethpc.xyz`) with their own accounts. Bundles an adapted bash CLI and provides guided setup, commit conventions, and Gitea-aware skills.
|
|
|
|
**Target users:** Friends and collaborators Seth invites, who have their own Gitea accounts on `git.sethpc.xyz` and use Claude Code.
|
|
|
|
## Plugin Structure
|
|
|
|
```
|
|
gitea-connector/
|
|
├── plugin.json # Plugin manifest
|
|
├── commands/
|
|
│ └── gitea-setup.md # /gitea-setup slash command
|
|
├── skills/
|
|
│ └── gitea-workflow.md # Commit conventions & Gitea awareness
|
|
├── hooks/
|
|
│ └── push-reminder.sh # Post-commit push reminder (opt-in)
|
|
├── agents/
|
|
│ └── gitea-setup.md # Interactive setup agent
|
|
├── bin/
|
|
│ └── gitea # Bash CLI (external-only, no LAN)
|
|
└── README.md
|
|
```
|
|
|
|
## Component Details
|
|
|
|
### 1. Bash CLI (`bin/gitea`)
|
|
|
|
Adapted from Seth's existing `~/bin/gitea` with these changes:
|
|
|
|
- **Host:** Always `https://git.sethpc.xyz` — no LAN detection, no `192.168.0.125` references. All users are external.
|
|
- **Username:** Read from `~/.config/gitea/username` (not hardcoded to `Seth`).
|
|
- **Token:** Read from `~/.config/gitea/token` (same convention as original).
|
|
- **Host override:** Optional `~/.config/gitea/host` file for future flexibility, defaults to `git.sethpc.xyz`.
|
|
|
|
Commands (unchanged interface):
|
|
```
|
|
gitea create <name> [--private] [--description "..."]
|
|
gitea remote <name>
|
|
gitea push
|
|
gitea delete <name>
|
|
gitea list
|
|
```
|
|
|
|
Drops the `api_base()` LAN/WAN probe function — replaced with a simple `https://${GITEA_HOST}/api/v1` base URL.
|
|
|
|
### 2. Setup Flow (`/gitea-setup`)
|
|
|
|
Invokes the `gitea-setup` agent for interactive credential setup.
|
|
|
|
**Steps:**
|
|
|
|
1. **Dependency check:** Verify `curl`, `jq`, `git` are installed. If missing, tell the user what to install and stop.
|
|
2. **Existing config check:** If `~/.config/gitea/token` exists, ask if they want to reconfigure.
|
|
3. **Collect username:** Ask the user for their Gitea username.
|
|
4. **Walk through API key generation:**
|
|
> Go to `https://git.sethpc.xyz` → click your **profile icon** (top right) → **Settings** → **Applications** → under **Manage Access Tokens**, name it `claude-code`, grant **repo** (read/write) and **user** (read) permissions, click **Generate Token** → paste the token back here.
|
|
5. **Store credentials:**
|
|
- Create `~/.config/gitea/` if missing
|
|
- Write `token` and `username` files
|
|
- `chmod 600` both files
|
|
6. **Install CLI:**
|
|
- Copy `bin/gitea` to `~/bin/gitea`
|
|
- `chmod +x ~/bin/gitea`
|
|
- If `~/bin` not on PATH, warn and suggest adding it
|
|
7. **Validate:** `GET /api/v1/user` with the token, confirm returned username matches what they entered.
|
|
8. **Success message:** Confirm everything works, list available commands.
|
|
|
|
**Tone:** Silly but appropriate throughout the entire experience — the setup agent's conversational messages, CLI help text, success/error messages, and skill descriptions should all have personality. Think friendly chaos goblin who knows their way around git, not corporate onboarding wizard.
|
|
|
|
### 3. Skill (`skills/gitea-workflow.md`)
|
|
|
|
Loaded into Claude Code's context when working in repos with a `git.sethpc.xyz` origin. Provides:
|
|
|
|
- **Commit conventions (default-on, overridable):**
|
|
- Conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
|
|
- Commit every meaningful change immediately
|
|
- Always push after commit
|
|
- No squashing, no batching unrelated changes
|
|
- **Gitea CLI usage:** Reference for `gitea create`, `remote`, `push`, `delete`, `list`
|
|
- **Credential safety:** Never commit tokens; ensure `.gitignore` covers `.env`, credential files, `~/.config/gitea/`
|
|
- **Override mechanism:** Users can override any convention in their project's CLAUDE.md
|
|
|
|
Trigger condition: Skill activates when current repo's origin URL contains `git.sethpc.xyz`.
|
|
|
|
### 4. Hook (`hooks/push-reminder.sh`)
|
|
|
|
- **Type:** PostToolUse hook on the `Bash` tool
|
|
- **Trigger:** Detects successful `git commit` in command output
|
|
- **Action:** Echoes a reminder to push
|
|
- **Default:** Disabled (opt-in via plugin settings)
|
|
|
|
### 5. Agent (`agents/gitea-setup.md`)
|
|
|
|
The interactive agent behind `/gitea-setup`. Uses `AskUserQuestion` to collect input step by step. Handles all the logic described in the setup flow above.
|
|
|
|
## Error Handling
|
|
|
|
| Scenario | Behavior |
|
|
|----------|----------|
|
|
| Token invalid / expired | "That token didn't work. Generate a new one at Settings → Applications." |
|
|
| Gitea unreachable | "Can't reach git.sethpc.xyz. Check your network or VPN connection." |
|
|
| `~/bin` not on PATH | Warn and suggest adding it to shell profile |
|
|
| Token file exists, re-running setup | "Found existing config. Reconfigure? (y/N)" |
|
|
| `jq` / `curl` / `git` not installed | Check at start, list what's missing |
|
|
| Username mismatch (token returns different user) | "Token belongs to <X> but you said <Y>. Which is correct?" |
|
|
|
|
## Networking
|
|
|
|
- **Always HTTPS to `git.sethpc.xyz`** (Caddy reverse proxy to Gitea CT 146)
|
|
- No LAN IP references anywhere — all users are external
|
|
- Default host overridable via `~/.config/gitea/host` file
|
|
|
|
## Dependencies
|
|
|
|
- `curl` — API calls
|
|
- `jq` — JSON parsing
|
|
- `git` — repo operations
|
|
|
|
No other external dependencies. Pure bash CLI.
|
|
|
|
## Out of Scope
|
|
|
|
- Multi-instance support (connecting to arbitrary Gitea servers)
|
|
- User account creation on Gitea (Seth invites users manually)
|
|
- SSH key setup (HTTPS + token auth only)
|
|
- CI/CD integration
|