sovrium 0.0.2

package/src/infrastructure/database/table-queries/shared/user-join-helpers.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 { UserMetadataWithOptionalImage } from '@/application/ports/models/user-metadata'
+
+/**
+ * Row shape from a LEFT JOIN on the users table
+ *
+ * Fields are nullable because LEFT JOIN returns NULL when no user matches.
+ */
+export interface UserJoinRow {
+  readonly userId: string | null | undefined
+  readonly userName: string | null | undefined
+  readonly userEmail: string | null | undefined
+  readonly userImage: string | null | undefined
+}
+
+/**
+ * Extract user metadata from a LEFT JOIN row
+ *
+ * Returns undefined when required fields (userId, userName, userEmail) are missing,
+ * which happens when the LEFT JOIN finds no matching user.
+ */
+export function extractUserFromRow(row: UserJoinRow): UserMetadataWithOptionalImage | undefined {
+  if (row.userId && row.userName && row.userEmail) {
+    return {
+      id: row.userId,
+      name: row.userName,
+      email: row.userEmail,
+      image: row.userImage ?? undefined,
+    }
+  }
+  return undefined
+}

package/src/infrastructure/database/table-queries/shared/validation.ts

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+
+/**
+ * Validate a table name to prevent SQL injection
+ *
+ * PostgreSQL identifiers cannot be fully parameterized, so we validate them.
+ * This function ensures table names:
+ * - Only contain alphanumeric characters, underscores
+ * - Start with a letter or underscore
+ * - Are within PostgreSQL's 63-character limit
+ *
+ * @param tableName - Raw table name from user input
+ * @throws Error if table name contains invalid characters
+ */
+export const validateTableName = (tableName: string): void => {
+  // PostgreSQL identifier rules: start with letter/underscore, contain alphanumeric/underscore
+  // Max 63 characters (PostgreSQL limit)
+  const validIdentifier = /^[a-z_][a-z0-9_]*$/i
+  if (!validIdentifier.test(tableName) || tableName.length > 63) {
+    // eslint-disable-next-line functional/no-throw-statements -- Validation requires throwing for invalid input
+    throw new Error(`Invalid table name: ${tableName}`)
+  }
+}
+
+/**
+ * Validate a column name to prevent SQL injection
+ */
+export const validateColumnName = (columnName: string): void => {
+  const validIdentifier = /^[a-z_][a-z0-9_]*$/i
+  if (!validIdentifier.test(columnName) || columnName.length > 63) {
+    // eslint-disable-next-line functional/no-throw-statements -- Validation requires throwing for invalid input
+    throw new Error(`Invalid column name: ${columnName}`)
+  }
+}

package/src/infrastructure/database/views/view-generators.ts

