Mail access: IMAP + app password (IPv4 only), not Gmail API

internal/config/config.go

@@ -0,0 +1,160 @@
+// Package config loads the Email Agent runtime configuration from the
+// environment.
+//
+// Values are read from process environment variables. In production those
+// variables are provided by the host (for example by
+// ~/.config/environment.d/10-secrets.conf) and passed into the container by
+// docker-compose. Secret values are never written to disk by this package and
+// must never be committed to the repository.
+package config
+
+import (
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+)
+
+// Defaults for the service. Port 8790 is recorded in AGENTS.md §9.
+const (
+	DefaultPort = 8790
+	DefaultEnv  = "development"
+	DefaultAddr = ":" + "8790"
+	DefaultDB   = "data/email_agent.db"
+)
+
+// Config is the fully resolved runtime configuration.
+type Config struct {
+	// Env is the deployment environment: "development" or "production".
+	Env string
+
+	// Addr is the TCP address the HTTP server listens on, e.g. ":8790".
+	Addr string
+
+	// Port is the TCP port the HTTP server listens on.
+	Port int
+
+	// DBPath is the filesystem path to the SQLite database file.
+	DBPath string
+
+	// SessionSecret signs session cookies for the login screen (FR auth).
+	// Login itself is implemented in Phase 1.2; the value is loaded here so the
+	// service has a single configuration surface.
+	SessionSecret string
+
+	// LogLevel controls slog verbosity: debug, info, warn, error.
+	LogLevel string
+
+	// PublicBaseURL is the externally visible base URL of the service.
+	PublicBaseURL string
+
+	// Integration settings. These are loaded for later phases so that secret
+	// names are defined in one place. Phase 1 does not use them.
+
+	// JEVBaseURL is the base URL of the JEV/TypeSafe HTTP API.
+	JEVBaseURL string
+	// JEVAPIKey authenticates to JEV. Secret.
+	JEVAPIKey string
+
+	// OmniRouteBaseURL is the base URL of the OmniRoute gateway.
+	OmniRouteBaseURL string
+	// OmniRouteAPIKey authenticates to OmniRoute. Secret.
+	OmniRouteAPIKey string
+
+	// GmailCredentialsFile is the OAuth client credentials JSON path.
+	GmailCredentialsFile string
+	// GmailTokenFile is the path where the OAuth token is cached.
+	GmailTokenFile string
+
+	// HubToken authenticates the read-only Hub API. Secret.
+	HubToken string
+}
+
+// Load reads configuration from the environment, applying defaults.
+func Load() (*Config, error) {
+	c := &Config{
+		Env:                  getenvDefault("EMAIL_AGENT_ENV", DefaultEnv),
+		SessionSecret:        os.Getenv("EMAIL_AGENT_SESSION_SECRET"),
+		LogLevel:             strings.ToLower(getenvDefault("EMAIL_AGENT_LOG_LEVEL", "info")),
+		PublicBaseURL:        strings.TrimRight(getenvDefault("EMAIL_AGENT_PUBLIC_BASE_URL", "http://localhost:8790"), "/"),
+		JEVBaseURL:           strings.TrimRight(os.Getenv("JEV_BASE_URL"), "/"),
+		JEVAPIKey:            os.Getenv("JEV_API_KEY"),
+		OmniRouteBaseURL:     strings.TrimRight(os.Getenv("OMNIROUTE_BASE_URL"), "/"),
+		OmniRouteAPIKey:      os.Getenv("OMNIROUTE_API_KEY"),
+		GmailCredentialsFile: os.Getenv("EMAIL_AGENT_GMAIL_CREDENTIALS_FILE"),
+		GmailTokenFile:       os.Getenv("EMAIL_AGENT_GMAIL_TOKEN_FILE"),
+		HubToken:             os.Getenv("HUB_TOKEN"),
+	}
+
+	port, err := resolvePort()
+	if err != nil {
+		return nil, err
+	}
+	c.Port = port
+	c.Addr = resolveAddr(port)
+	c.DBPath = getenvDefault("EMAIL_AGENT_DB_PATH", DefaultDB)
+
+	if err := c.validate(); err != nil {
+		return nil, err
+	}
+	return c, nil
+}
+
+// resolvePort determines the listening port from EMAIL_AGENT_PORT or the port
+// component of EMAIL_AGENT_ADDR, falling back to DefaultPort.
+func resolvePort() (int, error) {
+	if raw := strings.TrimSpace(os.Getenv("EMAIL_AGENT_PORT")); raw != "" {
+		p, err := strconv.Atoi(raw)
+		if err != nil {
+			return 0, fmt.Errorf("EMAIL_AGENT_PORT %q is not a number: %w", raw, err)
+		}
+		return p, nil
+	}
+	if addr := strings.TrimSpace(os.Getenv("EMAIL_AGENT_ADDR")); addr != "" {
+		if i := strings.LastIndex(addr, ":"); i >= 0 && i < len(addr)-1 {
+			if p, err := strconv.Atoi(addr[i+1:]); err == nil {
+				return p, nil
+			}
+		}
+	}
+	return DefaultPort, nil
+}
+
+// resolveAddr prefers an explicit EMAIL_AGENT_ADDR, otherwise builds one from
+// the resolved port.
+func resolveAddr(port int) string {
+	if addr := strings.TrimSpace(os.Getenv("EMAIL_AGENT_ADDR")); addr != "" {
+		return addr
+	}
+	return fmt.Sprintf(":%d", port)
+}
+
+func (c *Config) validate() error {
+	if c.Port < 1 || c.Port > 65535 {
+		return fmt.Errorf("port %d is out of range", c.Port)
+	}
+	if strings.TrimSpace(c.DBPath) == "" {
+		return fmt.Errorf("EMAIL_AGENT_DB_PATH must not be empty")
+	}
+	switch c.Env {
+	case "development", "production", "test":
+	default:
+		return fmt.Errorf("EMAIL_AGENT_ENV %q must be development, production, or test", c.Env)
+	}
+	switch c.LogLevel {
+	case "debug", "info", "warn", "error":
+	default:
+		return fmt.Errorf("EMAIL_AGENT_LOG_LEVEL %q must be debug, info, warn, or error", c.LogLevel)
+	}
+	return nil
+}
+
+// IsProduction reports whether the service runs in the production environment.
+func (c *Config) IsProduction() bool { return c.Env == "production" }
+
+func getenvDefault(key, def string) string {
+	if v := strings.TrimSpace(os.Getenv(key)); v != "" {
+		return v
+	}
+	return def
+}

