oslstats/AGENTS.md

AGENTS.md - Developer Guide for oslstats

This document provides guidelines for AI coding agents and developers working on the oslstats codebase.

Project Overview

Module: git.haelnorr.com/h/oslstats
Language: Go 1.25.5
Architecture: Web application with Discord OAuth, PostgreSQL database, templ templates
Key Technologies: Bun ORM, templ, TailwindCSS, custom golib libraries

Build, Test, and Development Commands

Building

# Full production build (tailwind → templ → go generate → go build)
make build

# Build and run
make run

# Clean build artifacts
make clean

Development Mode

# Watch mode with hot reload (templ, air, tailwindcss in parallel)
make dev

# Development server runs on:
# - Proxy: http://localhost:3000 (use this)
# - App: http://localhost:3333 (internal)

Testing

# Run all tests
go test ./...

# Run tests for a specific package
go test ./pkg/oauth

# Run a single test function
go test ./pkg/oauth -run TestGenerateState_Success

# Run tests with verbose output
go test -v ./pkg/oauth

# Run tests with coverage
go test -cover ./...
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Database

# Run migrations
make migrate
# OR
./bin/oslstats --migrate

Configuration Management

# Generate .env template file
make genenv
# OR with custom output: make genenv OUT=.env.example

# Show environment variable documentation
make envdoc

# Show current environment values
make showenv

Code Style Guidelines

Import Organization

Organize imports in 3 groups separated by blank lines:

import (
    // 1. Standard library
    "context"
    "net/http"
    "fmt"
    
    // 2. External dependencies
    "git.haelnorr.com/h/golib/hws"
    "github.com/pkg/errors"
    "github.com/uptrace/bun"
    
    // 3. Internal packages
    "git.haelnorr.com/h/oslstats/internal/config"
    "git.haelnorr.com/h/oslstats/pkg/oauth"
)

Naming Conventions

Variables:

• Local: camelCase (userAgentKey, httpServer, dbConn)
• Exported: PascalCase (Config, User, Token)
• Common abbreviations: cfg, ctx, tx, db, err, w, r

Functions:

• Exported: PascalCase (GetConfig, NewStore, GenerateState)
• Private: camelCase (throwError, shouldShowDetails, loadModels)
• HTTP handlers: Return http.Handler, use dependency injection pattern
• Database functions: Use bun.Tx as parameter for transactions

Types:

• Structs/Interfaces: PascalCase (Config, User, OAuthSession)
• Use -er suffix for interfaces (implied from usage)

Files:

• Prefer single word: config.go, oauth.go, errors.go
• Don't use snake_case except for tests: state_test.go
• Test files: *_test.go alongside source files

Error Handling

Always wrap errors with context using github.com/pkg/errors:

if err != nil {
    return errors.Wrap(err, "operation_name")
}

Validate inputs at function start:

func DoSomething(cfg *Config, data string) error {
    if cfg == nil {
        return errors.New("cfg cannot be nil")
    }
    if data == "" {
        return errors.New("data cannot be empty")
    }
    // ... rest of function
}

HTTP error helpers (in handlers package): Note: msg should be a frontend presentable message

• throwInternalServiceError(s, w, r, msg, err) - 500 errors
• throwBadRequest(s, w, r, msg, err) - 400 errors
• throwForbidden(s, w, r, msg, err) - 403 errors (normal)
• throwForbiddenSecurity(s, w, r, msg, err) - 403 security violations (WARN level)
• throwUnauthorized(s, w, r, msg, err) - 401 errors (normal)
• throwUnauthorizedSecurity(s, w, r, msg, err) - 401 security violations (WARN level)
• throwNotFound(s, w, r, path) - 404 errors

Common Patterns

HTTP Handler Pattern:

func HandlerName(server *hws.Server, deps ...) http.Handler {
    return http.HandlerFunc(
        func(w http.ResponseWriter, r *http.Request) {
            // Handler logic here
        },
    )
}

Database Operation Pattern:

func GetSomething(ctx context.Context, tx bun.Tx, id int) (*Result, error) {
    result := new(Result)
    err := tx.NewSelect().
        Model(result).
        Where("id = ?", id).
        Scan(ctx)
    if err != nil {
        if err.Error() == "sql: no rows in result set" {
            return nil, nil  // Return nil, nil for not found
        }
        return nil, errors.Wrap(err, "tx.Select")
    }
    return result, nil
}

Setup Function Pattern (returns instance, cleanup func, error):

func setupSomething(ctx context.Context, cfg *Config) (*Type, func() error, error) {
    instance := newInstance()
    
    err := configure(instance)
    if err != nil {
        return nil, nil, errors.Wrap(err, "configure")
    }
    
    return instance, instance.Close, nil
}

