sovrium 0.0.2

package/src/cli.ts

@@ -0,0 +1,370 @@
+#!/usr/bin/env bun
+/**
+ * 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 CLI - Command-line interface for Sovrium operations
+ *
+ * This script provides commands for running a Sovrium server or building static sites.
+ *
+ * ## Commands
+ *
+ * ### sovrium start [config]
+ * Start a development server
+ * ```bash
+ * sovrium start app.json                              # Load from JSON file
+ * sovrium start app.yaml                              # Load from YAML file
+ * APP_SCHEMA='{"name":"My App"}' sovrium              # Inline JSON
+ * APP_SCHEMA='name: My App' sovrium                   # Inline YAML
+ * APP_SCHEMA='https://example.com/app.yaml'           # Remote URL
+ * ```
+ *
+ * ### sovrium build [config]
+ * Build static site files
+ * ```bash
+ * sovrium build app.json                           # Load from JSON file
+ * SOVRIUM_OUTPUT_DIR=./dist sovrium build          # Or use env variable
+ * ```
+ *
+ * ## Arguments
+ * - `config` (optional) - Path to config file (JSON or YAML)
+ *
+ * ## Environment Variables (start command)
+ * - `APP_SCHEMA` (optional if file provided) - App schema (inline JSON, YAML, or remote URL)
+ * - `PORT` (optional) - Server port (default: 3000)
+ * - `HOSTNAME` (optional) - Server hostname (default: localhost)
+ *
+ * ## Environment Variables (build command)
+ * - `APP_SCHEMA` (optional if file provided) - App schema (inline JSON, YAML, or remote URL)
+ * - `SOVRIUM_OUTPUT_DIR` (optional) - Output directory (default: ./dist)
+ * - `SOVRIUM_BASE_URL` (optional) - Base URL for sitemap
+ * - `SOVRIUM_BASE_PATH` (optional) - Base path for deployments
+ * - `SOVRIUM_DEPLOYMENT` (optional) - Deployment type (github-pages | generic)
+ * - `SOVRIUM_LANGUAGES` (optional) - Comma-separated language codes
+ * - `SOVRIUM_DEFAULT_LANGUAGE` (optional) - Default language
+ * - `SOVRIUM_GENERATE_SITEMAP` (optional) - Generate sitemap.xml (true/false)
+ * - `SOVRIUM_GENERATE_ROBOTS` (optional) - Generate robots.txt (true/false)
+ * - `SOVRIUM_HYDRATION` (optional) - Enable client-side hydration (true/false)
+ * - `SOVRIUM_GENERATE_MANIFEST` (optional) - Generate manifest.json (true/false)
+ * - `SOVRIUM_BUNDLE_OPTIMIZATION` (optional) - Bundle optimization strategy
+ */
+
+import { watch } from 'node:fs'
+import { Effect, Console } from 'effect'
+import { start, build, type StartOptions, type GenerateStaticOptions } from '@/index'
+import { parseAppSchema, loadSchemaFromFileForReload } from '@/presentation/cli'
+
+// Server instance type (returned by start())
+type ServerInstance = Awaited<ReturnType<typeof start>>
+
+/**
+ * Reload server with new configuration from changed config file
+ *
+ * This function is called when the config file changes during --watch mode.
+ * It gracefully reloads the server with the new configuration.
+ *
+ * @param filePath - Path to the config file that changed
+ * @param currentServer - The currently running server instance
+ * @param options - Server options (port, hostname)
+ * @returns Promise with the new server instance
+ * @throws Error if config file cannot be parsed or new server fails to start
+ */
+const reloadServer = async (
+  filePath: string,
+  currentServer: ServerInstance,
+  options: StartOptions
+): Promise<ServerInstance> => {
+  // Parse the new config file (throws on invalid JSON/YAML, doesn't exit process)
+  const newApp = await loadSchemaFromFileForReload(filePath)
+
+  // Stop the current server before starting the new one
+  // eslint-disable-next-line functional/no-expression-statements
+  await currentServer.stop()
+
+  // Start new server with the updated config
+  const newServer = await start(newApp, options)
+
+  return newServer
+}
+
+/**
+ * Show CLI help text
+ */
+const showHelp = (): void => {
+  const helpText = [
+    'Sovrium CLI',
+    '',
+    'Commands:',
+    '  sovrium start [config]        Start a development server (default)',
+    '  sovrium build [config]        Build static site files',
+    '  sovrium --help                Show this help message',
+    '',
+    'Options:',
+    '  --watch, -w                   Watch config file for changes and hot reload',
+    '',
+    'Supported config formats: .json, .yaml, .yml',
+    '',
+    'Examples:',
+    '  # Start development server with JSON file',
+    '  sovrium start app.json',
+    '',
+    '  # Start with YAML file',
+    '  sovrium start app.yaml',
+    '',
+    '  # Start with watch mode (hot reload on config changes)',
+    '  sovrium start app.yaml --watch',
+    '',
+    '  # Start with environment variable (JSON, YAML, or URL)',
+    '  APP_SCHEMA=\'{"name":"My App"}\' sovrium start',
+    '',
+    '  # Build static site',
+    '  sovrium build app.json',
+    '',
+    'For more information, see the documentation at https://sovrium.com/docs/cli',
+  ]
+
+  Effect.runSync(Console.log(helpText.join('\n')))
+}
+
+/**
+ * Parse server options from environment variables
+ */
+const parseStartOptions = (): StartOptions => {
+  const port = Bun.env.PORT
+  const hostname = Bun.env.HOSTNAME
+
+  if (!port && !hostname) {
+    return {}
+  }
+
+  const parsedPort = port ? parseInt(port, 10) : undefined
+  if (parsedPort !== undefined && (isNaN(parsedPort) || parsedPort < 0 || parsedPort > 65_535)) {
+    Effect.runSync(
+      Console.error(
+        `Error: Invalid port number "${port}". Must be between 0 and 65535 (0 = auto-select).`
+      )
+    )
+    // Terminate process - imperative statement required for CLI
+    // eslint-disable-next-line functional/no-expression-statements
+    process.exit(1)
+  }
+
+  return {
+    ...(parsedPort !== undefined && { port: parsedPort }),
+    ...(hostname && { hostname }),
+  }
+}
+
+/**
+ * Handle the 'start' command
+ */
+const handleStartCommand = async (filePath?: string, watchMode = false): Promise<void> => {
+  const app = await parseAppSchema('start', filePath)
+  const options = parseStartOptions()
+
+  Effect.runSync(
+    Effect.gen(function* () {
+      yield* Console.log('Starting Sovrium server from CLI...')
+      yield* Console.log(`App: ${app.name}${app.description ? ` - ${app.description}` : ''}`)
+      if (filePath) yield* Console.log(`Config: ${filePath}`)
+      if (options.port) yield* Console.log(`Port: ${options.port}`)
+      if (options.hostname) yield* Console.log(`Hostname: ${options.hostname}`)
+      if (watchMode) yield* Console.log(`Watch mode: enabled`)
+      yield* Console.log('')
+    })
+  )
+
+  // Start the server
+  const server = await start(app, options).catch((error) => {
+    Effect.runSync(Console.error('Failed to start server:', error))
+    // Terminate process - imperative statement required for CLI
+    // eslint-disable-next-line functional/no-expression-statements
+    process.exit(1)
+  })
+
+  // If watch mode enabled, set up file watcher
+  if (watchMode && filePath) {
+    console.log(`\n👀 Watching ${filePath} for changes...\n`)
+
+    // Track current server instance (mutable for watch mode)
+    // eslint-disable-next-line functional/no-let
+    let currentServer = server
+
+    // Set up file watcher using Node.js fs.watch (stable in Bun)
+
+    watch(filePath, async (eventType) => {
+      if (eventType === 'change') {
+        console.log(`\n🔄 Config changed, reloading...`)
+
+        try {
+          // eslint-disable-next-line functional/no-expression-statements
+          currentServer = await reloadServer(filePath, currentServer, options)
+
+          console.log(`✅ Server reloaded successfully\n`)
+        } catch (error) {
+          console.error(`❌ Reload failed: ${error instanceof Error ? error.message : error}\n`)
+          // Keep the old server running on error
+        }
+      }
+    })
+  }
+}
+
+/**
+ * Parse boolean environment variable
+ */
+const parseBooleanEnv = (value: string | undefined): boolean | undefined =>
+  value === 'true' ? true : value === 'false' ? false : undefined
+
+/**
+ * Parse build options from environment variables
+ */
+const parseBuildOptions = (): GenerateStaticOptions => {
+  // Parse environment variables
+  const envVars = {
+    outputDir: Bun.env.SOVRIUM_OUTPUT_DIR,
+    baseUrl: Bun.env.SOVRIUM_BASE_URL,
+    basePath: Bun.env.SOVRIUM_BASE_PATH,
+    deployment: Bun.env.SOVRIUM_DEPLOYMENT as 'github-pages' | 'generic' | undefined,
+    languages: Bun.env.SOVRIUM_LANGUAGES?.split(',').map((lang) => lang.trim()),
+    defaultLanguage: Bun.env.SOVRIUM_DEFAULT_LANGUAGE,
+    generateSitemap: parseBooleanEnv(Bun.env.SOVRIUM_GENERATE_SITEMAP),
+    generateRobotsTxt: parseBooleanEnv(Bun.env.SOVRIUM_GENERATE_ROBOTS),
+    hydration: parseBooleanEnv(Bun.env.SOVRIUM_HYDRATION),
+    generateManifest: parseBooleanEnv(Bun.env.SOVRIUM_GENERATE_MANIFEST),
+    bundleOptimization: Bun.env.SOVRIUM_BUNDLE_OPTIMIZATION as 'split' | 'none' | undefined,
+    publicDir: Bun.env.SOVRIUM_PUBLIC_DIR,
+  }
+
+  // Build options object with only defined values
+  const options = [
+    { key: 'outputDir', value: envVars.outputDir },
+    { key: 'baseUrl', value: envVars.baseUrl },
+    { key: 'basePath', value: envVars.basePath },
+    { key: 'deployment', value: envVars.deployment },
+    { key: 'languages', value: envVars.languages },
+    { key: 'defaultLanguage', value: envVars.defaultLanguage },
+    { key: 'generateSitemap', value: envVars.generateSitemap },
+    { key: 'generateRobotsTxt', value: envVars.generateRobotsTxt },
+    { key: 'hydration', value: envVars.hydration },
+    { key: 'generateManifest', value: envVars.generateManifest },
+    { key: 'bundleOptimization', value: envVars.bundleOptimization },
+    { key: 'publicDir', value: envVars.publicDir },
+  ].reduce(
+    (acc, { key, value }) =>
+      value !== undefined && value !== false ? { ...acc, [key]: value } : acc,
+    {} as GenerateStaticOptions
+  )
+
+  return options
+}
+
+/**
+ * Handle the 'build' command
+ */
+const handleBuildCommand = async (filePath?: string): Promise<void> => {
+  const app = await parseAppSchema('build', filePath)
+  const options = parseBuildOptions()
+
+  Effect.runSync(
+    Effect.gen(function* () {
+      yield* Console.log('Building static site from CLI...')
+      yield* Console.log(`App: ${app.name}${app.description ? ` - ${app.description}` : ''}`)
+      if (filePath) yield* Console.log(`Config: ${filePath}`)
+      if (options.outputDir) yield* Console.log(`Output directory: ${options.outputDir}`)
+      if (options.baseUrl) yield* Console.log(`Base URL: ${options.baseUrl}`)
+      if (options.deployment) yield* Console.log(`Deployment: ${options.deployment}`)
+      yield* Console.log('')
+    })
+  )
+
+  // Build static site
+  // eslint-disable-next-line functional/no-expression-statements
+  await build(app, options).catch((error) => {
+    Effect.runSync(Console.error('Failed to build static site:', error))
+    // Terminate process - imperative statement required for CLI
+    // eslint-disable-next-line functional/no-expression-statements
+    process.exit(1)
+  })
+}
+
+// Main CLI entry point
+const args = Bun.argv.slice(2)
+
+/**
+ * Check if argument is a config file path (JSON, YAML, or YML)
+ */
+const isConfigFile = (arg: string | undefined): boolean =>
+  arg !== undefined &&
+  (arg.endsWith('.json') ||
+    arg.endsWith('.yaml') ||
+    arg.endsWith('.yml') ||
+    arg.endsWith('.JSON') ||
+    arg.endsWith('.YAML') ||
+    arg.endsWith('.YML') ||
+    arg.includes('/'))
+
+/**
+ * Parse CLI arguments into command, config file, and flags
+ */
+const parseArgs = (
+  argv: readonly string[]
+): { readonly command: string; readonly configFile?: string; readonly watchMode: boolean } => {
+  const watchMode = argv.includes('--watch') || argv.includes('-w')
+  const nonFlagArgs = argv.filter((arg) => !arg.startsWith('-'))
+
+  const command = nonFlagArgs[0] || 'start'
+  const configFile = nonFlagArgs[1]
+
+  // Handle case where first arg is a config file (implicit 'start' command)
+  if (isConfigFile(command)) {
+    return { command: 'start', configFile: command, watchMode }
+  }
+
+  return { command, configFile, watchMode }
+}
+
+const { command, configFile, watchMode } = parseArgs(args)
+
+// Execute command - side effects required for CLI operation
+;(async () => {
+  switch (command) {
+    case 'start':
+      // eslint-disable-next-line functional/no-expression-statements -- CLI command execution requires side effects
+      await handleStartCommand(configFile, watchMode)
+      break
+    case 'build':
+      // eslint-disable-next-line functional/no-expression-statements -- CLI command execution requires side effects
+      await handleBuildCommand(configFile)
+      break
+    case '--help':
+    case '-h':
+    case 'help':
+      showHelp()
+      // Terminate process - imperative statement required for CLI
+      // eslint-disable-next-line functional/no-expression-statements
+      process.exit(0)
+      break
+    default:
+      if (!command.startsWith('-')) {
+        // Unknown command without dash - try as start command
+        // eslint-disable-next-line functional/no-expression-statements -- CLI command execution requires side effects
+        await handleStartCommand(undefined, watchMode)
+      } else {
+        Effect.runSync(
+          Effect.gen(function* () {
+            yield* Console.error(`Error: Unknown command "${command}"`)
+            yield* Console.error('')
+          })
+        )
+        showHelp()
+        // Terminate process - imperative statement required for CLI
+        // eslint-disable-next-line functional/no-expression-statements
+        process.exit(1)
+      }
+  }
+})()