@@ -0,0 +1,258 @@
+/**
+ * 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 { generateSqlCondition } from '../filter-operators'
+import {
+  getExistingViews,
+  getExistingMaterializedViews,
+  executeSQLStatements,
+  executeSQLStatementsParallel,
+  type TransactionLike,
+} from '../sql/sql-execution'
+import type { Table } from '@/domain/models/app/table'
+import type { View } from '@/domain/models/app/table/views'
+import type { ViewFilterNode } from '@/domain/models/app/table/views/filters'
+
+/**
+ * Map filter nodes to SQL condition strings
+ * Extracts field, operator, value from each condition and generates SQL
+ * Handles leaf conditions only (not nested AND/OR groups)
+ */
+const mapFilterConditions = (nodes: readonly ViewFilterNode[]): readonly string[] => {
+  return nodes
+    .map((node) => {
+      if ('field' in node && 'operator' in node && 'value' in node) {
+        return generateSqlCondition(node.field, node.operator, node.value)
+      }
+      return ''
+    })
+    .filter((c) => c !== '')
+}
+
+/**
+ * Generate SQL WHERE clause from view filters
+ * Supports comparison operators (equals, greaterThan, lessThan, etc.)
+ * Values are properly escaped to prevent SQL injection
+ */
+const generateWhereClause = (filters: View['filters']): string => {
+  if (!filters) return ''
+
+  // Handle AND filters
+  if ('and' in filters && filters.and) {
+    const conditions = mapFilterConditions(filters.and)
+    return conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : ''
+  }
+
+  // Handle OR filters
+  if ('or' in filters && filters.or) {
+    const conditions = mapFilterConditions(filters.or)
+    return conditions.length > 0 ? `WHERE ${conditions.join(' OR ')}` : ''
+  }
+
+  return ''
+}
+
+/**
+ * Generate SQL ORDER BY clause from view sorts and groupBy
+ * GroupBy takes precedence - when present, it's used for ordering
+ * If both groupBy and sorts are present, groupBy is applied first
+ */
+const generateOrderByClause = (sorts: View['sorts'], groupBy: View['groupBy']): string => {
+  // Build order items immutably
+  const groupByItems = groupBy
+    ? [`${groupBy.field} ${(groupBy.direction || 'asc').toUpperCase()}`]
+    : []
+
+  const sortItems =
+    sorts && sorts.length > 0 && !groupBy
+      ? sorts.map((sort) => `${sort.field} ${sort.direction.toUpperCase()}`)
+      : []
+
+  const orderItems = [...groupByItems, ...sortItems]
+
+  return orderItems.length > 0 ? `ORDER BY ${orderItems.join(', ')}` : ''
+}
+
+/**
+ * Generate CREATE VIEW or CREATE MATERIALIZED VIEW statement for a table view
+ * PostgreSQL doesn't support IF NOT EXISTS for CREATE VIEW, so we drop first
+ */
+export const generateViewSQL = (table: Table, view: View): string => {
+  const viewType = view.materialized ? 'MATERIALIZED VIEW' : 'VIEW'
+  // Convert view.id to string (ViewId can be number or string)
+  const viewIdStr = String(view.id)
+
+  // If view has a custom query, use it directly
+  if (view.query) {
+    return `CREATE ${viewType} ${viewIdStr} AS ${view.query}`
+  }
+
+  // Otherwise, build query from filters, sorts, fields, groupBy
+  const fields = view.fields && view.fields.length > 0 ? view.fields.join(', ') : '*'
+  const whereClause = generateWhereClause(view.filters)
+  const orderByClause = generateOrderByClause(view.sorts, view.groupBy)
+
+  const clauses = [`SELECT ${fields}`, `FROM ${table.name}`, whereClause, orderByClause].filter(
+    (clause) => clause !== ''
+  )
+
+  const query = clauses.join(' ')
+
+  return `CREATE ${viewType} ${viewIdStr} AS ${query}`
+}
+
+/**
+ * Generate all CREATE VIEW statements for a table
+ */
+export const generateTableViewStatements = (table: Table): readonly string[] => {
+  if (!table.views || table.views.length === 0) return []
+
+  return table.views.map((view) => generateViewSQL(table, view))
+}
+
+/**
+ * Generate trigger to make a view read-only
+ * PostgreSQL views can be automatically updatable if they meet certain criteria
+ * To ensure views are truly read-only, we create INSTEAD OF triggers that reject modifications
+ */
+export const generateReadOnlyViewTrigger = (viewId: string | number): readonly string[] => {
+  const viewIdStr = String(viewId)
+  const triggerBaseName = `${viewIdStr}_readonly`
+
+  return [
+    // INSTEAD OF INSERT trigger
+    `CREATE OR REPLACE FUNCTION ${triggerBaseName}_insert_fn()
+    RETURNS TRIGGER AS $$
+    BEGIN
+      RAISE EXCEPTION 'cannot insert into view "%"', TG_TABLE_NAME;
+    END;
+    $$ LANGUAGE plpgsql`,
+    `CREATE TRIGGER ${triggerBaseName}_insert
+    INSTEAD OF INSERT ON ${viewIdStr}
+    FOR EACH ROW EXECUTE FUNCTION ${triggerBaseName}_insert_fn()`,
+
+    // INSTEAD OF UPDATE trigger
+    `CREATE OR REPLACE FUNCTION ${triggerBaseName}_update_fn()
+    RETURNS TRIGGER AS $$
+    BEGIN
+      RAISE EXCEPTION 'cannot update view "%"', TG_TABLE_NAME;
+    END;
+    $$ LANGUAGE plpgsql`,
+    `CREATE TRIGGER ${triggerBaseName}_update
+    INSTEAD OF UPDATE ON ${viewIdStr}
+    FOR EACH ROW EXECUTE FUNCTION ${triggerBaseName}_update_fn()`,
+
+    // INSTEAD OF DELETE trigger
+    `CREATE OR REPLACE FUNCTION ${triggerBaseName}_delete_fn()
+    RETURNS TRIGGER AS $$
+    BEGIN
+      RAISE EXCEPTION 'cannot delete from view "%"', TG_TABLE_NAME;
+    END;
+    $$ LANGUAGE plpgsql`,
+    `CREATE TRIGGER ${triggerBaseName}_delete
+    INSTEAD OF DELETE ON ${viewIdStr}
+    FOR EACH ROW EXECUTE FUNCTION ${triggerBaseName}_delete_fn()`,
+  ]
+}
+
+/**
+ * Drop views that no longer exist in the schema
+ * Called once for all tables to ensure clean state before creating views
+ */
+/* eslint-disable functional/no-expression-statements */
+export const generateDropObsoleteViewsSQL = async (
+  tx: TransactionLike,
+  tables: readonly Table[]
+): Promise<void> => {
+  // Get existing views using Effect-based queries
+  const program = Effect.gen(function* () {
+    // Query both view types in parallel
+    const [existingViewNames, existingMatViewNames] = yield* Effect.all(
+      [getExistingViews(tx), getExistingMaterializedViews(tx)],
+      { concurrency: 2 }
+    )
+
+    const existingViews = new Set(existingViewNames)
+    const existingMatViews = new Set(existingMatViewNames)
+
+    // Collect ALL view IDs from schema (across all tables)
+    const allSchemaViewIds = new Set<string>(
+      tables.flatMap((table) =>
+        table.views && table.views.length > 0 ? table.views.map((view) => String(view.id)) : []
+      )
+    )
+
+    // Find views to drop: exist in DB but not in schema
+    const viewsToDrop = Array.from(existingViews).filter(
+      (viewName) => !allSchemaViewIds.has(viewName)
+    )
+    const matViewsToDrop = Array.from(existingMatViews).filter(
+      (viewName) => !allSchemaViewIds.has(viewName)
+    )
+
+    // Generate DROP statements
+    const dropViewStatements = viewsToDrop.map(
+      (viewName) => `DROP VIEW IF EXISTS ${viewName} CASCADE`
+    )
+    const dropMatViewStatements = matViewsToDrop.map(
+      (viewName) => `DROP MATERIALIZED VIEW IF EXISTS ${viewName} CASCADE`
+    )
+
+    // Execute all DROP statements sequentially (not in parallel)
+    // Sequential execution ensures CASCADE dependencies are handled correctly
+    // When dropping view A that view B depends on, CASCADE will drop B automatically
+    // If we then try to drop B, IF EXISTS makes it a no-op
+    yield* executeSQLStatements(tx, [...dropViewStatements, ...dropMatViewStatements])
+  })
+
+  await Effect.runPromise(program)
+}
+/* eslint-enable functional/no-expression-statements */
+
+/**
+ * Drop all views that are not defined in any table's schema
+ * This ensures orphaned views (manually created or from previous schemas) are cleaned up
+ */
+/* eslint-disable functional/no-expression-statements */
+export const dropAllObsoleteViews = async (
+  tx: TransactionLike,
+  tables: readonly Table[]
+): Promise<void> => {
+  const program = Effect.gen(function* () {
+    // Query both view types in parallel
+    const [existingViewNames, existingMatViewNames] = yield* Effect.all(
+      [getExistingViews(tx), getExistingMaterializedViews(tx)],
+      { concurrency: 2 }
+    )
+
+    // Collect all view IDs from all tables (functional construction)
+    const allSchemaViews = new Set<string>(
+      tables.flatMap((table) => (table.views ? table.views.map((view) => String(view.id)) : []))
+    )
+
+    // Find views to drop - any view in DB that's not in schema
+    const viewsToDrop = existingViewNames.filter((viewName) => !allSchemaViews.has(viewName))
+    const matViewsToDrop = existingMatViewNames.filter((viewName) => !allSchemaViews.has(viewName))
+
+    // Generate DROP statements with CASCADE
+    const dropViewStatements = viewsToDrop.map(
+      (viewName) => `DROP VIEW IF EXISTS ${viewName} CASCADE`
+    )
+    const dropMatViewStatements = matViewsToDrop.map(
+      (viewName) => `DROP MATERIALIZED VIEW IF EXISTS ${viewName} CASCADE`
+    )
+
+    // Execute all DROP statements in parallel
+    if (dropViewStatements.length > 0 || dropMatViewStatements.length > 0) {
+      yield* executeSQLStatementsParallel(tx, [...dropViewStatements, ...dropMatViewStatements])
+    }
+  })
+
+  await Effect.runPromise(program)
+}
+/* eslint-enable functional/no-expression-statements */

