sovrium 0.0.2

package/src/presentation/api/validation/rules/field-rules.ts

@@ -0,0 +1,158 @@
+/**
+ * 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 } from 'effect'
+import { hasPermission } from '@/domain/models/app/table/permissions'
+import { ValidationError, PermissionError, ValidationContext } from '../../middleware/validation'
+
+/**
+ * Validate that 'id' field is not in the request (readonly)
+ */
+export function validateReadonlyIdField(
+  fields: Record<string, unknown>
+): Effect.Effect<void, ValidationError, never> {
+  if ('id' in fields) {
+    return Effect.fail(new ValidationError("Cannot write to readonly field 'id'", 'id'))
+  }
+  return Effect.void
+}
+
+/**
+ * Validate that fields with default values are not in the request (system-managed)
+ */
+export function validateDefaultFields(
+  fields: Record<string, unknown>
+): Effect.Effect<void, ValidationError, ValidationContext> {
+  return Effect.gen(function* () {
+    const ctx = yield* ValidationContext
+    const table = ctx.app.tables?.find((t) => t.name === ctx.tableName)
+
+    const fieldsWithDefaults =
+      table?.fields?.filter((f) => 'default' in f && f.default !== undefined) ?? []
+
+    const attemptedDefaultField = fieldsWithDefaults.find((f) => f.name in fields)
+
+    if (attemptedDefaultField) {
+      return yield* Effect.fail(
+        new ValidationError(
+          `Cannot write to readonly field '${attemptedDefaultField.name}'`,
+          attemptedDefaultField.name
+        )
+      )
+    }
+  })
+}
+
+/**
+ * Validate required fields are present
+ */
+export function validateRequiredFields(
+  fields: Record<string, unknown>
+): Effect.Effect<void, ValidationError, ValidationContext> {
+  return Effect.gen(function* () {
+    const ctx = yield* ValidationContext
+    const table = ctx.app.tables?.find((t) => t.name === ctx.tableName)
+
+    if (!table) return
+
+    // Get primary key field names to exclude from validation
+    const primaryKeyFields = new Set(
+      table.primaryKey?.fields ?? (table.primaryKey?.field ? [table.primaryKey.field] : [])
+    )
+
+    // Auto-injected fields that should be excluded from required field validation
+    const autoInjectedFields = new Set<string>([])
+
+    const missingRequiredFields = table.fields
+      .filter(
+        (field) =>
+          field.required &&
+          !(field.name in fields) &&
+          !primaryKeyFields.has(field.name) &&
+          !autoInjectedFields.has(field.name)
+      )
+      .map((field) => field.name)
+
+    if (missingRequiredFields.length > 0) {
+      return yield* Effect.fail(
+        new ValidationError(
+          'Missing required fields',
+          missingRequiredFields[0] // Report first missing field
+        )
+      )
+    }
+  })
+}
+
+/**
+ * Check if a field permission restricts writing based on user role
+ */
+function hasWriteRoleRestriction(
+  fieldPermission: { write?: 'all' | 'authenticated' | readonly string[] } | null | undefined,
+  userRole: string
+): boolean {
+  const writePermission = fieldPermission?.write
+  if (writePermission === undefined) return false
+  return !hasPermission(writePermission, userRole)
+}
+
+/**
+ * Filter fields based on write permissions
+ * Returns only fields the user is allowed to write
+ */
+export function filterAllowedFields(
+  fields: Record<string, unknown>
+): Effect.Effect<
+  { allowedData: Record<string, unknown>; forbiddenFields: readonly string[] },
+  never,
+  ValidationContext
+> {
+  return Effect.gen(function* () {
+    const ctx = yield* ValidationContext
+    const table = ctx.app.tables?.find((t) => t.name === ctx.tableName)
+
+    // System-protected fields that cannot be modified
+    const SYSTEM_PROTECTED_FIELDS = new Set(['user_id'])
+
+    // Get forbidden fields based on field-level permissions (functional filter pattern)
+    const forbiddenFields: readonly string[] = Object.keys(fields).filter((fieldName) => {
+      const field = table?.fields?.find((f) => f.name === fieldName)
+      if (!field) return false
+
+      const fieldPermission = table?.permissions?.fields?.find((fp) => fp.field === fieldName)
+      return hasWriteRoleRestriction(fieldPermission, ctx.userRole)
+    })
+
+    // Filter out forbidden and system-protected fields
+    const allowedData = Object.fromEntries(
+      Object.entries(fields).filter(
+        ([fieldName]) =>
+          !forbiddenFields.includes(fieldName) && !SYSTEM_PROTECTED_FIELDS.has(fieldName)
+      )
+    )
+
+    return { allowedData, forbiddenFields }
+  })
+}
+
+/**
+ * Validate field write permissions - fails if any forbidden fields found
+ */
+export function validateFieldWritePermissions(
+  forbiddenFields: readonly string[]
+): Effect.Effect<void, PermissionError, never> {
+  if (forbiddenFields.length > 0) {
+    const firstForbiddenField = forbiddenFields[0]
+    return Effect.fail(
+      new PermissionError(
+        `Cannot write to field '${firstForbiddenField}': insufficient permissions`,
+        firstForbiddenField
+      )
+    )
+  }
+  return Effect.void
+}