internal/config/config_test.go

@@ -0,0 +1,72 @@
+package config
+
+import "testing"
+
+func TestLoadDefaults(t *testing.T) {
+	// Ensure no ambient values leak into the test.
+	for _, k := range []string{
+		"EMAIL_AGENT_ENV", "EMAIL_AGENT_ADDR", "EMAIL_AGENT_PORT",
+		"EMAIL_AGENT_DB_PATH", "EMAIL_AGENT_LOG_LEVEL", "EMAIL_AGENT_PUBLIC_BASE_URL",
+	} {
+		t.Setenv(k, "")
+	}
+
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("Load() error = %v", err)
+	}
+	if cfg.Port != DefaultPort {
+		t.Errorf("Port = %d, want %d", cfg.Port, DefaultPort)
+	}
+	if cfg.Addr != DefaultAddr {
+		t.Errorf("Addr = %q, want %q", cfg.Addr, DefaultAddr)
+	}
+	if cfg.Env != DefaultEnv {
+		t.Errorf("Env = %q, want %q", cfg.Env, DefaultEnv)
+	}
+	if cfg.DBPath != DefaultDB {
+		t.Errorf("DBPath = %q, want %q", cfg.DBPath, DefaultDB)
+	}
+}
+
+func TestLoadOverrides(t *testing.T) {
+	t.Setenv("EMAIL_AGENT_ENV", "production")
+	t.Setenv("EMAIL_AGENT_PORT", "9000")
+	t.Setenv("EMAIL_AGENT_DB_PATH", "/tmp/custom.db")
+	t.Setenv("EMAIL_AGENT_LOG_LEVEL", "debug")
+	t.Setenv("EMAIL_AGENT_PUBLIC_BASE_URL", "https://example.test/")
+	t.Setenv("EMAIL_AGENT_ADDR", "")
+
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("Load() error = %v", err)
+	}
+	if cfg.Port != 9000 {
+		t.Errorf("Port = %d, want 9000", cfg.Port)
+	}
+	if cfg.Addr != ":9000" {
+		t.Errorf("Addr = %q, want %q", cfg.Addr, ":9000")
+	}
+	if !cfg.IsProduction() {
+		t.Errorf("IsProduction() = false, want true")
+	}
+	if cfg.PublicBaseURL != "https://example.test" {
+		t.Errorf("PublicBaseURL = %q, want trimmed URL", cfg.PublicBaseURL)
+	}
+}
+
+func TestLoadInvalidPort(t *testing.T) {
+	t.Setenv("EMAIL_AGENT_PORT", "not-a-number")
+	t.Setenv("EMAIL_AGENT_ADDR", "")
+	if _, err := Load(); err == nil {
+		t.Fatal("Load() error = nil, want error for invalid port")
+	}
+}
+
+func TestLoadInvalidEnv(t *testing.T) {
+	t.Setenv("EMAIL_AGENT_ENV", "staging")
+	t.Setenv("EMAIL_AGENT_ADDR", "")
+	if _, err := Load(); err == nil {
+		t.Fatal("Load() error = nil, want error for invalid env")
+	}
+}

