golib/AGENTS.md

# AGENTS.md - Coding Agent Guidelines for golib

## Project Overview
This is a Go library repository containing multiple independent packages:
- **cookies**: HTTP cookie utilities
- **env**: Environment variable helpers
- **ezconf**: Configuration loader with ENV parsing
- **hlog**: Logging with zerolog
- **hws**: HTTP web server
- **hwsauth**: Authentication middleware for hws
- **jwt**: JWT token generation and validation
- **tmdb**: The Movie Database API client

Each package has its own `go.mod` and can be used independently.

## Interactive Questions
All questions in plan mode should use the opencode interactive question prompter for user interaction.

## Build, Test, and Lint Commands

### Running Tests
```bash
# Test all packages from repo root
go test ./...

# Test a specific package
cd <package> && go test

# Run a single test function
cd <package> && go test -run TestFunctionName

# Run tests with verbose output
cd <package> && go test -v

# Run tests matching a pattern
cd <package> && go test -run "TestName.*"
```

### Building
```bash
# Each package is a library - no build needed
# Verify code compiles:
go build ./...

# Or for specific package:
cd <package> && go build
```

### Linting
```bash
# Use standard go tools
go vet ./...
go fmt ./...

# Check formatting without changing files
gofmt -l .
```

## Code Style Guidelines

### Package Structure
- Each package must have its own `go.mod` with module path: `git.haelnorr.com/h/golib/<package>`
- Go version should be current (1.23.4+)
- Each package should have a `doc.go` file with package documentation

### Imports
- Use standard library imports first
- Then third-party imports
- Then local imports from this repo (e.g., `git.haelnorr.com/h/golib/hlog`)
- Group imports with blank lines between groups
- Example:
```go
import (
    "context"
    "net/http"
    
    "github.com/pkg/errors"
    "github.com/stretchr/testify/require"
    
    "git.haelnorr.com/h/golib/hlog"
)
```

### Formatting
- Use `gofmt` standard formatting
- No tabs for alignment, use spaces inside structs
- Line length: no hard limit, but prefer readability

### Types
- Use explicit types for struct fields
- Config structs must have ENV comments (see below)
- Prefer named return values for complex functions
- Use generics where appropriate (see `hwsauth.Authenticator[T Model, TX DBTransaction]`)

### Naming Conventions
- Packages: lowercase, single word (e.g., `cookies`, `ezconf`)
- Exported functions: PascalCase (e.g., `NewServer`, `ConfigFromEnv`)
- Unexported functions: camelCase (e.g., `isValidHostname`, `waitUntilReady`)
- Test functions: `Test<FunctionName>` or `Test<FunctionName>_<Case>` (underscore for sub-cases)
- Variables: camelCase, descriptive names
- Constants: PascalCase or UPPER_CASE depending on scope

### Error Handling
- Use `github.com/pkg/errors` for error wrapping
- Wrap errors with context: `errors.Wrap(err, "context message")`
- Return errors, don't panic (except in truly exceptional cases)
- Validate inputs and return descriptive errors
- Example:
```go
if config == nil {
    return nil, errors.New("Config cannot be nil")
}
```

### Configuration Pattern
- Each package with config should have a `Config` struct
- Provide `ConfigFromEnv() (*Config, error)` function
- ENV comment format for Config struct fields:
```go
type Config struct {
    Host string // ENV HWS_HOST: Host to listen on (default: 127.0.0.1)
    Port uint64 // ENV HWS_PORT: Port to listen on (default: 3000)
    SSL  bool   // ENV HWS_SSL: Enable SSL (required when using production)
}
```
- Format: `// ENV ENV_NAME: Description (required <condition>) (default: <value>)`
- Include "required" only if no default
- Include "default" only if one exists

### Testing
- Use `testing` package from standard library
- Use `github.com/stretchr/testify` for assertions (`require`, `assert`)
- Table-driven tests for multiple cases:
```go
tests := []struct {
    name    string
    input   string
    wantErr bool
}{
    {"valid case", "input", false},
    {"error case", "", true},
}
```
- Test files use `<package>_test` for black-box tests or `<package>` for white-box
- Helper functions should use `t.Helper()`

### Documentation
- All exported functions, types, and constants must have godoc comments
- Comments should start with the name being documented
- Example: `// NewServer returns a new hws.Server with the specified configuration.`
- Keep doc.go files up to date with package overview
- Follow RULES.md for README and wiki documentation

## Version Control (from RULES.md)
- Do NOT make changes to master branch
- Checkout a branch for new features
- Version numbers use git tags - do NOT change manually
- When updating docs, append branch name to version
- Changes to golib-wiki repo should use same branch name

## Testing Requirements (from RULES.md)
- All features MUST have tests
- Update existing tests when modifying features
- New features require new tests

## Documentation Requirements (from RULES.md)
- Document via: docstrings, README.md, doc.go, wiki
- README structure: Title+version, Features (NO EMOTICONS), Installation, Quick Start, Docs links, Additional info, License, Contributing, Related projects
- Wiki location: `~/projects/golib-wiki`
- Docstrings must conform to godoc standards

## License
- All modules use MIT License