### Install and Run Project

Source: https://github.com/rachel/git-on-cloudflare/blob/main/CLAUDE.md

Installs project dependencies and starts the development server.

```bash
npm install
npm run dev
```

--------------------------------

### Clone and Run Locally

Source: https://github.com/rachel/git-on-cloudflare/blob/main/README.md

Clone the project, install dependencies, and start a local development server using Vite and Workers SSR. This allows for local testing without Docker.

```bash
# Clone the project
git clone https://github.com/zllovesuki/git-on-cloudflare
cd git-on-cloudflare
npm install

# Start locally with Vite + Workers SSR (no Docker required)
npm run dev

# Push any repo to it
cd /your/existing/repo
git push http://localhost:8787/test/myrepo main
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/rachel/git-on-cloudflare/blob/main/README.md

Install all necessary Node.js dependencies for the project using npm.

```bash
npm install
```

--------------------------------

### Deploy Phase 2 Follow-up

Source: https://github.com/rachel/git-on-cloudflare/blob/main/MIGRATION-TESSERA-OIDC.md

Checkout, install, migrate, and deploy the phase 2 follow-up.

```bash
git checkout 7e1cdb2
npm install
npm run db:migrate
npx wrangler deploy
```

--------------------------------

### GET /auth

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

Entry point for Tessera sign-in and account management.

```APIDOC
## GET /auth

### Description
Entry point for Tessera sign-in and account management.

### Method
GET

### Endpoint
/auth
```

--------------------------------

### Deploy Phase 2

Source: https://github.com/rachel/git-on-cloudflare/blob/main/MIGRATION-TESSERA-OIDC.md

Checkout, install, migrate, and deploy phase 2 of the migration.

```bash
git checkout b274ea0
npm install
npm run db:migrate
npx wrangler deploy
```

--------------------------------

### Development Environment Variables

Source: https://github.com/rachel/git-on-cloudflare/blob/main/README.md

Copy the example development environment variables file to be used for local development.

```bash
# Development
cp .dev.vars.example .dev.vars
```

--------------------------------

### GET /

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

Serves the home page of the web UI.

```APIDOC
## GET /

### Description
Serves the home page of the web UI.

### Method
GET

### Endpoint
/
```

--------------------------------

### Deploy Phase 1

Source: https://github.com/rachel/git-on-cloudflare/blob/main/MIGRATION-TESSERA-OIDC.md

Checks out and deploys Phase 1 of the migration, including installing dependencies, migrating the database, and deploying with Wrangler.

```bash
git checkout b70097c
npm install
npm run db:migrate
npx wrangler deploy
```

--------------------------------

### GET /:owner

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

Lists repositories for a given owner.

```APIDOC
## GET /:owner

### Description
Lists repositories for a given owner.

### Method
GET

### Endpoint
/:owner
```

--------------------------------

### Deploy Phase 3

Source: https://github.com/rachel/git-on-cloudflare/blob/main/MIGRATION-TESSERA-OIDC.md

Checkout, install, migrate, and deploy phase 3 of the migration, which removes legacy components.

```bash
git checkout b894c74
npm install
npm run db:migrate
npx wrangler deploy
```

--------------------------------

### GET /:owner/:repo/blob

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

View the contents of a file with syntax highlighting.

```APIDOC
## GET /:owner/:repo/blob

### Description
View the contents of a file with syntax highlighting.

### Method
GET

### Endpoint
/:owner/:repo/blob

### Parameters
#### Query Parameters
- **ref** (string) - Optional - The branch name.
- **path** (string) - Optional - The path to the file.
```

--------------------------------

### Start Local Development Server

Source: https://github.com/rachel/git-on-cloudflare/blob/main/README.md

Run the local development server using npm to test your Cloudflare Worker locally.

```bash
npm run dev
```

--------------------------------

### Standard JSON Response Example

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

This is an example of a standard JSON response format returned by the API.

```json
{
  "field": "value"
  // Standard JSON responses
}
```

--------------------------------

### Deploy Latest Main Branch

Source: https://github.com/rachel/git-on-cloudflare/blob/main/MIGRATION-TESSERA-OIDC.md

Checkout, install, build, and deploy the latest main branch after migration closure.

```bash
git checkout main
npm install
npm run db:migrate
npm run build
npx wrangler deploy
```

--------------------------------

### GET /:owner/:repo

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

Displays the repository overview, including branches, tags, and the README file.

```APIDOC
## GET /:owner/:repo

