sovrium 0.0.2

package/src/infrastructure/server/route-setup/openapi-schema.ts

@@ -0,0 +1,120 @@
+/**
+ * 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 { OpenAPIHono, createRoute } from '@hono/zod-openapi'
+import { healthResponseSchema } from '@/domain/models/api/health'
+
+/**
+ * OpenAPI Schema Generator
+ *
+ * This file creates a parallel OpenAPI schema using OpenAPIHono.
+ * **Important**: This is separate from the runtime API routes.
+ *
+ * Located in Infrastructure layer because schema generation is an
+ * infrastructure concern (documentation/tooling), not presentation logic.
+ *
+ * **Why Separate?**
+ * - Runtime routes use regular Hono (for RPC compatibility with `:id` syntax)
+ * - OpenAPI schema uses OpenAPIHono (for documentation with `{id}` syntax)
+ * - Both share the same Zod schemas for consistency
+ *
+ * **Usage**:
+ * 1. Runtime: Server uses regular Hono routes from api-routes.ts
+ * 2. Docs: Server exposes this schema at `/api/openapi.json` and `/api/scalar`
+ * 3. Export: Script exports this schema to `schemas/0.0.1/app.openapi.json`
+ */
+
+/**
+ * Create OpenAPI Hono app with all routes
+ *
+ * This function defines all API routes using OpenAPI syntax for documentation.
+ * The routes here are "dummy" implementations - they're only used to generate
+ * the OpenAPI schema. The real implementations are in api-routes.ts.
+ */
+const createOpenApiApp = () => {
+  const app = new OpenAPIHono()
+
+  // Define health check route with OpenAPI annotations
+  const healthRoute = createRoute({
+    method: 'get',
+    path: '/api/health',
+    summary: 'Health check endpoint',
+    description:
+      'Returns server health status. Used by monitoring tools and E2E tests to verify server is running.',
+    operationId: 'healthCheck',
+    tags: ['infrastructure'],
+    responses: {
+      200: {
+        content: {
+          'application/json': {
+            schema: healthResponseSchema,
+          },
+        },
+        description: 'Server is healthy',
+      },
+    },
+  })
+
+  // Mount route with dummy handler (only for schema generation)
+
+  app.openapi(healthRoute, (c) => {
+    return c.json({
+      status: 'ok',
+      timestamp: new Date().toISOString(),
+      app: {
+        name: 'Sovrium',
+      },
+    })
+  })
+
+  // Future routes will be added here:
+  // app.openapi(listTablesRoute, ...)
+  // app.openapi(getTableRoute, ...)
+
+  return app
+}
+
+/**
+ * Get OpenAPI document as JSON
+ *
+ * This function generates the complete OpenAPI specification document.
+ * It's used by:
+ * - `/api/openapi.json` endpoint (runtime documentation)
+ * - `/api/scalar` endpoint (Scalar UI)
+ * - `scripts/export-openapi.ts` (export to schemas/ folder)
+ *
+ * @returns OpenAPI 3.1.0 specification document
+ */
+export const getOpenAPIDocument = () => {
+  const app = createOpenApiApp()
+
+  return app.getOpenAPIDocument({
+    openapi: '3.1.0',
+    info: {
+      title: 'Sovrium API',
+      version: '0.0.1',
+      description:
+        'REST API specification for Sovrium application.\n\n' +
+        '**Generated Schema**: This schema is automatically generated from the runtime implementation. ' +
+        'It reflects the currently implemented endpoints and their schemas.\n\n' +
+        '**Design Specs**: Hand-written OpenAPI specs in `docs/specifications/app/` define the complete API design. ' +
+        'Comparing this generated schema with the design specs shows implementation progress.',
+    },
+    servers: [
+      {
+        url: 'http://localhost:3000',
+        description: 'Development server',
+      },
+    ],
+    tags: [
+      {
+        name: 'infrastructure',
+        description: 'Infrastructure endpoints (health, metrics)',
+      },
+    ],
+  })
+}

