# gitea

Consolidated Gitea API client and pi extension for git.dominat.us.

Provides a pure TypeScript Gitea API client (no external dependencies), a pi extension that registers tools for LLM use, and a standalone CLI.

## Structure

```
src/           Core API client (pure fetch, token auth, zero deps)
pi-extension/  Pi extension adapter (registers tools + webhook server)
cli.ts         Standalone CLI
SKILL.md       Agent skill definition (auto-discovered by pi)
TOOL.md        Tool reference documentation
```

## Installation

### As a pi extension

Add to your `settings.json`:

```json
{
  "packages": ["/path/to/gitea/pi-extension"]
}
```

Or place/symlink `pi-extension/` into your `<agentDir>/extensions/` directory.

### As a library

```typescript
import { GiteaClient, listRepos, getIssue } from "./src/index.js";

const client = new GiteaClient({
  url: "https://git.dominat.us",
  token: "your-token",
});

const repos = await listRepos(client);
const issue = await getIssue(client, "owner", "repo", 1);
```

### As a CLI

```bash
export GITEA_TOKEN="your-token"
npx tsx cli.ts whoami
npx tsx cli.ts repos
npx tsx cli.ts issues owner/repo
npx tsx cli.ts create-issue owner/repo "Bug title" --body "Description"
```

## Configuration

| Variable | Purpose | Default |
|----------|---------|---------|
| `GITEA_URL` | Gitea instance URL | `https://git.dominat.us` |
| `GITEA_TOKEN` | API token (required) | — |
| `GITEA_OWNER` | Default repo owner | — |
| `GITEA_REPO` | Default repo name | — |

See [TOOL.md](TOOL.md) for full tool documentation and [SKILL.md](SKILL.md) for the agent skill definition.

## Auth

All API calls use `Authorization: token <GITEA_TOKEN>` header. No HMAC secrets.

Webhook endpoint optionally validates with `Authorization: Bearer <PI_WEBHOOK_TOKEN>`.