package/src/presentation/api/validation/rules/record-rules.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 } from 'effect'
+import {
+  validateReadonlyIdField,
+  validateDefaultFields,
+  validateRequiredFields,
+  filterAllowedFields,
+  validateFieldWritePermissions,
+} from './field-rules'
+import type {
+  ValidationError,
+  PermissionError,
+  ValidationContext,
+} from '../../middleware/validation'
+
+/**
+ * Validate fields for record creation
+ * Composes all field-level validations
+ */
+export function validateRecordCreation(
+  requestedFields: Record<string, unknown>
+): Effect.Effect<Record<string, unknown>, ValidationError | PermissionError, ValidationContext> {
+  return Effect.gen(function* () {
+    // Step 1: Check readonly 'id' field
+    yield* validateReadonlyIdField(requestedFields)
+
+    // Step 2: Check fields with default values
+    yield* validateDefaultFields(requestedFields)
+
+    // Step 3: Filter fields based on write permissions
+    const { allowedData, forbiddenFields } = yield* filterAllowedFields(requestedFields)
+
+    // Step 4: Check for forbidden fields
+    yield* validateFieldWritePermissions(forbiddenFields)
+
+    // Step 5: Validate required fields (on allowed data)
+    yield* validateRequiredFields(allowedData)
+
+    return allowedData
+  })
+}
+
+/**
+ * Validate fields for record update
+ * Similar to creation but without required field validation
+ */
+export function validateRecordUpdate(
+  requestedFields: Record<string, unknown>
+): Effect.Effect<Record<string, unknown>, ValidationError | PermissionError, ValidationContext> {
+  return Effect.gen(function* () {
+    // Step 1: Check readonly 'id' field
+    yield* validateReadonlyIdField(requestedFields)
+
+    // Step 2: Check fields with default values
+    yield* validateDefaultFields(requestedFields)
+
+    // Step 3: Filter fields based on write permissions
+    const { allowedData, forbiddenFields } = yield* filterAllowedFields(requestedFields)
+
+    // Step 4: Check for forbidden fields
+    yield* validateFieldWritePermissions(forbiddenFields)
+
+    // Note: No required field validation for updates (partial updates allowed)
+
+    return allowedData
+  })
+}

package/src/presentation/cli/index.ts

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+
+/**
+ * CLI Presentation Module
+ *
+ * CLI-specific utilities with user-facing error handling.
+ */
+
+export {
+  loadSchemaFromFile,
+  loadSchemaFromFileForReload,
+  parseSchemaFromEnv,
+  parseAppSchema,
+} from './schema-loader'

package/src/presentation/cli/schema-loader.ts

