sovrium 0.0.2

package/src/application/use-cases/server/start-server.ts

@@ -0,0 +1,118 @@
+/**
+ * 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, Schema } from 'effect'
+import { AppValidationError } from '@/application/errors/app-validation-error'
+import { PageRenderer } from '@/application/ports/services/page-renderer'
+import { ServerFactory } from '@/application/ports/services/server-factory'
+import { bootstrapAdmin } from '@/application/use-cases/auth/bootstrap-admin'
+import { AppSchema } from '@/domain/models/app'
+import { Logger } from '@/infrastructure/logging/logger'
+import type { ServerInstance } from '@/application/models/server'
+import type { AuthRepository } from '@/application/ports/repositories/auth-repository'
+import type { App } from '@/domain/models/app'
+import type { Auth } from '@/infrastructure/auth/better-auth'
+import type { AuthConfigRequiredForUserFields } from '@/infrastructure/errors/auth-config-required-error'
+import type { CSSCompilationError } from '@/infrastructure/errors/css-compilation-error'
+import type { SchemaInitializationError } from '@/infrastructure/errors/schema-initialization-error'
+import type { ServerCreationError } from '@/infrastructure/errors/server-creation-error'
+
+/**
+ * Server configuration options
+ */
+export interface StartOptions {
+  /**
+   * Port number for the HTTP server
+   * @default 3000
+   */
+  readonly port?: number
+
+  /**
+   * Hostname to bind the server to
+   * @default "localhost"
+   */
+  readonly hostname?: string
+
+  /**
+   * Directory to serve static files from during development
+   * Files are served at their relative path (e.g., `publicDir/logos/x.png` → `/logos/x.png`)
+   */
+  readonly publicDir?: string
+}
+
+/**
+ * Use case for starting an Sovrium web server
+ *
+ * This orchestrates the server startup process:
+ * 1. Validates the app configuration using Effect Schema
+ * 2. Obtains rendering and server creation services via Effect Context
+ * 3. Creates and starts the server via injected dependencies
+ * 4. Bootstraps admin account if configured via environment variables
+ *
+ * Dependencies are provided via Effect.provide(AppLayer) at the application boundary.
+ *
+ * @param app - Application configuration
+ * @param options - Server configuration options
+ * @returns Effect that yields ServerInstance or errors
+ *
+ * @example
+ * ```typescript
+ * // In src/index.ts
+ * const program = startServer(appConfig, { port: 3000 }).pipe(
+ *   Effect.provide(AppLayer)
+ * )
+ * ```
+ */
+export const startServer = (
+  app: unknown,
+  options: StartOptions = {}
+): Effect.Effect<
+  ServerInstance,
+  | AppValidationError
+  | ServerCreationError
+  | CSSCompilationError
+  | AuthConfigRequiredForUserFields
+  | SchemaInitializationError
+  | Error,
+  ServerFactory | PageRenderer | Auth | AuthRepository | Logger
+> =>
+  Effect.gen(function* () {
+    // Validate app configuration using domain model schema
+    const validatedApp = yield* Effect.try({
+      try: (): App => Schema.decodeUnknownSync(AppSchema)(app),
+      catch: (error) => new AppValidationError(error),
+    })
+
+    // Obtain dependencies from Effect Context
+    const serverFactory = yield* ServerFactory
+    const pageRenderer = yield* PageRenderer
+
+    // Bootstrap admin account BEFORE starting the server
+    // This ensures admin user exists before server signals "ready"
+    const logger = yield* Logger
+    yield* bootstrapAdmin(validatedApp).pipe(
+      Effect.catchAll((error) =>
+        // Log bootstrap errors but don't fail server startup
+        logger.warn('Admin bootstrap error', error.message)
+      )
+    )
+
+    // Create server using injected dependencies
+    // Server only starts listening after bootstrap completes
+    const serverInstance = yield* serverFactory.create({
+      app: validatedApp,
+      port: options.port,
+      hostname: options.hostname,
+      publicDir: options.publicDir,
+      renderHomePage: pageRenderer.renderHome,
+      renderPage: pageRenderer.renderPage,
+      renderNotFoundPage: pageRenderer.renderNotFound,
+      renderErrorPage: pageRenderer.renderError,
+    })
+
+    return serverInstance
+  })