package/src/infrastructure/server/route-setup/page-routes.ts

@@ -0,0 +1,219 @@
+/**
+ * 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 } from 'effect'
+import { type Context, type Hono } from 'hono'
+import {
+  detectLanguageIfEnabled,
+  validateLanguageSubdirectory,
+} from '@/infrastructure/server/language-detection'
+import type { App } from '@/domain/models/app'
+
+/**
+ * Hono app configuration for route setup
+ */
+export interface HonoAppConfig {
+  readonly app: App
+  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
+}
+
+/**
+ * Setup homepage route
+ *
+ * Handles:
+ * - No languages configured: Serve default
+ * - Browser detection disabled: Serve default
+ * - Browser detection enabled: Detect and redirect if needed
+ *
+ * @param honoApp - Hono application instance
+ * @param config - Route configuration
+ * @returns Hono app with homepage route configured
+ */
+export function setupHomepageRoute(honoApp: Readonly<Hono>, config: HonoAppConfig): Readonly<Hono> {
+  const { app, renderHomePage, renderErrorPage } = config
+
+  return honoApp.get('/', (c) => {
+    try {
+      // If no languages configured, render with default (en-US)
+      if (!app.languages) {
+        const html = renderHomePage(app, undefined)
+        return c.html(html)
+      }
+
+      // If browser detection disabled, always serve default language at /
+      if (app.languages.detectBrowser === false) {
+        const html = renderHomePage(app, undefined)
+        return c.html(html)
+      }
+
+      // Browser detection enabled - detect language from Accept-Language header
+      const detectedLanguage = detectLanguageIfEnabled(app, c.req.header('Accept-Language'))
+      const targetLanguage = detectedLanguage || app.languages.default
+
+      // Only redirect if detected language is different from default
+      if (targetLanguage !== app.languages.default) {
+        return c.redirect(`/${targetLanguage}/`, 302)
+      }
+
+      // Same as default - serve at / (no redirect, cacheable)
+      const html = renderHomePage(app, undefined)
+      return c.html(html)
+    } catch (error) {
+      Effect.runSync(Console.error('Error rendering homepage:', error))
+      return c.html(renderErrorPage(app), 500)
+    }
+  })
+}
+
+/**
+ * Handle /:lang/ route (homepage in specific language)
+ */
+function handleLanguageHomepageRoute(config: HonoAppConfig) {
+  const { app, renderHomePage, renderPage, renderNotFoundPage, renderErrorPage } = config
+  return (c: Readonly<Context>) => {
+    try {
+      const { path } = c.req
+      const detectedLanguage = detectLanguageIfEnabled(app, c.req.header('Accept-Language'))
+      const exactPageMatch = renderPage(app, path, detectedLanguage)
+      if (exactPageMatch) {
+        return c.html(exactPageMatch)
+      }
+      const urlLanguage = validateLanguageSubdirectory(app, path)
+      if (!urlLanguage) {
+        const detectedLang = detectLanguageIfEnabled(app, c.req.header('Accept-Language'))
+        return c.html(renderNotFoundPage(app, detectedLang), 404)
+      }
+      const html = renderHomePage(app, urlLanguage)
+      return c.html(html)
+    } catch (error) {
+      Effect.runSync(Console.error('Error rendering homepage:', error))
+      const detectedLang = detectLanguageIfEnabled(app, c.req.header('Accept-Language'))
+      return c.html(renderErrorPage(app, detectedLang), 500)
+    }
+  }
+}
+
+/**
+ * Handle /:lang/* route (pages in specific language)
+ */
+function handleLanguagePageRoute(config: HonoAppConfig) {
+  const { app, renderPage, renderNotFoundPage, renderErrorPage } = config
+  return (c: Readonly<Context>) => {
+    const { path } = c.req
+    const detectedLanguage = detectLanguageIfEnabled(app, c.req.header('Accept-Language'))
+    try {
+      const exactPageMatch = renderPage(app, path, detectedLanguage)
+      if (exactPageMatch) {
+        return c.html(exactPageMatch)
+      }
+      const urlLanguage = validateLanguageSubdirectory(app, path)
+      if (!urlLanguage) {
+        return c.html(renderNotFoundPage(app, detectedLanguage), 404)
+      }
+      const pathWithoutLang = path.replace(`/${urlLanguage}`, '') || '/'
+      const html = renderPage(app, pathWithoutLang, urlLanguage)
+      if (!html) {
+        return c.html(renderNotFoundPage(app, urlLanguage), 404)
+      }
+      return c.html(html)
+    } catch (error) {
+      Effect.runSync(Console.error('Error rendering page:', error))
+      return c.html(renderErrorPage(app, detectedLanguage), 500)
+    }
+  }
+}
+
+/**
+ * Setup language subdirectory routes
+ *
+ * Handles:
+ * - GET /:lang/ - Homepage in specific language
+ * - GET /:lang/* - Pages in specific language
+ *
+ * @param honoApp - Hono application instance
+ * @param config - Route configuration
+ * @returns Hono app with language routes configured
+ */
+export function setupLanguageRoutes(
+  honoApp: Readonly<Hono>,
+  config: HonoAppConfig
+): Readonly<Hono> {
+  return honoApp
+    .get('/:lang/', handleLanguageHomepageRoute(config))
+    .get('/:lang/*', handleLanguagePageRoute(config))
+}
+
+/**
+ * Setup dynamic page routes
+ *
+ * Catches all other routes and attempts to render them as pages
+ *
+ * @param honoApp - Hono application instance
+ * @param config - Route configuration
+ * @returns Hono app with dynamic page routes configured
+ */
+export function setupDynamicPageRoutes(
+  honoApp: Readonly<Hono>,
+  config: HonoAppConfig
+): Readonly<Hono> {
+  const { app, renderPage, renderNotFoundPage } = config
+
+  return honoApp.get('*', (c) => {
+    const { path } = c.req
+    const detectedLanguage = detectLanguageIfEnabled(app, c.req.header('Accept-Language'))
+    const html = renderPage(app, path, detectedLanguage)
+    if (!html) {
+      return c.html(renderNotFoundPage(app, detectedLanguage), 404)
+    }
+    return c.html(html)
+  })
+}
+
+/**
+ * Setup test error route
+ *
+ * Only available in non-production environments
+ *
+ * @param honoApp - Hono application instance
+ * @param config - Route configuration
+ * @returns Hono app with test error route configured
+ */
+export function setupTestErrorRoute(
+  honoApp: Readonly<Hono>,
+  config: HonoAppConfig
+): Readonly<Hono> {
+  const { app, renderNotFoundPage } = config
+
+  return honoApp.get('/test/error', (c) => {
+    if (process.env.NODE_ENV === 'production') {
+      const detectedLanguage = detectLanguageIfEnabled(app, c.req.header('Accept-Language'))
+      return c.html(renderNotFoundPage(app, detectedLanguage), 404)
+    }
+    // eslint-disable-next-line functional/no-throw-statements
+    throw new Error('Test error')
+  })
+}
+
+/**
+ * Setup page routes (homepage, language subdirectories, dynamic pages)
+ *
+ * Mounts all page-related routes in correct order
+ *
+ * @param honoApp - Hono application instance
+ * @param config - Route configuration
+ * @returns Hono app with all page routes configured
+ */
+export function setupPageRoutes(honoApp: Readonly<Hono>, config: HonoAppConfig): Readonly<Hono> {
+  return setupDynamicPageRoutes(
+    setupLanguageRoutes(setupTestErrorRoute(setupHomepageRoute(honoApp, config), config), config),
+    config
+  )
+}

