61 lines
2.9 KiB
Markdown
61 lines
2.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Overview
|
|
|
|
A Node.js Playwright-based browser automation toolkit for interacting with a Gitea instance at `https://git.hq.ars9.space`. The goal is to automate the full Gitea workflow: login, listing repositories, viewing a repo, and creating/maintaining pull requests.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
npm install # Install dependencies
|
|
npx playwright install chromium # Install Chromium browser if needed
|
|
npm run typecheck # Type-check without emitting (tsc --noEmit)
|
|
npm run login # Smoke test login
|
|
npm run inspect # Dump login page form elements as JSON
|
|
npm start # Start the MCP server (normally launched by Claude Code)
|
|
```
|
|
|
|
Requires Node.js >= 18. All scripts run directly via `tsx` with no compile step.
|
|
|
|
## Target Functions
|
|
|
|
The scripts in this repo should collectively cover:
|
|
|
|
1. **Login** — Authenticate to Gitea, handle forced password change flows, verify success via `.avatar` element.
|
|
2. **List repos** — Navigate to the user's repository list and extract repo names/metadata.
|
|
3. **View repo** — Navigate to a specific repo and read its contents (files, branches, README, etc.).
|
|
4. **Create and maintain a pull request** — Open a PR from a branch, set title/description, and perform follow-up actions (comment, update, merge, close).
|
|
|
|
## Architecture
|
|
|
|
### MCP server (primary interface)
|
|
|
|
`server.mjs` is an MCP server registered globally at `~/.claude/mcp.json`. It exposes 9 tools that any Claude Code session can call:
|
|
|
|
| Tool | Description |
|
|
|---|---|
|
|
| `create_repo` | Create a new repository |
|
|
| `list_repos` | List repos accessible to the agent account |
|
|
| `view_repo` | File list, default branch, README excerpt |
|
|
| `view_file` | Raw content of a file at a given branch/path |
|
|
| `list_prs` | List PRs (open/closed/all) |
|
|
| `create_pr` | Create a PR from head→base with title and body |
|
|
| `view_pr` | PR details, status, branches, and comments |
|
|
| `comment_pr` | Add a comment to a PR |
|
|
| `merge_pr` | Merge a PR |
|
|
| `close_pr` | Close a PR without merging |
|
|
|
|
### Shared modules
|
|
|
|
- **`src/lib/auth.ts`** — exports the `Session` interface and `createSession()`, which launches headless Chromium, logs in, handles forced password changes, and returns `{ browser, page }`. Throws if login fails.
|
|
- **`src/lib/gitea.ts`** — All Gitea operations, each typed with explicit return interfaces. Functions take a `Session` plus operation-specific args, navigate to the relevant Gitea page, and return scraped data.
|
|
|
|
Each tool call in `src/server.ts` creates a fresh session via `withSession<T>()` and closes the browser when done.
|
|
|
|
### Standalone scripts
|
|
|
|
- **`src/login.ts`** — Standalone login smoke test.
|
|
- **`src/inspect.ts`** — Dumps form element metadata from the login page as JSON; useful for updating Playwright selectors when Gitea's HTML changes.
|