sovrium 0.0.2

package/src/domain/utils/translation-resolver.ts

@@ -0,0 +1,170 @@
+/**
+ * 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 type { Languages } from '@/domain/models/app/languages'
+
+/**
+ * Normalize language code to match translation keys
+ *
+ * Tries exact match first, then falls back to base language code (e.g., 'fr-FR' → 'fr')
+ *
+ * @param lang - Language code (e.g., 'fr-FR', 'en-US', 'fr')
+ * @param translations - Available translations object
+ * @returns Matching translation key or original language code
+ *
+ * @example
+ * ```typescript
+ * normalizeLanguageCode('fr-FR', { fr: {...}, en: {...} }) // 'fr'
+ * normalizeLanguageCode('fr', { fr: {...}, en: {...} })    // 'fr'
+ * normalizeLanguageCode('en-US', { 'en-US': {...} })       // 'en-US'
+ * ```
+ */
+export function normalizeLanguageCode(
+  lang: string,
+  translations: Record<string, Record<string, string>>
+): string {
+  // Try exact match first
+  if (translations[lang]) {
+    return lang
+  }
+
+  // Try base language code (e.g., 'fr-FR' → 'fr')
+  const baseLang = lang.split('-')[0]
+  if (baseLang && translations[baseLang]) {
+    return baseLang
+  }
+
+  // No match found - return original
+  return lang
+}
+
+/**
+ * Resolve translation key with fallback support
+ *
+ * Implements the $t:key pattern for centralized translations.
+ * When a translation is missing in the current language, falls back to the fallback language.
+ *
+ * @param key - Translation key (e.g., 'welcome', 'common.save')
+ * @param currentLang - Current language code (e.g., 'fr-FR')
+ * @param languages - Languages configuration from app schema
+ * @returns Translated string or key if not found
+ *
+ * @example
+ * ```typescript
+ * const text = resolveTranslation('welcome', 'fr-FR', languages)
+ * // Returns: 'Bienvenue' if exists in fr-FR
+ * // Returns: 'Welcome' if missing in fr-FR but exists in fallback en-US
+ * // Returns: 'welcome' if not found in any language
+ * ```
+ */
+export function resolveTranslation(
+  key: string,
+  currentLang: string,
+  languages?: Languages
+): string {
+  // No translations configured - return key as-is
+  if (!languages?.translations) {
+    return key
+  }
+
+  const { translations, fallback } = languages
+
+  // Normalize language code to match translation keys (e.g., 'fr-FR' → 'fr')
+  const normalizedLang = normalizeLanguageCode(currentLang, translations)
+
+  // Try current language first
+  const currentTranslations = translations[normalizedLang]
+  if (currentTranslations?.[key]) {
+    return currentTranslations[key]
+  }
+
+  // Try fallback language (defaults to default language)
+  const fallbackLang = fallback || languages.default
+  if (fallbackLang !== normalizedLang) {
+    const normalizedFallback = normalizeLanguageCode(fallbackLang, translations)
+    const fallbackTranslations = translations[normalizedFallback]
+    if (fallbackTranslations?.[key]) {
+      return fallbackTranslations[key]
+    }
+  }
+
+  // Translation not found - return key
+  return key
+}
+
+/**
+ * Resolve $t:key pattern in a string
+ *
+ * Processes strings containing $t:key syntax and replaces them with translations.
+ * Supports fallback when translation is missing.
+ *
+ * @param text - String that may contain $t:key patterns
+ * @param currentLang - Current language code
+ * @param languages - Languages configuration from app schema
+ * @returns String with resolved translations
+ *
+ * @example
+ * ```typescript
+ * resolveTranslationPattern('$t:welcome', 'fr-FR', languages) // 'Bienvenue'
+ * resolveTranslationPattern('$t:goodbye', 'fr-FR', languages) // 'Goodbye' (fallback)
+ * resolveTranslationPattern('Hello world', 'fr-FR', languages) // 'Hello world' (no pattern)
+ * ```
+ */
+export function resolveTranslationPattern(
+  text: string,
+  currentLang: string,
+  languages?: Languages
+): string {
+  // Check if text starts with $t: pattern
+  if (text.startsWith('$t:')) {
+    const key = text.slice(3) // Remove '$t:' prefix
+    return resolveTranslation(key, currentLang, languages)
+  }
+
+  // No pattern found - return text as-is
+  return text
+}
+
+/**
+ * Collect all available translations for a key across all languages
+ *
+ * Used for pre-resolving translations on the server side, allowing client-side
+ * code to simply lookup translations without re-implementing fallback logic.
+ *
+ * @param key - Translation key (e.g., 'welcome', 'common.save')
+ * @param languages - Languages configuration from app schema
+ * @returns Object mapping language codes to translated strings, or undefined if no translations
+ *
+ * @example
+ * ```typescript
+ * collectTranslationsForKey('welcome', languages)
+ * // Returns: { 'en-US': 'Welcome', 'fr-FR': 'Bienvenue', 'es-ES': 'Bienvenido' }
+ * ```
+ */
+export function collectTranslationsForKey(
+  key: string,
+  languages?: Languages
+): Record<string, string> | undefined {
+  if (!languages?.translations) {
+    return undefined
+  }
+
+  // Collect translation for this key from all available languages (functional approach)
+  const result = Object.entries(languages.translations).reduce(
+    (acc, [lang, translations]) => {
+      const translationDict = translations as Record<string, string>
+      if (translationDict[key]) {
+        return { ...acc, [lang]: translationDict[key] }
+      }
+      return acc
+    },
+    {} as Record<string, string>
+  )
+
+  // Return undefined if no translations found (key doesn't exist in any language)
+  return Object.keys(result).length > 0 ? result : undefined
+}