### Description
Displays the repository overview, including branches, tags, and the README file.

### Method
GET

### Endpoint
/:owner/:repo
```

--------------------------------

### GET /:owner/:repo/info/refs?service=git-receive-pack

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

Capability advertisement for push operations.

```APIDOC
## GET /:owner/:repo/info/refs?service=git-receive-pack

### Description
Capability advertisement for push operations.

### Method
GET

### Endpoint
/:owner/:repo/info/refs?service=git-receive-pack

### Parameters
#### Query Parameters
- **service** (string) - Required - Must be 'git-receive-pack'
```

--------------------------------

### GET /:owner/:repo/tree

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

Browse the repository files at a specific branch and path.

```APIDOC
## GET /:owner/:repo/tree

### Description
Browse the repository files at a specific branch and path.

### Method
GET

### Endpoint
/:owner/:repo/tree

### Parameters
#### Query Parameters
- **ref** (string) - Optional - The branch name.
- **path** (string) - Optional - The path within the repository.
```

--------------------------------

### GET /:owner/:repo/info/refs?service=git-upload-pack

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

Capability advertisement for fetch operations. Returns refs and capabilities for Git v2 protocol.

```APIDOC
## GET /:owner/:repo/info/refs?service=git-upload-pack

### Description
Capability advertisement for fetch operations. Returns refs and capabilities for Git v2 protocol.

### Method
GET

### Endpoint
/:owner/:repo/info/refs?service=git-upload-pack

### Parameters
#### Query Parameters
- **service** (string) - Required - Must be 'git-upload-pack'

### Response
#### Success Response (200)
Advertised capabilities (protocol v2):
- `version 2`
- `agent=git-on-cloudflare/0.1`
- `ls-refs`
- `fetch`
- `side-band-64k`
- `ofs-delta`
- `object-format=sha1`

ls-refs arguments supported:
- `ref-prefix <prefix>` — filter refs by one or more prefixes
- `peel` — include `peeled:<oid>` attribute for annotated tags
- `symrefs` — include `symref-target:<ref>` attribute on the `HEAD` line

The `HEAD` line is emitted first when available and includes `symref-target` for compatibility. When `HEAD` is unborn, the line `unborn HEAD` is advertised.
```

--------------------------------

### Deploying a Specific Phase with Git Checkout

Source: https://github.com/rachel/git-on-cloudflare/blob/main/MIGRATION-STREAMING-PUSH.md

Checkout a specific commit and deploy using Wrangler. Ensure you have installed dependencies and are using the correct compatibility date.

```bash
git checkout 98ad7dd   # cutover
npm install && npx wrangler deploy
```

--------------------------------

### Deploying a Specific Phase of Git-on-Cloudflare

Source: https://github.com/rachel/git-on-cloudflare/blob/main/MIGRATION-TESSERA-OIDC.md

Use this command to deploy a specific phase of the git-on-cloudflare project by checking out a particular commit hash. Ensure you run `npm install` and `npm run db:migrate` before deploying.

```bash
git checkout b70097c   # phase 1, identity + D1 + backfill
npm install
npm run db:migrate
npx wrangler deploy
```

--------------------------------

### GET /:owner/:repo/admin

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

Admin dashboard displaying repository refs, HEAD status, compaction status, and pack statistics.

```APIDOC
## GET /:owner/:repo/admin

### Description
Admin dashboard displaying repository refs, HEAD status, compaction status, and pack statistics.

### Method
GET

### Endpoint
/:owner/:repo/admin

### Authentication
Requires a tessera-backed browser session and namespace membership.
```

--------------------------------

### GET /:owner/:repo/api/refs

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

Returns branch and tag references in JSON format, intended for UI dropdowns. Cached for 60 seconds.

```APIDOC
## GET /:owner/:repo/api/refs

### Description
Returns branch and tag references in JSON format, intended for UI dropdowns. Cached for 60 seconds.

### Method
GET

### Endpoint
/:owner/:repo/api/refs

