sovrium 0.0.2

package/src/application/use-cases/server/generate-static-helpers.ts

@@ -0,0 +1,374 @@
+/**
+ * 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 fs from 'node:fs/promises'
+import path from 'node:path'
+import { Effect, Console } from 'effect'
+import { StaticGenerationError } from '@/application/errors/static-generation-error'
+import { copyDirectory } from '@/infrastructure/filesystem/copy-directory'
+import {
+  formatHtmlWithPrettier,
+  generateClientHydrationScript,
+  generateRobotsContent,
+  generateSitemapContent,
+  type HreflangConfig,
+} from './static-content-generators'
+import {
+  injectHydrationScript,
+  isGitHubPagesUrl,
+  rewriteBasePathInHtml,
+} from './static-url-rewriter'
+import * as translationReplacer from './translation-replacer'
+import type { GenerateStaticOptions } from './generate-static'
+import type { App } from '@/domain/models/app'
+
+// Re-export static modules for callers that previously used the import helpers
+export { fs, path, translationReplacer }
+
+/**
+ * Minimal filesystem interface for static generation
+ *
+ * Compatible with Node.js fs/promises, Bun's filesystem APIs, and test mocks.
+ * Only includes methods actually used by static generation functions.
+ */
+export interface FileSystemLike {
+  readonly mkdir: (
+    path: string,
+    options?: { readonly recursive?: boolean }
+  ) => Promise<string | undefined>
+  readonly writeFile: (path: string, data: string, encoding?: BufferEncoding) => Promise<void>
+  readonly readFile: (path: string, encoding: BufferEncoding) => Promise<string>
+}
+
+/**
+ * Minimal path module interface for static generation
+ *
+ * Compatible with Node.js path module, Bun's path APIs, and test mocks.
+ */
+export interface PathModuleLike {
+  readonly join: (...paths: readonly string[]) => string
+}
+
+/**
+ * Write CSS file to output directory
+ *
+ * @param outputDir - Output directory path
+ * @param css - Compiled CSS content
+ * @param fs - Filesystem module (Node.js fs/promises or Bun's equivalent)
+ */
+export function writeCssFile(outputDir: string, css: string, fs: FileSystemLike) {
+  return Effect.gen(function* () {
+    yield* Console.log('🎨 Writing compiled CSS...')
+
+    yield* Effect.tryPromise({
+      try: () => fs.mkdir(`${outputDir}/assets`, { recursive: true }),
+      catch: (error) =>
+        new StaticGenerationError({
+          message: `Failed to create assets directory`,
+          cause: error,
+        }),
+    })
+
+    yield* Effect.tryPromise({
+      try: () => fs.writeFile(`${outputDir}/assets/output.css`, css, 'utf-8'),
+      catch: (error) =>
+        new StaticGenerationError({
+          message: 'Failed to write CSS file',
+          cause: error,
+        }),
+    })
+
+    return 'assets/output.css'
+  })
+}
+
+/**
+ * Generate client-side hydration script if enabled
+ *
+ * @param outputDir - Output directory path
+ * @param enabled - Whether hydration is enabled
+ * @param fs - Filesystem module (Node.js fs/promises or Bun's equivalent)
+ */
+export function generateHydrationFiles(outputDir: string, enabled: boolean, fs: FileSystemLike) {
+  return Effect.if(enabled, {
+    onTrue: () =>
+      Effect.gen(function* () {
+        yield* Console.log('💧 Generating client-side hydration script...')
+        const clientJS = generateClientHydrationScript()
+        yield* Effect.tryPromise({
+          try: () => fs.writeFile(`${outputDir}/assets/client.js`, clientJS, 'utf-8'),
+          catch: (error) =>
+            new StaticGenerationError({
+              message: 'Failed to write client.js',
+              cause: error,
+            }),
+        })
+        return ['assets/client.js'] as const
+      }),
+    onFalse: () => Effect.succeed([] as readonly string[]),
+  })
+}
+
+/**
+ * Copy static assets from public directory if provided
+ */
+export function copyPublicAssets(publicDir: string | undefined, outputDir: string) {
+  return Effect.if(publicDir !== undefined, {
+    onTrue: () =>
+      Effect.gen(function* () {
+        yield* Console.log(`📁 Copying assets from ${publicDir}...`)
+        return yield* copyDirectory(publicDir!, outputDir)
+      }),
+    onFalse: () => Effect.succeed([] as readonly string[]),
+  })
+}
+
+/**
+ * Format HTML files with Prettier
+ *
+ * @param generatedFiles - List of generated file paths
+ * @param outputDir - Output directory path
+ * @param fs - Filesystem module (Node.js fs/promises or Bun's equivalent)
+ * @param path - Path module (Node.js path or Bun's equivalent)
+ */
+export function formatHtmlFiles(
+  generatedFiles: readonly string[],
+  outputDir: string,
+  fs: FileSystemLike,
+  path: PathModuleLike
+) {
+  return Effect.gen(function* () {
+    yield* Console.log('📝 Formatting HTML files with Prettier...')
+
+    yield* Effect.forEach(
+      generatedFiles.filter((f) => f.endsWith('.html') && !f.endsWith('.js.html')),
+      (file) =>
+        Effect.gen(function* () {
+          const filePath = file.startsWith('/') ? file : path.join(outputDir, file)
+          const content = yield* Effect.tryPromise({
+            try: () => fs.readFile(filePath, 'utf-8') as Promise<string>,
+            catch: (error) =>
+              new StaticGenerationError({
+                message: `Failed to read HTML file for formatting: ${file}`,
+                cause: error,
+              }),
+          })
+          const formatted = yield* Effect.tryPromise({
+            try: () => formatHtmlWithPrettier(content),
+            catch: (error) =>
+              new StaticGenerationError({
+                message: `Failed to format HTML with Prettier: ${file}`,
+                cause: error,
+              }),
+          })
+          yield* Effect.tryPromise({
+            try: () => fs.writeFile(filePath, formatted, 'utf-8'),
+            catch: (error) =>
+              new StaticGenerationError({
+                message: `Failed to write formatted HTML file: ${file}`,
+                cause: error,
+              }),
+          })
+        }),
+      { concurrency: 'unbounded' }
+    )
+  })
+}
+
+/**
+ * Apply optimizations to generated HTML files
+ *
+ * @param config - Configuration object
+ * @param config.generatedFiles - List of generated file paths
+ * @param config.outputDir - Output directory path
+ * @param config.options - Static generation options
+ * @param config.fs - Filesystem module (Node.js fs/promises or Bun's equivalent)
+ * @param config.path - Path module (Node.js path or Bun's equivalent)
+ */
+export function applyHtmlOptimizations(config: {
+  readonly generatedFiles: readonly string[]
+  readonly outputDir: string
+  readonly options: GenerateStaticOptions
+  readonly fs: FileSystemLike
+  readonly path: PathModuleLike
+}) {
+  return Effect.gen(function* () {
+    // Step 1: Apply base path rewriting if basePath is configured
+    yield* Effect.if(config.options.basePath !== undefined && config.options.basePath !== '', {
+      onTrue: () =>
+        rewriteBasePathInHtml(
+          config.generatedFiles,
+          config.outputDir,
+          config.options.basePath!,
+          config.options.baseUrl,
+          config.fs
+        ),
+      onFalse: () => Effect.void,
+    })
+
+    // Step 2: Inject hydration script into HTML if enabled
+    yield* Effect.if(config.options.hydration ?? false, {
+      onTrue: () =>
+        injectHydrationScript(
+          config.generatedFiles,
+          config.outputDir,
+          config.options.basePath || '',
+          config.fs,
+          config.path
+        ),
+      onFalse: () => Effect.void,
+    })
+  })
+}
+
+/**
+ * Build HreflangConfig from app languages when multi-language mode is active
+ */
+const buildHreflangConfig = (
+  app: App,
+  options: GenerateStaticOptions
+): HreflangConfig | undefined => {
+  if (!app.languages || !options.languages) return undefined
+  return {
+    localeMap: Object.fromEntries(
+      app.languages.supported.map((lang) => [lang.code, lang.locale ?? lang.code])
+    ),
+    defaultLanguage: options.defaultLanguage ?? app.languages.default,
+  }
+}
+
+/**
+ * Generate sitemap.xml if enabled
+ */
+export function generateSitemapFile(
+  app: App,
+  outputDir: string,
+  options: GenerateStaticOptions,
+  fs: FileSystemLike
+) {
+  return Effect.if(options.generateSitemap ?? false, {
+    onTrue: () =>
+      Effect.gen(function* () {
+        yield* Console.log('🗺️  Generating sitemap.xml...')
+        const pages = app.pages || []
+        const languages = app.languages && options.languages ? options.languages : undefined
+        const hreflangConfig = buildHreflangConfig(app, options)
+
+        const sitemap = generateSitemapContent(
+          pages,
+          options.baseUrl || 'https://example.com',
+          options.basePath || '',
+          languages || hreflangConfig ? { languages, hreflangConfig } : undefined
+        )
+        yield* Effect.tryPromise({
+          try: () => fs.writeFile(`${outputDir}/sitemap.xml`, sitemap, 'utf-8'),
+          catch: (error) =>
+            new StaticGenerationError({
+              message: 'Failed to write sitemap.xml',
+              cause: error,
+            }),
+        })
+        return ['sitemap.xml'] as const
+      }),
+    onFalse: () => Effect.succeed([] as readonly string[]),
+  })
+}
+
+/**
+ * Generate robots.txt if enabled
+ *
+ * @param app - Application configuration
+ * @param outputDir - Output directory path
+ * @param options - Static generation options
+ * @param fs - Filesystem module (Node.js fs/promises or Bun's equivalent)
+ */
+export function generateRobotsFile(
+  app: App,
+  outputDir: string,
+  options: GenerateStaticOptions,
+  fs: FileSystemLike
+) {
+  return Effect.if(options.generateRobotsTxt ?? false, {
+    onTrue: () =>
+      Effect.gen(function* () {
+        yield* Console.log('🤖 Generating robots.txt...')
+        const pages = app.pages || []
+        const basePath = options.basePath || ''
+        const robots = generateRobotsContent(
+          pages,
+          options.baseUrl || 'https://example.com',
+          basePath,
+          options.generateSitemap
+        )
+        yield* Effect.tryPromise({
+          try: () => fs.writeFile(`${outputDir}/robots.txt`, robots, 'utf-8'),
+          catch: (error) =>
+            new StaticGenerationError({
+              message: 'Failed to write robots.txt',
+              cause: error,
+            }),
+        })
+        return ['robots.txt'] as const
+      }),
+    onFalse: () => Effect.succeed([] as readonly string[]),
+  })
+}
+
+/**
+ * Generate GitHub Pages specific files
+ */
+export function generateGitHubPagesFiles(
+  outputDir: string,
+  options: GenerateStaticOptions,
+  fs: FileSystemLike
+) {
+  return Effect.gen(function* () {
+    // Create .nojekyll file
+    const nojekyllFiles = yield* Effect.if(options.deployment === 'github-pages', {
+      onTrue: () =>
+        Effect.gen(function* () {
+          yield* Console.log('📄 Creating .nojekyll file for GitHub Pages...')
+          yield* Effect.tryPromise({
+            try: () => fs.writeFile(`${outputDir}/.nojekyll`, '', 'utf-8'),
+            catch: (error) =>
+              new StaticGenerationError({
+                message: 'Failed to write .nojekyll',
+                cause: error,
+              }),
+          })
+          return ['.nojekyll'] as const
+        }),
+      onFalse: () => Effect.succeed([] as readonly string[]),
+    })
+
+    // Generate CNAME file for custom domains
+    const cnameFiles = yield* Effect.if(
+      options.deployment === 'github-pages' &&
+        options.baseUrl !== undefined &&
+        !isGitHubPagesUrl(options.baseUrl),
+      {
+        onTrue: () =>
+          Effect.gen(function* () {
+            const domain = new URL(options.baseUrl!).hostname
+            yield* Console.log(`📄 Creating CNAME file for custom domain: ${domain}...`)
+            yield* Effect.tryPromise({
+              try: () => fs.writeFile(`${outputDir}/CNAME`, domain, 'utf-8'),
+              catch: (error) =>
+                new StaticGenerationError({
+                  message: 'Failed to write CNAME',
+                  cause: error,
+                }),
+            })
+            return ['CNAME'] as const
+          }),
+        onFalse: () => Effect.succeed([] as readonly string[]),
+      }
+    )
+
+    return [...nojekyllFiles, ...cnameFiles] as readonly string[]
+  })
+}

