gitea-browser/CLAUDE.md

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

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.