### Caching
`Cache-Control: public, max-age=60`
```

--------------------------------

### Setting Up Authentication Credentials

Source: https://github.com/rachel/git-on-cloudflare/blob/main/MIGRATION-STREAMING-PUSH.md

Set environment variables for domain, owner, and authentication token for accessing admin endpoints. These are required for Basic authentication.

```bash
# Set these once per session:
export DOMAIN="your-domain.example.com"
export OWNER="your-owner"
export AUTH_TOKEN="your-owner-auth-token"
```

--------------------------------

### GET /:owner/:repo/commit/:oid

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

View the details of a single commit.

```APIDOC
## GET /:owner/:repo/commit/:oid

### Description
View the details of a single commit.

### Method
GET

### Endpoint
/:owner/:repo/commit/:oid

### Parameters
#### Path Parameters
- **oid** (string) - Required - The commit OID.
```

--------------------------------

### Create D1 Database and Migrate

Source: https://github.com/rachel/git-on-cloudflare/blob/main/MIGRATION-TESSERA-OIDC.md

Creates a D1 database for global ownership metadata and runs database migrations. Ensure the D1 binding is named 'DB'.

```bash
npx wrangler d1 create git-on-cloudflare
npm run db:migrate
```

--------------------------------

### GET /:owner/:repo/commits

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

Retrieve the commit history for a repository, with support for pagination.

```APIDOC
## GET /:owner/:repo/commits

### Description
Retrieve the commit history for a repository, with support for pagination.

### Method
GET

### Endpoint
/:owner/:repo/commits

### Parameters
#### Query Parameters
- **ref** (string) - Optional - The branch name.
- **per_page** (integer) - Optional - The number of commits per page (default 50).
- **page** (integer) - Optional - The page number (default 0).
```

--------------------------------

### Verification Commands

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/streaming-push-closure-plan.md

Run these commands to verify the project after migration. Includes type checking, formatting checks, unit tests, worker integration tests, and authentication tests.

```bash
npm run typecheck
npm run format:check
npm run test            # AVA unit tests
npm run test:workers    # Vitest worker integration tests
npm run test:auth       # Auth tests
```

--------------------------------

### Run Pack-Indexer Fixture Test (Opt-in)

Source: https://github.com/rachel/git-on-cloudflare/blob/main/CLAUDE.md

Intentionally runs the large pack-indexer fixture test. Requires setting an environment variable.

```bash
PACK_INDEXER_FIXTURE=1 npx vitest run --config vitest.config.ts test/pack-indexer-fixture.worker.test.ts
```

--------------------------------

### GET /auth/api/tokens

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

Lists metadata for personal access tokens (PATs) owned by the signed-in user.

```APIDOC
## GET /auth/api/tokens

### Description
Lists metadata for personal access tokens (PATs) owned by the signed-in user.

### Method
GET

### Endpoint
/auth/api/tokens
```

--------------------------------

### GET /:owner/:repo/raw

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

Retrieve the raw content of a file by its OID. Defaults to inline display.

```APIDOC
## GET /:owner/:repo/raw

### Description
Retrieve the raw content of a file by its OID. Defaults to inline display.

### Method
GET

### Endpoint
/:owner/:repo/raw

### Parameters
#### Query Parameters
- **oid** (string) - Required - The OID of the file.
- **name** (string) - Required - The name of the file.
- **download** (integer) - Optional - Set to 1 to force download.

### Response
Notes:
- Defaults to `Content-Disposition: inline` and `Content-Type: text/plain; charset=utf-8` for safety.
- Add `download=1` to force `attachment` and trigger a file download.
```

--------------------------------

### Configure Git Push with Custom Headers for Local Testing

Source: https://github.com/rachel/git-on-cloudflare/blob/main/README.md

When testing locally with Miniflare, configure Git to send custom HTTP headers for authentication to bypass potential 500 errors that mask 401s.

```bash
git -c http.extraHeader='Authorization: Basic <base64(rachel:goc_abcd1234_secret)>' \
  push http://127.0.0.1:5173/rachel/my-repo HEAD:refs/heads/main
```

--------------------------------

### Apply D1 Migrations to Production

Source: https://github.com/rachel/git-on-cloudflare/blob/main/MIGRATION-TESSERA-OIDC.md

Use this command to apply D1 database migrations to the production environment.

```bash
npm run db:migrate
```

--------------------------------

### Verifying New Repos Default to Streaming Mode

Source: https://github.com/rachel/git-on-cloudflare/blob/main/MIGRATION-STREAMING-PUSH.md

Create a test repository and use curl to check its storage mode via the admin endpoint. The expected output is 'streaming'.

```bash
curl -s -u "$OWNER:$AUTH_TOKEN" \
  "https://$DOMAIN/test-owner/test-repo/admin/storage-mode" | jq .currentMode
