Add package readme files

Author: adrianpk

app/readme.md

@@ -0,0 +1,49 @@
+# app
+
+Lifecycle management for application components.
+
+## Usage
+
+```go
+// Components implement optional interfaces
+type MyService struct{}
+
+func (s *MyService) Start(ctx context.Context) error { return nil }
+func (s *MyService) Stop(ctx context.Context) error { return nil }
+func (s *MyService) RegisterRoutes(r chi.Router) {
+    r.Get("/health", s.Health)
+}
+
+// Setup discovers capabilities automatically
+starts, stops, registrars := app.Setup(ctx, router,
+    dbPool,
+    &myService,
+    &anotherService,
+)
+
+// Start executes in order, auto-rollback on failure
+if err := app.Start(ctx, log, starts, stops, registrars, router); err != nil {
+    log.Fatal(err)
+}
+
+// Shutdown in reverse order (LIFO)
+app.Shutdown(srv, log, stops)
+```
+
+## API
+
+```go
+type Startable interface {
+    Start(context.Context) error
+}
+
+type Stoppable interface {
+    Stop(context.Context) error
+}
+
+type RouteRegistrar interface {
+    RegisterRoutes(chi.Router)
+}
+```
+
+Components implement the interfaces they need. Setup inspects and groups them.

auth/readme.md

@@ -0,0 +1,38 @@
+# auth
+
+Session-based authentication service.
+
+## Usage
+
+```go
+// Create service with your Queries implementation
+svc := auth.NewService(queries, cfg, log)
+
+// Signup
+user, err := svc.Signup(ctx, "user@example.com", "password123")
+
+// Signin (returns session with token)
+session, err := svc.Signin(ctx, "user@example.com", "password123")
+
+// Validate session (e.g., in middleware)
+user, err := svc.ValidateSession(ctx, sessionToken)
+
+// Signout
+svc.Signout(ctx, sessionToken)
+```
+
+## API
+
+```go
+type Queries interface {
+    CreateUser(ctx context.Context, id, email, passwordHash string, createdAt, updatedAt time.Time) (*User, error)
+    GetUserByEmail(ctx context.Context, email string) (*User, error)
+    GetUserByID(ctx context.Context, id string) (*User, error)
+    CreateSession(ctx context.Context, id, userID, token string, expiresAt, createdAt time.Time) (*Session, error)
+    GetSessionByToken(ctx context.Context, token string) (*Session, error)
+    DeleteSession(ctx context.Context, sessionID string) error
+    DeleteExpiredSessions(ctx context.Context) error
+}
+```
+
+Implement with sqlc or manually. See `middleware.go` for HTTP middleware and `context.go` for request context helpers.

config/readme.md

@@ -0,0 +1,30 @@
+# config
+
+Application configuration from YAML, env vars, and flags.
+
+## Usage
+
+```go
+cfg, err := config.Load("config.yaml", "MYAPP_", os.Args)
+if err != nil {
+    log.Fatal(err)
+}
+
+if err := cfg.Validate(); err != nil {
+    log.Fatal(err)
+}
+
+// Access config
+fmt.Println(cfg.Server.Port)
+fmt.Println(cfg.Database.ConnectionString())
+```
+
+Precedence (highest to lowest):
+1. Flags (`--database.host=x`)
+2. Env vars (`MYAPP_DATABASE_HOST=x`)
+3. YAML file
+4. Defaults
+
+## Notes
+
+Static configuration at startup. For dynamic runtime configuration, see `settings/`.

crypto/readme.md

@@ -0,0 +1,24 @@
+# crypto
+
+Cryptographic utilities: AES-256-GCM encryption, Argon2id hashing, HMAC, TOTP.
+
+## Usage
+
+```go
+// AES-256-GCM encryption (e.g., for PII)
+ciphertext, iv, tag, err := crypto.EncryptEmail(email, key)
+plaintext, err := crypto.DecryptEmail(ciphertext, iv, tag, key)
+
+// HMAC for deterministic lookups
+hash := crypto.ComputeLookupHash(email, signingKey)
+
+// Argon2id password hashing
+salt, _ := crypto.GenerateSalt()
+hash := crypto.HashPassword(password, salt)
+ok := crypto.VerifyPassword(password, hash, salt)
+
+// Secure random tokens
+token, _ := crypto.GenerateSecureToken(32)
+```
+
+For TOTP/MFA, see `totp.go`. For PASETO tokens, see `tokens.go`.

db/readme.md

@@ -0,0 +1,25 @@
+# db
+
+PostgreSQL connection with lifecycle management.
+
+## Usage
+
+```go
+//go:embed migrations/*.sql
+var migrations embed.FS
+
+database := db.New(migrations, "postgres", cfg, log)
+
+// Implements app.Startable/Stoppable
+if err := database.Start(ctx); err != nil {
+    log.Fatal(err)
+}
+defer database.Stop(ctx)
+
+// Use the connection
+sqlDB := database.GetDB()
+```
+
+Creates schema automatically if `cfg.Database.Schema` is set.
+
+For migrations, see `migrate.go`.