@@ -0,0 +1,172 @@
+/**
+ * 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.
+ */
+
+/**
+ * CLI Schema Loader - Presentation Layer
+ *
+ * CLI-specific schema loading with user-facing error messages and process.exit.
+ * Orchestrates domain and infrastructure layers.
+ */
+
+import { Effect, Console } from 'effect'
+import {
+  detectFormat,
+  getFileExtension,
+  isInlineJson,
+  isUrl,
+  parseJsonContent,
+  parseYamlContent,
+} from '@/domain/utils'
+import {
+  loadSchemaFromFile as loadFromFile,
+  fileExists,
+  fetchRemoteSchema,
+} from '@/infrastructure/schema'
+import type { AppEncoded } from '@/domain/models/app'
+
+/**
+ * Load schema from file with CLI error handling (calls process.exit on error)
+ */
+export const loadSchemaFromFile = async (
+  filePath: string,
+  command: string
+): Promise<AppEncoded> => {
+  const exists = await fileExists(filePath)
+
+  if (!exists) {
+    Effect.runSync(
+      Effect.gen(function* () {
+        yield* Console.error(`Error: File not found: ${filePath}`)
+        yield* Console.error('')
+        yield* Console.error('Usage:')
+        yield* Console.error(`  sovrium ${command} <config.json>`)
+      })
+    )
+    // eslint-disable-next-line functional/no-expression-statements
+    process.exit(1)
+  }
+
+  const format = detectFormat(filePath)
+
+  if (format === 'unsupported') {
+    Effect.runSync(
+      Effect.gen(function* () {
+        yield* Console.error(`Error: Unsupported file format: .${getFileExtension(filePath)}`)
+        yield* Console.error('')
+        yield* Console.error('Supported formats: .json, .yaml, .yml')
+      })
+    )
+    // eslint-disable-next-line functional/no-expression-statements
+    process.exit(1)
+  }
+
+  try {
+    return await loadFromFile(filePath)
+  } catch (error) {
+    Effect.runSync(
+      Effect.gen(function* () {
+        yield* Console.error(
+          `Error: Failed to parse ${format === 'json' ? 'JSON' : 'YAML'} file: ${filePath}`
+        )
+        yield* Console.error('')
+        yield* Console.error('Details:', error instanceof Error ? error.message : String(error))
+      })
+    )
+    // eslint-disable-next-line functional/no-expression-statements
+    process.exit(1)
+  }
+}
+
+/**
+ * Load schema from file for watch mode reloads (throws instead of process.exit)
+ */
+export const loadSchemaFromFileForReload = async (filePath: string): Promise<AppEncoded> =>
+  loadFromFile(filePath)
+
+/**
+ * Parse schema from environment variable value
+ * Supports: inline JSON, inline YAML, remote URL
+ *
+ * @throws Error if parsing fails
+ */
+export const parseSchemaFromEnv = async (envValue: string): Promise<AppEncoded> => {
+  const trimmedValue = envValue.trim()
+
+  // Detect if value is inline JSON
+  if (isInlineJson(trimmedValue)) {
+    try {
+      return parseJsonContent(trimmedValue)
+    } catch (error) {
+      // eslint-disable-next-line functional/no-throw-statements
+      throw new Error(
+        `Invalid JSON in APP_SCHEMA: ${error instanceof Error ? error.message : String(error)}`
+      )
+    }
+  }
+
+  // Detect if value is a URL
+  if (isUrl(trimmedValue)) {
+    return fetchRemoteSchema(trimmedValue)
+  }
+
+  // Otherwise, treat as YAML
+  try {
+    return parseYamlContent(trimmedValue)
+  } catch (error) {
+    // eslint-disable-next-line functional/no-throw-statements
+    throw new Error(
+      `Invalid YAML in APP_SCHEMA: ${error instanceof Error ? error.message : String(error)}`
+    )
+  }
+}
+
+/**
+ * Show error message when no configuration is provided
+ */
+const showNoConfigError = (command: string): never => {
+  Effect.runSync(
+    Effect.gen(function* () {
+      yield* Console.error('Error: No configuration provided')
+      yield* Console.error('')
+      yield* Console.error('Usage:')
+      yield* Console.error(`  sovrium ${command} <config.json>`)
+      yield* Console.error('')
+      yield* Console.error('Or with environment variable:')
+      yield* Console.error(`  APP_SCHEMA='{"name":"My App"}' sovrium ${command}`)
+    })
+  )
+  // eslint-disable-next-line functional/no-expression-statements
+  process.exit(1)
+}
+
+/**
+ * Parse and validate app schema from file path or environment variable
+ */
+export const parseAppSchema = async (command: string, filePath?: string): Promise<AppEncoded> => {
+  // If a file path is provided, load from file (takes precedence over env)
+  if (filePath) {
+    return loadSchemaFromFile(filePath, command)
+  }
+
+  // Try APP_SCHEMA environment variable
+  const appSchemaEnv = Bun.env.APP_SCHEMA
+
+  if (appSchemaEnv) {
+    try {
+      return await parseSchemaFromEnv(appSchemaEnv)
+    } catch (error) {
+      Effect.runSync(
+        Console.error(`Error: ${error instanceof Error ? error.message : String(error)}`)
+      )
+      // eslint-disable-next-line functional/no-expression-statements
+      process.exit(1)
+    }
+  }
+
+  // No configuration provided
+  return showNoConfigError(command)
+}