package/src/application/use-cases/server/startup-error-handler.ts

@@ -0,0 +1,69 @@
+/**
+ * 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, Console } from 'effect'
+import type { AppValidationError } from '@/application/errors/app-validation-error'
+import type { CSSCompilationError } from '@/infrastructure/errors/css-compilation-error'
+import type { ServerCreationError } from '@/infrastructure/errors/server-creation-error'
+
+/**
+ * Error types that can occur during server startup
+ */
+export type ServerStartupError = AppValidationError | ServerCreationError | CSSCompilationError
+
+/**
+ * Handles server startup errors and logs appropriate messages
+ *
+ * This utility provides comprehensive error handling for all error types
+ * that can occur during server startup, including:
+ * - App validation errors (invalid configuration)
+ * - Server creation errors (port already in use, etc.)
+ * - CSS compilation errors (Tailwind/PostCSS issues)
+ *
+ * @param error - Error that occurred during server startup
+ * @returns Effect that logs error details and exits with code 1
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { start } from '@/index'
+ * import { handleStartupError } from '@/application/use-cases/server/startup-error-handler'
+ *
+ * const program = start(myApp).pipe(
+ *   Effect.catchAll(handleStartupError)
+ * )
+ *
+ * Effect.runPromise(program)
+ * ```
+ */
+export const handleStartupError = (error: ServerStartupError): Effect.Effect<never> =>
+  Effect.gen(function* () {
+    yield* Console.error('Failed to start server:')
+
+    // Handle specific error types
+    if ('_tag' in error) {
+      switch (error._tag) {
+        case 'AppValidationError':
+          yield* Console.error('Invalid app configuration:', error.cause)
+          break
+        case 'ServerCreationError':
+          yield* Console.error('Server creation failed:', error.cause)
+          break
+        case 'CSSCompilationError':
+          yield* Console.error('CSS compilation failed:', error.cause)
+          break
+        default:
+          yield* Console.error('Unknown error:', error)
+      }
+    } else {
+      yield* Console.error('Unknown error:', error)
+    }
+
+    // Exit process with error code
+    // eslint-disable-next-line functional/no-expression-statements
+    process.exit(1)
+  })

package/src/application/use-cases/server/static-content-generators.ts