package/src/index.ts

@@ -0,0 +1,208 @@
+/**
+ * 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.
+ */
+
+/**
+ * Sovrium - A Bun web framework with React SSR and Tailwind CSS
+ *
+ * This is the main entry point for Sovrium applications. It provides a simple
+ * Promise-based API for starting a web server with automatic:
+ * - React 19 server-side rendering
+ * - Tailwind CSS compilation (no build step)
+ * - Type-safe configuration validation
+ * - Graceful shutdown handling
+ */
+
+import { Console, Effect, Schema } from 'effect'
+import { generateStatic as generateStaticUseCase } from '@/application/use-cases/server/generate-static'
+import { startServer } from '@/application/use-cases/server/start-server'
+import { AppSchema } from '@/domain/models/app'
+import { createAppLayer } from '@/infrastructure/layers/app-layer'
+import { withGracefulShutdown } from '@/infrastructure/server/lifecycle'
+import type { ServerInstance } from '@/application/models/server'
+import type {
+  GenerateStaticOptions,
+  GenerateStaticResult,
+} from '@/application/use-cases/server/generate-static'
+import type { StartOptions } from '@/application/use-cases/server/start-server'
+import type { App, AppEncoded } from '@/domain/models/app'
+
+/**
+ * Simple server interface with Promise-based methods
+ */
+export interface SimpleServer {
+  /**
+   * Server URL (e.g., "http://localhost:3000")
+   */
+  readonly url: string
+
+  /**
+   * Stop the server gracefully
+   * @returns Promise that resolves when server is stopped
+   */
+  stop: () => Promise<void>
+}
+
+/**
+ * Convert Effect-based ServerInstance to simple Promise-based interface
+ */
+const toSimpleServer = (server: Readonly<ServerInstance>): SimpleServer => ({
+  url: server.url,
+  stop: () => Effect.runPromise(server.stop),
+})
+
+/**
+ * Start an Sovrium server with automatic logging and graceful shutdown
+ *
+ * This is the main entry point for Sovrium applications. It:
+ * 1. Validates the app configuration using Effect Schema
+ * 2. Compiles Tailwind CSS dynamically using PostCSS
+ * 3. Creates a Hono web server with React SSR
+ * 4. Serves the homepage at "/" and compiled CSS at "/assets/output.css"
+ * 5. Sets up graceful shutdown handlers (SIGINT, SIGTERM)
+ * 6. Returns a simple server interface with url and stop method
+ *
+ * @param app - Application configuration with name and description
+ * @param options - Optional server configuration (port, hostname)
+ * @returns Promise that resolves to a simple server interface
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * import { start } from 'sovrium'
+ *
+ * const myApp = {
+ *   name: 'My App',
+ *   description: 'A simple Bun application'
+ * }
+ *
+ * // Start with default port (3000) and hostname ('localhost')
+ * const server = await start(myApp)
+ * console.log(`Server running at ${server.url}`)
+ * // Server stays alive until Ctrl+C
+ * ```
+ *
+ * @example
+ * With custom configuration:
+ * ```typescript
+ * const server = await start(myApp, {
+ *   port: 8080,
+ *   hostname: '0.0.0.0'
+ * })
+ * ```
+ *
+ * @example
+ * With error handling:
+ * ```typescript
+ * start(myApp).catch((error) => {
+ *   console.error('Failed to start server:', error)
+ *   process.exit(1)
+ * })
+ * ```
+ */
+export const start = async (app: AppEncoded, options: StartOptions = {}): Promise<SimpleServer> => {
+  // Parse app configuration once to extract auth config
+  const validatedApp: App = Schema.decodeUnknownSync(AppSchema)(app)
+
+  const program = Effect.gen(function* () {
+    yield* Console.log('Starting Sovrium server...')
+
+    // Start the server (dependencies injected via AppLayer with auth config)
+    const server = yield* startServer(app, options)
+
+    // Setup graceful shutdown in background (forked so it doesn't block)
+    yield* Effect.fork(withGracefulShutdown(server))
+
+    // Return the server instance immediately (don't wait for shutdown)
+    return server
+  }).pipe(
+    // Provide dependencies (ServerFactory + PageRenderer + Auth with app-specific config)
+    Effect.provide(createAppLayer(validatedApp.auth))
+  )
+
+  // Run the Effect program and convert to simple server interface
+  const server = await Effect.runPromise(program)
+  return toSimpleServer(server)
+}
+
+/**
+ * Build static site files from a Sovrium application
+ *
+ * This function generates static HTML files and supporting assets that can be
+ * deployed to any static hosting provider (GitHub Pages, Netlify, Vercel, etc.).
+ *
+ * @param app - Application configuration with pages, theme, etc.
+ * @param options - Optional static generation configuration
+ * @returns Promise that resolves to generation result with output directory and file list
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * import { build } from 'sovrium'
+ *
+ * const myApp = {
+ *   name: 'My App',
+ *   pages: [
+ *     {
+ *       name: 'home',
+ *       path: '/',
+ *       meta: { title: 'Home' },
+ *       sections: []
+ *     }
+ *   ]
+ * }
+ *
+ * const result = await build(myApp)
+ * console.log(`Generated ${result.files.length} files to ${result.outputDir}`)
+ * ```
+ *
+ * @example
+ * With options:
+ * ```typescript
+ * const result = await build(myApp, {
+ *   outputDir: './dist',
+ *   baseUrl: 'https://example.com',
+ *   generateSitemap: true,
+ *   generateRobotsTxt: true,
+ *   deployment: 'github-pages'
+ * })
+ * ```
+ */
+export const build = async (
+  app: AppEncoded,
+  options: GenerateStaticOptions = {}
+): Promise<GenerateStaticResult> => {
+  // Parse app configuration once to extract auth config
+  const validatedApp: App = Schema.decodeUnknownSync(AppSchema)(app)
+
+  const program = Effect.gen(function* () {
+    yield* Console.log('Generating static site...')
+
+    // Generate static site (dependencies injected via AppLayer)
+    const result = yield* generateStaticUseCase(app, options)
+
+    yield* Console.log(`✅ Static site generated to ${result.outputDir}`)
+    yield* Console.log(`   Generated ${result.files.length} files`)
+
+    return result
+  }).pipe(
+    // Provide dependencies (ServerFactory + PageRenderer + Auth with app-specific config)
+    Effect.provide(createAppLayer(validatedApp.auth))
+  )
+
+  // Run the Effect program and return the result
+  return await Effect.runPromise(program)
+}
+
+/**
+ * Re-export types for convenience
+ */
+export type { StartOptions, GenerateStaticOptions, GenerateStaticResult }
+export type { App, AppEncoded } from '@/domain/models/app'
+export { AppSchema } from '@/domain/models/app'
+export type { Page, PageEncoded } from '@/domain/models/app/pages'
+export { PageSchema } from '@/domain/models/app/pages'
+export type { ComponentTemplate } from '@/domain/models/app/component/component'

