Merge pull request #118 from keyxmakerx/claude/fix-navbar-features-page-8RZuE

Claude/fix navbar features page 8 r zu e

Author: keyxmakerx

.ai/architecture.md

@@ -94,9 +94,11 @@ chronicle/
 │   ├── config/                       # CORE: Configuration loading (env vars)
 │   │   └── config.go
 │   │
-│   ├── database/                     # CORE: Database connections
+│   ├── database/                     # CORE: Database connections + migrations
 │   │   ├── mariadb.go                #   MariaDB connection pool
-│   │   └── redis.go                  #   Redis client
+│   │   ├── redis.go                  #   Redis client
+│   │   ├── plugin_schema.go          #   Plugin migration runner (reads embed.FS)
+│   │   └── plugin_health.go          #   Plugin health registry
 │   │
 │   ├── middleware/                    # CORE: HTTP middleware
 │   │   ├── auth.go                   #   Session validation
@@ -220,6 +222,7 @@ Every plugin follows this exact structure. No exceptions.
 ```
 internal/plugins/<name>/
   .ai.md              # Plugin-level AI documentation
+  embed.go            # Embeds migrations/*.sql via Go embed.FS (ADR-030)
   handler.go          # Echo handlers (thin: bind, call service, render)
   handler_test.go     # Handler tests (HTTP-level, mock service)
   service.go          # Business logic (never imports Echo types)
@@ -228,6 +231,9 @@ internal/plugins/<name>/
   repository_test.go  # Repository tests (integration, real DB)
   model.go            # Domain models, DTOs, request/response structs
   routes.go           # Route registration function
+  migrations/         # Plugin-specific schema migrations (embedded in binary)
+    001_*.up.sql
+    001_*.down.sql
   templates/          # Templ components for this plugin
     index.templ       #   List view
     show.templ        #   Detail view

.ai/conventions.md

@@ -253,8 +253,11 @@ Chronicle uses a **plugin-isolated database schema architecture**:
 - **Core schema** (`db/migrations/`): Single baseline migration with all core tables.
   Runs via golang-migrate on startup. Failure is fatal.
 - **Plugin schema** (`internal/plugins/<name>/migrations/`): Each built-in plugin
-  has its own numbered migration files. Runs via `RunPluginMigrations()` after core
-  migrations. Failure disables that plugin; app continues serving.
+  has its own numbered migration files **embedded in the binary** via Go's `embed.FS`
+  (ADR-030). Each plugin has an `embed.go` exporting `MigrationsFS`. Runs via
+  `RunPluginMigrations()` after core migrations. Failure disables that plugin; app
+  continues serving. `RegisteredPlugins()` lives in `cmd/server/main.go` (not in
+  the database package) to avoid import cycles.
 
 ```sql
 -- Core migration example: db/migrations/000001_baseline.up.sql
@@ -280,6 +283,9 @@ CREATE TABLE IF NOT EXISTS calendars ( ... );
    in migration SQL. Update the valid sets there when adding new ENUM values.
 6. **Plugin tables**: Plugin tables belong in `internal/plugins/<name>/migrations/`,
    not in `db/migrations/`. Plugin schema failures degrade gracefully (ADR-028).
+   Migrations are embedded in the binary via `embed.FS` (ADR-030). When adding a
+   new plugin with migrations, create an `embed.go` in the plugin package and
+   register it in `registeredPlugins()` in `cmd/server/main.go`.
 
 ### Permission Model
 

.ai/decisions.md

@@ -1050,3 +1050,42 @@ capabilities. Non-owners could see features but couldn't tell which were enabled
 - Single source of truth for feature management.
 - Owners can manage features directly from the same page all members see.
 - Future enhancements (per-addon entity usage, "offline" banners) have one target page.
