readme

2026-06-03 06:34:28 +05:00
parent dc8706e809
commit b8b4cb3eae
2 changed files with 72 additions and 0 deletions
@@ -1,3 +1,4 @@
 .DS_Store
 .docs/
+.claude/
 tmp/
@@ -0,0 +1,71 @@
+# tea — Claude Code plugin for the Gitea CLI
+
+A Claude Code plugin that gives Claude a reference for the `tea` CLI and enforces a hard rule: every `tea` command runs under the login **the operator chose**, never one Claude picked.
+
+## What it ships
+
+| Piece | What it does |
+|---|---|
+| `/tea:login` skill | Prompts you to pick a Gitea login and pins it to the project |
+| `/tea:use` skill | Tea CLI reference — loads command docs on demand |
+| `tea-guard` hook | PreToolUse hook that blocks or rewrites every `tea` invocation |
+
+## Prerequisites
+
+- **Claude Code** — CLI, desktop app, or IDE extension
+- **`tea`** — Gitea's official CLI. Install with `brew install tea` (macOS) or from [gitea.com/gitea/tea/releases](https://gitea.com/gitea/tea/releases)
+- At least one login configured: `tea logins add` (interactive — run it in a terminal, not via Claude)
+
+## Installation
+
+Clone this repo into your Claude Code plugins directory:
+
+```bash
+git clone <repo-url> ~/.claude/plugins/tea
+```
+
+Then add it to your project's `.claude/settings.json`:
+
+```json
+{
+  "plugins": ["~/.claude/plugins/tea"]
+}
+```
+
+Or to your global settings (`~/.claude/settings.json`) to enable it everywhere.
+
+## First use
+
+Run `/tea:login` once per project. Claude will list your available Gitea logins and ask you to pick one. The choice is written to `.claude/settings.local.json` and takes effect immediately — no restart needed.
+
+```
+/tea:login
+```
+
+After that, use `/tea:use` to look up commands, or just ask Claude to do something with Gitea and it will load the reference automatically.
+
+## How the login guard works
+
+Every `tea` invocation Claude writes must carry the literal placeholder `--login "$GITEA_LOGIN"`. The `tea-guard` hook intercepts the Bash call before it runs, looks up the pinned login from `.claude/settings.local.json`, and rewrites the command to use it.
+
+Claude is **blocked** from:
+- running `tea` without `--login` at all
+- naming a login itself (e.g. `--login myaccount`)
+- using any variable other than `$GITEA_LOGIN`
+
+This prevents silent fallback to the machine's default login (often a personal account) when working in a project that belongs to a different identity.
+
+`tea logins list` and `tea --version / --help` are exempt — they don't touch Gitea data.
+
+## Project layout
+
+```
+.claude-plugin/plugin.json   plugin manifest
+hooks/
+  hooks.json                 registers the PreToolUse hook
+  tea-guard.sh               the guard (Python 3, no deps)
+skills/
+  login/SKILL.md             /tea:login skill
+  use/SKILL.md               /tea:use skill
+  use/references/tea/        tea CLI reference docs
+```