package/src/infrastructure/server/route-setup/static-assets.ts

@@ -0,0 +1,191 @@
+/**
+ * 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 } from 'effect'
+import { type Context, type Hono } from 'hono'
+import { generateTrackingScript } from '@/infrastructure/analytics/tracking-script'
+import { compileCSS } from '@/infrastructure/css/compiler'
+import type { App } from '@/domain/models/app'
+
+/**
+ * Cache duration for static assets (CSS, JS) in seconds (1 hour)
+ */
+const STATIC_ASSET_CACHE_DURATION_SECONDS = 3600
+
+/**
+ * Setup CSS compilation route
+ *
+ * Serves dynamically compiled CSS with theme tokens at /assets/output.css
+ *
+ * @param honoApp - Hono application instance
+ * @param app - Application configuration
+ * @returns Hono app with CSS route configured
+ */
+export function setupCSSRoute(honoApp: Readonly<Hono>, app: App): Readonly<Hono> {
+  return honoApp.get('/assets/output.css', async (c) => {
+    try {
+      const result = await Effect.runPromise(
+        compileCSS(app).pipe(Effect.tap(() => Console.log('CSS compiled successfully')))
+      )
+
+      return c.text(result.css, 200, {
+        'Content-Type': 'text/css',
+        'Cache-Control': `public, max-age=${STATIC_ASSET_CACHE_DURATION_SECONDS}`,
+      })
+    } catch (error) {
+      // Log error - intentional side effect for error tracking
+      // eslint-disable-next-line functional/no-expression-statements
+      await Effect.runPromise(Console.error('CSS compilation failed:', error))
+      return c.text('/* CSS compilation failed */', 500, {
+        'Content-Type': 'text/css',
+      })
+    }
+  })
+}
+
+/**
+ * Create handler for serving JavaScript file
+ *
+ * @param scriptName - Display name for error logging
+ * @param scriptPath - File path to JavaScript file
+ * @returns Hono route handler function
+ */
+export function createJavaScriptHandler(scriptName: string, scriptPath: string) {
+  return async (c: Readonly<Context>) => {
+    try {
+      const file = Bun.file(scriptPath)
+      const content = await file.text()
+
+      return c.text(content, 200, {
+        'Content-Type': 'application/javascript',
+        'Cache-Control': `public, max-age=${STATIC_ASSET_CACHE_DURATION_SECONDS}`,
+      })
+    } catch (error) {
+      // eslint-disable-next-line functional/no-expression-statements
+      await Effect.runPromise(Console.error(`Failed to load ${scriptName}:`, error))
+      return c.text(`/* ${scriptName} failed to load */`, 500, {
+        'Content-Type': 'application/javascript',
+      })
+    }
+  }
+}
+
+/**
+ * Setup built-in analytics tracking script route
+ *
+ * Serves dynamically generated analytics tracking script at /assets/analytics.js
+ * Template variables are replaced at serve time with app-specific values.
+ * Only serves the script when built-in analytics is enabled.
+ *
+ * @param honoApp - Hono application instance
+ * @param app - Application configuration
+ * @returns Hono app with analytics script route configured
+ */
+export function setupAnalyticsScriptRoute(honoApp: Readonly<Hono>, app: App): Readonly<Hono> {
+  const analyticsEnabled = app.analytics !== undefined && app.analytics !== false
+
+  if (!analyticsEnabled) return honoApp
+
+  const respectDoNotTrack =
+    typeof app.analytics === 'object' ? app.analytics.respectDoNotTrack !== false : true
+  const scriptContent = generateTrackingScript(
+    '/api/analytics/collect',
+    app.name,
+    respectDoNotTrack
+  )
+
+  return honoApp.get('/assets/analytics.js', (c) => {
+    return c.text(scriptContent, 200, {
+      'Content-Type': 'application/javascript',
+      'Cache-Control': `public, max-age=${STATIC_ASSET_CACHE_DURATION_SECONDS}`,
+    })
+  })
+}
+
+/**
+ * Setup JavaScript asset routes
+ *
+ * Serves client-side JavaScript files at /assets/*.js
+ *
+ * @param honoApp - Hono application instance
+ * @returns Hono app with JavaScript routes configured
+ */
+export function setupJavaScriptRoutes(honoApp: Readonly<Hono>): Readonly<Hono> {
+  return honoApp
+    .get(
+      '/assets/language-switcher.js',
+      createJavaScriptHandler(
+        'language-switcher.js',
+        './src/presentation/scripts/client/language-switcher.js'
+      )
+    )
+    .get(
+      '/assets/banner-dismiss.js',
+      createJavaScriptHandler(
+        'banner-dismiss.js',
+        './src/presentation/scripts/client/banner-dismiss.js'
+      )
+    )
+    .get(
+      '/assets/scroll-animation.js',
+      createJavaScriptHandler(
+        'scroll-animation.js',
+        './src/presentation/scripts/client/scroll-animation.js'
+      )
+    )
+}
+
+/**
+ * Setup public directory file serving for development
+ *
+ * Serves files from a local directory at their relative path.
+ * e.g., `publicDir/logos/escp.png` is served at `/logos/escp.png`
+ *
+ * @param honoApp - Hono application instance
+ * @param publicDir - Directory path to serve files from
+ * @returns Hono app with public dir route configured
+ */
+export function setupPublicDirRoute(honoApp: Readonly<Hono>, publicDir: string): Readonly<Hono> {
+  return honoApp.get('/*', async (c, next) => {
+    const { path } = c.req
+    const filePath = `${publicDir}${path}`
+    const file = Bun.file(filePath)
+
+    if (await file.exists()) {
+      return new Response(file, {
+        headers: {
+          'Cache-Control': `public, max-age=${STATIC_ASSET_CACHE_DURATION_SECONDS}`,
+        },
+      })
+    }
+
+    // eslint-disable-next-line functional/no-expression-statements
+    await next()
+  })
+}
+
+/**
+ * Setup static asset routes (CSS, JavaScript, and optional public directory)
+ *
+ * Mounts CSS, JavaScript, and optionally public directory asset routes
+ *
+ * @param honoApp - Hono application instance
+ * @param app - Application configuration
+ * @param publicDir - Optional directory to serve static files from
+ * @returns Hono app with static asset routes configured
+ */
+export function setupStaticAssets(
+  honoApp: Readonly<Hono>,
+  app: App,
+  publicDir?: string
+): Readonly<Hono> {
+  const withAssets = setupAnalyticsScriptRoute(
+    setupJavaScriptRoutes(setupCSSRoute(honoApp, app)),
+    app
+  )
+  return publicDir ? setupPublicDirRoute(withAssets, publicDir) : withAssets
+}