package/src/domain/errors/create-tagged-error.ts

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+
+/**
+ * Factory function to create tagged error classes for Effect discriminated unions.
+ *
+ * This factory reduces boilerplate for error classes that follow the pattern:
+ * - `readonly _tag` property for discriminated union matching
+ * - `readonly cause` property to wrap underlying errors
+ *
+ * @example
+ * ```typescript
+ * // Instead of manually defining:
+ * export class MyError {
+ *   readonly _tag = 'MyError'
+ *   constructor(readonly cause: unknown) {}
+ * }
+ *
+ * // Use the factory:
+ * export const MyError = createTaggedError('MyError')
+ * export type MyError = InstanceType<typeof MyError>
+ * ```
+ *
+ * @param tag - The unique tag string for the error type (used in Effect matching)
+ * @returns A class constructor that creates tagged error instances
+ */
+export function createTaggedError<T extends string>(tag: T) {
+  return class {
+    readonly _tag = tag
+    constructor(readonly cause: unknown) {}
+  } as new (cause: unknown) => { readonly _tag: T; readonly cause: unknown }
+}

package/src/domain/errors/index.ts

@@ -0,0 +1,78 @@
+/**
+ * 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.
+ */
+
+export { createTaggedError } from './create-tagged-error'
+
+/**
+ * Database session context error
+ */
+export class SessionContextError extends Error {
+  readonly _tag = 'SessionContextError'
+  override readonly cause?: unknown
+
+  constructor(message: string, cause?: unknown) {
+    super(message)
+    // eslint-disable-next-line functional/no-expression-statements -- Required for Error subclass
+    this.name = 'SessionContextError'
+    // eslint-disable-next-line functional/no-expression-statements -- Required for Error subclass
+    this.cause = cause
+  }
+}
+
+/**
+ * Forbidden error for authorization failures
+ */
+export class ForbiddenError extends Error {
+  readonly _tag = 'ForbiddenError'
+
+  constructor(message: string) {
+    super(message)
+    // eslint-disable-next-line functional/no-expression-statements -- Required for Error subclass
+    this.name = 'ForbiddenError'
+  }
+}
+
+/**
+ * Unique constraint violation error
+ * Thrown when attempting to insert/update a record that violates a unique constraint
+ */
+export class UniqueConstraintViolationError extends Error {
+  readonly _tag = 'UniqueConstraintViolationError'
+  override readonly cause?: unknown
+
+  constructor(message: string, cause?: unknown) {
+    super(message)
+    // eslint-disable-next-line functional/no-expression-statements -- Required for Error subclass
+    this.name = 'UniqueConstraintViolationError'
+    // eslint-disable-next-line functional/no-expression-statements -- Required for Error subclass
+    this.cause = cause
+  }
+}
+
+/**
+ * Validation error for invalid input data
+ * Thrown when input data fails validation before database operations
+ */
+export class ValidationError extends Error {
+  readonly _tag = 'ValidationError'
+  readonly details?: readonly {
+    readonly record: number
+    readonly field: string
+    readonly error: string
+  }[]
+
+  constructor(
+    message: string,
+    details?: readonly { readonly record: number; readonly field: string; readonly error: string }[]
+  ) {
+    super(message)
+    // eslint-disable-next-line functional/no-expression-statements -- Required for Error subclass
+    this.name = 'ValidationError'
+    // eslint-disable-next-line functional/no-expression-statements -- Required for Error subclass
+    this.details = details
+  }
+}