+
+---
+
+## ADR-030: Embed Plugin Migrations via Go embed.FS
+
+**Date:** 2026-03-11
+**Status:** Accepted (amends ADR-028)
+
+**Context:** ADR-028 introduced per-plugin migration directories at
+`internal/plugins/<name>/migrations/`. The migration runner used `os.Stat` and
+`os.ReadDir` with relative filesystem paths. This worked in development (CWD =
+project root) but failed silently in Docker: the runtime image copies the binary
+to `/app` but never copies plugin migration directories. Since `os.Stat` returned
+`os.IsNotExist`, the runner treated each plugin as "healthy with 0 migrations"
+— no tables were created, entity pages crashed, and the DB Explorer showed 0/0.
+
+**Decision:** Embed plugin migration SQL files in the binary using Go's `embed.FS`:
+- Each plugin package gets an `embed.go` that exports `MigrationsFS embed.FS`
+  with `//go:embed migrations/*.sql`.
+- `PluginSchema.MigrationsDir` (string) replaced with `MigrationsFS` (`fs.FS`).
+- `parsePluginMigrations` and `LatestMigrationVersion` read from `fs.FS` instead
+  of the real filesystem.
+- `RegisteredPlugins()` moved from `database` package to `cmd/server/main.go`
+  to avoid import cycles (database can't import plugin packages). Uses `fs.Sub`
+  to strip the `migrations/` prefix from each embed.FS.
+- `PluginSchemas` stored on `App` struct and passed to `DatabaseExplorer` for
+  on-demand re-migration from the admin panel.
+
+**Alternatives considered:**
+- Copy plugin migration dirs to Docker runtime image: fragile, requires syncing
+  Dockerfile whenever plugins are added/removed. Still fails if CWD changes.
+- Centralise all plugin migrations in one directory: loses per-plugin isolation
+  that ADR-028 established.
+
+**Consequences:**
+- Migrations work in any environment regardless of working directory.
+- No Dockerfile changes needed when adding new plugins with migrations.
+- Each plugin must have an `embed.go` exporting its `MigrationsFS`.
+- `RegisteredPlugins()` now lives in `cmd/server/main.go` instead of `database`.

.ai/status.md

@@ -10,6 +10,11 @@
 ## Last Updated
 2026-03-11 -- **Sprint W-0.5: Visual Customization + Admin DB Explorer (IN PROGRESS).**
 
+27. **Fix: Embed plugin migrations in binary (ADR-030).** Root cause of entity page errors and DB Explorer showing 0/0: plugin migrations used relative filesystem paths (`internal/plugins/*/migrations/`) that only resolve when the binary's CWD is the project root. In Docker, the binary runs from `/app` so migration directories were never found, tables were never created, and entity pages crashed. Fix: each plugin now embeds its `migrations/*.sql` via Go's `embed.FS`. `PluginSchema.MigrationsDir` (string) replaced with `MigrationsFS` (`fs.FS`). `RegisteredPlugins()` moved from `database` package to `cmd/server/main.go` to avoid import cycles (database can't import plugin packages). `PluginSchemas` stored on `App` struct and passed to `DatabaseExplorer` for on-demand re-migration. New `embed.go` files in calendar, maps, sessions, timeline, syncapi plugins.
+
+### Previous Update
+2026-03-11 -- **Sprint W-0.5: Visual Customization + Admin DB Explorer (IN PROGRESS).**
+
 26. Admin Database Explorer: New `/admin/database` page with interactive D3.js schema diagram showing all tables, FK relationships, plugin grouping, and migration status. Table detail panel on click. "Apply Pending Migrations" button (fixes sessions table missing issue). Removed "Manual DB Record (Advanced)" form from Features page. New files: `database_service.go` (info_schema introspection), `database.templ`, `db_explorer.js` widget. Added `LatestMigrationVersion()` to database package. Dashboard card + sidebar link.
 
 ### Previous Update

.ai/todo.md

@@ -16,6 +16,7 @@ Known broken or missing things, ordered by severity.
 ### Critical
 
 - [x] **Public campaign widget 403s** — Editor and attributes widgets return 403 for non-member visitors on public campaigns. Root cause: GET `/entry`, `/fields`, `/tags`, `/relations` only registered in authenticated route group, not in public-capable group. Fixed by adding routes to `pub` group in entities/routes.go, tags/routes.go, relations/routes.go.
+- [x] **Plugin migrations not applied in Docker (entity page errors, 0/0 in DB Explorer)** — Plugin migrations used relative filesystem paths (`internal/plugins/*/migrations/`) that only resolve when CWD is the project root. In Docker, binary runs from `/app` so dirs were never found, tables never created, entity pages crashed on missing tables, and DB Explorer showed 0/0 for all plugins. Fixed by embedding migrations in the binary via Go's `embed.FS` (ADR-030). Each plugin now has `embed.go` exporting `MigrationsFS`. `PluginSchema.MigrationsDir` replaced with `MigrationsFS` (`fs.FS`).
 
 ### High
 

cmd/server/main.go

@@ -5,6 +5,7 @@ package main
 
 import (
 	"context"
+	"io/fs"
 	"log/slog"
 	"os"
 	"os/signal"
@@ -14,6 +15,11 @@ import (
 	"github.com/keyxmakerx/chronicle/internal/app"
 	"github.com/keyxmakerx/chronicle/internal/config"
 	"github.com/keyxmakerx/chronicle/internal/database"
+	"github.com/keyxmakerx/chronicle/internal/plugins/calendar"
+	"github.com/keyxmakerx/chronicle/internal/plugins/maps"
+	"github.com/keyxmakerx/chronicle/internal/plugins/sessions"
+	"github.com/keyxmakerx/chronicle/internal/plugins/syncapi"
+	"github.com/keyxmakerx/chronicle/internal/plugins/timeline"
 	"github.com/keyxmakerx/chronicle/internal/systems"
 
 	// Import system packages for their init() factory registrations.
@@ -56,9 +62,11 @@ func main() {
 
 	// --- Run Plugin Migrations ---
 	// Each plugin runs its own schema migrations independently. Failures
-	// disable the plugin instead of crashing the app.
+	// disable the plugin instead of crashing the app. Migrations are
+	// embedded in the binary via embed.FS so they work in any environment.
 	pluginHealth := database.NewPluginHealthRegistry()
-	pluginResults := database.RunPluginMigrations(db, database.RegisteredPlugins())
+	pluginSchemas := registeredPlugins()
+	pluginResults := database.RunPluginMigrations(db, pluginSchemas)
 	for _, r := range pluginResults {
 		pluginHealth.Register(r.Slug, r.Healthy, r.Error, r.Version, r.LatestVersion)
 	}
@@ -85,7 +93,7 @@ func main() {
 	}
 
 	// --- Create Application ---
-	application := app.New(cfg, db, rdb, pluginHealth)
+	application := app.New(cfg, db, rdb, pluginHealth, pluginSchemas)
 
 	// Register all routes (public, plugin, system, widget, API).
 	application.RegisterRoutes()
@@ -139,3 +147,24 @@ func setupLogging(cfg *config.Config) {
 
 	slog.SetDefault(slog.New(handler))
 }
+
+// registeredPlugins returns the list of built-in plugins with their embedded
+// migration filesystems. Each plugin embeds its own migrations/*.sql files
+// via Go's embed package, ensuring they're available in the compiled binary
+// regardless of working directory.
+func registeredPlugins() []database.PluginSchema {
+	mustSub := func(fsys fs.FS, dir string) fs.FS {
+		sub, err := fs.Sub(fsys, dir)
+		if err != nil {
+			panic("embedded migrations sub-dir: " + err.Error())
+		}
+		return sub
+	}
+	return []database.PluginSchema{
+		{Slug: "calendar", MigrationsFS: mustSub(calendar.MigrationsFS, database.PluginMigrationsSubdir)},
+		{Slug: "maps", MigrationsFS: mustSub(maps.MigrationsFS, database.PluginMigrationsSubdir)},
+		{Slug: "sessions", MigrationsFS: mustSub(sessions.MigrationsFS, database.PluginMigrationsSubdir)},
+		{Slug: "timeline", MigrationsFS: mustSub(timeline.MigrationsFS, database.PluginMigrationsSubdir)},
+		{Slug: "syncapi", MigrationsFS: mustSub(syncapi.MigrationsFS, database.PluginMigrationsSubdir)},
+	}
+}

internal/app/app.go

@@ -49,11 +49,15 @@ type App struct {
 	// PluginHealth tracks which built-in plugins have healthy schemas.
 	// Used during route registration to skip degraded plugins.
 	PluginHealth *database.PluginHealthRegistry
+
+	// PluginSchemas holds the registered plugin migration configurations.
+	// Used by the database explorer to re-run migrations on demand.
+	PluginSchemas []database.PluginSchema
 }
 
 // New creates a new App instance with the given dependencies and configures
 // the Echo server with global middleware and error handling.
-func New(cfg *config.Config, db *sql.DB, rdb *redis.Client, pluginHealth *database.PluginHealthRegistry) *App {
+func New(cfg *config.Config, db *sql.DB, rdb *redis.Client, pluginHealth *database.PluginHealthRegistry, pluginSchemas []database.PluginSchema) *App {
 	e := echo.New()
 
 	// Disable Echo's default banner and startup message -- we log our own.
@@ -76,7 +80,8 @@ func New(cfg *config.Config, db *sql.DB, rdb *redis.Client, pluginHealth *databa
 		DB:           db,
 		Redis:        rdb,
 		Echo:         e,
-		PluginHealth: pluginHealth,
+		PluginHealth:  pluginHealth,
+		PluginSchemas: pluginSchemas,
 	}
 
 	// Register global middleware in order of execution.

internal/app/routes.go

@@ -862,7 +862,7 @@ func (a *App) RegisterRoutes() {
 	adminHandler.SetHygieneScanner(hygieneScanner)
 
 	// Database explorer: schema visualization and migration management.
-	dbExplorer := admin.NewDatabaseExplorer(a.DB, a.PluginHealth)
+	dbExplorer := admin.NewDatabaseExplorer(a.DB, a.PluginHealth, a.PluginSchemas)
 	adminHandler.SetDatabaseExplorer(dbExplorer)
 
 	// Wire security event logging into the auth handler so logins, logouts,

internal/database/plugin_schema.go

@@ -8,9 +8,8 @@ import (
 	"context"
 	"database/sql"
 	"fmt"
+	"io/fs"
 	"log/slog"
-	"os"
-	"path/filepath"
 	"regexp"
 	"sort"
 	"strconv"
@@ -23,9 +22,10 @@ type PluginSchema struct {
 	// Slug is the unique plugin identifier (e.g., "calendar", "maps").
 	Slug string
 
-	// MigrationsDir is the absolute or relative path to the plugin's
-	// migrations/ directory containing numbered SQL files.
-	MigrationsDir string
+	// MigrationsFS is an embedded filesystem containing the plugin's
+	// numbered SQL migration files. Using embed.FS ensures migrations
+	// are available regardless of the binary's working directory.
+	MigrationsFS fs.FS
 }
 
 // PluginMigrationResult holds the outcome of running a single plugin's
@@ -109,20 +109,13 @@ func ensurePluginSchemaTable(db *sql.DB) error {
 func runSinglePluginMigrations(db *sql.DB, plugin PluginSchema) PluginMigrationResult {
 	ctx := context.Background()
 
-	// Check if the migrations directory exists.
-	if _, err := os.Stat(plugin.MigrationsDir); err != nil {
-		if os.IsNotExist(err) {
-			// No migrations directory = nothing to do, plugin is healthy.
-			return PluginMigrationResult{Slug: plugin.Slug, Healthy: true, Version: 0}
-		}
-		return PluginMigrationResult{
-			Slug:  plugin.Slug,
-			Error: fmt.Errorf("checking migrations dir: %w", err),
-		}
+	if plugin.MigrationsFS == nil {
+		// No embedded migrations = nothing to do, plugin is healthy.
+		return PluginMigrationResult{Slug: plugin.Slug, Healthy: true, Version: 0}
 	}
 
-	// Parse migration files from disk.
-	migrations, err := parsePluginMigrations(plugin.MigrationsDir)
+	// Parse migration files from embedded filesystem.
+	migrations, err := parsePluginMigrations(plugin.MigrationsFS)
 	if err != nil {
 		return PluginMigrationResult{
 			Slug:  plugin.Slug,
@@ -192,10 +185,10 @@ func runSinglePluginMigrations(db *sql.DB, plugin PluginSchema) PluginMigrationR
 	}
 }
 
-// parsePluginMigrations reads numbered SQL migration files from a directory.
+// parsePluginMigrations reads numbered SQL migration files from an embedded filesystem.
 // Returns migrations sorted by version number ascending.
-func parsePluginMigrations(dir string) ([]pluginMigration, error) {
-	entries, err := os.ReadDir(dir)
+func parsePluginMigrations(migrationsFS fs.FS) ([]pluginMigration, error) {
+	entries, err := fs.ReadDir(migrationsFS, ".")
 	if err != nil {
 		return nil, fmt.Errorf("reading migrations dir: %w", err)
 	}
@@ -225,7 +218,7 @@ func parsePluginMigrations(dir string) ([]pluginMigration, error) {
 			pairs[version] = &migPair{}
 		}
 
-		content, err := os.ReadFile(filepath.Join(dir, entry.Name()))
+		content, err := fs.ReadFile(migrationsFS, entry.Name())
 		if err != nil {
 			return nil, fmt.Errorf("reading %s: %w", entry.Name(), err)
 		}
@@ -331,16 +324,13 @@ func splitPluginStatements(sql string) []string {
 }
 
 // LatestMigrationVersion returns the highest migration version number found
-// in a plugin's migrations directory. Returns 0 if no migrations exist.
-func LatestMigrationVersion(migrationsDir string) (int, error) {
-	if _, err := os.Stat(migrationsDir); err != nil {
-		if os.IsNotExist(err) {
-			return 0, nil
-		}
-		return 0, err
+// in a plugin's embedded migrations filesystem. Returns 0 if nil or empty.
+func LatestMigrationVersion(migrationsFS fs.FS) (int, error) {
+	if migrationsFS == nil {
+		return 0, nil
 	}
 
-	entries, err := os.ReadDir(migrationsDir)
+	entries, err := fs.ReadDir(migrationsFS, ".")
 	if err != nil {
 		return 0, err
 	}
@@ -366,14 +356,6 @@ func LatestMigrationVersion(migrationsDir string) (int, error) {
 	return highest, nil
 }
 
-// RegisteredPlugins returns the list of built-in plugins that have schema
-// migrations. The MigrationsDir paths are relative to the working directory.
-func RegisteredPlugins() []PluginSchema {
-	return []PluginSchema{
-		{Slug: "calendar", MigrationsDir: "internal/plugins/calendar/migrations"},
-		{Slug: "maps", MigrationsDir: "internal/plugins/maps/migrations"},
-		{Slug: "sessions", MigrationsDir: "internal/plugins/sessions/migrations"},
-		{Slug: "timeline", MigrationsDir: "internal/plugins/timeline/migrations"},
-		{Slug: "syncapi", MigrationsDir: "internal/plugins/syncapi/migrations"},
-	}
-}
+// PluginMigrationsSubdir is the subdirectory within each plugin's embed.FS
+// that contains migration SQL files (from //go:embed migrations/*.sql).
+const PluginMigrationsSubdir = "migrations"

internal/plugins/admin/database_service.go

@@ -80,15 +80,17 @@ type MigrationHistory struct {
 
 // databaseExplorer implements DatabaseExplorer with direct DB access.
 type databaseExplorer struct {
-	db           *sql.DB
-	pluginHealth *database.PluginHealthRegistry
+	db            *sql.DB
+	pluginHealth  *database.PluginHealthRegistry
+	pluginSchemas []database.PluginSchema
 }
 
 // NewDatabaseExplorer creates a new database explorer service.
-func NewDatabaseExplorer(db *sql.DB, pluginHealth *database.PluginHealthRegistry) DatabaseExplorer {
+func NewDatabaseExplorer(db *sql.DB, pluginHealth *database.PluginHealthRegistry, pluginSchemas []database.PluginSchema) DatabaseExplorer {
 	return &databaseExplorer{
-		db:           db,
-		pluginHealth: pluginHealth,
+		db:            db,
+		pluginHealth:  pluginHealth,
+		pluginSchemas: pluginSchemas,
 	}
 }
 
@@ -220,10 +222,9 @@ func (e *databaseExplorer) GetSchema(ctx context.Context) (*DatabaseSchema, erro
 
 // GetMigrationStatus computes the migration status for each registered plugin.
 func (e *databaseExplorer) GetMigrationStatus(ctx context.Context) ([]PluginMigrationStatus, error) {
-	plugins := database.RegisteredPlugins()
-	statuses := make([]PluginMigrationStatus, 0, len(plugins))
+	statuses := make([]PluginMigrationStatus, 0, len(e.pluginSchemas))
 
-	for _, p := range plugins {
+	for _, p := range e.pluginSchemas {
 		status := PluginMigrationStatus{
 			Slug:    p.Slug,
 			Healthy: true,
@@ -285,8 +286,7 @@ func (e *databaseExplorer) getMigrationHistory(ctx context.Context, slug string)
 // ApplyPendingMigrations runs all pending plugin migrations and updates the
 // health registry. Returns the results for each plugin.
 func (e *databaseExplorer) ApplyPendingMigrations(ctx context.Context) ([]database.PluginMigrationResult, error) {
-	plugins := database.RegisteredPlugins()
-	results := database.RunPluginMigrations(e.db, plugins)
+	results := database.RunPluginMigrations(e.db, e.pluginSchemas)
 
 	// Update the health registry with new results.
 	for _, r := range results {