# 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

- **`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.
- **`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 `server.ts` creates a fresh session via `withSession<T>()` and closes the browser when done.

### Standalone scripts

- **`login.ts`** — Standalone login smoke test.
- **`inspect.ts`** — Dumps form element metadata from the login page as JSON; useful for updating Playwright selectors when Gitea's HTML changes.