internal/server/server.go

@@ -0,0 +1,228 @@
+// Package server wires the HTTP surface of the Email Agent.
+//
+// Phase 1 exposes liveness/readiness endpoints and a placeholder dashboard.
+// Login and the real HTMX screens arrive in Phase 1.2.
+package server
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"html/template"
+	"log/slog"
+	"net/http"
+	"time"
+
+	"gitea.lab.audasmedia.com.au/sam/email_agent/internal/config"
+	"gitea.lab.audasmedia.com.au/sam/email_agent/internal/store"
+	"gitea.lab.audasmedia.com.au/sam/email_agent/internal/version"
+)
+
+// Server holds the HTTP dependencies.
+type Server struct {
+	cfg    *config.Config
+	store  *store.Store
+	logger *slog.Logger
+	http   *http.Server
+	index  *template.Template
+}
+
+// New builds a Server. It does not start listening.
+func New(cfg *config.Config, st *store.Store, logger *slog.Logger) (*Server, error) {
+	index, err := template.New("index").Parse(indexHTML)
+	if err != nil {
+		return nil, fmt.Errorf("parse index template: %w", err)
+	}
+
+	s := &Server{
+		cfg:    cfg,
+		store:  st,
+		logger: logger,
+		index:  index,
+	}
+	s.http = &http.Server{
+		Addr:              cfg.Addr,
+		Handler:           s.Handler(),
+		ReadHeaderTimeout: 10 * time.Second,
+		ReadTimeout:       30 * time.Second,
+		WriteTimeout:      30 * time.Second,
+		IdleTimeout:       60 * time.Second,
+	}
+	return s, nil
+}
+
+// Handler returns the root HTTP handler with middleware applied.
+func (s *Server) Handler() http.Handler {
+	mux := http.NewServeMux()
+	mux.HandleFunc("GET /health", s.handleHealth)
+	mux.HandleFunc("GET /readyz", s.handleReady)
+	mux.HandleFunc("GET /{$}", s.handleIndex)
+	return s.recoverPanic(s.logRequests(mux))
+}
+
+// Run starts the HTTP server and blocks until ctx is cancelled.
+func (s *Server) Run(ctx context.Context) error {
+	errCh := make(chan error, 1)
+	go func() {
+		s.logger.Info("http server listening",
+			"addr", s.cfg.Addr,
+			"env", s.cfg.Env,
+			"db", s.store.Path(),
+			"version", version.Version,
+		)
+		if err := s.http.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			errCh <- err
+			return
+		}
+		errCh <- nil
+	}()
+
+	select {
+	case err := <-errCh:
+		return err
+	case <-ctx.Done():
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+		defer cancel()
+		s.logger.Info("shutting down http server")
+		return s.http.Shutdown(shutdownCtx)
+	}
+}
+
+type healthResponse struct {
+	Status        string `json:"status"`
+	Version       string `json:"version"`
+	Commit        string `json:"commit"`
+	Env           string `json:"env"`
+	UptimeSeconds int64  `json:"uptime_seconds"`
+	Database      string `json:"database"`
+	Time          string `json:"time"`
+}
+
+var startedAt = time.Now()
+
+// handleHealth reports liveness plus a database connectivity check.
+func (s *Server) handleHealth(w http.ResponseWriter, r *http.Request) {
+	ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
+	defer cancel()
+
+	resp := healthResponse{
+		Status:        "ok",
+		Version:       version.Version,
+		Commit:        version.Commit,
+		Env:           s.cfg.Env,
+		UptimeSeconds: int64(time.Since(startedAt).Seconds()),
+		Database:      "ok",
+		Time:          time.Now().UTC().Format(time.RFC3339),
+	}
+	code := http.StatusOK
+
+	if err := s.store.Ping(ctx); err != nil {
+		s.logger.Error("health check: database unreachable", "error", err)
+		resp.Status = "degraded"
+		resp.Database = "unreachable"
+		code = http.StatusServiceUnavailable
+	}
+
+	writeJSON(w, code, resp)
+}
+
+// handleReady reports readiness for load balancers (same signal as health).
+func (s *Server) handleReady(w http.ResponseWriter, r *http.Request) {
+	ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
+	defer cancel()
+	if err := s.store.Ping(ctx); err != nil {
+		writeJSON(w, http.StatusServiceUnavailable, map[string]string{"status": "not ready"})
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]string{"status": "ready"})
+}
+
+// handleIndex renders a placeholder dashboard. The real login + inbox screens
+// are Phase 1.2.
+func (s *Server) handleIndex(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	data := struct {
+		Version string
+		Env     string
+	}{Version: version.Version, Env: s.cfg.Env}
+	if err := s.index.Execute(w, data); err != nil {
+		s.logger.Error("render index", "error", err)
+	}
+}
+
+func writeJSON(w http.ResponseWriter, code int, v any) {
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	w.WriteHeader(code)
+	_ = json.NewEncoder(w).Encode(v)
+}
+
+// logRequests logs one line per request at debug level.
+func (s *Server) logRequests(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		start := time.Now()
+		rec := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
+		next.ServeHTTP(rec, r)
+		s.logger.Debug("request",
+			"method", r.Method,
+			"path", r.URL.Path,
+			"status", rec.status,
+			"duration_ms", time.Since(start).Milliseconds(),
+			"remote", r.RemoteAddr,
+		)
+	})
+}
+
+// recoverPanic keeps one bad request from taking down the process.
+func (s *Server) recoverPanic(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		defer func() {
+			if rec := recover(); rec != nil {
+				s.logger.Error("panic recovered", "error", rec, "path", r.URL.Path)
+				http.Error(w, "internal server error", http.StatusInternalServerError)
+			}
+		}()
+		next.ServeHTTP(w, r)
+	})
+}
+
+type statusRecorder struct {
+	http.ResponseWriter
+	status int
+}
+
+func (r *statusRecorder) WriteHeader(code int) {
+	r.status = code
+	r.ResponseWriter.WriteHeader(code)
+}
+
+const indexHTML = `<!doctype html>
+<html lang="en" data-theme="light">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Email Agent</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font-family: Inter, -apple-system, system-ui, "Segoe UI", Helvetica, Arial, sans-serif;
+         background: #f6f5f4; color: #31302e; margin: 0; }
+  @media (prefers-color-scheme: dark) { body { background: #141518; color: #dcdee2; } }
+  main { max-width: 640px; margin: 12vh auto; padding: 0 24px; }
+  .band { background: #213183; color: #fff; border-radius: 12px; padding: 24px; }
+  h1 { font-size: 32px; line-height: 1.1; margin: 0 0 8px; }
+  p { font-size: 15px; line-height: 1.5; }
+  code { background: rgba(127,127,127,.15); padding: 2px 6px; border-radius: 4px; }
+</style>
+</head>
+<body>
+<main>
+  <div class="band">
+    <h1>Email Agent</h1>
+    <p>Phase 1 skeleton is running. Version <code>{{.Version}}</code> ({{.Env}}).</p>
+  </div>
+  <p>Login and the inbox arrive in Phase 1.2. Liveness is at
+     <a href="/health">/health</a>.</p>
+</main>
+</body>
+</html>
+`