package/src/infrastructure/devtools/devtools-layer.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 { DevTools } from '@effect/experimental'
+import { Layer } from 'effect'
+
+/**
+ * Effect DevTools layer for development debugging
+ *
+ * Provides runtime tracing and telemetry via the Effect DevTools extension.
+ * Enable by setting EFFECT_DEVTOOLS=1 environment variable.
+ *
+ * Requirements:
+ * - Install VS Code/Cursor Effect extension: https://marketplace.visualstudio.com/items?itemName=effectful-tech.effect-vscode
+ * - Set EFFECT_DEVTOOLS=1 in your environment
+ * - Run the application
+ * - Open Effect panel in your editor to see telemetry
+ *
+ * @example
+ * ```bash
+ * EFFECT_DEVTOOLS=1 bun run start
+ * ```
+ *
+ * @see https://effect.website/docs/getting-started/devtools/
+ */
+export const DevToolsLayer = DevTools.layer()
+
+/**
+ * Check if DevTools should be enabled based on environment variable
+ */
+export const isDevToolsEnabled = (): boolean => process.env['EFFECT_DEVTOOLS'] === '1'
+
+/**
+ * Conditionally provide DevTools layer based on environment
+ *
+ * Returns the DevTools layer if EFFECT_DEVTOOLS=1, otherwise returns an empty layer.
+ * This allows safe integration without runtime overhead when disabled.
+ */
+export const DevToolsLayerOptional = isDevToolsEnabled() ? DevToolsLayer : Layer.empty