package/src/domain/models/api/analytics.ts

@@ -0,0 +1,179 @@
+/**
+ * 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 { z } from 'zod'
+
+// ============================================================================
+// Collection Schema (POST /api/analytics/collect)
+// ============================================================================
+
+/**
+ * Analytics collection payload schema
+ *
+ * Minimal payload sent by the tracking script.
+ * Single-letter keys to minimize bandwidth usage.
+ */
+export const analyticsCollectSchema = z.object({
+  /** Page path (required) */
+  p: z.string().min(1).describe('Page path being viewed'),
+  /** Page title (optional) */
+  t: z.string().optional().describe('Page title'),
+  /** Referrer URL (optional) */
+  r: z.string().optional().describe('Full referrer URL'),
+  /** Screen width (optional) */
+  sw: z.number().int().positive().optional().describe('Screen width in pixels'),
+  /** Screen height (optional) */
+  sh: z.number().int().positive().optional().describe('Screen height in pixels'),
+  /** UTM source (optional) */
+  us: z.string().optional().describe('UTM source parameter'),
+  /** UTM medium (optional) */
+  um: z.string().optional().describe('UTM medium parameter'),
+  /** UTM campaign (optional) */
+  uc: z.string().optional().describe('UTM campaign parameter'),
+  /** UTM content (optional) */
+  ux: z.string().optional().describe('UTM content parameter'),
+  /** UTM term (optional) */
+  ut: z.string().optional().describe('UTM term parameter'),
+})
+
+export type AnalyticsCollectPayload = z.infer<typeof analyticsCollectSchema>
+
+// ============================================================================
+// Query Parameters Schema (shared across query endpoints)
+// ============================================================================
+
+/**
+ * Analytics query parameters schema
+ *
+ * Shared query parameters for all analytics query endpoints.
+ */
+export const analyticsQuerySchema = z.object({
+  /** Start of date range (ISO 8601) */
+  from: z.string().describe('Start of date range (ISO 8601 datetime)'),
+  /** End of date range (ISO 8601) */
+  to: z.string().describe('End of date range (ISO 8601 datetime)'),
+  /** Time series granularity */
+  granularity: z
+    .enum(['hour', 'day', 'week', 'month'])
+    .default('day')
+    .describe('Time series granularity'),
+})
+
+export type AnalyticsQueryParams = z.infer<typeof analyticsQuerySchema>
+
+// ============================================================================
+// Response Schemas
+// ============================================================================
+
+/**
+ * Time series data point
+ */
+export const timeSeriesPointSchema = z.object({
+  period: z.string().describe('Time period start (ISO 8601)'),
+  pageViews: z.number().int().describe('Total page views in period'),
+  uniqueVisitors: z.number().int().describe('Unique visitors in period'),
+  sessions: z.number().int().describe('Unique sessions in period'),
+})
+
+export type TimeSeriesPoint = z.infer<typeof timeSeriesPointSchema>
+
+/**
+ * Analytics overview response schema
+ *
+ * GET /api/analytics/overview
+ */
+export const analyticsOverviewResponseSchema = z.object({
+  summary: z.object({
+    pageViews: z.number().int().describe('Total page views'),
+    uniqueVisitors: z.number().int().describe('Total unique visitors'),
+    sessions: z.number().int().describe('Total sessions'),
+  }),
+  timeSeries: z.array(timeSeriesPointSchema).describe('Time series data points'),
+})
+
+export type AnalyticsOverviewResponse = z.infer<typeof analyticsOverviewResponseSchema>
+
+/**
+ * Top pages response schema
+ *
+ * GET /api/analytics/pages
+ */
+export const analyticsTopPagesResponseSchema = z.object({
+  pages: z.array(
+    z.object({
+      path: z.string().describe('Page path'),
+      pageViews: z.number().int().describe('Total page views'),
+      uniqueVisitors: z.number().int().describe('Unique visitors'),
+    })
+  ),
+  total: z.number().int().describe('Total number of pages'),
+})
+
+export type AnalyticsTopPagesResponse = z.infer<typeof analyticsTopPagesResponseSchema>
+
+/**
+ * Top referrers response schema
+ *
+ * GET /api/analytics/referrers
+ */
+export const analyticsTopReferrersResponseSchema = z.object({
+  referrers: z.array(
+    z.object({
+      domain: z.string().nullable().describe('Referrer domain (null for direct traffic)'),
+      pageViews: z.number().int().describe('Total page views from this referrer'),
+      uniqueVisitors: z.number().int().describe('Unique visitors from this referrer'),
+    })
+  ),
+  total: z.number().int().describe('Total referrer entries'),
+})
+
+export type AnalyticsTopReferrersResponse = z.infer<typeof analyticsTopReferrersResponseSchema>
+
+/**
+ * Device breakdown entry schema
+ */
+const breakdownEntrySchema = z.object({
+  name: z.string().describe('Category name'),
+  count: z.number().int().describe('Number of page views'),
+  percentage: z.number().describe('Percentage of total (0-100)'),
+})
+
+/**
+ * Device breakdown response schema
+ *
+ * GET /api/analytics/devices
+ */
+export const analyticsDevicesResponseSchema = z.object({
+  deviceTypes: z.array(breakdownEntrySchema).describe('Device type breakdown'),
+  browsers: z.array(breakdownEntrySchema).describe('Browser name breakdown'),
+  operatingSystems: z.array(breakdownEntrySchema).describe('OS name breakdown'),
+})
+
+export type AnalyticsDevicesResponse = z.infer<typeof analyticsDevicesResponseSchema>
+
+/**
+ * Campaign entry schema
+ */
+const campaignEntrySchema = z.object({
+  source: z.string().nullable().describe('UTM source'),
+  medium: z.string().nullable().describe('UTM medium'),
+  campaign: z.string().nullable().describe('UTM campaign'),
+  pageViews: z.number().int().describe('Total page views'),
+  uniqueVisitors: z.number().int().describe('Unique visitors'),
+})
+
+/**
+ * Campaigns response schema
+ *
+ * GET /api/analytics/campaigns
+ */
+export const analyticsCampaignsResponseSchema = z.object({
+  campaigns: z.array(campaignEntrySchema).describe('UTM campaign breakdown'),
+  total: z.number().int().describe('Total campaign entries'),
+})
+
+export type AnalyticsCampaignsResponse = z.infer<typeof analyticsCampaignsResponseSchema>