@@ -0,0 +1,182 @@
+/**
+ * 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 { Page } from '@/domain/models/app'
+
+/**
+ * Hreflang configuration for multilingual sitemaps
+ */
+export interface HreflangConfig {
+  /** Maps language codes to full locales (e.g., { en: 'en-US', fr: 'fr-FR' }) */
+  readonly localeMap: Readonly<Record<string, string>>
+  /** Default language code for x-default hreflang (e.g., 'en') */
+  readonly defaultLanguage: string
+}
+
+/**
+ * Format HTML with Prettier for professional formatting
+ * Loads Prettier config and formats HTML using the HTML parser
+ */
+export const formatHtmlWithPrettier = async (html: string): Promise<string> => {
+  const prettier = await import('prettier')
+  const config = await prettier.resolveConfig(process.cwd())
+
+  return await prettier.format(html, {
+    ...config,
+    parser: 'html',
+  })
+}
+
+/**
+ * Build the full URL for a page in a specific language
+ */
+const buildLanguageUrl = (baseUrl: string, lang: string, pagePath: string): string => {
+  const normalizedPath = pagePath === '/' ? '' : pagePath
+  return `${baseUrl}/${lang}${normalizedPath}${normalizedPath === '' ? '/' : ''}`
+}
+
+/**
+ * Generate hreflang <xhtml:link> elements for a single URL entry
+ */
+export const generateHreflangLinks = (
+  baseUrl: string,
+  pagePath: string,
+  languages: readonly string[],
+  hreflangConfig: HreflangConfig
+): readonly string[] => {
+  const languageLinks = languages.map((lang) => {
+    const locale = hreflangConfig.localeMap[lang] ?? lang
+    const url = buildLanguageUrl(baseUrl, lang, pagePath)
+    return `<xhtml:link rel="alternate" hreflang="${locale}" href="${url}" />`
+  })
+
+  const defaultUrl = buildLanguageUrl(baseUrl, hreflangConfig.defaultLanguage, pagePath)
+  const xDefaultLink = `<xhtml:link rel="alternate" hreflang="x-default" href="${defaultUrl}" />`
+
+  return [...languageLinks, xDefaultLink]
+}
+
+/**
+ * Build a single <url> entry for the sitemap
+ */
+const buildUrlEntry = (
+  loc: string,
+  lastmod: string,
+  page: Page,
+  hreflangSection: string
+): string => {
+  const priority = page.meta?.priority ?? 0.5
+  const changefreq = page.meta?.changefreq ?? 'monthly'
+  return `  <url>
+    <loc>${loc}</loc>${hreflangSection}
+    <lastmod>${lastmod}</lastmod>
+    <priority>${priority.toFixed(1)}</priority>
+    <changefreq>${changefreq}</changefreq>
+  </url>`
+}
+
+/**
+ * Generate sitemap.xml content
+ */
+export const generateSitemapContent = (
+  pages: readonly Page[],
+  baseUrl: string,
+  _basePath: string = '',
+  options?: { readonly languages?: readonly string[]; readonly hreflangConfig?: HreflangConfig }
+): string => {
+  const indexablePages = pages.filter((page) => !page.meta?.noindex && !page.path.startsWith('/_'))
+  const lastmod = new Date().toISOString().split('T')[0] ?? ''
+  const languages = options?.languages
+  const hreflangConfig = options?.hreflangConfig
+  const hasHreflang = languages && languages.length > 0 && hreflangConfig !== undefined
+
+  const entries: readonly string[] =
+    languages && languages.length > 0
+      ? languages.flatMap((lang) =>
+          indexablePages.map((page) => {
+            const hreflangLinks = hasHreflang
+              ? generateHreflangLinks(baseUrl, page.path, languages, hreflangConfig).map(
+                  (link) => `    ${link}`
+                )
+              : []
+            const hreflangSection = hreflangLinks.length > 0 ? `\n${hreflangLinks.join('\n')}` : ''
+            return buildUrlEntry(
+              buildLanguageUrl(baseUrl, lang, page.path),
+              lastmod,
+              page,
+              hreflangSection
+            )
+          })
+        )
+      : indexablePages.map((page) => buildUrlEntry(`${baseUrl}${page.path}`, lastmod, page, ''))
+
+  const xmlnsAttr = hasHreflang
+    ? ' xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"\n        xmlns:xhtml="http://www.w3.org/1999/xhtml"'
+    : ' xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"'
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset${xmlnsAttr}>
+${entries.join('\n')}
+</urlset>`
+}
+
+/**
+ * Generate robots.txt content
+ */
+export const generateRobotsContent = (
+  pages: readonly Page[],
+  baseUrl: string,
+  _basePath: string = '',
+  includeSitemap: boolean = false
+): string => {
+  const baseLines = ['User-agent: *', 'Allow: /']
+
+  // Add Disallow rules for:
+  // 1. Pages with noindex or robots directives containing "noindex"
+  // 2. Underscore-prefixed pages (admin/internal pages)
+  const disallowedPages = pages.filter(
+    (page) =>
+      page.meta?.noindex === true ||
+      (page.meta?.robots && page.meta.robots.includes('noindex')) ||
+      page.path.startsWith('/_')
+  )
+
+  const disallowLines = disallowedPages.map((page) => `Disallow: ${page.path}`)
+
+  const sitemapLine = includeSitemap ? [`Sitemap: ${baseUrl}/sitemap.xml`] : []
+  const lines = [...baseLines, ...disallowLines, ...sitemapLine]
+
+  return lines.join('\n')
+}
+
+/**
+ * Generate client-side hydration script
+ *
+ * This minimal script enables React hydration on the client side.
+ * For production, this would:
+ * - Load React runtime
+ * - Re-render components with client-side state
+ * - Attach event listeners
+ * - Enable interactive features
+ *
+ * Current implementation: Minimal placeholder for testing
+ */
+export const generateClientHydrationScript = (): string => {
+  return `/**
+ * Sovrium Client-Side Hydration Script
+ * Generated by Sovrium Static Site Generator
+ */
+
+// Minimal hydration script for static sites
+// This enables client-side interactivity after initial SSR
+console.log('Sovrium: Client-side hydration enabled')
+
+// Future: Load React runtime and hydrate components
+// Future: Initialize client-side routing
+// Future: Restore interactive state
+`
+}

package/src/application/use-cases/server/static-language-generators.ts

@@ -0,0 +1,181 @@
+/**
+ * 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.
+ */
+
+/* eslint-disable max-params, max-lines-per-function -- Complex multi-language generators require explicit dependencies */
+
+import { Effect, Console, Schema, type Context } from 'effect'
+import { AppValidationError } from '@/application/errors/app-validation-error'
+import { AppSchema } from '@/domain/models/app'
+import type { CSSCompilationError } from '@/application/ports/services/css-compiler'
+import type { PageRenderer as PageRendererService } from '@/application/ports/services/page-renderer'
+import type { ServerFactory as ServerFactoryService } from '@/application/ports/services/server-factory'
+import type {
+  SSGGenerationError,
+  StaticSiteGenerator as StaticSiteGeneratorService,
+} from '@/application/ports/services/static-site-generator'
+import type { App } from '@/domain/models/app'
+import type { AuthConfigRequiredForUserFields } from '@/infrastructure/errors/auth-config-required-error'
+import type { SchemaInitializationError } from '@/infrastructure/errors/schema-initialization-error'
+import type { ServerCreationError } from '@/infrastructure/errors/server-creation-error'
+
+// Service types extracted from Context.Tag
+type ServerFactory = Context.Tag.Service<ServerFactoryService>
+type PageRenderer = Context.Tag.Service<PageRendererService>
+type StaticSiteGenerator = Context.Tag.Service<StaticSiteGeneratorService>
+
+/**
+ * Generate static files for multi-language configuration
+ */
+export const generateMultiLanguageFiles = (
+  validatedApp: App,
+  outputDir: string,
+  replaceAppTokens: (app: App, lang: string) => App,
+  serverFactory: ServerFactory,
+  pageRenderer: PageRenderer,
+  staticSiteGenerator: StaticSiteGenerator
+): Effect.Effect<
+  readonly string[],
+  | AppValidationError
+  | CSSCompilationError
+  | ServerCreationError
+  | SSGGenerationError
+  | AuthConfigRequiredForUserFields
+  | SchemaInitializationError
+  | Error,
+  never
+> =>
+  Effect.gen(function* () {
+    yield* Console.log(`🌍 Generating multi-language static site...`)
+    const supportedLanguages = validatedApp.languages!.supported
+
+    // Generate files for each language using Effect.forEach
+    const langFiles = yield* Effect.forEach(
+      supportedLanguages,
+      (lang) =>
+        Effect.gen(function* () {
+          yield* Console.log(`📝 Generating pages for language: ${lang.code}...`)
+
+          // Replace tokens for this language
+          const langApp = replaceAppTokens(validatedApp, lang.code)
+
+          // Validate the language-specific app
+          const validatedLangApp = yield* Effect.try({
+            try: (): App => Schema.decodeUnknownSync(AppSchema)(langApp),
+            catch: (error) => new AppValidationError(error),
+          })
+
+          // Create server instance for this language
+          const serverInstance = yield* serverFactory.create({
+            app: validatedLangApp,
+            port: 0,
+            hostname: 'localhost',
+            renderHomePage: pageRenderer.renderHome,
+            renderPage: pageRenderer.renderPage,
+            renderNotFoundPage: pageRenderer.renderNotFound,
+            renderErrorPage: pageRenderer.renderError,
+          })
+
+          yield* serverInstance.stop
+
+          // Generate static files in language subdirectory
+          const langOutputDir = `${outputDir}/${lang.code}`
+          // Filter out underscore-prefixed pages (admin/internal pages)
+          const pagePaths =
+            validatedLangApp.pages
+              ?.filter((page) => !page.path.startsWith('/_'))
+              .map((page) => page.path) || []
+          const ssgResult = yield* staticSiteGenerator.generate(serverInstance.app, {
+            outputDir: langOutputDir,
+            pagePaths,
+          })
+
+          // Return files with language prefix (normalize paths to be relative)
+          return ssgResult.files.map((f) => {
+            // toSSG returns relative paths from the outputDir
+            // Simply prefix with language code
+            return `${lang.code}/${f}`
+          })
+        }),
+      { concurrency: 'unbounded' }
+    )
+
+    // Generate root index.html with default language
+    yield* Console.log(`📝 Generating root index.html with default language...`)
+    const defaultLang = validatedApp.languages!.default
+    const defaultLangApp = replaceAppTokens(validatedApp, defaultLang)
+    const validatedDefaultApp = yield* Effect.try({
+      try: (): App => Schema.decodeUnknownSync(AppSchema)(defaultLangApp),
+      catch: (error) => new AppValidationError(error),
+    })
+
+    const defaultServer = yield* serverFactory.create({
+      app: validatedDefaultApp,
+      port: 0,
+      hostname: 'localhost',
+      renderHomePage: pageRenderer.renderHome,
+      renderPage: pageRenderer.renderPage,
+      renderNotFoundPage: pageRenderer.renderNotFound,
+      renderErrorPage: pageRenderer.renderError,
+    })
+
+    yield* defaultServer.stop
+
+    // Generate only root index.html
+    const rootSSGResult = yield* staticSiteGenerator.generate(defaultServer.app, {
+      outputDir,
+      pagePaths: ['/'],
+    })
+
+    // Combine all files immutably
+    return [...langFiles.flat(), ...rootSSGResult.files]
+  })
+
+/**
+ * Generate static files for single-language configuration
+ */
+export const generateSingleLanguageFiles = (
+  validatedApp: App,
+  outputDir: string,
+  serverFactory: ServerFactory,
+  pageRenderer: PageRenderer,
+  staticSiteGenerator: StaticSiteGenerator
+): Effect.Effect<
+  readonly string[],
+  | CSSCompilationError
+  | ServerCreationError
+  | SSGGenerationError
+  | AuthConfigRequiredForUserFields
+  | SchemaInitializationError
+  | Error,
+  never
+> =>
+  Effect.gen(function* () {
+    // No multi-language - generate normally
+    yield* Console.log('🏗️  Creating application instance...')
+    const serverInstance = yield* serverFactory.create({
+      app: validatedApp,
+      port: 0,
+      hostname: 'localhost',
+      renderHomePage: pageRenderer.renderHome,
+      renderPage: pageRenderer.renderPage,
+      renderNotFoundPage: pageRenderer.renderNotFound,
+      renderErrorPage: pageRenderer.renderError,
+    })
+
+    yield* serverInstance.stop
+
+    // Filter out underscore-prefixed pages (admin/internal pages)
+    const pagePaths =
+      validatedApp.pages?.filter((page) => !page.path.startsWith('/_')).map((page) => page.path) ||
+      []
+    yield* Console.log(`📝 Generating static HTML files for ${pagePaths.length} pages...`)
+    const ssgResult = yield* staticSiteGenerator.generate(serverInstance.app, {
+      outputDir,
+      pagePaths,
+    })
+    return ssgResult.files
+  })