package/src/infrastructure/devtools/index.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 { DevToolsLayer, DevToolsLayerOptional, isDevToolsEnabled } from './devtools-layer'

package/src/infrastructure/email/email-config.ts

@@ -0,0 +1,103 @@
+/**
+ * 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 { logError, logWarning } from '../logging'
+import type { EmailConfig } from './nodemailer'
+
+/**
+ * SMTP Configuration using type-safe environment variable access
+ *
+ * This module provides email configuration with:
+ * 1. Type-safe environment variable access
+ * 2. Sensible defaults for development (Mailpit)
+ * 3. Structured logging for missing configuration
+ * 4. Clear separation of production vs development modes
+ *
+ * Environment Variables:
+ * - SMTP_HOST: SMTP server hostname (required in production)
+ * - SMTP_PORT: SMTP server port (default: 587)
+ * - SMTP_SECURE: Use SSL/TLS (default: false for port 587, true for port 465)
+ * - SMTP_USER: SMTP authentication username
+ * - SMTP_PASS: SMTP authentication password
+ * - SMTP_FROM: Default "from" email address (default: noreply@sovrium.com)
+ * - SMTP_FROM_NAME: Default "from" display name (default: 'Sovrium')
+ *
+ * @see https://mailpit.axllent.org/ for local development email testing
+ */
+
+/**
+ * Read optional string from environment
+ */
+const getEnvString = (key: string, defaultValue: string): string => process.env[key] ?? defaultValue
+
+/**
+ * Read optional number from environment
+ */
+const getEnvNumber = (key: string, defaultValue: number): number => {
+  const value = process.env[key]
+  return value ? parseInt(value, 10) : defaultValue
+}
+
+/**
+ * Read optional boolean from environment
+ */
+const getEnvBoolean = (key: string, defaultValue: boolean): boolean => {
+  const value = process.env[key]
+  return value ? value === 'true' : defaultValue
+}
+
+/**
+ * Get email configuration from environment variables
+ *
+ * In production, SMTP_HOST is required. In development, falls back to
+ * localhost:1025 (Mailpit) for local email testing.
+ */
+export const getEmailConfigFromEffect = (): EmailConfig => {
+  const host = process.env.SMTP_HOST
+  const isProduction = process.env.NODE_ENV === 'production'
+
+  // Use real SMTP when host is configured
+  if (host) {
+    const port = getEnvNumber('SMTP_PORT', 587)
+    return {
+      host,
+      port,
+      secure: getEnvBoolean('SMTP_SECURE', false) || port === 465,
+      auth: {
+        user: getEnvString('SMTP_USER', ''),
+        pass: getEnvString('SMTP_PASS', ''),
+      },
+      from: {
+        email: getEnvString('SMTP_FROM', 'noreply@sovrium.com'),
+        name: getEnvString('SMTP_FROM_NAME', 'Sovrium'),
+      },
+    }
+  }
+
+  // Log warnings for missing SMTP config
+  if (isProduction) {
+    logError('[EMAIL] SMTP_HOST not configured in production mode')
+  } else {
+    logWarning('[EMAIL] SMTP_HOST not configured, using 127.0.0.1:1025 (Mailpit)')
+  }
+
+  // Development fallback - Mailpit on localhost
+  // Use explicit IPv4 address to avoid IPv6 resolution issues
+  return {
+    host: '127.0.0.1',
+    port: 1025,
+    secure: false,
+    auth: {
+      user: '',
+      pass: '',
+    },
+    from: {
+      email: getEnvString('SMTP_FROM', 'noreply@sovrium.local'),
+      name: getEnvString('SMTP_FROM_NAME', 'Sovrium (Dev)'),
+    },
+  }
+}