```

--------------------------------

### GET /auth/account

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

Displays the signed-in account page, including namespaces, repositories, and personal access tokens.

```APIDOC
## GET /auth/account

### Description
Displays the signed-in account page, including namespaces, repositories, and personal access tokens.

### Method
GET

### Endpoint
/auth/account
```

--------------------------------

### Preparing Backfill for Rollback Safety

Source: https://github.com/rachel/git-on-cloudflare/blob/main/MIGRATION-STREAMING-PUSH.md

Initiate a backfill process for a repository to ensure rollback safety before promotion. This is a preparatory step for migrating legacy repositories.

```bash
curl -s -X POST -u "$OWNER:$AUTH_TOKEN" \
  "https://$DOMAIN/$OWNER/$REPO/admin/storage-mode/backfill"
```

--------------------------------

### Listing Repositories Under an Owner

Source: https://github.com/rachel/git-on-cloudflare/blob/main/MIGRATION-STREAMING-PUSH.md

Use curl to list all repositories associated with a specific owner. This is useful for inventory and verification purposes.

```bash
# List repos under an owner:
curl -s -u "$OWNER:$AUTH_TOKEN" "https://$DOMAIN/$OWNER/admin/registry" | jq '.repos[]'
```

--------------------------------

### Promoting a Legacy Repository to Streaming Mode

Source: https://github.com/rachel/git-on-cloudflare/blob/main/MIGRATION-STREAMING-PUSH.md

Promote a legacy repository to streaming mode if it has active packs. This involves sending a PUT request to the admin endpoint with the desired mode.

```bash
curl -s -X PUT -u "$OWNER:$AUTH_TOKEN" \
  "https://$DOMAIN/$OWNER/$REPO/admin/storage-mode" \
  -H "Content-Type: application/json" \
  -d '{"mode": "streaming"}'
```

--------------------------------

### GET /:owner/:repo/commits/fragments/:oid

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

Fetch side branch commits for a merge, returned as an HTML fragment for dynamic insertion.

```APIDOC
## GET /:owner/:repo/commits/fragments/:oid

### Description
Fetch side branch commits for a merge, returned as an HTML fragment for dynamic insertion.

### Method
GET

### Endpoint
/:owner/:repo/commits/fragments/:oid

### Parameters
#### Path Parameters
- **oid** (string) - Required - The commit OID.
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of commits to return (default 20).
```

--------------------------------

### Verify Queue Binding Exists

Source: https://github.com/rachel/git-on-cloudflare/blob/main/MIGRATION-STREAMING-PUSH.md

Check if the necessary queue binding for compaction is configured. This command lists all available queues.

```bash
npx wrangler queues list
```

--------------------------------

### Preview or Enqueue Compaction

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

This endpoint can be used to preview compaction operations by setting `dryRun=true` (default) or to enqueue actual compaction work by setting `dryRun=false`.

```bash
POST /:owner/:repo/admin/compact
```

--------------------------------

### Deploy to Production

Source: https://github.com/rachel/git-on-cloudflare/blob/main/README.md

Steps to deploy the git-on-cloudflare project to Cloudflare Workers. This involves logging into Wrangler, setting secrets, and running the deploy command.

```bash
# Configure Cloudflare account
wrangler login

# Set session and tessera OIDC secrets
wrangler secret put SESSION_SECRET
wrangler secret put TESSERA_OIDC_CLIENT_SECRET

# Deploy to Workers
npm run deploy
```

--------------------------------

### GET /:owner/:repo/rawpath

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

Retrieve the raw content of a file by its path. Primarily for assets like Markdown images. Supports forcing download.

```APIDOC
## GET /:owner/:repo/rawpath

### Description
Retrieve the raw content of a file by its path. Primarily for assets like Markdown images. Supports forcing download.

### Method
GET

### Endpoint
/:owner/:repo/rawpath

### Parameters
#### Query Parameters
- **ref** (string) - Optional - The branch name.
- **path** (string) - Required - The path to the file.
- **name** (string) - Required - The name of the file.
- **download** (integer) - Optional - Set to 1 to force download.