package/src/infrastructure/analytics/tracking-script.ts

@@ -0,0 +1,48 @@
+/**
+ * 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.
+ */
+
+/**
+ * Minimal first-party analytics tracking script (~1KB minified)
+ *
+ * Features:
+ * - Sends page path, title, referrer, screen size via navigator.sendBeacon
+ * - Extracts UTM params from URL on load
+ * - Listens for history.pushState / popstate for SPA navigation
+ * - Respects navigator.doNotTrack if configured
+ * - No cookies, no external dependencies
+ *
+ * Template variables replaced at serve time:
+ * - __ENDPOINT__ — collection API URL (e.g., /api/analytics/collect)
+ * - __APP_NAME__ — application name for multi-tenant support
+ * - __RESPECT_DNT__ — whether to respect Do Not Track header ("true" or "false")
+ */
+export function generateTrackingScript(
+  endpoint: string,
+  appName: string,
+  respectDoNotTrack: boolean
+): string {
+  return `(function(){
+"use strict";
+var E="${endpoint}",A="${appName}",D=${respectDoNotTrack ? 'true' : 'false'};
+if(D&&navigator.doNotTrack==="1")return;
+var u=function(){
+try{var s=new URLSearchParams(location.search);
+var d={p:location.pathname,t:document.title,r:document.referrer||void 0,
+sw:screen.width,sh:screen.height,
+us:s.get("utm_source")||void 0,um:s.get("utm_medium")||void 0,
+uc:s.get("utm_campaign")||void 0,ux:s.get("utm_content")||void 0,
+ut:s.get("utm_term")||void 0};
+var b=JSON.stringify(d);
+if(navigator.sendBeacon){navigator.sendBeacon(E,new Blob([b],{type:"application/json"}))}
+else{var x=new XMLHttpRequest();x.open("POST",E,true);x.setRequestHeader("Content-Type","application/json");x.send(b)}
+}catch(e){}};
+u();
+var op=history.pushState;
+history.pushState=function(){op.apply(this,arguments);u()};
+window.addEventListener("popstate",u);
+})();`
+}