package/src/infrastructure/email/email-service.ts

@@ -0,0 +1,152 @@
+/**
+ * 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 { Context, Effect, Layer, Data } from 'effect'
+import { transporter, getDefaultFrom, type SendMailOptions } from './nodemailer'
+
+/**
+ * Email service error types
+ */
+export class EmailError extends Data.TaggedError('EmailError')<{
+  readonly message: string
+  readonly cause?: unknown
+}> {}
+
+export class EmailConnectionError extends Data.TaggedError('EmailConnectionError')<{
+  readonly message: string
+  readonly cause?: unknown
+}> {}
+
+/**
+ * Email service interface
+ *
+ * Provides a functional interface for sending emails with Effect-based
+ * error handling and composition.
+ */
+export interface EmailService {
+  /**
+   * Send an email
+   *
+   * @param options - Nodemailer mail options
+   * @returns Effect that resolves with message info or fails with EmailError
+   */
+  readonly send: (options: Readonly<SendMailOptions>) => Effect.Effect<string, EmailError>
+
+  /**
+   * Send an email with the default "from" address
+   *
+   * @param options - Mail options without "from" field
+   * @returns Effect that resolves with message info or fails with EmailError
+   */
+  readonly sendWithDefaultFrom: (
+    options: Readonly<Omit<SendMailOptions, 'from'>>
+  ) => Effect.Effect<string, EmailError>
+
+  /**
+   * Verify SMTP connection
+   *
+   * @returns Effect that resolves with true or fails with EmailConnectionError
+   */
+  readonly verifyConnection: () => Effect.Effect<boolean, EmailConnectionError>
+}
+
+/**
+ * Email service tag for Effect dependency injection
+ */
+export class Email extends Context.Tag('Email')<Email, EmailService>() {}
+
+/**
+ * Live implementation of EmailService using Nodemailer
+ */
+export const EmailLive = Layer.succeed(
+  Email,
+  Email.of({
+    send: (options) =>
+      Effect.tryPromise({
+        try: async () => {
+          const info = await transporter.sendMail(options)
+          return info.messageId
+        },
+        catch: (error) =>
+          new EmailError({
+            message: `Failed to send email: ${error instanceof Error ? error.message : String(error)}`,
+            cause: error,
+          }),
+      }),
+
+    sendWithDefaultFrom: (options) =>
+      Effect.tryPromise({
+        try: async () => {
+          const info = await transporter.sendMail({
+            from: getDefaultFrom(),
+            ...options,
+          })
+          return info.messageId
+        },
+        catch: (error) =>
+          new EmailError({
+            message: `Failed to send email: ${error instanceof Error ? error.message : String(error)}`,
+            cause: error,
+          }),
+      }),
+
+    verifyConnection: () =>
+      Effect.tryPromise({
+        try: () => transporter.verify(),
+        catch: (error) =>
+          new EmailConnectionError({
+            message: `SMTP connection failed: ${error instanceof Error ? error.message : String(error)}`,
+            cause: error,
+          }),
+      }),
+  })
+)
+
+/**
+ * Send email helper function (for use outside Effect context)
+ *
+ * This is a convenience function for Better Auth integration where
+ * we need to use async/await directly instead of Effect.
+ *
+ * @example
+ * ```typescript
+ * import { sendEmail } from '@/infrastructure/email/email-service'
+ *
+ * await sendEmail({
+ *   to: 'user@example.com',
+ *   subject: 'Welcome',
+ *   html: '<h1>Welcome!</h1>',
+ * })
+ * ```
+ */
+export async function sendEmail(options: Readonly<Omit<SendMailOptions, 'from'>>): Promise<string> {
+  const info = await transporter.sendMail({
+    from: getDefaultFrom(),
+    ...options,
+  })
+  return info.messageId
+}
+
+/**
+ * Send email with full options (including custom "from")
+ *
+ * @example
+ * ```typescript
+ * import { sendEmailWithOptions } from '@/infrastructure/email/email-service'
+ *
+ * await sendEmailWithOptions({
+ *   from: '"Custom Sender" <custom@example.com>',
+ *   to: 'user@example.com',
+ *   subject: 'Hello',
+ *   text: 'Hello World',
+ * })
+ * ```
+ */
+export async function sendEmailWithOptions(options: Readonly<SendMailOptions>): Promise<string> {
+  const info = await transporter.sendMail(options)
+  return info.messageId
+}