package/src/presentation/hooks/use-breakpoint.ts

@@ -0,0 +1,155 @@
+/**
+ * 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 { useSyncExternalStore } from 'react'
+
+/**
+ * Breakpoint type matching responsive schema
+ */
+export type Breakpoint = 'mobile' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+
+/**
+ * Tailwind default breakpoints (min-width)
+ */
+const BREAKPOINTS: Record<Exclude<Breakpoint, 'mobile'>, number> = {
+  sm: 640,
+  md: 768,
+  lg: 1024,
+  xl: 1280,
+  '2xl': 1536,
+}
+
+/**
+ * Gets current viewport width (works in both normal browsers and test environments)
+ *
+ * Prioritizes document.documentElement.clientWidth for Playwright compatibility
+ *
+ * @returns Viewport width in pixels
+ */
+function getViewportWidth(): number {
+  // Use document.documentElement.clientWidth first (most reliable in Playwright)
+  if (typeof document !== 'undefined' && document.documentElement) {
+    return document.documentElement.clientWidth
+  }
+  // Try visualViewport (reliable in some browsers/test environments)
+  if (typeof window !== 'undefined' && window.visualViewport?.width) {
+    return window.visualViewport.width
+  }
+  // Fallback to innerWidth
+  if (typeof window !== 'undefined' && window.innerWidth) {
+    return window.innerWidth
+  }
+  // Last resort fallback
+  return 0
+}
+
+/**
+ * Determines current breakpoint from window width
+ *
+ * @param width - Window width in pixels
+ * @returns Current breakpoint name
+ */
+function getBreakpoint(width: number): Breakpoint {
+  if (width >= BREAKPOINTS['2xl']) return '2xl'
+  if (width >= BREAKPOINTS.xl) return 'xl'
+  if (width >= BREAKPOINTS.lg) return 'lg'
+  if (width >= BREAKPOINTS.md) return 'md'
+  if (width >= BREAKPOINTS.sm) return 'sm'
+  return 'mobile'
+}
+
+/**
+ * Subscribe to viewport breakpoint changes
+ *
+ * @param callback - Callback to invoke when breakpoint changes
+ * @returns Unsubscribe function
+ */
+function subscribe(callback: () => void): () => void {
+  if (typeof window === 'undefined') return () => {}
+
+  // Call callback immediately to ensure we have the latest viewport state
+  // This is important for detecting viewport changes that happened before subscription
+  callback()
+
+  // Listen to resize events
+  window.addEventListener('resize', callback)
+
+  // Create media query listeners for each breakpoint
+  const mediaQueries = [
+    window.matchMedia(`(min-width: ${BREAKPOINTS.sm}px)`),
+    window.matchMedia(`(min-width: ${BREAKPOINTS.md}px)`),
+    window.matchMedia(`(min-width: ${BREAKPOINTS.lg}px)`),
+    window.matchMedia(`(min-width: ${BREAKPOINTS.xl}px)`),
+    window.matchMedia(`(min-width: ${BREAKPOINTS['2xl']}px)`),
+  ]
+
+  mediaQueries.forEach((mq) => {
+    // Modern API
+    if (mq.addEventListener) {
+      mq.addEventListener('change', callback)
+    } else {
+      // Legacy API fallback
+      mq.addListener(callback)
+    }
+  })
+
+  // Listen to visualViewport resize (more reliable in some environments)
+  window.visualViewport?.addEventListener('resize', callback)
+
+  // Poll for viewport changes (for E2E tests where events might not fire)
+  // This ensures responsive behavior works in automated testing environments
+  // Using 16ms (one frame at 60fps) for fastest possible detection
+  const pollInterval = setInterval(callback, 16)
+
+  return () => {
+    window.removeEventListener('resize', callback)
+    mediaQueries.forEach((mq) => {
+      if (mq.removeEventListener) {
+        mq.removeEventListener('change', callback)
+      } else {
+        mq.removeListener(callback)
+      }
+    })
+    window.visualViewport?.removeEventListener('resize', callback)
+    clearInterval(pollInterval)
+  }
+}
+
+/**
+ * Get current breakpoint snapshot
+ *
+ * @returns Current breakpoint based on viewport width
+ */
+function getSnapshot(): Breakpoint {
+  if (typeof window === 'undefined') return 'mobile'
+  return getBreakpoint(getViewportWidth())
+}
+
+/**
+ * Get server-side breakpoint (always mobile for SSR)
+ *
+ * @returns Mobile breakpoint
+ */
+function getServerSnapshot(): Breakpoint {
+  return 'mobile'
+}
+
+/**
+ * Hook to detect current viewport breakpoint
+ *
+ * Returns the current breakpoint based on window width.
+ * Updates automatically when viewport is resized.
+ * Uses useSyncExternalStore for reliable external state synchronization.
+ *
+ * Uses matchMedia to detect breakpoint changes reliably, which works with
+ * both user-initiated resizes and programmatic viewport changes (e.g., Playwright's setViewportSize).
+ *
+ * @returns Current breakpoint name
+ */
+export function useBreakpoint(): Breakpoint {
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
+}