package/src/infrastructure/server/server-factory-live.ts

@@ -0,0 +1,45 @@
+/**
+ * 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, Layer } from 'effect'
+import { ServerFactory } from '@/application/ports/services/server-factory'
+import { createServer } from './server'
+
+/**
+ * Live implementation of ServerFactory using Bun.serve
+ *
+ * This Layer provides the production server creation logic,
+ * wrapping the infrastructure createServer function in an
+ * Effect Context service.
+ *
+ * The implementation uses Layer.effect because createServer
+ * returns an Effect (async operations with error handling).
+ *
+ * @example
+ * ```typescript
+ * // Provide ServerFactoryLive to use cases
+ * const program = startServer(appConfig).pipe(
+ *   Effect.provide(ServerFactoryLive)
+ * )
+ * ```
+ */
+export const ServerFactoryLive = Layer.effect(
+  ServerFactory,
+  Effect.sync(() => ({
+    create: (config) =>
+      createServer({
+        app: config.app,
+        port: config.port,
+        hostname: config.hostname,
+        publicDir: config.publicDir,
+        renderHomePage: config.renderHomePage,
+        renderPage: config.renderPage,
+        renderNotFoundPage: config.renderNotFoundPage,
+        renderErrorPage: config.renderErrorPage,
+      }),
+  }))
+)