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

# 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

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

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

Linting

# 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:

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:

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:

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:

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