package/src/presentation/rendering/render-error-pages.tsx

@@ -0,0 +1,60 @@
+/**
+ * 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 { renderToString } from 'react-dom/server'
+import { ErrorPage } from '@/presentation/ui/pages/ErrorPage'
+import { NotFoundPage } from '@/presentation/ui/pages/NotFoundPage'
+import { renderPageByPath } from './render-homepage'
+import type { App } from '@/domain/models/app'
+
+/**
+ * Renders NotFoundPage (404) to HTML string for server-side rendering
+ *
+ * If the app has a custom page configured at '/404', renders that page.
+ * Otherwise, renders the default NotFoundPage.
+ *
+ * @param app - Optional validated application data from AppSchema
+ * @param detectedLanguage - Optional detected language from Accept-Language header
+ * @returns Complete HTML document as string with DOCTYPE
+ */
+export function renderNotFoundPage(app?: App, detectedLanguage?: string): string {
+  // Try to render custom 404 page first if app is provided
+  if (app) {
+    const custom404 = renderPageByPath(app, '/404', detectedLanguage)
+    if (custom404) {
+      return custom404
+    }
+  }
+
+  // Fallback to default 404 page
+  const html = renderToString(<NotFoundPage />)
+  return `<!DOCTYPE html>\n${html}`
+}
+
+/**
+ * Renders ErrorPage (500) to HTML string for server-side rendering
+ *
+ * If the app has a custom page configured at '/500', renders that page.
+ * Otherwise, renders the default ErrorPage.
+ *
+ * @param app - Optional validated application data from AppSchema
+ * @param detectedLanguage - Optional detected language from Accept-Language header
+ * @returns Complete HTML document as string with DOCTYPE
+ */
+export function renderErrorPage(app?: App, detectedLanguage?: string): string {
+  // Try to render custom 500 page first if app is provided
+  if (app) {
+    const custom500 = renderPageByPath(app, '/500', detectedLanguage)
+    if (custom500) {
+      return custom500
+    }
+  }
+
+  // Fallback to default 500 page
+  const html = renderToString(<ErrorPage />)
+  return `<!DOCTYPE html>\n${html}`
+}