sovrium 0.0.2

package/src/infrastructure/server/server.ts

@@ -0,0 +1,275 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Console, Effect, Config } from 'effect'
+import { Hono } from 'hono'
+import { purgeOldAnalyticsData } from '@/application/use-cases/analytics/purge-old-data'
+import { compileCSS } from '@/infrastructure/css/compiler'
+import { runMigrations } from '@/infrastructure/database/drizzle/migrate'
+import { AnalyticsRepositoryLive } from '@/infrastructure/database/repositories/analytics-repository-live'
+import {
+  initializeSchema,
+  type AuthConfigRequiredForUserFields,
+  type SchemaInitializationError,
+} from '@/infrastructure/database/schema/schema-initializer'
+import { ServerCreationError } from '@/infrastructure/errors/server-creation-error'
+import { createApiRoutes } from '@/infrastructure/server/route-setup/api-routes'
+import {
+  setupAuthMiddleware,
+  setupAuthRoutes,
+} from '@/infrastructure/server/route-setup/auth-routes'
+import { setupOpenApiRoutes } from '@/infrastructure/server/route-setup/openapi-routes'
+import {
+  setupPageRoutes,
+  type HonoAppConfig,
+} from '@/infrastructure/server/route-setup/page-routes'
+import { setupStaticAssets } from '@/infrastructure/server/route-setup/static-assets'
+import type { ServerInstance } from '@/application/models/server'
+import type { App } from '@/domain/models/app'
+import type {
+  DatabaseConnectionError,
+  MigrationError,
+} from '@/infrastructure/database/drizzle/migrate'
+import type { CSSCompilationError } from '@/infrastructure/errors/css-compilation-error'
+import type { Server } from 'bun'
+
+/**
+ * Server configuration options
+ */
+export interface ServerConfig {
+  readonly app: App
+  readonly port?: number
+  readonly hostname?: string
+  readonly publicDir?: string
+  readonly renderHomePage: (app: App, detectedLanguage?: string) => string
+  readonly renderPage: (app: App, path: string, detectedLanguage?: string) => string | undefined
+  readonly renderNotFoundPage: (app?: App, detectedLanguage?: string) => string
+  readonly renderErrorPage: (app?: App, detectedLanguage?: string) => string
+}
+
+/**
+ * Creates a Hono application with routes
+ *
+ * Mounts the following routes:
+ * - GET /api/* - API routes (health, tables, records) with RPC type safety
+ * - GET /api/openapi.json - Generated OpenAPI specification (application endpoints)
+ * - GET /api/auth/openapi.json - Generated OpenAPI specification (authentication endpoints)
+ * - GET /api/scalar - Unified Scalar API documentation UI (shows both API and Auth tabs)
+ * - POST/GET /api/auth/* - Better Auth authentication endpoints
+ * - GET / - Homepage
+ * - GET /assets/output.css - Compiled Tailwind CSS
+ * - GET /test/error - Test error handler (non-production only)
+ *
+ * @param config - Configuration object with app data and render functions
+ * @returns Configured Hono app instance
+ * @knip-ignore - Used by both createServer and createHonoAppForSSG
+ */
+export function createHonoApp(config: HonoAppConfig): Readonly<Hono> {
+  const { app, renderNotFoundPage, renderErrorPage } = config
+
+  const honoApp = new Hono()
+
+  // Analytics retention cleanup middleware — purges stale page view records.
+  // Runs awaited on page requests to guarantee old data is removed before response.
+  const analyticsEnabled = app.analytics !== undefined && app.analytics !== false
+  if (analyticsEnabled) {
+    const retentionDays =
+      typeof app.analytics === 'object' ? app.analytics.retentionDays : undefined
+
+    honoApp.use('*', async (_c, next) => {
+      await Effect.runPromise(
+        purgeOldAnalyticsData(app.name, retentionDays).pipe(
+          Effect.provide(AnalyticsRepositoryLive),
+          Effect.catchAll(() => Effect.void)
+        )
+      )
+      // eslint-disable-next-line functional/no-expression-statements
+      await next()
+    })
+  }
+
+  // Create base Hono app and chain API routes directly
+  // This pattern is required for Hono RPC type inference to work correctly
+  // Setup all routes by chaining the setup functions
+  const honoWithRoutes = setupPageRoutes(
+    setupStaticAssets(
+      setupAuthRoutes(
+        setupAuthMiddleware(setupOpenApiRoutes(createApiRoutes(app, honoApp)), app),
+        app
+      ),
+      app,
+      config.publicDir
+    ),
+    config
+  )
+
+  // Add error handlers
+  return honoWithRoutes
+    .notFound((c) => c.html(renderNotFoundPage(app), 404))
+    .onError((error, c) => {
+      // Fire-and-forget error logging (onError handler is synchronous)
+      Effect.runPromise(Console.error('Server error:', error)).catch(() => {
+        // Silently ignore logging failures to prevent unhandled promise rejections
+      })
+      return c.html(renderErrorPage(app), 500)
+    })
+}
+
+/**
+ * Create server stop effect
+ */
+const createStopEffect = (server: ReturnType<typeof Bun.serve>): Effect.Effect<void, never> =>
+  Effect.gen(function* () {
+    yield* Console.log('Stopping server...')
+    yield* Effect.sync(() => server.stop())
+    yield* Console.log('Server stopped')
+  })
+
+/**
+ * Log server startup information
+ */
+const logServerStartup = (url: string): Effect.Effect<void, never> =>
+  Effect.gen(function* () {
+    yield* Console.log('✓ Server started successfully!')
+    yield* Console.log(`✓ Homepage: ${url}`)
+    yield* Console.log(`✓ Health check: ${url}/api/health`)
+    yield* Console.log(`✓ API documentation: ${url}/api/scalar`)
+    yield* Console.log(`✓ OpenAPI schema: ${url}/api/openapi.json`)
+    yield* Console.log(`✓ Compiled CSS: ${url}/assets/output.css`)
+  })
+
+/**
+ * Get database URL from environment configuration
+ */
+const getDatabaseUrl = (): Effect.Effect<string, never> =>
+  Config.string('DATABASE_URL').pipe(
+    Config.withDefault(''),
+    Effect.catchAll(() => Effect.succeed(''))
+  )
+
+/**
+ * Run migrations if database URL is configured
+ */
+const runMigrationsIfConfigured = (
+  databaseUrl: string
+): Effect.Effect<
+  void,
+  DatabaseConnectionError | MigrationError | SchemaInitializationError,
+  never
+> => (databaseUrl ? runMigrations(databaseUrl) : Effect.void)
+
+/**
+ * Compile CSS and log results
+ */
+const compileCSSWithLogging = (
+  app: App
+): Effect.Effect<{ css: string }, CSSCompilationError, never> =>
+  Effect.gen(function* () {
+    yield* Console.log('Compiling CSS...')
+    const cssResult = yield* compileCSS(app)
+    yield* Console.log(`CSS compiled: ${cssResult.css.length} bytes`)
+    return cssResult
+  })
+
+/**
+ * Start Bun HTTP server
+ */
+const startBunServer = (
+  honoApp: Readonly<Hono>,
+  port: number,
+  hostname: string
+): Effect.Effect<Server<undefined>, ServerCreationError, never> =>
+  Effect.try({
+    try: () =>
+      Bun.serve({
+        port,
+        hostname,
+        fetch: honoApp.fetch,
+      }),
+    catch: (error) => new ServerCreationError(error),
+  })
+
+/**
+ * Creates and starts a Bun server with Hono
+ *
+ * This function:
+ * 1. Pre-compiles CSS on startup for faster initial requests
+ * 2. Creates a Hono app with routes (/, /assets/output.css, /api/*)
+ * 3. Starts a Bun HTTP server
+ * 4. Returns server instance with stop capability
+ *
+ * @param config - Server configuration with app data and optional port/hostname
+ * @returns Effect that yields ServerInstance or ServerCreationError
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const server = yield* createServer({
+ *     app: { name: 'My App' },
+ *     port: 3000
+ *   })
+ *   console.log(`Server running at ${server.url}`)
+ * })
+ *
+ * Effect.runPromise(program)
+ * ```
+ */
+// @knip-ignore - Used via dynamic import in StartServer.ts
+export const createServer = (
+  config: ServerConfig
+): Effect.Effect<
+  ServerInstance,
+  | ServerCreationError
+  | CSSCompilationError
+  | AuthConfigRequiredForUserFields
+  | SchemaInitializationError
+  | Error
+> =>
+  Effect.gen(function* () {
+    const {
+      app,
+      port = 3000,
+      hostname = 'localhost',
+      publicDir,
+      renderHomePage,
+      renderPage,
+      renderNotFoundPage,
+      renderErrorPage,
+    } = config
+
+    // Initialize database
+    const databaseUrl = yield* getDatabaseUrl()
+    yield* runMigrationsIfConfigured(databaseUrl)
+    yield* initializeSchema(app)
+
+    // Compile CSS
+    yield* compileCSSWithLogging(app)
+
+    // Create Hono app
+    const honoApp = createHonoApp({
+      app,
+      publicDir,
+      renderHomePage,
+      renderPage,
+      renderNotFoundPage,
+      renderErrorPage,
+    })
+
+    // Start server
+    const server = yield* startBunServer(honoApp, port, hostname)
+    const url = `http://${hostname}:${server.port}`
+
+    // Log and return
+    yield* logServerStartup(url)
+
+    return {
+      server,
+      url,
+      stop: createStopEffect(server),
+      app: honoApp,
+    }
+  })