fake/readme.md

@@ -0,0 +1,24 @@
+# fake
+
+Test doubles for hatmax interfaces.
+
+## Usage
+
+```go
+// Fake mailer records all sent messages
+fm := fake.NewMailer()
+fm.WithOutput(os.Stdout)  // print emails to stdout
+fm.WithValidation()       // fail on invalid messages
+
+// Use in tests
+svc := NewService(fm)
+svc.SendWelcome(ctx, user)
+
+// Assert
+if fm.SendCount() != 1 { t.Error("expected 1 email") }
+if !fm.HasMessageTo("user@example.com") { t.Error("wrong recipient") }
+if !fm.HasMessageWithSubject("Welcome") { t.Error("wrong subject") }
+
+msg := fm.LastMessage()
+fm.Reset()  // clear for next test
+```

image/readme.md

@@ -0,0 +1,41 @@
+# image
+
+Image storage and processing with variants.
+
+## Usage
+
+```go
+// Create store (local or S3)
+store := local.NewStore("/var/uploads", "https://cdn.example.com")
+store := s3.NewStore(s3Client, bucket, "https://cdn.example.com")
+
+// Store image
+err := store.Put(ctx, "images/photo.jpg", reader)
+
+// Get image
+reader, err := store.Get(ctx, "images/photo.jpg")
+
+// Get URL
+url := store.URL("images/photo.jpg")
+
+// Process variants
+processor := stdprocessor.New()
+variants := []image.Variant{image.Large, image.Medium, image.Thumbnail}
+for _, v := range variants {
+    resized, _ := processor.Resize(original, v.Width, v.Height)
+    store.Put(ctx, v.Path(basePath), resized)
+}
+```
+
+## API
+
+```go
+type Store interface {
+    Put(ctx context.Context, path string, data io.Reader) error
+    Get(ctx context.Context, path string) (io.ReadCloser, error)
+    Delete(ctx context.Context, path string) error
+    URL(path string) string
+}
+```
+
+Implementations: `local/`, `s3/`. Processor: `stdprocessor/`.

log/readme.md

@@ -0,0 +1,37 @@
+# log
+
+Structured logging on top of slog.
+
+## Usage
+
+```go
+log := log.NewLogger(cfg)
+
+log.Info("server started")
+log.Infof("listening on %s", port)
+log.Error("connection failed")
+
+// With context
+reqLog := log.With("request_id", reqID, "user_id", userID)
+reqLog.Info("processing request")
+```
+
+Levels: `debug`, `info`, `error`. Configured via `cfg.Log.Level`.
+
+JSON output if `LOG_FORMAT=json`, human-readable text by default.
+
+## API
+
+```go
+type Logger interface {
+    Debug(v ...any)
+    Debugf(format string, a ...any)
+    Info(v ...any)
+    Infof(format string, a ...any)
+    Error(v ...any)
+    Errorf(format string, a ...any)
+    With(args ...any) Logger
+}
+```
+
+For tests: `log.NewNoopLogger()` or `log.NewTestLogger("debug")`.

mailer/readme.md

@@ -0,0 +1,32 @@
+# mailer
+
+Email delivery with multiple providers.
+
+## Usage
+
+```go
+// Create mailer (SMTP, SendGrid, SES, or Noop)
+mailer := mailer.NewSMTP(smtpConfig)
+mailer := mailer.NewSendGrid(apiKey, from)
+mailer := mailer.NewSES(awsConfig, from)
+mailer := mailer.NewNoop()  // for tests
+
+// Send email
+msg := &mailer.Message{
+    From:    mailer.Address{Email: "noreply@example.com", Name: "My App"},
+    To:      []mailer.Address{{Email: "user@example.com"}},
+    Subject: "Welcome",
+    HTML:    "<h1>Hello</h1>",
+    Text:    "Hello",
+}
+
+if err := mailer.Send(ctx, msg); err != nil { ... }
+```
+
+## API
+
+```go
+type Mailer interface {
+    Send(ctx context.Context, msg *Message) error
+}
+```

middleware/readme.md

@@ -0,0 +1,25 @@
+# middleware
+
+HTTP middleware for chi router.
+
+## Usage
+
+```go
+// Apply default stack (RequestID, RealIP, Logger, Recoverer)
+r := chi.NewRouter()
+for _, mw := range middleware.DefaultStack() {
+    r.Use(mw)
+}
+
+// Internal services only (adds IP restriction)
+for _, mw := range middleware.DefaultInternal() {
+    r.Use(mw)
+}
+
+// Individual middleware
+r.Use(middleware.RequestID)
+r.Use(middleware.RequireRole(model.RoleAdmin))
+r.Use(middleware.RateLimit(100, time.Minute))
+```
+
+See: `requestid.go`, `roles.go`, `ratelimit.go`, `stack.go`.