Configuration Pattern (using ezconf):

type Config struct {
    Field string // ENV FIELD_NAME: Description (required/default: value)
}

func ConfigFromEnv() (any, error) {
    cfg := &Config{
        Field: env.String("FIELD_NAME", "default"),
    }
    // Validation here
    return cfg, nil
}

Formatting & Types

Formatting:

• Use gofmt (standard Go formatting)

Types:

• Prefer explicit types over inference when it improves clarity
• Use struct tags for ORM and JSON marshaling:

  type User struct {
      bun.BaseModel `bun:"table:users,alias:u"`
      ID           int    `bun:"id,pk,autoincrement"`
      Username     string `bun:"username,unique"`
      AccessToken  string `json:"access_token"`
  }
  

Comments:

• Document exported functions and types
• Use inline comments for ENV var documentation in Config structs
• Explain security-critical code flows

Testing

Test File Location: Place *_test.go files alongside source files

Test Naming:

func TestFunctionName_Scenario(t *testing.T)
func TestGenerateState_Success(t *testing.T)
func TestVerifyState_WrongUserAgentKey(t *testing.T)

Test Structure:

• Use subtests with t.Run() for related scenarios
• Use table-driven tests for multiple similar cases
• Create helper functions for common setup (e.g., testConfig())
• Test happy paths, error cases, edge cases, and security properties

Test Categories (from pkg/oauth/state_test.go example):

1. Happy path tests
2. Error handling (nil params, empty fields, malformed input)
3. Security tests (MITM, CSRF, replay attacks, tampering)
4. Edge cases (concurrency, constant-time comparison)
5. Integration tests (round-trip verification)

Security

Critical Practices:

• Use crypto/subtle.ConstantTimeCompare for cryptographic comparisons
• Implement CSRF protection via state tokens
• Store sensitive cookies as HttpOnly
• Use separate logging levels for security violations (WARN)
• Validate all inputs at function boundaries
• Use parameterized queries (Bun ORM handles this)
• Never commit secrets (.env, keys/ are gitignored)

Project Structure

oslstats/
├── cmd/oslstats/          # Application entry point
│   ├── main.go            # Entry point with flag parsing
│   ├── run.go             # Server initialization & graceful shutdown
│   ├── httpserver.go      # HTTP server setup
│   ├── routes.go          # Route registration
│   ├── middleware.go      # Middleware registration
│   ├── auth.go            # Authentication setup
│   └── db.go              # Database connection & migrations
├── internal/              # Private application code
│   ├── config/            # Configuration aggregation
│   ├── db/                # Database models & queries (Bun ORM)
│   ├── discord/           # Discord OAuth integration
│   ├── handlers/          # HTTP request handlers
│   ├── session/           # Session store (in-memory)
│   └── view/              # Templ templates
│       ├── component/     # Reusable UI components
│       ├── layout/        # Page layouts
│       └── page/          # Full pages
├── pkg/                   # Reusable packages
│   ├── contexts/          # Context key definitions
│   ├── embedfs/           # Embedded static files
│   └── oauth/             # OAuth state management
├── bin/                   # Compiled binaries (gitignored)
├── keys/                  # Private keys (gitignored)
├── tmp/                   # Air hot reload temp files (gitignored)
├── Makefile               # Build automation
├── .air.toml              # Hot reload configuration
└── go.mod                 # Go module definition

Key Dependencies

• git.haelnorr.com/h/golib/* - Custom libraries (env, ezconf, hlog, hws, hwsauth, cookies, jwt)
• github.com/a-h/templ - Type-safe HTML templating
• github.com/uptrace/bun - PostgreSQL ORM
• github.com/bwmarrin/discordgo - Discord API client
• github.com/pkg/errors - Error wrapping (use this, not fmt.Errorf)
• github.com/joho/godotenv - .env file loading

Notes for AI Agents

1. Never commit .env files, keys/, or generated files (*_templ.go, output.css)
2. Database operations should use bun.Tx for transaction safety
3. Templates are written in templ, not Go html/template - run templ generate after changes
4. Static files are embedded via //go:embed - check pkg/embedfs/
5. Error messages should be descriptive and use errors.Wrap for context
6. Security is critical - especially in OAuth flows (see pkg/oauth/state_test.go for examples)
7. Air proxy runs on port 3000 during development; app runs on 3333
8. Test coverage is currently limited - prioritize testing security-critical code
9. Configuration uses ezconf pattern - see internal/*/ezconf.go files for examples
10. Graceful shutdown is implemented in cmd/oslstats/run.go - follow this pattern
11. When in plan mode, always use the interactive question tool if available