### Response
Notes:
- Best-effort `Content-Type` is derived from the file extension for inline rendering.
- Requires a same-origin `Referer` header (hotlink protection). Requests from other origins will be rejected with 403.
```

--------------------------------

### Test Git with Basic Auth

Source: https://github.com/rachel/git-on-cloudflare/blob/main/MIGRATION-TESSERA-OIDC.md

Test Git operations using Basic Authentication with a provided PAT.

```bash
git -c http.extraHeader='Authorization: Basic <base64(namespace:goc_prefix_secret)>' \
  ls-remote https://<your-goc-host>/<namespace>/<repo>
```

--------------------------------

### Build UI Cache Key

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/caching.md

Constructs a cache key for same-origin GET requests for UI-related JSON responses. Used for caching data like repository refs, tree listings, blob metadata, README content, and commits.

```typescript
buildCacheKeyFrom(req: Request, pathname: string, params: Record<string, string>)
// Example: buildCacheKeyFrom(req, "/_cache/commits", { ref: "main" })
```

--------------------------------

### POST /auth/api/repositories

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

Creates a new repository within a namespace where the signed-in user is a member.

```APIDOC
## POST /auth/api/repositories

### Description
Creates a new repository within a namespace where the signed-in user is a member.

### Method
POST

### Endpoint
/auth/api/repositories
```

--------------------------------

### Clone a Repository

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/api-endpoints.md

Use this command to clone a remote repository to your local machine. Replace 'your-domain.com/owner/repo' with the actual repository URL.

```bash
git clone https://your-domain.com/owner/repo
```

--------------------------------

### Create Repository

Source: https://github.com/rachel/git-on-cloudflare/blob/main/docs/tessera-ownership-migration-plan.md

Endpoint for creating a new repository. Requires session authorization and specific body parameters. Handles validation and database insertion, with best-effort route caching.

```APIDOC
## POST /auth/api/repositories

### Description
Creates a new repository within a specified namespace. This operation requires session authorization and cannot be performed using PATs to prevent accidental creation of ghost repositories.

### Method
POST

### Endpoint
/auth/api/repositories

### Parameters
#### Request Body
- **namespaceSlug** (string) - Required - The slug of the namespace where the repository will be created.
- **slug** (string) - Required - The desired slug for the new repository.
- **visibility** ("public" | "private") - Required - The visibility setting for the repository.

### Request Example
```json
{
  "namespaceSlug": "example-namespace",
  "slug": "new-repo",
  "visibility": "private"
}
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success.
- **id** (string) - The unique identifier of the created repository.
- **namespaceSlug** (string) - The namespace slug.
- **slug** (string) - The repository slug.
- **visibility** ("public" | "private") - The visibility of the repository.

#### Error Response
- **ok** (boolean) - Indicates failure.
- **reason** ("invalid-slug" | "namespace-not-found" | "not-member" | "slug-taken") - The reason for the failure.

#### Response Example (Success)
```json
{
  "ok": true,
  "id": "repo:xxxxxxxxxxxx",
  "namespaceSlug": "example-namespace",
  "slug": "new-repo",
  "visibility": "private"
}
```

#### Response Example (Failure)
```json
{
  "ok": false,
  "reason": "slug-taken"
}
```
```

--------------------------------

### Build and Static Validation

Source: https://github.com/rachel/git-on-cloudflare/blob/main/CLAUDE.md

Builds the project and performs static validation checks including type checking and formatting.

```bash
npm run build
npm run typecheck
npm run format:check
```

--------------------------------

### Run Node.js Vitest Unit Tests

Source: https://github.com/rachel/git-on-cloudflare/blob/main/README.md

Execute the Node.js-based Vitest unit tests for the project.

```bash
npm run test
```

--------------------------------

### Checking a Specific Repository's Storage Mode

Source: https://github.com/rachel/git-on-cloudflare/blob/main/MIGRATION-STREAMING-PUSH.md

Retrieve detailed information about a repository's storage mode, active pack count, and promotion status. Use this to assess readiness for migration.

```bash
export REPO="your-repo"
curl -s -u "$OWNER:$AUTH_TOKEN" \
  "https://$DOMAIN/$OWNER/$REPO/admin/storage-mode" \
  | jq '{mode: .currentMode, packs: .activePackCount, canChange: .canChange, blockers: .blockers}'
```