# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is `go-git-server`, an experimental Git HTTP server in Go that provides authentication and authorization for Git repositories. It wraps the built-in `git-http-backend` CGI process to maintain compatibility while adding security features.

## Key Architecture

- **Main Entry Point**: `cmd/main.go` - HTTP server with middleware stack
- **Core Components**:
  - `internal/git/handler.go` - Git HTTP backend CGI wrapper
  - `internal/authz/` - Authentication/authorization middleware using Casbin
  - `internal/admin/` - Administrative services and configuration management
  - `internal/modules/` - Go module proxy endpoints and go-import metadata
- **Configuration**: Uses Casbin for RBAC with auth model (`auth_model.ini`) and policy files
- **Authentication**: Token-based system with bcrypt hashing stored in CSV format
- **Authorization**: Role-based access control with roles like admin, maintainers, bots

## Common Commands

### Development
```bash
# Run tests and linting
just test

# Build the application
just build <version>

# Run server locally with debug mode
just debug-run

# Run specific test with debugger
just debug-test <package> <function>

# Run server with sample data
just run [repo_path]
```

### Testing
```bash
# Run all tests with coverage
just test

# Coverage is automatically generated in temp directories
```

### Building and Deployment
```bash
# Create new version and build
just release <part>  # where part is: patch, minor, major, or latest

# Build Docker image
just docker-build

# Local Kubernetes deployment
just local-deploy

# Clean build artifacts
just clean
```

### Token Management
```bash
# Generate new authentication token
TMPDIR=$PWD/testdata go run cmd/tokentool/main.go -generate -name <username>

# List existing tokens
TMPDIR=$PWD/testdata go run cmd/tokentool/main.go -list

# Generate token directly from main binary
./main -g
```

## Development Notes

- **Go Version**: Requires Go 1.24+
- **Dependencies**: Uses Casbin for authorization, go-git for Git operations
- **Testing**: Uses standard Go testing with coverage reporting
- **Linting**: Uses golangci-lint
- **Build System**: Uses `just` (justfile) for task automation
- **Container**: Designed for Kubernetes deployment with minimal dependencies
- **TMPDIR**: **CRITICAL** - /tmp filesystem doesn't allow executables. Always use `TMPDIR=$PWD/testdata` for `go run` commands
- **Go Module Support**: Implements basic Go module proxy protocol for `go get` compatibility

## Large File Support

For pushing large binary files (>1MB), clients need to increase git's HTTP POST buffer:

```bash
# Global configuration (recommended)
git config --global http.postBuffer 524288000

# Per-repository configuration
git config http.postBuffer 524288000
```

This setting allows git to handle large file pushes over HTTP without timing out.

## Go Module Support

The server implements basic Go module proxy functionality to enable `go get` operations:

### Usage
```bash
# Enable go module proxy (make repositories discoverable)
go get yourdomain.com/repo

# The server automatically serves:
# - go-import meta tags for module discovery
# - Module proxy endpoints (@v/list, @latest, .info, .mod, .zip)
# - Version metadata from git tags
```

### Features
- **Module Discovery**: Serves go-import HTML meta tags
- **Version Listing**: Lists available versions from git tags
- **Pseudo-versions**: Generates pseudo-versions for untagged commits  
- **Module Archives**: Creates zip files from git repository content
- **go.mod Serving**: Extracts go.mod files from specific versions

### Limitations
- Basic implementation focused on compatibility, not full Athens-style features
- No caching, authentication bypass, or advanced proxy features
- Requires properly tagged semantic versions (v1.0.0, v1.2.3, etc.)

## Configuration Files

- `gitserver.yaml` - Server configuration and repository definitions
- `auth_model.ini` - Casbin authentication model
- `policy.csv` - Casbin authorization policies
- `tokens.csv` - Authentication tokens (format: access_id,friendly_name,hash)

## Code Conventions

From `CONVENTIONS.md`:
- Prefer idiomatic Go code
- Minimize dependencies
- Expert-level Git and Go programming expected
- Building a proxy server for `git-http-backend`

# Workflow

1. Write Tests
2. Lint Code
3. Commit
4. Write Code
5. Lint
6. Run tests
7. Fix Code
8. Lint
6. Iterate