package/src/infrastructure/server/ssg-adapter.ts

@@ -0,0 +1,196 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Effect, Data } from 'effect'
+import { toSSG } from 'hono/bun'
+import type { Hono } from 'hono'
+
+/**
+ * SSG Generation Error - infrastructure layer error
+ */
+export class SSGGenerationError extends Data.TaggedError('SSGGenerationError')<{
+  readonly message: string
+  readonly cause?: unknown
+}> {}
+
+/**
+ * Options for static site generation (infrastructure layer)
+ */
+export interface SSGOptions {
+  readonly outputDir?: string
+  readonly baseUrl?: string
+  readonly basePath?: string
+  readonly deployment?: 'github-pages' | 'generic'
+  readonly languages?: readonly string[]
+  readonly defaultLanguage?: string
+  readonly generateSitemap?: boolean
+  readonly generateRobotsTxt?: boolean
+  readonly hydration?: boolean
+  readonly generateManifest?: boolean
+  readonly bundleOptimization?: 'split' | 'none'
+  readonly pagePaths?: readonly string[] // Explicit list of page paths to generate
+  readonly publicDir?: string // Directory containing static assets to copy
+}
+
+/**
+ * Register explicit page paths in Hono app for SSG discovery
+ */
+function registerPagePaths(
+  // eslint-disable-next-line functional/prefer-immutable-types -- Hono type is mutable
+  app: Hono,
+  pagePaths: readonly string[]
+): void {
+  const mutableApp = app as Hono
+
+  // eslint-disable-next-line functional/no-loop-statements -- Imperative route registration required by Hono's mutable API for toSSG discovery
+  for (const path of pagePaths) {
+    if (path !== '/') {
+      // eslint-disable-next-line functional/no-expression-statements -- Necessary side effect to mutate Hono app for toSSG route discovery
+      mutableApp.get(path, (c) => c.text(''))
+    }
+  }
+}
+
+/**
+ * Check if a route should be excluded from SSG
+ */
+function shouldExcludeRoute(pathname: string): boolean {
+  return (
+    pathname === '/api/health' ||
+    pathname === '/api/openapi.json' ||
+    pathname === '/api/scalar' ||
+    pathname.startsWith('/api/auth/') ||
+    pathname === '/api/tables' || // Exact match for list endpoint
+    pathname.startsWith('/api/tables/') ||
+    pathname === '/api/records' || // Exact match for records endpoint
+    pathname.startsWith('/api/records/') ||
+    pathname.startsWith('/test/')
+  )
+}
+
+/**
+ * Normalize file path to be relative to output directory
+ */
+function normalizeFilePath(file: string, outputDir: string): string {
+  const normalizedOutputDir = outputDir.startsWith('./') ? outputDir.substring(2) : outputDir
+  const normalizedFile = file.startsWith('./') ? file.substring(2) : file
+
+  if (normalizedFile.startsWith(normalizedOutputDir + '/')) {
+    return normalizedFile.substring(normalizedOutputDir.length + 1)
+  }
+  if (normalizedFile.startsWith(normalizedOutputDir)) {
+    return normalizedFile.substring(normalizedOutputDir.length)
+  }
+  return normalizedFile
+}
+
+/**
+ * Generate static site using Hono's SSG functionality
+ *
+ * This adapter wraps Hono's toSSG function with Effect.ts patterns
+ * and Sovrium-specific logic.
+ *
+ * @param app - Hono application instance
+ * @param options - Static generation options
+ * @returns Effect with output directory and generated files
+ */
+export const generateStaticSite = (
+  // eslint-disable-next-line functional/prefer-immutable-types -- Hono is a mutable class from external library
+  app: Hono | Readonly<Hono>,
+  options: Readonly<SSGOptions>
+): Effect.Effect<
+  { readonly outputDir: string; readonly files: readonly string[] },
+  SSGGenerationError,
+  never
+> =>
+  Effect.tryPromise({
+    try: async () => {
+      const outputDir = options.outputDir || './static'
+
+      // Register explicit page paths for SSG discovery
+      if (options.pagePaths && options.pagePaths.length > 0) {
+        registerPagePaths(app as Hono, options.pagePaths)
+      }
+
+      // Use Hono's toSSG to generate static files
+      const result = await toSSG(app as Hono, {
+        dir: outputDir,
+        beforeRequestHook: (req) => {
+          const url = new URL(req.url)
+          return shouldExcludeRoute(url.pathname) ? false : req
+        },
+      })
+
+      // Check if SSG generation was successful
+      if (!result.success) {
+        // eslint-disable-next-line functional/no-throw-statements -- Error handling requires throw
+        throw new Error(
+          `Static site generation failed: ${result.error?.message || 'Unknown error'}`
+        )
+      }
+
+      // Normalize file paths to be relative to outputDir
+      const normalizedFiles = (result.files as readonly string[]).map((file) =>
+        normalizeFilePath(file, outputDir)
+      )
+
+      // Return output directory and generated files from toSSG
+      return {
+        outputDir,
+        files: normalizedFiles,
+      } as const
+    },
+    catch: (error) =>
+      new SSGGenerationError({
+        message: `Static site generation failed: ${error instanceof Error ? error.message : String(error)}`,
+        cause: error,
+      }),
+  })
+
+/**
+ * Page info for sitemap generation
+ */
+interface SitemapPage {
+  readonly path: string
+  readonly priority?: string
+  readonly changefreq?: string
+}
+
+/**
+ * Plugin to generate sitemap.xml
+ */
+export const sitemapPlugin = (baseUrl: string) => ({
+  name: 'sitemap',
+  async generate(pages: readonly SitemapPage[]) {
+    const entries = pages.map(
+      (page) => `  <url>
+    <loc>${baseUrl}${page.path}</loc>
+    <priority>${page.priority || '0.5'}</priority>
+    <changefreq>${page.changefreq || 'monthly'}</changefreq>
+  </url>`
+    )
+
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${entries.join('\n')}
+</urlset>`
+  },
+})
+
+/**
+ * Plugin to generate robots.txt
+ */
+export const robotsPlugin = (baseUrl: string, includeSitemap: boolean = false) => ({
+  name: 'robots',
+  async generate() {
+    const baseLines = ['User-agent: *', 'Allow: /'] as const
+    const sitemapLine = includeSitemap ? ([`Sitemap: ${baseUrl}/sitemap.xml`] as const) : []
+    const lines = [...baseLines, ...sitemapLine] as readonly string[]
+
+    return lines.join('\n')
+  },
+})

package/src/infrastructure/server/static-site-generator-live.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Layer } from 'effect'
+import { StaticSiteGenerator } from '@/application/ports/services/static-site-generator'
+import { generateStaticSite } from '@/infrastructure/server/ssg-adapter'
+
+/**
+ * Live implementation of StaticSiteGenerator using Hono SSG
+ *
+ * This layer provides the production implementation of static site generation
+ * using Hono's toSSG functionality.
+ */
+export const StaticSiteGeneratorLive = Layer.succeed(StaticSiteGenerator, {
+  generate: generateStaticSite,
+})

package/src/infrastructure/utils/accept-language-parser.ts

@@ -0,0 +1,106 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+/**
+ * Accept-Language Header Parser
+ *
+ * Parses the Accept-Language HTTP header and returns an ordered list of
+ * preferred languages based on quality values (q parameter).
+ *
+ * Format: Accept-Language: en-US,en;q=0.9,fr;q=0.8
+ *
+ * @example
+ * ```typescript
+ * const languages = parseAcceptLanguage('en-US,en;q=0.9,fr;q=0.8')
+ * // Returns: ['en-US', 'en', 'fr']
+ * ```
+ */
+
+interface LanguagePreference {
+  readonly language: string
+  readonly quality: number
+}
+
+/**
+ * Parse Accept-Language header into ordered list of language preferences
+ *
+ * @param header - Accept-Language header value (e.g., 'en-US,en;q=0.9,fr;q=0.8')
+ * @returns Array of language codes ordered by preference (highest quality first)
+ */
+export function parseAcceptLanguage(header: string | null | undefined): ReadonlyArray<string> {
+  if (!header) {
+    return []
+  }
+
+  // Parse each language-quality pair and sort by quality (highest first)
+  const sortedPreferences: ReadonlyArray<LanguagePreference> = header
+    .split(',')
+    .map((lang) => {
+      const [language, qualityStr] = lang.trim().split(';')
+
+      // Skip invalid entries without a language code
+      if (!language) {
+        return undefined
+      }
+
+      // Extract quality value (default is 1.0 if not specified)
+      const quality = qualityStr ? parseFloat(qualityStr.split('=')[1] || '1.0') : 1.0
+
+      return {
+        language: language.trim(),
+        quality: isNaN(quality) ? 0 : quality,
+      }
+    })
+    .filter(
+      (pref): pref is LanguagePreference =>
+        pref !== undefined && pref.language.length > 0 && pref.quality > 0
+    )
+    .toSorted((a, b) => b.quality - a.quality)
+
+  return sortedPreferences.map((pref) => pref.language)
+}
+
+/**
+ * Detect best matching language from Accept-Language header
+ *
+ * Tries exact match first (e.g., 'fr-FR' === 'fr-FR'),
+ * then base language match (e.g., 'fr' from 'fr-FR' matches 'fr-CA')
+ *
+ * @param header - Accept-Language header value
+ * @param supportedLanguages - Array of supported language codes
+ * @returns Best matching language code or undefined
+ */
+export function detectLanguageFromHeader(
+  header: string | null | undefined,
+  supportedLanguages: ReadonlyArray<string>
+): string | undefined {
+  const preferences = parseAcceptLanguage(header)
+
+  // Try exact matches first
+  const exactMatch = preferences.find((preferred) => supportedLanguages.includes(preferred))
+  if (exactMatch) {
+    return exactMatch
+  }
+
+  // Try base language matches (e.g., 'fr' from 'fr-FR')
+  const baseMatch = preferences
+    .map((preferred) => ({
+      preferred,
+      basePreferred: preferred.split('-')[0],
+    }))
+    .find(({ basePreferred }) =>
+      supportedLanguages.some((supported) => supported.split('-')[0] === basePreferred)
+    )
+
+  if (baseMatch) {
+    return supportedLanguages.find(
+      (supported) => supported.split('-')[0] === baseMatch.basePreferred
+    )
+  }
+
+  return undefined
+}

package/src/infrastructure/utils/glob-matcher.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+/**
+ * Simple glob pattern matcher for URL paths.
+ *
+ * Supports:
+ * - Exact matches: /admin
+ * - Wildcard suffix: /admin/* matches /admin/dashboard, /admin/users/123
+ * - Wildcard prefix: star/api matches /v1/api, /public/api
+ * - Wildcard anywhere: /admin/star/users matches /admin/123/users
+ *
+ * Does NOT support:
+ * - Character classes: [abc]
+ * - Brace expansion: curly braces
+ * - Double asterisk: treated same as single asterisk
+ *
+ * @param pattern - Glob pattern string (e.g., /admin/*)
+ * @param path - Path to test (e.g., /admin/dashboard)
+ * @returns true if path matches pattern, false otherwise
+ */
+export function matchGlobPattern(pattern: string, path: string): boolean {
+  // Escape special regex characters except *
+  const escapedPattern = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')
+
+  // Create regex with exact start and end anchors
+  const regex = new RegExp(`^${escapedPattern}$`)
+
+  return regex.test(path)
+}
+
+/**
+ * Check if a path matches any of the provided glob patterns.
+ *
+ * @param patterns - Array of glob patterns
+ * @param path - Path to test
+ * @returns true if path matches any pattern, false otherwise
+ */
+export function matchesAnyGlobPattern(
+  patterns: readonly string[] | undefined,
+  path: string
+): boolean {
+  if (!patterns || patterns.length === 0) return false
+
+  return patterns.some((pattern) => matchGlobPattern(pattern, path))
+}