package/src/application/use-cases/server/generate-static.ts

@@ -0,0 +1,287 @@
+/**
+ * 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, Schema, type Context } from 'effect'
+import { AppValidationError } from '@/application/errors/app-validation-error'
+import {
+  CSSCompiler as CSSCompilerService,
+  type CSSCompilationError,
+} from '@/application/ports/services/css-compiler'
+import { PageRenderer as PageRendererService } from '@/application/ports/services/page-renderer'
+import { ServerFactory as ServerFactoryService } from '@/application/ports/services/server-factory'
+import {
+  StaticSiteGenerator as StaticSiteGeneratorService,
+  type SSGGenerationError,
+} from '@/application/ports/services/static-site-generator'
+import { AppSchema } from '@/domain/models/app'
+import {
+  fs,
+  path,
+  translationReplacer,
+  writeCssFile,
+  generateHydrationFiles,
+  copyPublicAssets,
+  formatHtmlFiles,
+  applyHtmlOptimizations,
+  generateSitemapFile,
+  generateRobotsFile,
+  generateGitHubPagesFiles,
+  type FileSystemLike,
+} from './generate-static-helpers'
+import {
+  generateMultiLanguageFiles,
+  generateSingleLanguageFiles,
+} from './static-language-generators'
+import type { StaticGenerationError } from '@/application/errors/static-generation-error'
+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'
+import type { FileCopyError } from '@/infrastructure/filesystem/copy-directory'
+
+/**
+ * Options for static site generation
+ */
+export interface GenerateStaticOptions {
+  readonly outputDir?: string // default: './static'
+  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 publicDir?: string // Directory containing static assets to copy
+}
+
+/**
+ * Result of static site generation
+ */
+export interface GenerateStaticResult {
+  readonly outputDir: string
+  readonly files: readonly string[]
+}
+
+/**
+ * Validate app schema handling multi-language apps
+ */
+function validateAppSchema(app: unknown): Effect.Effect<App, AppValidationError, never> {
+  const rawApp = app as Record<string, unknown>
+  const hasLanguages = rawApp.languages !== undefined
+
+  return hasLanguages && rawApp.pages
+    ? Effect.gen(function* () {
+        const appWithoutPages = { ...rawApp, pages: undefined }
+        const baseApp = yield* Effect.try({
+          try: (): App => Schema.decodeUnknownSync(AppSchema)(appWithoutPages),
+          catch: (error) => new AppValidationError(error),
+        })
+        return { ...baseApp, pages: rawApp.pages as App['pages'] }
+      })
+    : Effect.gen(function* () {
+        yield* Console.log('🔍 Validating app schema...')
+        return yield* Effect.try({
+          try: (): App => Schema.decodeUnknownSync(AppSchema)(app),
+          catch: (error) => new AppValidationError(error),
+        })
+      })
+}
+
+/**
+ * Get required services from Effect context
+ */
+function getServicesFromContext() {
+  return Effect.gen(function* () {
+    return {
+      serverFactory: yield* ServerFactoryService,
+      pageRenderer: yield* PageRendererService,
+      cssCompiler: yield* CSSCompilerService,
+      staticSiteGenerator: yield* StaticSiteGeneratorService,
+    }
+  })
+}
+
+/**
+ * Generate HTML files for single or multi-language apps
+ */
+function generateHtmlFiles(
+  app: App,
+  outputDir: string,
+  replaceAppTokens: (app: App, lang: string) => App,
+  serverFactory: Context.Tag.Service<ServerFactoryService>,
+  pageRenderer: Context.Tag.Service<PageRendererService>,
+  staticSiteGenerator: Context.Tag.Service<StaticSiteGeneratorService>
+) {
+  return app.languages && app.pages
+    ? generateMultiLanguageFiles(
+        app,
+        outputDir,
+        replaceAppTokens,
+        serverFactory,
+        pageRenderer,
+        staticSiteGenerator
+      )
+    : generateSingleLanguageFiles(app, outputDir, serverFactory, pageRenderer, staticSiteGenerator)
+}
+
+/**
+ * Generate and write CSS file
+ */
+function generateCssFile(
+  outputDir: string,
+  app: App,
+  cssCompiler: Context.Tag.Service<CSSCompilerService>,
+  fs: FileSystemLike
+) {
+  return Effect.gen(function* () {
+    yield* Console.log('🎨 Getting compiled CSS...')
+    const { css } = yield* cssCompiler.compile(app)
+    return yield* writeCssFile(outputDir, css, fs)
+  })
+}
+
+/**
+ * Optimize HTML files with formatting and transformations
+ *
+ * @param generatedFiles - List of generated file paths
+ * @param outputDir - Output directory path
+ * @param options - Static generation options
+ * @param fsModule - Filesystem module (Node.js fs/promises or Bun's equivalent)
+ */
+function optimizeHtmlFiles(
+  generatedFiles: readonly string[],
+  outputDir: string,
+  options: GenerateStaticOptions,
+  fsModule: FileSystemLike
+) {
+  return Effect.gen(function* () {
+    yield* formatHtmlFiles(generatedFiles, outputDir, fsModule, path)
+    yield* applyHtmlOptimizations({
+      generatedFiles,
+      outputDir,
+      options,
+      fs: fsModule,
+      path,
+    })
+  })
+}
+
+/**
+ * Generate all supporting files (sitemap, robots.txt, GitHub Pages files)
+ */
+function generateSupportingFiles(
+  app: App,
+  outputDir: string,
+  options: GenerateStaticOptions,
+  fs: FileSystemLike
+) {
+  return Effect.gen(function* () {
+    const sitemapFiles = yield* generateSitemapFile(app, outputDir, options, fs)
+    const robotsFiles = yield* generateRobotsFile(app, outputDir, options, fs)
+    const githubFiles = yield* generateGitHubPagesFiles(outputDir, options, fs)
+
+    return [...sitemapFiles, ...robotsFiles, ...githubFiles] as readonly string[]
+  })
+}
+
+/**
+ * Generate static site from app configuration
+ *
+ * This use case:
+ * 1. Validates the app schema
+ * 2. Creates a Hono app instance
+ * 3. Generates static HTML files
+ * 4. Creates supporting files (sitemap, robots.txt, etc.)
+ *
+ * @param app - The app configuration (unknown type, will be validated)
+ * @param options - Static generation options
+ * @returns Effect with output directory and generated files
+ */
+export const generateStatic = (
+  app: unknown,
+  options: GenerateStaticOptions = {}
+): Effect.Effect<
+  GenerateStaticResult,
+  | AppValidationError
+  | StaticGenerationError
+  | SSGGenerationError
+  | CSSCompilationError
+  | ServerCreationError
+  | FileCopyError
+  | AuthConfigRequiredForUserFields
+  | SchemaInitializationError
+  | Error,
+  ServerFactoryService | PageRendererService | CSSCompilerService | StaticSiteGeneratorService
+> => {
+  const program = Effect.gen(function* () {
+    // Step 1: Dependencies are statically imported
+    const { replaceAppTokens } = translationReplacer
+
+    // Step 2: Validate app schema
+    const validatedApp = yield* validateAppSchema(app)
+
+    // Step 3: Get services and initialize
+    const services = yield* getServicesFromContext()
+    const outputDir = options.outputDir || './static'
+
+    // Step 4: Generate HTML files
+    const htmlFiles = yield* generateHtmlFiles(
+      validatedApp,
+      outputDir,
+      replaceAppTokens,
+      services.serverFactory,
+      services.pageRenderer,
+      services.staticSiteGenerator
+    )
+
+    // Step 5: Generate CSS and assets
+    const cssFile = yield* generateCssFile(outputDir, validatedApp, services.cssCompiler, fs)
+    const hydrationFiles = yield* generateHydrationFiles(outputDir, options.hydration ?? false, fs)
+    const assetFiles = yield* copyPublicAssets(options.publicDir, outputDir)
+
+    // Collect all generated files
+    const generatedFiles = [
+      ...htmlFiles,
+      cssFile,
+      ...hydrationFiles,
+      ...assetFiles,
+    ] as readonly string[]
+
+    // Step 6: Optimize HTML files
+    yield* optimizeHtmlFiles(generatedFiles, outputDir, options, fs)
+
+    // Step 7: Generate supporting files
+    const supportingFiles = yield* generateSupportingFiles(validatedApp, outputDir, options, fs)
+
+    // Combine all files immutably
+    const allFiles = [...generatedFiles, ...supportingFiles] as readonly string[]
+
+    yield* Console.log(`✅ Generated ${allFiles.length} files to ${outputDir}`)
+
+    return {
+      outputDir,
+      files: allFiles,
+    }
+  })
+
+  return program as Effect.Effect<
+    GenerateStaticResult,
+    | AppValidationError
+    | StaticGenerationError
+    | SSGGenerationError
+    | CSSCompilationError
+    | ServerCreationError
+    | FileCopyError
+    | AuthConfigRequiredForUserFields
+    | SchemaInitializationError
+    | Error,
+    ServerFactoryService | PageRendererService | CSSCompilerService | StaticSiteGeneratorService
+  >
+}