package/src/infrastructure/auth/better-auth/auth.ts

@@ -0,0 +1,216 @@
+/**
+ * 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 { betterAuth } from 'better-auth'
+import { drizzleAdapter } from 'better-auth/adapters/drizzle'
+import { createAuthMiddleware, APIError } from 'better-auth/api'
+import { openAPI } from 'better-auth/plugins'
+import { getStrategy, hasStrategy } from '@/domain/models/app/auth'
+import { db } from '@/infrastructure/database'
+import { createEmailHandlers } from './email-handlers'
+import { buildAdminPlugin } from './plugins/admin'
+import { buildMagicLinkPlugin } from './plugins/magic-link'
+import { buildTwoFactorPlugin } from './plugins/two-factor'
+import { users, sessions, accounts, verifications, twoFactors } from './schema'
+import type { Auth } from '@/domain/models/app/auth'
+
+/**
+ * Build socialProviders configuration from auth config
+ *
+ * Maps enabled OAuth providers to Better Auth socialProviders configuration.
+ * Credentials are loaded from environment variables using the pattern:
+ * - {PROVIDER}_CLIENT_ID (e.g., GOOGLE_CLIENT_ID)
+ * - {PROVIDER}_CLIENT_SECRET (e.g., GOOGLE_CLIENT_SECRET)
+ */
+export const buildSocialProviders = (authConfig?: Auth) => {
+  const oauthStrategy = getStrategy(authConfig, 'oauth')
+  if (!oauthStrategy?.providers) return {}
+
+  return oauthStrategy.providers.reduce(
+    (providers, provider) => {
+      const envVarPrefix = provider.toUpperCase()
+      return {
+        ...providers,
+        [provider]: {
+          clientId: process.env[`${envVarPrefix}_CLIENT_ID`] || '',
+          clientSecret: process.env[`${envVarPrefix}_CLIENT_SECRET`] || '',
+        },
+      }
+    },
+    {} as Record<string, { clientId: string; clientSecret: string }>
+  )
+}
+
+/**
+ * Schema mapping for Better Auth's drizzle adapter
+ *
+ * IMPORTANT: The keys MUST be Better Auth's internal model names (user, account, session, etc.)
+ * NOT the custom table names. The actual database table name is determined by the Drizzle
+ * table definition (e.g., pgTable('_sovrium_auth_users', ...)).
+ *
+ * This is a critical fix for GitHub issue #5879 - using table names as keys causes
+ * the adapter to return wrong records, breaking account linking.
+ *
+ * See: https://github.com/better-auth/better-auth/issues/5879
+ */
+const drizzleSchema = {
+  user: users,
+  session: sessions,
+  account: accounts,
+  verification: verifications,
+  twoFactor: twoFactors,
+}
+
+/**
+ * Build Better Auth plugins array with custom table names
+ *
+ * Conditionally includes plugins when enabled in auth configuration.
+ * If a plugin is not enabled, its endpoints will not be available (404).
+ */
+export const buildAuthPlugins = (
+  handlers: Readonly<ReturnType<typeof createEmailHandlers>>,
+  authConfig?: Auth
+) => [
+  openAPI({ disableDefaultReference: true }),
+  ...buildAdminPlugin(authConfig),
+  ...buildTwoFactorPlugin(authConfig),
+  ...buildMagicLinkPlugin(handlers.magicLink, authConfig),
+]
+
+/**
+ * Build rate limiting configuration for Better Auth
+ *
+ * NOTE: Better Auth's native rate limiting has known issues with customRules not working reliably
+ * (see GitHub issues #392, #1891, #2153). As a workaround, Sovrium uses custom Hono middleware
+ * in auth-routes.ts to implement endpoint-specific rate limiting for sign-in, sign-up, and
+ * password-reset endpoints.
+ *
+ * This configuration keeps Better Auth's rate limiting disabled to avoid conflicts with the
+ * custom middleware implementation.
+ */
+export function buildRateLimitConfig() {
+  return {
+    enabled: false, // Disabled in favor of custom Hono middleware
+    window: 60,
+    max: 100,
+  }
+}
+
+/**
+ * Build email and password configuration from auth config
+ */
+export function buildEmailAndPasswordConfig(
+  authConfig: Auth | undefined,
+  handlers: Readonly<ReturnType<typeof createEmailHandlers>>
+) {
+  const strategy = getStrategy(authConfig, 'emailAndPassword')
+  const requireEmailVerification = strategy?.requireEmailVerification ?? false
+
+  return {
+    enabled: hasStrategy(authConfig, 'emailAndPassword'),
+    requireEmailVerification,
+    sendResetPassword: handlers.passwordReset,
+    minPasswordLength: strategy?.minPasswordLength ?? 8,
+    maxPasswordLength: strategy?.maxPasswordLength ?? 128,
+  }
+}
+
+type AuthMiddlewareCtx = Parameters<typeof createAuthMiddleware>[0] extends (
+  ctx: infer C
+) => unknown
+  ? C
+  : never
+
+/**
+ * Validate admin create-user password length (Better Auth Issue #4651 workaround).
+ * The admin plugin doesn't respect emailAndPassword validation settings.
+ */
+// eslint-disable-next-line functional/prefer-immutable-types
+async function validateAdminCreateUserPassword(ctx: AuthMiddlewareCtx) {
+  const body = ctx.body as { password?: string }
+  if (!body?.password) return
+  const minLength = 8
+  const maxLength = 128
+  if (body.password.length < minLength) {
+    // eslint-disable-next-line functional/no-throw-statements
+    throw new APIError('BAD_REQUEST', {
+      message: `Password must be at least ${minLength} characters`,
+    })
+  }
+  if (body.password.length > maxLength) {
+    // eslint-disable-next-line functional/no-throw-statements
+    throw new APIError('BAD_REQUEST', {
+      message: `Password must not exceed ${maxLength} characters`,
+    })
+  }
+}
+
+/**
+ * Build auth hooks with request validation middleware
+ *
+ * Validates password length for admin createUser endpoint (Better Auth Issue #4651 workaround).
+ * The admin plugin doesn't respect emailAndPassword validation settings.
+ *
+ * Note: The /change-email endpoint uses Better Auth 1.5's native email enumeration protection,
+ * which always returns 200 OK regardless of whether the target email exists.
+ */
+export function buildAuthHooks() {
+  return {
+    before: createAuthMiddleware(async (ctx) => {
+      if (ctx.path === '/admin/create-user') {
+        // eslint-disable-next-line functional/no-expression-statements
+        await validateAdminCreateUserPassword(ctx)
+      }
+    }),
+  }
+}
+/**
+ * Create Better Auth instance with dynamic configuration
+ */
+export function createAuthInstance(authConfig?: Auth) {
+  const handlers = createEmailHandlers(authConfig)
+  const emailAndPasswordConfig = buildEmailAndPasswordConfig(authConfig, handlers)
+  const { requireEmailVerification } = emailAndPasswordConfig
+
+  return betterAuth({
+    secret: process.env.AUTH_SECRET,
+    baseURL: process.env.BASE_URL || `http://localhost:${process.env.PORT || 3000}`,
+    database: drizzleAdapter(db, {
+      provider: 'pg',
+      usePlural: false,
+      schema: drizzleSchema,
+    }),
+    // NOTE: modelName options removed - drizzleSchema uses standard model names
+    // and Drizzle pgTable() definitions specify actual database table names
+    trustedOrigins: ['*'],
+    advanced: {
+      useSecureCookies: process.env.NODE_ENV === 'production',
+      disableCSRFCheck: process.env.NODE_ENV !== 'production',
+    },
+    emailAndPassword: emailAndPasswordConfig,
+    emailVerification: {
+      sendOnSignUp: requireEmailVerification,
+      autoSignInAfterVerification: true,
+      sendVerificationEmail: handlers.verification,
+    },
+    user: {
+      changeEmail: { enabled: true, sendChangeEmailVerification: handlers.verification },
+    },
+    socialProviders: buildSocialProviders(authConfig),
+    plugins: buildAuthPlugins(handlers, authConfig),
+    rateLimit: buildRateLimitConfig(),
+    hooks: buildAuthHooks(),
+  })
+}
+
+/**
+ * Default Better Auth instance for OpenAPI schema generation
+ * Uses default configuration (requireEmailVerification: false)
+ *
+ * For app-specific configuration, use createAuthLayer(authConfig) instead.
+ */
+export const auth = createAuthInstance()