internal/server/server_test.go

@@ -0,0 +1,81 @@
+package server
+
+import (
+	"context"
+	"encoding/json"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"gitea.lab.audasmedia.com.au/sam/email_agent/internal/config"
+	"gitea.lab.audasmedia.com.au/sam/email_agent/internal/store"
+)
+
+func newTestServer(t *testing.T) *Server {
+	t.Helper()
+	cfg := &config.Config{
+		Env:      "test",
+		Addr:     ":0",
+		DBPath:   filepath.Join(t.TempDir(), "email_agent.db"),
+		LogLevel: "error",
+	}
+	st, err := store.Open(context.Background(), cfg.DBPath)
+	if err != nil {
+		t.Fatalf("store.Open() error = %v", err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+
+	srv, err := New(cfg, st, slog.New(slog.DiscardHandler))
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+	return srv
+}
+
+func TestHealthOK(t *testing.T) {
+	srv := newTestServer(t)
+	req := httptest.NewRequest(http.MethodGet, "/health", nil)
+	rec := httptest.NewRecorder()
+
+	srv.Handler().ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+	var body map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("decode body: %v", err)
+	}
+	if body["status"] != "ok" {
+		t.Errorf("status field = %v, want ok", body["status"])
+	}
+}
+
+func TestReadyz(t *testing.T) {
+	srv := newTestServer(t)
+	req := httptest.NewRequest(http.MethodGet, "/readyz", nil)
+	rec := httptest.NewRecorder()
+
+	srv.Handler().ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+}
+
+func TestIndexRendersHTML(t *testing.T) {
+	srv := newTestServer(t)
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	rec := httptest.NewRecorder()
+
+	srv.Handler().ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+	if ct := rec.Header().Get("Content-Type"); ct == "" {
+		t.Error("Content-Type header is empty")
+	}
+}

internal/store/schema.sql

@@ -0,0 +1,101 @@
+-- Email Agent schema (AGENTS.md §7).
+--
+-- Every statement is idempotent (CREATE ... IF NOT EXISTS) so this file can be
+-- executed on every start. Retention/capping jobs belong to later phases.
+--
+-- Attribution: created for the Email Agent Phase 1 skeleton.
+
+PRAGMA foreign_keys = ON;
+
+-- Records the applied schema version for future migrations.
+CREATE TABLE IF NOT EXISTS schema_migrations (
+    version     INTEGER PRIMARY KEY,
+    applied_at  TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+-- FR-1, FR-2: mail metadata and body, plus the forwarding address it arrived at.
+CREATE TABLE IF NOT EXISTS messages (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    gmail_id        TEXT    NOT NULL UNIQUE,
+    thread_id       TEXT,
+    from_addr       TEXT,
+    to_addr         TEXT,
+    subject         TEXT,
+    body_text       TEXT,
+    source_address  TEXT,
+    date_sent       TEXT,
+    received_at     TEXT    NOT NULL DEFAULT (datetime('now')),
+    created_at      TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_messages_received_at ON messages (received_at);
+CREATE INDEX IF NOT EXISTS idx_messages_thread_id   ON messages (thread_id);
+CREATE INDEX IF NOT EXISTS idx_messages_source      ON messages (source_address);
+
+-- FR-3, FR-14: classifier output per message.
+CREATE TABLE IF NOT EXISTS classifications (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    message_id   INTEGER NOT NULL REFERENCES messages (id) ON DELETE CASCADE,
+    category     TEXT    NOT NULL,
+    importance   TEXT,
+    action       TEXT,
+    confidence   REAL,
+    model        TEXT,
+    created_at   TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_classifications_message ON classifications (message_id);
+
+-- FR-4, FR-11: versioned rules text.
+CREATE TABLE IF NOT EXISTS rules (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    text        TEXT    NOT NULL,
+    version     INTEGER NOT NULL,
+    created_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+-- FR-13: append-only action log.
+CREATE TABLE IF NOT EXISTS actions_log (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    message_id  INTEGER REFERENCES messages (id) ON DELETE SET NULL,
+    action      TEXT    NOT NULL,
+    actor       TEXT,
+    rule_id     INTEGER REFERENCES rules (id) ON DELETE SET NULL,
+    detail      TEXT,
+    created_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_actions_log_message ON actions_log (message_id);
+CREATE INDEX IF NOT EXISTS idx_actions_log_created ON actions_log (created_at);
+
+-- FR-7: unsubscribe tracker and ignore list.
+CREATE TABLE IF NOT EXISTS unsubscribe (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    domain      TEXT    NOT NULL UNIQUE,
+    status      TEXT    NOT NULL DEFAULT 'done' CHECK (status IN ('done', 'ignored')),
+    created_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+-- FR-8: reply drafts.
+CREATE TABLE IF NOT EXISTS drafts (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    message_id   INTEGER NOT NULL REFERENCES messages (id) ON DELETE CASCADE,
+    body         TEXT    NOT NULL,
+    template_id  TEXT,
+    status       TEXT    NOT NULL DEFAULT 'draft',
+    created_at   TEXT    NOT NULL DEFAULT (datetime('now')),
+    updated_at   TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_drafts_message ON drafts (message_id);
+
+-- FR-10: daily summary and its delivery target.
+CREATE TABLE IF NOT EXISTS summaries (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    date          TEXT    NOT NULL UNIQUE,
+    text          TEXT    NOT NULL,
+    delivered_to  TEXT,
+    created_at    TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+INSERT OR IGNORE INTO schema_migrations (version) VALUES (1);

internal/store/store.go

@@ -0,0 +1,117 @@
+// Package store owns the SQLite database: opening it, applying the schema, and
+// exposing a small query surface to the rest of the service.
+package store
+
+import (
+	"context"
+	"database/sql"
+	_ "embed"
+	"fmt"
+	"net/url"
+	"os"
+	"path/filepath"
+	"time"
+
+	// Pure-Go SQLite driver. Keeps the container CGO-free.
+	_ "modernc.org/sqlite"
+)
+
+//go:embed schema.sql
+var schemaSQL string
+
+// Store wraps the SQLite connection pool.
+type Store struct {
+	db   *sql.DB
+	path string
+}
+
+// Open creates (if needed) and connects to the SQLite database at path, then
+// applies the schema. The parent directory is created when missing.
+func Open(ctx context.Context, path string) (*Store, error) {
+	if dir := filepath.Dir(path); dir != "" && dir != "." {
+		if err := os.MkdirAll(dir, 0o750); err != nil {
+			return nil, fmt.Errorf("create database directory %q: %w", dir, err)
+		}
+	}
+
+	dsn := buildDSN(path)
+	db, err := sql.Open("sqlite", dsn)
+	if err != nil {
+		return nil, fmt.Errorf("open sqlite database: %w", err)
+	}
+
+	// SQLite handles one writer at a time; keep the pool small and give the
+	// busy handler room. Reads and writes share the connection here.
+	db.SetMaxOpenConns(1)
+	db.SetMaxIdleConns(1)
+	db.SetConnMaxLifetime(0)
+
+	pingCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	if err := db.PingContext(pingCtx); err != nil {
+		_ = db.Close()
+		return nil, fmt.Errorf("ping sqlite database: %w", err)
+	}
+
+	s := &Store{db: db, path: path}
+	if err := s.migrate(ctx); err != nil {
+		_ = db.Close()
+		return nil, err
+	}
+	return s, nil
+}
+
+// buildDSN returns a modernc.org/sqlite DSN with safe pragmas applied on every
+// new connection.
+func buildDSN(path string) string {
+	abs, err := filepath.Abs(path)
+	if err != nil {
+		abs = path
+	}
+	q := url.Values{}
+	q.Add("_pragma", "busy_timeout(5000)")
+	q.Add("_pragma", "journal_mode(WAL)")
+	q.Add("_pragma", "foreign_keys(1)")
+	q.Add("_pragma", "synchronous(NORMAL)")
+	return "file:" + abs + "?" + q.Encode()
+}
+
+// migrate applies the embedded schema. It is safe to run on every start.
+func (s *Store) migrate(ctx context.Context) error {
+	if _, err := s.db.ExecContext(ctx, schemaSQL); err != nil {
+		return fmt.Errorf("apply schema: %w", err)
+	}
+	return nil
+}
+
+// DB exposes the underlying pool for callers that need it.
+func (s *Store) DB() *sql.DB { return s.db }
+
+// Path returns the database file path.
+func (s *Store) Path() string { return s.path }
+
+// Ping verifies the database is reachable.
+func (s *Store) Ping(ctx context.Context) error {
+	return s.db.PingContext(ctx)
+}
+
+// Close releases the connection pool.
+func (s *Store) Close() error {
+	if s == nil || s.db == nil {
+		return nil
+	}
+	return s.db.Close()
+}
+
+// SchemaVersion returns the highest applied migration version.
+func (s *Store) SchemaVersion(ctx context.Context) (int, error) {
+	var v sql.NullInt64
+	err := s.db.QueryRowContext(ctx, `SELECT MAX(version) FROM schema_migrations`).Scan(&v)
+	if err != nil {
+		return 0, err
+	}
+	if !v.Valid {
+		return 0, nil
+	}
+	return int(v.Int64), nil
+}

internal/store/store_test.go

@@ -0,0 +1,85 @@
+package store
+
+import (
+	"context"
+	"path/filepath"
+	"testing"
+)
+
+func TestOpenCreatesSchema(t *testing.T) {
+	ctx := context.Background()
+	path := filepath.Join(t.TempDir(), "nested", "email_agent.db")
+
+	s, err := Open(ctx, path)
+	if err != nil {
+		t.Fatalf("Open() error = %v", err)
+	}
+	defer s.Close()
+
+	v, err := s.SchemaVersion(ctx)
+	if err != nil {
+		t.Fatalf("SchemaVersion() error = %v", err)
+	}
+	if v < 1 {
+		t.Fatalf("SchemaVersion() = %d, want >= 1", v)
+	}
+
+	wantTables := []string{
+		"messages", "classifications", "rules", "actions_log",
+		"unsubscribe", "drafts", "summaries",
+	}
+	for _, table := range wantTables {
+		var name string
+		err := s.DB().QueryRowContext(ctx,
+			`SELECT name FROM sqlite_master WHERE type='table' AND name=?`, table).Scan(&name)
+		if err != nil {
+			t.Errorf("table %q missing: %v", table, err)
+		}
+	}
+}
+
+func TestOpenIsIdempotent(t *testing.T) {
+	ctx := context.Background()
+	path := filepath.Join(t.TempDir(), "email_agent.db")
+
+	s1, err := Open(ctx, path)
+	if err != nil {
+		t.Fatalf("first Open() error = %v", err)
+	}
+	_ = s1.Close()
+
+	s2, err := Open(ctx, path)
+	if err != nil {
+		t.Fatalf("second Open() error = %v", err)
+	}
+	defer s2.Close()
+
+	if err := s2.Ping(ctx); err != nil {
+		t.Fatalf("Ping() error = %v", err)
+	}
+}
+
+func TestMessagesInsertAndRead(t *testing.T) {
+	ctx := context.Background()
+	s, err := Open(ctx, filepath.Join(t.TempDir(), "email_agent.db"))
+	if err != nil {
+		t.Fatalf("Open() error = %v", err)
+	}
+	defer s.Close()
+
+	_, err = s.DB().ExecContext(ctx,
+		`INSERT INTO messages (gmail_id, subject, source_address) VALUES (?, ?, ?)`,
+		"abc123", "Hello", "hello@where-woof.com")
+	if err != nil {
+		t.Fatalf("insert message: %v", err)
+	}
+
+	var subject string
+	if err := s.DB().QueryRowContext(ctx,
+		`SELECT subject FROM messages WHERE gmail_id = ?`, "abc123").Scan(&subject); err != nil {
+		t.Fatalf("select message: %v", err)
+	}
+	if subject != "Hello" {
+		t.Errorf("subject = %q, want %q", subject, "Hello")
+	}
+}

internal/version/version.go

@@ -0,0 +1,16 @@
+// Package version holds build metadata for the Email Agent service.
+//
+// The values are overridden at build time via -ldflags, for example:
+//
+//	go build -ldflags "-X gitea.lab.audasmedia.com.au/sam/email_agent/internal/version.Version=1.2.3"
+package version
+
+// Version is the application version. It defaults to "dev" for local builds.
+var Version = "dev"
+
+// Commit is the git revision the binary was built from.
+var Commit = "unknown"
+
+// BuildTime is the RFC3339 timestamp of the build. It may be empty for
+// ad-hoc local builds.
+var BuildTime = ""