docs: add design spec and implementation plan

2026-04-01 17:51:39 -04:00
parent 4b7ac1cfde
commit 85a9b03171
2 changed files with 936 additions and 0 deletions
@@ -0,0 +1,133 @@
+# 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